chore: fix docs generation and regen docs

Signed-off-by: Gabor Boros <gabor.brs@gmail.com>

Author: gabor-boros

CHANGELOG.rst

@@ -16,46 +16,118 @@ The format is based on `Keep a Changelog`_, and this project adheres to
 Unreleased_
 -----------
 
+This is a major release that brings significant improvements including Python 3 support, async drivers, enhanced CLI tools, and comprehensive modernization of the codebase. This release is **NOT backward compatible** with 2.4.x.
+
 Added
 ~~~~~
 
-* `ValueError` raised by `ReqlTimeoutError` and `ReqlAuthError` if only host or port set
-* New error type for invalid handshake state: `InvalidHandshakeStateError`
+* **Python 3 Support**: Full Python 3 compatibility with support for Python 3.10+
+* **Async Drivers**: Ported async/await support for multiple event loop implementations:
+  * `rethinkdb.net_asyncio` - Native asyncio support with async/await syntax and `Connection` API
+  * `rethinkdb.net_gevent` - Gevent-based async support with `Connection` API
+  * `rethinkdb.net_tornado` - Tornado integration using `IOLoop` and `Connection` API
+  * `rethinkdb.net_trio` - Trio support with `Connection` API
+  * `rethinkdb.net_twisted` - Twisted integration with `inlineCallbacks` and `Connection` API
+* **CLI Tools (Click-based)**:
+  * `rethinkdb dump`, `export`, `import`, `index-rebuild`, `repl`, `restore`
+  * All commands accept common flags/options: `-q/--quiet`, `--debug`, `-c/--connect`, `--driver-port`, `--host-name`, `-u/--user`, `-p/--password`, `--password-file`, `--tls-cert`
+  * `export` supports `--format json|csv|ndjson|jsongz`, `--delimiter` (CSV), `--compression-level` (jsongz), `--fields`, `--clients`, `--read-outdated`
+* **Type Hints**: Extensive typing across modules
+* **Modern Build/Packaging**: `pyproject.toml` + Poetry
+* **Tests**: New integration tests for each async driver: `tests/integration/test_net_{asyncio,gevent,tornado,trio,twisted}.py`
+* **Documentation**: Sphinx docs under `docs/` with API, history, and vulnerabilities
+* **CI/CD**: GitHub Actions workflows; pre-commit hooks for linting/formatting
+* **Protocol Buffer**: `rethinkdb/ql2_pb2.py` now tracked in VCS
 
 Changed
 ~~~~~~~
 
