diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml new file mode 100644 index 0000000000..61ec76e9f8 --- /dev/null +++ b/.github/workflows/docs.yaml @@ -0,0 +1,47 @@ +name: Docs CI + +on: + push: + branches: + - master + - '[0-9].[0-9]' + pull_request: + branches: + - master + - '[0-9].[0-9]' + schedule: + - cron: '0 1 * * *' # nightly build + +concurrency: + group: ${{ github.event.pull_request.number || github.ref }} + cancel-in-progress: true + +permissions: + contents: read # to fetch code (actions/checkout) + +jobs: + + build-docs: + name: Build docs + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - uses: actions/setup-python@v4 + with: + python-version: 3.9 + cache: 'pip' + - name: install deps + run: | + sudo apt-get update -yqq + sudo apt-get install -yqq pandoc make + - name: run code linters + run: | + pip install -r requirements.txt -r dev_requirements.txt -r docs/requirements.txt + invoke build-docs + + - name: upload docs + uses: actions/upload-artifact@v3 + with: + name: redis-py-docs + path: | + docs/_build/html diff --git a/docs/conf.py b/docs/conf.py index cdbeb02c9a..8849752404 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -60,7 +60,7 @@ # General information about the project. project = "redis-py" -copyright = "2022, Redis Inc" +copyright = "2023, Redis Inc" # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the @@ -287,4 +287,4 @@ epub_title = "redis-py" epub_author = "Redis Inc" epub_publisher = "Redis Inc" -epub_copyright = "2022, Redis Inc" +epub_copyright = "2023, Redis Inc" diff --git a/docs/examples/redis-stream-example.ipynb b/docs/examples/redis-stream-example.ipynb index 9303b527ca..a84bf19cb6 100644 --- a/docs/examples/redis-stream-example.ipynb +++ b/docs/examples/redis-stream-example.ipynb @@ -313,7 +313,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "# stream groups\n", + "# Stream groups\n", "With the groups is possible track, for many consumers, and at the Redis side, which message have been already consumed.\n", "## add some data to streams\n", "Creating 2 streams with 10 messages each." diff --git a/docs/requirements.txt b/docs/requirements.txt index edecdffe4b..5b15c09268 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -5,3 +5,4 @@ sphinx_gallery ipython sphinx-autodoc-typehints furo +pandoc diff --git a/redis/asyncio/client.py b/redis/asyncio/client.py index 31e27a4462..0e3c879278 100644 --- a/redis/asyncio/client.py +++ b/redis/asyncio/client.py @@ -134,10 +134,13 @@ def from_url( There are several ways to specify a database number. The first value found will be used: - 1. A ``db`` querystring option, e.g. redis://localhost?db=0 - 2. If using the redis:// or rediss:// schemes, the path argument + + 1. A ``db`` querystring option, e.g. redis://localhost?db=0 + + 2. If using the redis:// or rediss:// schemes, the path argument of the url, e.g. redis://localhost/0 - 3. A ``db`` keyword argument to this function. + + 3. A ``db`` keyword argument to this function. If none of these options are specified, the default db=0 is used. diff --git a/redis/asyncio/connection.py b/redis/asyncio/connection.py index 22c5030e6c..d501989c83 100644 --- a/redis/asyncio/connection.py +++ b/redis/asyncio/connection.py @@ -948,10 +948,13 @@ def from_url(cls: Type[_CP], url: str, **kwargs) -> _CP: There are several ways to specify a database number. The first value found will be used: - 1. A ``db`` querystring option, e.g. redis://localhost?db=0 - 2. If using the redis:// or rediss:// schemes, the path argument + + 1. A ``db`` querystring option, e.g. redis://localhost?db=0 + + 2. If using the redis:// or rediss:// schemes, the path argument of the url, e.g. redis://localhost/0 - 3. A ``db`` keyword argument to this function. + + 3. A ``db`` keyword argument to this function. If none of these options are specified, the default db=0 is used. diff --git a/redis/commands/core.py b/redis/commands/core.py index 6abcd5a2ec..8b1b711df9 100644 --- a/redis/commands/core.py +++ b/redis/commands/core.py @@ -517,6 +517,7 @@ def client_list( """ Returns a list of currently connected clients. If type of client specified, only that type will be returned. + :param _type: optional. one of the client types (normal, master, replica, pubsub) :param client_id: optional. a list of client ids @@ -559,16 +560,17 @@ def client_reply( ) -> ResponseT: """ Enable and disable redis server replies. + ``reply`` Must be ON OFF or SKIP, - ON - The default most with server replies to commands - OFF - Disable server responses to commands - SKIP - Skip the response of the immediately following command. + ON - The default most with server replies to commands + OFF - Disable server responses to commands + SKIP - Skip the response of the immediately following command. Note: When setting OFF or SKIP replies, you will need a client object with a timeout specified in seconds, and will need to catch the TimeoutError. - The test_client_reply unit test illustrates this, and - conftest.py has a client with a timeout. + The test_client_reply unit test illustrates this, and + conftest.py has a client with a timeout. See https://redis.io/commands/client-reply """ @@ -724,19 +726,21 @@ def client_unblock( def client_pause(self, timeout: int, all: bool = True, **kwargs) -> ResponseT: """ - Suspend all the Redis clients for the specified amount of time - :param timeout: milliseconds to pause clients + Suspend all the Redis clients for the specified amount of time. + For more information see https://redis.io/commands/client-pause + + :param timeout: milliseconds to pause clients :param all: If true (default) all client commands are blocked. - otherwise, clients are only blocked if they attempt to execute - a write command. - For the WRITE mode, some commands have special behavior: - EVAL/EVALSHA: Will block client for all scripts. - PUBLISH: Will block client. - PFCOUNT: Will block client. - WAIT: Acknowledgments will be delayed, so this command will - appear blocked. + otherwise, clients are only blocked if they attempt to execute + a write command. + For the WRITE mode, some commands have special behavior: + EVAL/EVALSHA: Will block client for all scripts. + PUBLISH: Will block client. + PFCOUNT: Will block client. + WAIT: Acknowledgments will be delayed, so this command will + appear blocked. """ args = ["CLIENT PAUSE", str(timeout)] if not isinstance(timeout, int): @@ -1215,9 +1219,11 @@ def quit(self, **kwargs) -> ResponseT: def replicaof(self, *args, **kwargs) -> ResponseT: """ Update the replication settings of a redis replica, on the fly. + Examples of valid arguments include: - NO ONE (set no replication) - host port (set to the host and port of a redis server) + + NO ONE (set no replication) + host port (set to the host and port of a redis server) For more information see https://redis.io/commands/replicaof """ @@ -3603,27 +3609,37 @@ def xclaim( ) -> ResponseT: """ Changes the ownership of a pending message. + name: name of the stream. + groupname: name of the consumer group. + consumername: name of a consumer that claims the message. + min_idle_time: filter messages that were idle less than this amount of milliseconds + message_ids: non-empty list or tuple of message IDs to claim + idle: optional. Set the idle time (last time it was delivered) of the - message in ms + message in ms + time: optional integer. This is the same as idle but instead of a - relative amount of milliseconds, it sets the idle time to a specific - Unix time (in milliseconds). + relative amount of milliseconds, it sets the idle time to a specific + Unix time (in milliseconds). + retrycount: optional integer. set the retry counter to the specified - value. This counter is incremented every time a message is delivered - again. + value. This counter is incremented every time a message is delivered + again. + force: optional boolean, false by default. Creates the pending message - entry in the PEL even if certain specified IDs are not already in the - PEL assigned to a different client. + entry in the PEL even if certain specified IDs are not already in the + PEL assigned to a different client. + justid: optional boolean, false by default. Return just an array of IDs - of messages successfully claimed, without returning the actual message + of messages successfully claimed, without returning the actual message - For more information see https://redis.io/commands/xclaim + For more information see https://redis.io/commands/xclaim """ if not isinstance(min_idle_time, int) or min_idle_time < 0: raise DataError("XCLAIM min_idle_time must be a non negative integer") @@ -3875,11 +3891,15 @@ def xrange( ) -> ResponseT: """ Read stream values within an interval. + name: name of the stream. + start: first stream ID. defaults to '-', meaning the earliest available. + finish: last stream ID. defaults to '+', meaning the latest available. + count: if set, only return this many items, beginning with the earliest available. @@ -3902,10 +3922,13 @@ def xread( ) -> ResponseT: """ Block and monitor multiple streams for new data. + streams: a dict of stream names to stream IDs, where IDs indicate the last ID already seen. + count: if set, only return this many items, beginning with the earliest available. + block: number of milliseconds to wait, if nothing already present. For more information see https://redis.io/commands/xread @@ -3940,12 +3963,17 @@ def xreadgroup( ) -> ResponseT: """ Read from a stream via a consumer group. + groupname: name of the consumer group. + consumername: name of the requesting consumer. + streams: a dict of stream names to stream IDs, where IDs indicate the last ID already seen. + count: if set, only return this many items, beginning with the earliest available. + block: number of milliseconds to wait, if nothing already present. noack: do not add messages to the PEL @@ -3980,11 +4008,15 @@ def xrevrange( ) -> ResponseT: """ Read stream values within an interval, in reverse order. + name: name of the stream + start: first stream ID. defaults to '+', meaning the latest available. + finish: last stream ID. defaults to '-', meaning the earliest available. + count: if set, only return this many items, beginning with the latest available. @@ -5301,8 +5333,10 @@ def script_flush( self, sync_type: Union[Literal["SYNC"], Literal["ASYNC"]] = None ) -> ResponseT: """Flush all scripts from the script cache. + ``sync_type`` is by default SYNC (synchronous) but it can also be ASYNC. + For more information see https://redis.io/commands/script-flush """ @@ -5615,11 +5649,14 @@ def geosearch( area specified by a given shape. This command extends the GEORADIUS command, so in addition to searching within circular areas, it supports searching within rectangular areas. + This command should be used in place of the deprecated GEORADIUS and GEORADIUSBYMEMBER commands. + ``member`` Use the position of the given existing member in the sorted set. Can't be given with ``longitude`` and ``latitude``. + ``longitude`` and ``latitude`` Use the position given by this coordinates. Can't be given with ``member`` ``radius`` Similar to GEORADIUS, search inside circular @@ -5628,17 +5665,23 @@ def geosearch( ``height`` and ``width`` Search inside an axis-aligned rectangle, determined by the given height and width. Can't be given with ``radius`` + ``unit`` must be one of the following : m, km, mi, ft. `m` for meters (the default value), `km` for kilometers, `mi` for miles and `ft` for feet. + ``sort`` indicates to return the places in a sorted way, ASC for nearest to furthest and DESC for furthest to nearest. + ``count`` limit the results to the first count matching items. + ``any`` is set to True, the command will return as soon as enough matches are found. Can't be provided without ``count`` + ``withdist`` indicates to return the distances of each place. ``withcoord`` indicates to return the latitude and longitude of each place. + ``withhash`` indicates to return the geohash string of each place. For more information see https://redis.io/commands/geosearch diff --git a/tasks.py b/tasks.py index 5162566183..c60fa2791e 100644 --- a/tasks.py +++ b/tasks.py @@ -21,7 +21,7 @@ def devenv(c): def build_docs(c): """Generates the sphinx documentation.""" run("pip install -r docs/requirements.txt") - run("make html") + run("make -C docs html") @task