From ae9023b3f949d94c877f664dfee235b091134243 Mon Sep 17 00:00:00 2001 From: Eugene Toder Date: Fri, 8 Mar 2024 22:51:15 -0500 Subject: [PATCH] Update documentation and rename the extra to "gssauth" --- README.rst | 11 +++++++++-- asyncpg/protocol/coreproto.pyx | 4 ++-- docs/installation.rst | 29 ++++++++++++++++++++++------- pyproject.toml | 2 +- 4 files changed, 34 insertions(+), 12 deletions(-) diff --git a/README.rst b/README.rst index 438b4c44..0d078d82 100644 --- a/README.rst +++ b/README.rst @@ -58,11 +58,18 @@ This enables asyncpg to have easy-to-use support for: Installation ------------ -asyncpg is available on PyPI and has no dependencies. -Use pip to install:: +asyncpg is available on PyPI. When not using GSSAPI/SSPI authentication it +has no dependencies. Use pip to install:: $ pip install asyncpg +If you need GSSAPI/SSPI authentication, use:: + + $ pip install 'asyncpg[gssauth]' + +For more details, please `see the documentation +`_. + Basic Usage ----------- diff --git a/asyncpg/protocol/coreproto.pyx b/asyncpg/protocol/coreproto.pyx index 2dccbc83..fd65327b 100644 --- a/asyncpg/protocol/coreproto.pyx +++ b/asyncpg/protocol/coreproto.pyx @@ -724,7 +724,7 @@ cdef class CoreProtocol: import gssapi except ModuleNotFoundError: raise apg_exc.InterfaceError( - 'gssapi module not found; please install asyncpg[gssapi] to ' + 'gssapi module not found; please install asyncpg[gssauth] to ' 'use asyncpg with Kerberos/GSSAPI/SSPI authentication' ) from None @@ -736,7 +736,7 @@ cdef class CoreProtocol: import sspilib except ModuleNotFoundError: raise apg_exc.InterfaceError( - 'sspilib module not found; please install asyncpg[gssapi] to ' + 'sspilib module not found; please install asyncpg[gssauth] to ' 'use asyncpg with Kerberos/GSSAPI/SSPI authentication' ) from None diff --git a/docs/installation.rst b/docs/installation.rst index 6d9ec2ef..1a567fab 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -4,20 +4,35 @@ Installation ============ -**asyncpg** has no external dependencies and the recommended way to -install it is to use **pip**: +**asyncpg** has no external dependencies when not using GSSAPI/SSPI +authentication. The recommended way to install it is to use **pip**: .. code-block:: bash $ pip install asyncpg +If you need GSSAPI/SSPI authentication, the recommended way is to use -.. note:: +.. code-block:: bash + + $ pip install 'asyncpg[gssauth]' + +This installs SSPI support on Windows and GSSAPI support on non-Windows +platforms. SSPI and GSSAPI interoperate as clients and servers: an SSPI +client can authenticate to a GSSAPI server and vice versa. + +On Linux installing GSSAPI requires a working C compiler and Kerberos 5 +development files. The latter can be obtained by installing **libkrb5-dev** +package on Debian/Ubuntu or **krb5-devel** on RHEL/Fedora. (This is needed +because PyPI does not have Linux wheels for gssapi. See `here for the details +`_.) + +It is also possible to use GSSAPI on Windows: - It is recommended to use **pip** version **8.1** or later to take - advantage of the precompiled wheel packages. Older versions of pip - will ignore the wheel packages and install asyncpg from the source - package. In that case a working C compiler is required. + * `pip install gssapi` + * Install `Kerberos for Windows `_. + * Set the ``gsslib`` parameter or the ``PGGSSLIB`` environment variable to + `gssapi` when connecting. Building from source diff --git a/pyproject.toml b/pyproject.toml index fad88e6c..12f6ae68 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -35,7 +35,7 @@ dependencies = [ github = "https://github.com/MagicStack/asyncpg" [project.optional-dependencies] -gssapi = [ +gssauth = [ 'gssapi; platform_system != "Windows"', 'sspilib; platform_system == "Windows"', ]