-* QueryPrinter's `print_query` became a property and renamed to `query`
-* QueryPrinter's `print_carrots` became a property and renamed to `carrots`
-* Renamed `ReqlAvailabilityError` to `ReqlOperationError`
-* Extract REPL helper class to a separate file
-* `HandshakeV1_0` is waiting `bytes` for `username` and `password` attributes instead of `str`
-* `HandshakeV1_0` defines `username` and `password` attributes as protected attributes
-* `HandshakeV1_0` has a hardcoded `JSONEncoder` and `JSONDecoder` from now on
-* `HandshakeV1_0` raises `InvalidHandshakeStateError` when an unrecognized state called in `next_message`
-* Moved `ReQLEncoder`, `ReQLDecoder`, `recursively_make_hashable` to `encoder` module
-* Moved `T` to `utilities` to module and renamed to `EnhancedTuple`
-* Renamed `EnhancedTuple`/`T`'s `intsp` parameter to `int_separator`
-* Renamed `recursively_make_hashable` to `make_hashable`
-* Renamed `optargs` to `kwargs` in `ast` module
-* Renamed internal `_continue` method of connection to `resume` to make it public
-* Internal `_stop`, `_continue` methods of `Connection` became public
-* Renamed internal `_error` to `raise_error`
-* Internal `_extend`, `_error` of `Cursor` became public
-* Renamed `Rql*` to `Reql*`
+API and behavior changes (including breaking changes) compared to 2.4.x:
+
+* **Namespace and Entry Point**:
+  * The `r` entry point is now a `SimpleNamespace` exposing query helpers in `rethinkdb/__init__.py`
+  * A lightweight `Client` wrapper is provided to manage connection loop types via `set_loop_type()`
+* **Exceptions and Error Handling**:
+  * Renamed `Rql*` to `Reql*` across the codebase; removed `Rql*` aliases
+  * Introduced `InvalidHandshakeStateError` for invalid handshake transitions
+  * `ReqlAuthError` raises `ValueError` if only host or only port is provided; includes host:port in message if both are provided
+  * `ReqlTimeoutError` now subclasses `TimeoutError` and mirrors `ReqlAuthError` host/port validation and messaging
+* **QueryPrinter (errors.QueryPrinter)**:
+  * `print_query` -> property `query`
+  * `print_carrots` -> property `carets`
+  * Error messages now embed composed query and caret markers
+* **Handshake (`rethinkdb.handshake.HandshakeV1_0`)**:
+  * Uses protected attributes for credentials: `__username`, `__password`
+  * Username is escaped as per RFC (`,` => `=2C`, `=` => `=3D`)
+  * Accepts optional `json_encoder`/`json_decoder` (defaults to `json.JSONEncoder`/`json.JSONDecoder`)
+  * Raises `ReqlAuthError` for auth failures (error_code 10..20), `ReqlDriverError` for other handshake errors
+  * Raises `InvalidHandshakeStateError` on unexpected/unknown state and on invalid transitions in `next_message`
+  * Validates server protocol version range and server signature per SCRAM-SHA-256
+* **Encoder/Decoder (`rethinkdb.encoder`)**:
+  * Introduced `ReqlEncoder` and `ReqlDecoder` classes
+  * Moved pseudo-type conversions here (TIME, BINARY, GROUPED_DATA)
+  * Renamed utility `recursively_make_hashable` -> `make_hashable`
+* **Utilities**:
+  * Moved `T` to `rethinkdb.utils.EnhancedTuple` and renamed parameter `intsp` -> `int_separator`
+  * `utilities.py` renamed/moved to `utils.py`
+* **AST (`rethinkdb.ast`)**:
+  * Renamed internal `optargs` to `kwargs` consistently across query node implementations
+  * Query operators improved for infix precedence; better error hints for misuse (e.g., `a < b | b < c`)
+  * `__str__` of queries now uses `QueryPrinter(self).query`
+* **Cursor/Connection (`rethinkdb.net`)**:
+  * `Connection.resume(cursor)` replaces `_continue` (now public)
+  * `Connection.stop(cursor)` replaces `_stop` (now public)
+  * `Cursor.extend(...)` made public (from `_extend`)
+  * `Cursor.raise_error(...)` replaces `_error` (now public)
+  * Improved wait/timeout behavior and state tracking
+* **CLI**:
+  * Subcommand name standardized to `index-rebuild` (was `index_rebuild`)
+  * Logging unified; progress reporting moved to logger-based updates
+* **Build/Tooling**:
+  * Replaced `setup.py`/`requirements.txt` with Poetry; consistent formatting (black) and linting (flake8, pylint)
+  * Updated supported Python versions; CI matrix adjusted
 
 Fixed
 ~~~~~
 
-* Fixed a potential "no-member" error of `RqlBoolOperatorQuery`
-* Fixed variety of quality issues in `ast` module
+* Binary response parsing in network layer (`encoder.py`, `net.py`)
+* Numerous linter and mypy findings across `ast`, `net`, and CLI modules
+* Circular import issues and import path clean-ups
+* Error propagation and context in async operations
+* Potential memory leaks in connection handling and cursors
 
 Removed
 ~~~~~~~
 
-* Errors are not re-exported as `__all__` for `rethinkdb`
-* Removed `Rql*` aliases for `Reql*` exceptions
-* Removed `auth_key` in favor of `password` in connection params
+* Python 2 support dropped completely
+* Legacy CLI scripts removed; replaced by Click-based `rethinkdb/cli/*`
+* Deprecated modules removed:
+  * `rethinkdb/backports/*` (SSL hostname matching backports)
+  * `rethinkdb/logger.py`, `rethinkdb/helpers.py`, `rethinkdb/docs.py`
+* Old dependencies and tooling removed (bandit, legacy CI scripts)
+* Travis CI replaced with GitHub Actions
+* `setup.py` and `requirements.txt` removed in favor of `pyproject.toml` and Poetry lockfile
+* Top-level re-export of errors via package `__all__` removed; import from `rethinkdb.errors` instead
+* `auth_key` parameter removed in favor of `password` for connections
+* `Rql*` exception aliases removed (use `Reql*`)
+
+Deprecated
+~~~~~~~~~~
+
+* `ReqlQuery.to_json_string()` is an alias for `to_json()` and will be removed in a future release
+
+Migration Guide
+~~~~~~~~~~~~~~
+
+For users upgrading from 2.4.x to 2.5.0:
+
+1. **Python**: Use Python 3.7+.
+2. **Imports**: Update imports for moved modules (e.g., utilities now in `rethinkdb.utils`).
+3. **Exceptions**: Replace `Rql*` with `Reql*`. Adjust error handling for `ReqlAuthError`/`ReqlTimeoutError` host/port validation.
+4. **Handshake**: If customizing JSON encoding/decoding during handshake, pass `json_encoder`/`json_decoder` to `HandshakeV1_0`.
+5. **CLI**: Use `index-rebuild` (hyphen), and the standardized flags listed above.
+6. **Connection/Cursor**: Use public `Connection.resume`, `Connection.stop`, `Cursor.extend`, and `Cursor.raise_error`.
+7. **Queries**: If relying on `optargs`, update to `kwargs`. Prefer `to_json()` over `to_json_string()`.
 
 .. EXAMPLE CHANGELOG ENTRY
 

