add config option for an authorization file

README

@@ -1,107 +1,216 @@
-Mutt-LDAP provides an `external address query script`_ for Mutt_ which
-connects to LDAP_ databases using python-ldap_.  It can cache queries
-locally in case your LDAP server is slow or not always available,
-expiring cached queries after a configurable amount of time.
-
 Installation
 ============
 
-Packages
---------
+Recommended (isolated, user-level)
+----------------------------------
 
-Gentoo
-~~~~~~
+- Using uv:
 
-I've packaged Mutt-LDAP for Gentoo_.  You need layman_ and my `wtk
-overlay`_.  Install with::
+  .. code-block:: bash
 
-  # emerge -av app-portage/layman
-  # layman --add wtk
-  # emerge -av mail-client/mutt-ldap
+     uv tool install git+https://github.com/Konfekt/mutt-ldap
 
-Dependencies
-------------
+  Upgrade and uninstall:
 
-If you're installing by hand or packaging Mutt-LDAP for another
-distribution, you'll need the following dependencies:
+  .. code-block:: bash
 
-============  ====================  ===========  ======================
-Package       Purpose               Debian_      Gentoo_
-============  ====================  ===========  ======================
-python-ldap_  LDAP connections      python-ldap  dev-python/python-ldap
-PyXDG_        Optional XDG support  python-xdg   dev-python/pyxdg
-============  ====================  ===========  ======================
+     uv tool upgrade mutt-ldap
+     uv tool uninstall mutt-ldap
 
-Installing by hand
-------------------
+- Using pipx:
+
+  .. code-block:: bash
+
+     pipx install git+https://github.com/Konfekt/mutt-ldap
+
+  Upgrade and uninstall:
+
+  .. code-block:: bash
+
+     pipx upgrade mutt-ldap
+     pipx uninstall mutt-ldap
+
+Alternative
+-----------
+
+- Using pip in a virtual environment:
+
+  .. code-block:: bash
+
+     python -m venv .venv
+     . .venv/bin/activate
+     pip install git+https://github.com/Konfekt/mutt-ldap
 
-Mutt-LDAP is available as a Git_ repository::
+- From a local checkout:
 
-  $ git clone git://tremily.us/mutt-ldap.git
+  .. code-block:: bash
 
-It is also mirrored on GitHub_.  To install the checkout, run the
-standard::
+     git clone https://github.com/Konfekt/mutt-ldap.git
+     cd mutt-ldap
+     pipx install .
 
-  $ python setup.py install
+Dependencies
+============
 
-or you can just copy ``mutt_ldap.py`` into to your ``PATH``.
+- ldap3 (Python LDAP client; no system LDAP libs required)
+- pyxdg (for optional XDG base directory support)
+
+Both are declared as runtime dependencies and installed automatically by the methods above.
 
 Usage
 =====
 
-Add the following line to your ``~/.muttrc``::
+.. code-block:: text
+
+   usage: mutt-ldap [-h] [--version] [--config CONFIG] [--verbose]
+                    query [query ...]
+
+positional arguments:
+  query            Search query for the LDAP directory
+
+optional arguments:
+  --config CONFIG  Path to the configuration file
+  --verbose        Increase output verbosity
+
+If PyXDG is not available, the default configuration path falls back to ``~/.config/mutt-ldap/mutt-ldap.cfg`` and the default cache path falls back to ``~/.cache/mutt-ldap/mutt-ldap.json``.
 
-  set query_command = "mutt_ldap.py '%s'"
+To use in Mutt, add to ``~/.muttrc``::
 
-Search for addresses (from Mutt_) with ``^t``, optionally after typing
-part of the name.  Configure your connection by creating
-``$XDG_CONFIG_HOME/mutt-ldap.cfg`` containing something like::
+  set query_command = 'mutt-ldap "%s"'
 
-  [connection]
-  server = myserver.example.net
-  basedn = ou=people,dc=example,dc=net
+Search for addresses in Mutt with ``^t``, optionally after typing part of a name.
+
+Configure the connection by creating ``$XDG_CONFIG_HOME/mutt-ldap/mutt-ldap.cfg`` with content such as:
+
+.. code:: ini
+
+   [connection]
+   server = myserver.example.net
+   port   = 1389
+   basedn = ou=people,dc=example,dc=net
+
+   [auth]
+   user         = username
+   password-cmd = pass example
 
 The query cache (enabled by default) will be created at
-``$XDG_DATA_HOME/mutt-ldap.json``, unless overriden by an explicit
+``$XDG_DATA_HOME/mutt-ldap.json``, unless overridden by an explicit
 ``cache.path`` setting.
 
-See the ``CONFIG`` options in ``mutt_ldap.py`` for other available
-settings.  See the `XDG Base Directory Specification`_ for more
-details on configuration and cache file locations.  If the ``xdg``
-module supplied by PyXDG_ is not available, the default configuration
-path falls back on ``~/.config/mutt-ldap.cfg`` and the default cache
-path falls back on ``~/.cache/mutt-ldap.json``.
+See the XDG Base Directory Specification for details on configuration and cache locations.
+
+Example Config File
+===================
+
+.. code:: ini
+
+   [connection]
+   server = domaincontroller.yourdomain.com
+   port = 389
+   ssl = no
+   starttls = no
+   basedn = ou=x co.,dc=example,dc=net
+
+   [auth]
+   user =
+   password =
+   file =
+   gssapi = no
+
+   [query]
+   filter =
+   search-fields = cn displayName uid mail
+
+   [results]
+   optional-column =
+
+   [cache]
+   enable = yes
+   path =
+   fields =
+   longevity-days = 14
+
+   [system]
+   output-encoding =
+   argv-encoding =
+
+Config Settings
+===============
+
+Connection Section
+------------------
+
+- ``server``: LDAP server hostname or IP.
+- ``port``: 389 (LDAP) or 636 (LDAPS).
+- ``ssl``: ``yes`` to use LDAPS.
+- ``starttls``: ``yes`` to upgrade a plain connection.
+- ``basedn``: Base DN for searches.
+
+Auth Section
+------------
+
+- ``user``: Bind DN or user principal; blank for anonymous.
+- ``password``: Password; not required for GSSAPI or anonymous.
+- ``password-cmd``: Command whose stdout supplies the password (first line).
+- ``file``: Path to a separate INI with an ``[auth]`` section (e.g., for secrets).
+- ``gssapi``: ``yes`` to use SASL GSSAPI (Kerberos).
+
+Query Section
+-------------
+
+- ``filter``: LDAP filter to pre-restrict results, e.g. ``(objectClass=person)``.
+- ``search-fields``: Space-separated fields for wildcard search.
+
+Results Section
+---------------
+
+- ``optional-column``: Name of an attribute to emit as an extra column for Mutt.
+
+Cache Section
+-------------
+
+- ``enable``: ``yes`` to enable caching.
+- ``path``: Path to JSON cache (defaults to XDG cache dir).
+- ``fields``: Fields to cache; if blank, uses a sane default: ``mail cn displayName`` plus the optional column.
+- ``longevity-days``: Days before entries expire.
+
+System Section
+--------------
+
+- ``output-encoding``: Encoding for stdout (match Mutt’s charset).
+- ``argv-encoding``: Rarely needed on modern systems; provided for completeness.
 
 Licence
 =======
 
-This project is distributed under the `GNU General Public License
-Version 3`_ or greater.
+This project is distributed under the GNU General Public License version 3 or later.
 
 Bugs
 ====
 
-Use the `GitHub issue tracker`_ to submit bugs.
+Use the GitHub issue tracker.
 
 Related work
 ============
 
-`mutt_ldap_query`_ is a Perl script with a similar purpose.
-
-.. _external address query script:
-   http://www.mutt.org/doc/manual/manual-4.html#ss4.5
-.. _Mutt: http://www.mutt.org/
-.. _LDAP: http://en.wikipedia.org/wiki/Lightweight_Directory_Access_Protocol
-.. _python-ldap: http://www.python-ldap.org/
-.. _Gentoo: http://www.gentoo.org/
-.. _layman: http://layman.sourceforge.net/
-.. _wtk overlay: http://blog.tremily.us/posts/Gentoo_overlay/
-.. _Debian: http://www.debian.org/
-.. _PyXDG: http://freedesktop.org/wiki/Software/pyxdg
-.. _Git: http://git-scm.com/
-.. _XDG Base Directory Specification:
-   http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html
-.. _GNU General Public License Version 3: http://www.gnu.org/licenses/gpl.html
-.. _GitHub: https://github.com/wking/mutt-ldap
-.. _GitHub issue tracker: https://github.com/wking/mutt-ldap/issues
-.. _mutt_ldap_query: ftp://ftp.mutt.org/pub/mutt/contrib/mutt_ldap_query.README
+``mutt_ldap_query`` is a Perl script with a similar purpose.
+
+References
+==========
+
+- Mutt manual, external address query: http://www.mutt.org/doc/manual/#query
+- ldap3 documentation: https://ldap3.readthedocs.io/
+- PyXDG: https://freedesktop.org/wiki/Software/pyxdg
+- XDG Base Directory Specification: https://specifications.freedesktop.org/basedir-spec/latest/
+- uv tools: https://docs.astral.sh/uv/
+- pipx: https://pypa.github.io/pipx/
+- mutt_ldap_query: https://github.com/namato/dotfiles/blob/e7ce282c8883dd1971356a0ea53c75b47105c8fa/scripts/ldap.pl
+
+Notes on changes and rationale
+==========
+
+- Script name updated to ``mutt-ldap`` (matches entry point in pyproject).
+- Installation emphasizes isolated user-level installs via uv and pipx.
+- Dependencies updated to ``ldap3`` and ``pyxdg`` (the code uses ldap3, not python-ldap).
+- XDG paths corrected to use config dir ``~/.config/mutt-ldap/mutt-ldap.cfg`` and cache dir ``~/.cache/mutt-ldap/mutt-ldap.json`` (matches code).
+- Outdated Python 2 notes removed; project targets Python 3.7+.