From b43542bb3605c729a2498fe56da0f5f6942c7dfc Mon Sep 17 00:00:00 2001 From: Ali-Akber Saifee Date: Tue, 3 Dec 2024 20:26:59 -0800 Subject: [PATCH] Tweak documentation for credentials provider --- coredis/credentials.py | 10 ++++++++++ docs/source/api/credentials.rst | 6 +++++- docs/source/handbook/credentials.rst | 6 +++--- docs/source/handbook/index.rst | 6 +++++- docs/source/recipes/credentials.rst | 8 +++++--- requirements/docs.txt | 3 +++ 6 files changed, 31 insertions(+), 8 deletions(-) diff --git a/coredis/credentials.py b/coredis/credentials.py index ba38bfd8..361ff60e 100644 --- a/coredis/credentials.py +++ b/coredis/credentials.py @@ -6,7 +6,13 @@ class UserPass(NamedTuple): + """ + Username/password tuple. + """ + + #: Username username: str + #: Password password: str @@ -17,6 +23,10 @@ class AbstractCredentialProvider(ABC): @abstractmethod async def get_credentials(self) -> UserPass: + """ + Returns an instance of :class:`coredis.credentials.UserPass` for + establishing a connection to the redis server. + """ pass diff --git a/docs/source/api/credentials.rst b/docs/source/api/credentials.rst index cd2472d3..5d481de8 100644 --- a/docs/source/api/credentials.rst +++ b/docs/source/api/credentials.rst @@ -14,5 +14,9 @@ Credential Providers .. autoclass:: coredis.credentials.UserPassCredentialProvider :class-doc-from: both +.. autoclass:: coredis.credentials.UserPass + :no-inherited-members: + + .. autoclass:: coredis.recipes.credentials.ElastiCacheIAMProvider - :class-doc-from: both + :class-doc-from: both \ No newline at end of file diff --git a/docs/source/handbook/credentials.rst b/docs/source/handbook/credentials.rst index aaf35a97..2ba18e8b 100644 --- a/docs/source/handbook/credentials.rst +++ b/docs/source/handbook/credentials.rst @@ -4,15 +4,15 @@ Credential Providers In addition to supplying a static username and/or password, **coredis** allows a credential provider to be specified. The **coredis** clients accept any credential provider implementing the -:class:`coredis.credentials.AbstractCredentialProvider` interface. This allows clients to access +:class:`~coredis.credentials.AbstractCredentialProvider` interface. This allows clients to access credentials stored in external credential providers such as AWS IAM. Using the Credential Provider ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ **coredis** comes with a basic implementation of the :class:`coredis.credentials.AbstractCredentialProvider` -interface. This is :class:`coredis.credentials.UserPassCredentialProvider`. It allows a user +interface. This is :class:`~coredis.credentials.UserPassCredentialProvider`. It allows a user to specify a username and/or password that will be used to authenticate with a redis instance. -When the :method:`coredis.credentials.AbstractCredentialProvider.get_credentials` is called, the +When the :meth:`~coredis.credentials.AbstractCredentialProvider.get_credentials` is called, the username and/or password that was set will be returned whenever **coredis** needs the credentials in order to authenticate with the redis or other server. diff --git a/docs/source/handbook/index.rst b/docs/source/handbook/index.rst index 4bf12cc1..1bd2d09b 100644 --- a/docs/source/handbook/index.rst +++ b/docs/source/handbook/index.rst @@ -7,6 +7,7 @@ Handbook cluster sentinel + credentials pubsub streams caching @@ -21,7 +22,6 @@ Handbook typing development - This section contains details on high level concepts of redis that are supported by **coredis**. @@ -31,6 +31,10 @@ Deployment Topologies - :ref:`handbook/cluster:redis cluster` - :ref:`handbook/sentinel:sentinel support` +Authentication +-------------- +- :ref:`handbook/credentials:credential providers` + Event Driven Architectures -------------------------- - :ref:`handbook/pubsub:pubsub` diff --git a/docs/source/recipes/credentials.rst b/docs/source/recipes/credentials.rst index 8511b55e..133c2ddf 100644 --- a/docs/source/recipes/credentials.rst +++ b/docs/source/recipes/credentials.rst @@ -5,10 +5,11 @@ Credential Providers Elasticache IAM Credential Provider ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The implementation is based on `the Elasticache IAM provider described in redis docs .`__ +The implementation is based on `the Elasticache IAM provider described in redis docs `__ -The :class:`ElastiCacheIAMProvider` implements the :class:`coredis.credentials.AbstractCredentialProvider` -interface. It uses ``botocore`` to generate a short-lived authentication token +The :class:`~coredis.recipes.credentials.ElastiCacheIAMProvider` implements the +:class:`~coredis.credentials.AbstractCredentialProvider` interface. +It uses :pypi:`botocore` to generate a short-lived authentication token which can be used to authenticate with an IAM enabled Elasticache cluster. The token is cached for its lifetime of 15 minutes to reduce the number of unnecessary requests. @@ -18,4 +19,5 @@ on using IAM to authenticate with Elasticache. .. autoclass:: coredis.recipes.credentials.ElastiCacheIAMProvider :class-doc-from: both + :no-index: diff --git a/requirements/docs.txt b/requirements/docs.txt index ac0d1df5..a39112dc 100644 --- a/requirements/docs.txt +++ b/requirements/docs.txt @@ -10,4 +10,7 @@ sphinxext-opengraph==0.9.1 sphinx-sitemap==2.5.1 sphinx-paramlinks==0.6.0 sphinxcontrib-programoutput==0.17 +# For credentials recipe +botocore +cachetools