CONTRIBUTING.rst

@@ -65,7 +65,7 @@ Get Started!
 
 Ready to contribute? Here's how to set up `rethinkdb`'s Python client for local development.
 
-As `step 0` make sure you have python 3.7+, [https://python-poetry.org/](poetry) and [https://pre-commit.com/](pre-commit) installed.
+As `step 0` make sure you have python 3.10+, [https://python-poetry.org/](poetry) and [https://pre-commit.com/](pre-commit) installed.
 
 1. Fork the `rethinkdb-python` repo on GitHub.
 2. Clone your fork locally::
@@ -116,7 +116,7 @@ Before you submit a pull request, check that it meets these guidelines:
 2. If the pull request adds functionality, the docs should be updated. Put
    your new functionality into a function with a docstring, and add the
    feature to the list in README.rst.
-3. The pull request should work for Python 3.7 and 3.8.
+3. The pull request should work for Python 3.10+.
 
 Releasing
 ---------

Makefile

@@ -88,10 +88,10 @@ clean-test: ## remove test and coverage artifacts
 docs: ## generate Sphinx HTML documentation, including API docs
 	rm -f docs/rethinkdb.rst
 	rm -f docs/modules.rst
-	poetry export --E all --dev -f requirements.txt > docs/requirements.txt
-	sphinx-apidoc -o docs/ rethinkdb
-	$(MAKE) -C docs clean
-	$(MAKE) -C docs html
+	poetry export -E all --dev -f requirements.txt > docs/requirements.txt
+	poetry run sphinx-apidoc -o docs/ rethinkdb
+	poetry run $(MAKE) -C docs clean
+	poetry run $(MAKE) -C docs html
 	$(BROWSER) docs/_build/html/index.html
 
 .PHONY: format

README.rst

@@ -19,20 +19,25 @@ can tell the database to continuously push updated query results to applications
 RethinkDB allows developers to build scalable realtime apps in a fraction of the time with
 less effort.
 
-Utility Tools
-============
-If you came here looking for an utility tool, this functionality has been dropped during the porting from python 2 to 3.
-Instead, you should look (and we suggest to use) https://github.com/BOOMfinity-Developers/GoThink
-
+Utility Scripts
+===============
+RethinkDB Python Client prodvices a set of utility scripts to help you manage your RethinkDB
+database.
+
+* `rethinkdb dump` / `rethinkdb-dump` - Dump a database to a file
+* `rethinkdb export` / `rethinkdb-export` - Export a table to a file
+* `rethinkdb import` / `rethinkdb-import` - Import a table from a file
+* `rethinkdb index-rebuild` / `rethinkdb-index-rebuild` - Rebuild all indexes
+* `rethinkdb repl` / `rethinkdb-repl` - Start a REPL session
+* `rethinkdb restore` / `rethinkdb-restore` - Restore a database from a file
 
 Installation
 ============
 
 RethinkDB's Python Client can be installed by running ``pip install rethinkdb`` and it requires
-Python 3.7.0+ to run. This is the preferred method to install RethinkDB Python client, as it
-will always install the most recent stable release. If you don't have `pip`_
-installed, this `Python installation guide`_ can guide
-you through the process.
+Python 3.10+ to run. This is the preferred method to install RethinkDB Python client, as it will
+always install the most recent stable release. If you don't have `pip`_ installed, this
+`Python installation guide`_ can guide you through the process.
 
 .. _pip: https://pip.pypa.io
 .. _Python installation guide: http://docs.python-guide.org/en/latest/starting/installation/