From 3125bda012319ee8d8282306f1f719cac281f5ef Mon Sep 17 00:00:00 2001 From: Iris Date: Tue, 17 Nov 2026 16:50:26 -0800 Subject: [PATCH] PYTHON-6264 Enable ruff rules D205, D400, and D401 --- .evergreen/scripts/generate_config.py | 2 +- .evergreen/scripts/resync_all_specs.py | 6 +- .evergreen/scripts/setup_uv.py | 2 +- .evergreen/scripts/test_generate_config.py | 82 ++++++++++++--------- .evergreen/scripts/test_setup_uv.py | 4 +- bson/__init__.py | 13 ++-- bson/_helpers.py | 5 +- bson/binary.py | 4 +- bson/codec_options.py | 32 +++++--- bson/datetime_ms.py | 2 +- bson/decimal128.py | 17 ++--- bson/int64.py | 2 +- bson/json_util.py | 19 +++-- bson/objectid.py | 15 ++-- bson/raw_bson.py | 5 +- bson/son.py | 6 +- bson/timestamp.py | 4 +- bson/typings.py | 2 +- fuzz/build_corpus.py | 12 ++- fuzz/fuzz_shared.py | 2 +- gridfs/asynchronous/grid_file.py | 80 +++++++++----------- gridfs/errors.py | 2 +- gridfs/synchronous/grid_file.py | 80 +++++++++----------- pymongo/_asyncio_lock.py | 14 ++-- pymongo/_csot.py | 5 +- pymongo/asynchronous/aggregation.py | 6 +- pymongo/asynchronous/auth.py | 2 +- pymongo/asynchronous/change_stream.py | 5 +- pymongo/asynchronous/client_bulk.py | 8 +- pymongo/asynchronous/collection.py | 68 +++++++++-------- pymongo/asynchronous/command_cursor.py | 3 +- pymongo/asynchronous/command_runner.py | 5 +- pymongo/asynchronous/cursor.py | 16 ++-- pymongo/asynchronous/cursor_base.py | 4 +- pymongo/asynchronous/database.py | 21 +++--- pymongo/asynchronous/encryption.py | 4 +- pymongo/asynchronous/mongo_client.py | 47 ++++++------ pymongo/asynchronous/monitor.py | 4 +- pymongo/asynchronous/pool.py | 19 ++--- pymongo/asynchronous/topology.py | 9 +-- pymongo/bulk_shared.py | 9 +-- pymongo/change_stream_shared.py | 14 ++-- pymongo/client_session_shared.py | 32 ++++---- pymongo/collation.py | 22 ++---- pymongo/common.py | 74 ++++++++----------- pymongo/cursor_shared.py | 77 +++++++++---------- pymongo/encryption_shared.py | 11 ++- pymongo/errors.py | 33 +++++---- pymongo/helpers_shared.py | 6 +- pymongo/lock.py | 11 +-- pymongo/message.py | 57 ++++++-------- pymongo/mongo_client_shared.py | 19 +++-- pymongo/monitoring.py | 86 +++++++--------------- pymongo/network_layer.py | 11 ++- pymongo/ocsp_support.py | 2 +- pymongo/operations.py | 6 +- pymongo/pool_options.py | 30 ++++---- pymongo/pool_shared.py | 11 ++- pymongo/pyopenssl_context.py | 37 +++++----- pymongo/read_concern.py | 6 +- pymongo/read_preferences.py | 14 ++-- pymongo/response.py | 5 +- pymongo/results.py | 25 ++++--- pymongo/saslprep.py | 4 +- pymongo/server_api.py | 2 +- pymongo/settings_shared.py | 4 +- pymongo/socket_checker.py | 2 +- pymongo/synchronous/aggregation.py | 6 +- pymongo/synchronous/auth.py | 2 +- pymongo/synchronous/change_stream.py | 5 +- pymongo/synchronous/client_bulk.py | 8 +- pymongo/synchronous/collection.py | 68 +++++++++-------- pymongo/synchronous/command_cursor.py | 3 +- pymongo/synchronous/command_runner.py | 5 +- pymongo/synchronous/cursor.py | 16 ++-- pymongo/synchronous/cursor_base.py | 4 +- pymongo/synchronous/database.py | 21 +++--- pymongo/synchronous/encryption.py | 4 +- pymongo/synchronous/mongo_client.py | 47 ++++++------ pymongo/synchronous/monitor.py | 4 +- pymongo/synchronous/pool.py | 19 ++--- pymongo/synchronous/topology.py | 9 +-- pymongo/topology_description.py | 15 ++-- pymongo/topology_shared.py | 7 +- pymongo/typings.py | 7 +- pymongo/uri_parser_shared.py | 36 ++++----- pymongo/write_concern.py | 8 +- pyproject.toml | 3 + test/__init__.py | 32 ++++---- test/asynchronous/__init__.py | 32 ++++---- test/asynchronous/pymongo_mocks.py | 2 +- test/asynchronous/test_change_stream.py | 41 +++++------ test/asynchronous/test_client.py | 5 +- test/asynchronous/test_dns.py | 4 +- test/asynchronous/test_examples.py | 3 +- test/asynchronous/test_hello_latched.py | 14 ++-- test/asynchronous/test_locks.py | 2 +- test/asynchronous/test_monitor.py | 6 +- test/asynchronous/test_pooling.py | 11 +-- test/asynchronous/test_read_preferences.py | 7 +- test/asynchronous/test_retryable_writes.py | 10 +-- test/asynchronous/test_srv_polling.py | 13 ++-- test/asynchronous/unified_format.py | 15 ++-- test/asynchronous/utils.py | 19 +++-- test/asynchronous/utils_spec_runner.py | 4 +- test/helpers_shared.py | 2 +- test/lambda/mongodb/app.py | 7 +- test/mockupdb/test_cursor.py | 2 +- test/mockupdb/test_slave_okay_sharded.py | 3 +- test/mockupdb/test_slave_okay_single.py | 3 +- test/mod_wsgi_test/mod_wsgi_test.py | 2 +- test/pymongo_mocks.py | 2 +- test/test_bson.py | 9 ++- test/test_change_stream.py | 41 +++++------ test/test_client.py | 5 +- test/test_dns.py | 4 +- test/test_examples.py | 3 +- test/test_hello_latched.py | 14 ++-- test/test_kms_connect.py | 18 ++--- test/test_monitor.py | 6 +- test/test_pooling.py | 11 +-- test/test_raw_bson_shared.py | 5 +- test/test_read_preferences.py | 7 +- test/test_retryable_writes.py | 10 +-- test/test_son.py | 6 +- test/test_srv_polling.py | 13 ++-- test/test_typing.py | 5 +- test/test_typing_strict.py | 2 +- test/test_uri_spec.py | 6 +- test/unified_format.py | 15 ++-- test/unified_format_shared.py | 12 +-- test/utils.py | 19 +++-- test/utils_shared.py | 27 ++++--- test/utils_spec_runner.py | 4 +- tools/ensure_future_annotations_import.py | 2 +- 135 files changed, 1016 insertions(+), 1014 deletions(-) diff --git a/.evergreen/scripts/generate_config.py b/.evergreen/scripts/generate_config.py index 58299f7f33..add16f1ad4 100644 --- a/.evergreen/scripts/generate_config.py +++ b/.evergreen/scripts/generate_config.py @@ -843,7 +843,7 @@ def create_test_non_standard_tasks(): def create_test_standard_auth_tasks(): - """We only use auth on sharded clusters""" + """We only use auth on sharded clusters.""" tasks = [] task_combos = set() # Rotate through the CPython and MongoDB versions diff --git a/.evergreen/scripts/resync_all_specs.py b/.evergreen/scripts/resync_all_specs.py index 52c276b8b8..d7d5ced2e8 100644 --- a/.evergreen/scripts/resync_all_specs.py +++ b/.evergreen/scripts/resync_all_specs.py @@ -11,7 +11,7 @@ def resync_specs(directory: pathlib.Path, errored: dict[str, str]) -> None: - """Actually sync the specs""" + """Actually sync the specs.""" print("Beginning to sync specs") for spec in os.scandir(directory): if not spec.is_dir(): @@ -67,7 +67,7 @@ def apply_patches(errored): def check_new_spec_directories(directory: pathlib.Path) -> list[str]: - """Check to see if there are any directories in the spec repo that don't exist in pymongo/test""" + """Check for spec repo directories that don't exist in pymongo/test.""" spec_dir = pathlib.Path(os.environ["MDB_SPECS"]) / "source" spec_set = { entry.name.replace("-", "_") @@ -96,7 +96,7 @@ def check_new_spec_directories(directory: pathlib.Path) -> list[str]: def write_summary(errored: dict[str, str], new: list[str], filename: str | None) -> None: - """Generate the PR description""" + """Generate the PR description.""" pr_body = "" # Avoid shell=True and complex pipes by using Python to process git output process = subprocess.run( diff --git a/.evergreen/scripts/setup_uv.py b/.evergreen/scripts/setup_uv.py index 76d0d4e9b1..a7d3832a7a 100755 --- a/.evergreen/scripts/setup_uv.py +++ b/.evergreen/scripts/setup_uv.py @@ -71,7 +71,7 @@ def _install_uv_astral() -> None: def _uv_exe() -> str: - """The uv binary name on this platform.""" + """Return the uv binary name on this platform.""" return "uv.exe" if os.name == "nt" else "uv" diff --git a/.evergreen/scripts/test_generate_config.py b/.evergreen/scripts/test_generate_config.py index 67f9e8a639..83f43c31b7 100644 --- a/.evergreen/scripts/test_generate_config.py +++ b/.evergreen/scripts/test_generate_config.py @@ -45,8 +45,10 @@ def all_variants(): def variant_selects(variant, task): - """Whether the variant's task selectors match the task: "." selects a - tag, "!" negates the token that follows, a bare token names a task. + """Whether the variant's task selectors match the task. + + "." selects a tag, "!" negates the token that follows, a bare token + names a task. """ tags = task.tags or [] for ref in variant.tasks: @@ -74,9 +76,11 @@ def variant_selects(variant, task): def test_pr_tasks_pin_max_version(): - """Task-level pins: pr tasks pin MAX_VERSION (the "latest" nightly is - unstable); the explicit 4.4 min-deps pin is the exception. Variant-merged - pins are checked by test_pr_tasks_effectively_pin_max_version. + """Task-level pins: pr tasks pin MAX_VERSION. + + The "latest" nightly is unstable; the explicit 4.4 min-deps pin is the + exception. Variant-merged pins are checked by + test_pr_tasks_effectively_pin_max_version. """ offenders = [ (task.name, task_vars(task).get("VERSION")) @@ -90,10 +94,11 @@ def test_pr_tasks_pin_max_version(): def test_pr_tasks_effectively_pin_max_version(): - """Effective pins: a pr task without its own VERSION var inherits the - selecting variant's version, so every pr task that runs a server must - resolve to MAX_VERSION once variant expansions merge in. The explicit - 4.4 min-deps pin is the exception. + """Effective pins: every pr task that runs a server resolves to MAX_VERSION. + + A pr task without its own VERSION var inherits the selecting variant's + version once variant expansions merge in. The explicit 4.4 min-deps + pin is the exception. """ tasks = [task for task in all_tasks() if "pr" in (task.tags or [])] offenders = [] @@ -115,12 +120,14 @@ def test_pr_tasks_effectively_pin_max_version(): def test_server_version_pr_tasks_selected_once(): - """A pr server-version task must be selected only by the variant running - the server version it pins. The expected family comes from - create_server_version_variants(), not from the selections: a variant - missing its PR selector would otherwise drop from both sides and the - comparison would pass. Variants outside the family must not select these - tasks (the sanitizer variant pins MAX_VERSION for its own mongod). + """A pr server-version task must be selected only by its matching variant. + + The variant must run the server version the task pins. The expected + family comes from create_server_version_variants(), not from the + selections: a variant missing its PR selector would otherwise drop + from both sides and the comparison would pass. Variants outside the + family must not select these tasks (the sanitizer variant pins + MAX_VERSION for its own mongod). """ sv_tasks = [task for task in pr_tasks() if "server-version" in (task.tags or [])] sv_variants = generate_config.create_server_version_variants() @@ -141,8 +148,10 @@ def test_server_version_pr_tasks_selected_once(): def test_pr_tasks_cover_version_boundaries(): - """PRs test the server version boundaries: the newest numbered server - with every Python boundary, the min server with its min-Python floor. + """PRs test the server version boundaries. + + The newest numbered server runs with every Python boundary, the min + server with its min-Python floor. """ for version, pythons in ( ( @@ -164,8 +173,9 @@ def test_pr_tasks_cover_version_boundaries(): def test_server_version_rotated_tasks_keep_coverage(): - """Per-commit coverage for this family rides the rotated boundary-Python - tasks, not the pr tasks (which run only on MAX_VERSION). + """Per-commit coverage for this family rides the rotated boundary-Python tasks. + + Not the pr tasks, which run only on MAX_VERSION. """ family = [task for task in all_tasks() if "server-version" in (task.tags or [])] cov = [task for task in family if task_vars(task).get("COVERAGE") == "1"] @@ -198,9 +208,10 @@ def test_pr_min_deps_tasks_also_run_coverage(): def test_standard_family_pr_budget(): - """Patch-build PR budget: at most 5 pr-tagged test-standard tasks (the - pre-pin baseline), at most 3 on Python 3.14+ (the ubuntu22 compression - filter). + """Patch-build PR budget for test-standard pr tasks. + + At most 5 (the pre-pin baseline), at most 3 on Python 3.14+ (the + ubuntu22 compression filter). """ tasks = [task for task in pr_tasks() if "test-standard" in (task.tags or [])] assert len(tasks) <= 5, f"too many test-standard PR tasks: {[t.name for t in tasks]}" @@ -216,8 +227,9 @@ def test_standard_family_pr_budget(): def test_pr_tasks_run_coverage(): - """Pr tasks that pin a server version run with COVERAGE=1; no-cov - companions and infrastructure tasks (no VERSION) are exempt. + """Pr tasks that pin a server version run with COVERAGE=1. + + No-cov companions and infrastructure tasks (no VERSION) are exempt. """ offenders = [ task.name @@ -230,8 +242,9 @@ def test_pr_tasks_run_coverage(): def test_rotated_tasks_keep_nightly_coverage(): - """Batch coverage rides the rotation independently of the pr tasks: - rotated "latest" tasks and max-Python auth-aws tasks keep COVERAGE=1 + """Batch coverage rides the rotation independently of the pr tasks. + + Rotated "latest" tasks and max-Python auth-aws tasks keep COVERAGE=1 (min-deps excepted). """ offenders = [] @@ -279,8 +292,9 @@ def test_rotated_tasks_keep_nightly_coverage(): def test_non_standard_cov_tasks_have_no_cov_companions(): - """Each non-standard coverage task also emits a no-cov companion, so the - macOS/Win64 encryption variants (which filter .cov) have a task to + """Each non-standard coverage task also emits a no-cov companion. + + The macOS/Win64 encryption variants (which filter .cov) have a task to activate in patch builds. """ no_cov = {task.name for task in all_tasks() if "test-non-standard-no-cov" in (task.tags or [])} @@ -293,7 +307,8 @@ def test_non_standard_cov_tasks_have_no_cov_companions(): def test_load_balancer_marker_selection(monkeypatch): - """The load balancer tasks select the load_balancer marker explicitly: + """The load balancer tasks select the load_balancer marker explicitly. + pytest_conf.py only grants the implicit default markers to unmarked tests, so the marker expression must add the full default suite alongside the load balancer tests (PYTHON-6262). @@ -311,10 +326,11 @@ def test_load_balancer_marker_selection(monkeypatch): def test_sanitizer_task_wiring(): - """PYTHON-6048: one pr-tagged sanitizer task, selected by exactly one - variant that pins MAX_VERSION and runs on a large host for ASan's memory - headroom. VERSION stays off the task so it is exempt - from the pr COVERAGE rule (coverage under ASan is not useful). + """PYTHON-6048: one pr-tagged sanitizer task, selected by exactly one variant. + + The variant pins MAX_VERSION and runs on a large host for ASan's + memory headroom. VERSION stays off the task so it is exempt from the + pr COVERAGE rule (coverage under ASan is not useful). """ tasks = [task for task in all_tasks() if "sanitizer" in (task.tags or [])] assert len(tasks) == 1 diff --git a/.evergreen/scripts/test_setup_uv.py b/.evergreen/scripts/test_setup_uv.py index 1fd49a4bb2..d44bfceb8b 100644 --- a/.evergreen/scripts/test_setup_uv.py +++ b/.evergreen/scripts/test_setup_uv.py @@ -181,7 +181,7 @@ def run_setup_uv_python( @pytest.fixture def stub_env(tmp_path): - """A stub uv bin dir and its invocation log; returns (log, env-overrides).""" + """Return a stub uv bin dir and its invocation log as (log, env-overrides).""" log = tmp_path / "uv-stub.log" write_stub_uv(tmp_path / "stub-bin") return log, {"PATH": f"{tmp_path / 'stub-bin'}:/usr/bin:/bin", "UV_STUB_LOG": str(log)} @@ -396,7 +396,7 @@ def test_same_path_maps_cygwin_forms(): @pytest.fixture def project(tmp_path): - """A fake project tree: a pyproject.toml plus a copy of setup_uv.py.""" + """Create a fake project tree: a pyproject.toml plus a copy of setup_uv.py.""" proj = tmp_path / "proj" scripts = proj / ".evergreen" / "scripts" scripts.mkdir(parents=True) diff --git a/bson/__init__.py b/bson/__init__.py index 4fc30517aa..5f2689659a 100644 --- a/bson/__init__.py +++ b/bson/__init__.py @@ -676,8 +676,9 @@ def _bson_to_dict(data: Any, opts: CodecOptions[_DocumentType]) -> _DocumentType def gen_list_name() -> Generator[bytes, None, None]: - r"""Generate "keys" for encoded lists in the sequence - b"0\x00", b"1\x00", b"2\x00", ... + r"""Generate "keys" for encoded lists. + + The keys are the sequence b"0\x00", b"1\x00", b"2\x00", ... The first 1000 keys are returned from a pre-built cache. All subsequent keys are generated on the fly. @@ -1273,10 +1274,10 @@ def _convert_raw_document_lists_to_streams(document: Any) -> None: def _decode_all_selective( data: Any, codec_options: CodecOptions[_DocumentType], fields: Any ) -> list[_DocumentType]: - """Decode BSON data to a single document while using user-provided - custom decoding logic. + """Decode BSON data to a single document with custom decoding logic. - `data` must be a string representing a valid, BSON-encoded document. + The decoding logic is user-provided. `data` must be a string representing + a valid, BSON-encoded document. :param data: BSON data :param codec_options: An instance of @@ -1495,7 +1496,7 @@ def decode( # type:ignore[override] def has_c() -> bool: - """Is the C extension installed?""" + """Return True if the C extension is installed.""" return _USE_C diff --git a/bson/_helpers.py b/bson/_helpers.py index 596965a138..ad3ab04230 100644 --- a/bson/_helpers.py +++ b/bson/_helpers.py @@ -12,8 +12,9 @@ # See the License for the specific language governing permissions and # limitations under the License. -"""Setstate and getstate functions for objects with __slots__, allowing -compatibility with default pickling protocol +"""Setstate and getstate functions for objects with __slots__. + +These allow compatibility with the default pickling protocol. """ from __future__ import annotations diff --git a/bson/binary.py b/bson/binary.py index 54fc152d47..1eec953f74 100644 --- a/bson/binary.py +++ b/bson/binary.py @@ -233,6 +233,7 @@ class BinaryVectorDtype(Enum): class BinaryVector: """Vector of numbers along with metadata for binary interoperability. + .. versionadded:: 4.10 """ @@ -244,7 +245,8 @@ def __init__( dtype: BinaryVectorDtype, padding: int = 0, ): - """ + """Create a new BinaryVector. + :param data: Sequence of numbers representing the mathematical vector. :param dtype: The data type stored in binary :param padding: The number of bits in the final byte that are to be ignored diff --git a/bson/codec_options.py b/bson/codec_options.py index a7064804a5..6d01c91e80 100644 --- a/bson/codec_options.py +++ b/bson/codec_options.py @@ -50,8 +50,10 @@ def _raw_document_class(document_class: Any) -> bool: class TypeEncoder(abc.ABC): - """Base class for defining type codec classes which describe how a - custom type can be transformed to one of the types BSON understands. + """Base class for defining type codec classes. + + A type codec describes how a custom type can be transformed to one of + the types BSON understands. Codec classes must implement the ``python_type`` attribute, and the ``transform_python`` method to support encoding. @@ -69,8 +71,10 @@ def transform_python(self, value: Any) -> Any: class TypeDecoder(abc.ABC): - """Base class for defining type codec classes which describe how a - BSON type can be transformed to a custom type. + """Base class for defining type codec classes. + + A type codec describes how a BSON type can be transformed to a custom + type. Codec classes must implement the ``bson_type`` attribute, and the ``transform_bson`` method to support decoding. @@ -88,9 +92,10 @@ def transform_bson(self, value: Any) -> Any: class TypeCodec(TypeEncoder, TypeDecoder): - """Base class for defining type codec classes which describe how a - custom type can be transformed to/from one of the types :mod:`bson` - can already encode/decode. + """Base class for defining type codec classes. + + A type codec describes how a custom type can be transformed to/from one + of the types :mod:`bson` can already encode/decode. Codec classes must implement the ``python_type`` attribute, and the ``transform_python`` method to support encoding, as well as the @@ -106,9 +111,10 @@ class TypeCodec(TypeEncoder, TypeDecoder): class TypeRegistry: - """Encapsulates type codecs used in encoding and / or decoding BSON, as - well as the fallback encoder. Type registries cannot be modified after - instantiation. + """Encapsulates type codecs used in encoding and / or decoding BSON. + + The type registry also holds the fallback encoder. Type registries + cannot be modified after instantiation. ``TypeRegistry`` can be initialized with an iterable of type codecs, and a callable for the fallback encoder:: @@ -285,7 +291,7 @@ class CodecOptions(_BaseCodecOptions): """Encapsulates options used encoding and / or decoding BSON.""" def __init__(self, *args, **kwargs): - r"""Encapsulates options used encoding and / or decoding BSON. + r"""Encapsulate options used encoding and / or decoding BSON. The `document_class` option is used to define a custom type for use decoding BSON documents. Access to the underlying raw BSON bytes for @@ -452,7 +458,9 @@ def __repr__(self) -> str: return f"{self.__class__.__name__}({self._arguments_repr()})" def with_options(self, **kwargs: Any) -> CodecOptions: - """Make a copy of this CodecOptions, overriding some options:: + """Make a copy of this CodecOptions, overriding some options. + + For example:: >>> from bson.codec_options import DEFAULT_CODEC_OPTIONS >>> DEFAULT_CODEC_OPTIONS.tz_aware diff --git a/bson/datetime_ms.py b/bson/datetime_ms.py index 7fe5312445..861d39afad 100644 --- a/bson/datetime_ms.py +++ b/bson/datetime_ms.py @@ -42,7 +42,7 @@ class DatetimeMS: __slots__ = ("_value",) def __init__(self, value: int | datetime.datetime): - """Represents a BSON UTC datetime. + """Represent a BSON UTC datetime. BSON UTC datetimes are defined as an int64 of milliseconds since the Unix epoch. The principal use of DatetimeMS is to represent diff --git a/bson/decimal128.py b/bson/decimal128.py index 1e62d1767b..70dea15651 100644 --- a/bson/decimal128.py +++ b/bson/decimal128.py @@ -101,16 +101,14 @@ def transform_bson(self, value: Any) -> decimal.Decimal: def create_decimal128_context() -> decimal.Context: - """Returns an instance of :class:`decimal.Context` appropriate - for working with IEEE-754 128-bit decimal floating point values. - """ + """Return a :class:`decimal.Context` for IEEE-754 128-bit decimal floats.""" opts = _CTX_OPTIONS.copy() opts["traps"] = [] return decimal.Context(**opts) # type: ignore def _decimal_to_128(value: _VALUE_OPTIONS) -> tuple[int, int]: - """Converts a decimal.Decimal to BID (high bits, low bits). + """Convert a decimal.Decimal to BID (high bits, low bits). :param value: An instance of decimal.Decimal """ @@ -158,7 +156,9 @@ def _decimal_to_128(value: _VALUE_OPTIONS) -> tuple[int, int]: class Decimal128: - """BSON Decimal128 type:: + """BSON Decimal128 type. + + :: >>> Decimal128(Decimal("0.0005")) Decimal128('0.0005') @@ -270,9 +270,7 @@ def __init__(self, value: _VALUE_OPTIONS) -> None: raise TypeError(f"Cannot convert {value!r} to Decimal128") def to_decimal(self) -> decimal.Decimal: - """Returns an instance of :class:`decimal.Decimal` for this - :class:`Decimal128`. - """ + """Return an instance of :class:`decimal.Decimal` for this :class:`Decimal128`.""" high = self.__high low = self.__low sign = 1 if (high & _SIGN) else 0 @@ -317,8 +315,7 @@ def to_decimal(self) -> decimal.Decimal: @classmethod def from_bid(cls: type[Decimal128], value: bytes) -> Decimal128: - """Create an instance of :class:`Decimal128` from Binary Integer - Decimal string. + """Create an instance of :class:`Decimal128` from BID string. :param value: 16 byte string (128-bit IEEE 754-2008 decimal floating point in Binary Integer Decimal (BID) format). diff --git a/bson/int64.py b/bson/int64.py index a1a77b5b73..9bc8198ba5 100644 --- a/bson/int64.py +++ b/bson/int64.py @@ -12,7 +12,7 @@ # See the License for the specific language governing permissions and # limitations under the License. -"""A BSON wrapper for long (int in python3)""" +"""A BSON wrapper for long (int in python3).""" from __future__ import annotations diff --git a/bson/json_util.py b/bson/json_util.py index 82c0653934..f22ba9863d 100644 --- a/bson/json_util.py +++ b/bson/json_util.py @@ -245,7 +245,7 @@ class JSONOptions(_BASE_CLASS): document_class: type[MutableMapping[str, Any]] def __init__(self, *args: Any, **kwargs: Any): - """Encapsulates JSON options for :func:`dumps` and :func:`loads`. + """Encapsulate JSON options for :func:`dumps` and :func:`loads`. :param strict_number_long: If ``True``, :class:`~bson.int64.Int64` objects are encoded to MongoDB Extended JSON's *Strict mode* type @@ -374,8 +374,9 @@ def _arguments_repr(self) -> str: ) def with_options(self, **kwargs: Any) -> JSONOptions: - """ - Make a copy of this JSONOptions, overriding some options:: + """Make a copy of this JSONOptions, overriding some options. + + For example:: >>> from bson.json_util import CANONICAL_JSON_OPTIONS >>> CANONICAL_JSON_OPTIONS.tz_aware @@ -431,9 +432,9 @@ def with_options(self, **kwargs: Any) -> JSONOptions: def dumps(obj: Any, *args: Any, **kwargs: Any) -> str: - """Helper function that wraps :func:`json.dumps`. + """Wrap :func:`json.dumps` to handle BSON types. - Recursive function that handles all BSON types including + Recursively handles all BSON types including :class:`~bson.binary.Binary` and :class:`~bson.code.Code`. :param json_options: A :class:`JSONOptions` instance used to modify the @@ -452,7 +453,7 @@ def dumps(obj: Any, *args: Any, **kwargs: Any) -> str: def loads(s: str | bytes | bytearray, *args: Any, **kwargs: Any) -> Any: - """Helper function that wraps :func:`json.loads`. + """Wrap :func:`json.loads` to handle BSON types. Automatically passes the object_hook for BSON type conversion. @@ -486,9 +487,7 @@ def loads(s: str | bytes | bytearray, *args: Any, **kwargs: Any) -> Any: def _json_convert(obj: Any, json_options: JSONOptions = DEFAULT_JSON_OPTIONS) -> Any: - """Recursive helper method that converts BSON types so they can be - converted into json. - """ + """Recursive helper method that converts BSON types so they can be converted into json.""" if hasattr(obj, "items"): return {k: _json_convert(v, json_options) for k, v in obj.items()} elif hasattr(obj, "__iter__") and not isinstance(obj, (str, bytes)): @@ -1068,7 +1067,7 @@ def _get_dbref_size(obj: DBRef) -> int: def get_size(obj: Any, max_size: int, current_size: int = 0) -> int: - """Recursively finds size of objects""" + """Recursively find the size of objects.""" if current_size >= max_size: return current_size diff --git a/bson/objectid.py b/bson/objectid.py index d4c9dce545..7b3fac7748 100644 --- a/bson/objectid.py +++ b/bson/objectid.py @@ -158,7 +158,7 @@ def from_datetime(cls: type[ObjectId], generation_time: datetime.datetime) -> Ob @classmethod def is_valid(cls: type[ObjectId], oid: Any) -> bool: - """Checks if a `oid` string is valid or not. + """Check if a `oid` string is valid or not. :param oid: the object id to validate @@ -189,24 +189,23 @@ def binary(self) -> bytes: @property def generation_time(self) -> datetime.datetime: - """A :class:`datetime.datetime` instance representing the time of - generation for this :class:`ObjectId`. + """A :class:`datetime.datetime` instance for this :class:`ObjectId`. - The :class:`datetime.datetime` is timezone aware, and - represents the generation time in UTC. It is precise to the - second. + The :class:`datetime.datetime` is timezone aware, and represents + the generation time in UTC. It is precise to the second. """ timestamp = _UNPACK_INT(self.__id[0:4])[0] return datetime.datetime.fromtimestamp(timestamp, utc) def __getstate__(self) -> bytes: """Return value of object for pickling. - needed explicitly because __slots__() defined. + + Needed explicitly because ``__slots__`` is defined. """ return self.__id def __setstate__(self, value: Any) -> None: - """Explicit state set from pickling""" + """Explicit state set from pickling.""" # Provide backwards compatibility with OIDs # pickled with pymongo-1.9 or older. if isinstance(value, dict): diff --git a/bson/raw_bson.py b/bson/raw_bson.py index 2bc91dfa13..5d76fd8f04 100644 --- a/bson/raw_bson.py +++ b/bson/raw_bson.py @@ -78,8 +78,7 @@ def _inflate_bson( class RawBSONDocument(Mapping[str, Any]): - """Representation for a MongoDB document that provides access to the raw - BSON bytes that compose it. + """Representation of a MongoDB document that exposes its raw BSON bytes. Only when a field is accessed or modified within the document does RawBSONDocument decode its bytes. @@ -94,7 +93,7 @@ def __init__( bson_bytes: bytes | memoryview, codec_options: CodecOptions[RawBSONDocument] | None = None, ) -> None: - """Create a new :class:`RawBSONDocument` + """Create a new :class:`RawBSONDocument`. :class:`RawBSONDocument` is a representation of a BSON document that provides access to the underlying raw BSON bytes. Only when a field is diff --git a/bson/son.py b/bson/son.py index 2dce98bf4b..1a204e5106 100644 --- a/bson/son.py +++ b/bson/son.py @@ -176,8 +176,10 @@ def get( # type: ignore[override] return default def __eq__(self, other: object) -> bool: - """Comparison to another SON is order-sensitive while comparison to a - regular dictionary is order-insensitive. + """Compare this SON to another object. + + Comparison to another SON is order-sensitive while comparison to a regular + dictionary is order-insensitive. """ if isinstance(other, SON): return len(self) == len(other) and list(self.items()) == list(other.items()) diff --git a/bson/timestamp.py b/bson/timestamp.py index c346623604..8793ef4bcb 100644 --- a/bson/timestamp.py +++ b/bson/timestamp.py @@ -116,9 +116,9 @@ def __repr__(self) -> str: return f"Timestamp({self.__time}, {self.__inc})" def as_datetime(self) -> datetime.datetime: - """Return a :class:`~datetime.datetime` instance corresponding - to the time portion of this :class:`Timestamp`. + """Return a :class:`~datetime.datetime` for this :class:`Timestamp`. + The datetime corresponds to the time portion of this timestamp. The returned datetime's timezone is UTC. """ return datetime.datetime.fromtimestamp(self.__time, utc) diff --git a/bson/typings.py b/bson/typings.py index 593cf2c73d..1d89a51d6d 100644 --- a/bson/typings.py +++ b/bson/typings.py @@ -12,7 +12,7 @@ # See the License for the specific language governing permissions and # limitations under the License. -"""Type aliases used by bson""" +"""Type aliases used by bson.""" from __future__ import annotations diff --git a/fuzz/build_corpus.py b/fuzz/build_corpus.py index 4af9bde925..b0452524d3 100755 --- a/fuzz/build_corpus.py +++ b/fuzz/build_corpus.py @@ -1,7 +1,9 @@ #!/usr/bin/env python3 """ -OSS-Fuzz seed corpus builder for BSON fuzzing, mirroring the Go driver's -(mongodb/mongo-go-driver) internal/cmd/build-oss-fuzz-corpus/main.go. +OSS-Fuzz seed corpus builder for BSON fuzzing. + +Mirrors the Go driver's (mongodb/mongo-go-driver) +internal/cmd/build-oss-fuzz-corpus/main.go. Converts the valid cases in the vendored BSON spec corpus (test/bson_corpus/ by default) to raw BSON bytes and packages them into a ZIP, plus synthesized @@ -143,8 +145,10 @@ def seed_boundary_documents(zw: zipfile.ZipFile) -> None: def seed_large_document(zw: zipfile.ZipFile) -> None: - """Seed one ~500 KB document; without it, libFuzzer's max_len default - keeps mutation below the size where large-input paths live. + """Seed one ~500 KB document. + + Without it, libFuzzer's max_len default keeps mutation below the size + where large-input paths live. """ doc = { "long_string": "a" * (256 * 1024), diff --git a/fuzz/fuzz_shared.py b/fuzz/fuzz_shared.py index 255cc9a004..f4cde8aaae 100755 --- a/fuzz/fuzz_shared.py +++ b/fuzz/fuzz_shared.py @@ -45,7 +45,7 @@ def load_pure_python_bson(): def normalize(obj: object) -> object: - """Comparable form of a decoded document. + """Return a comparable form of a decoded document. The two bson handles are separate module instances, so bson type classes (ObjectId, Timestamp, ...) never compare equal across handles. Reduce diff --git a/gridfs/asynchronous/grid_file.py b/gridfs/asynchronous/grid_file.py index b601b8338b..ef55d0c048 100644 --- a/gridfs/asynchronous/grid_file.py +++ b/gridfs/asynchronous/grid_file.py @@ -246,9 +246,9 @@ async def get_last_version( session: AsyncClientSession | None = None, **kwargs: Any, ) -> AsyncGridOut: - """Get the most recent version of a file in GridFS by ``"filename"`` - or metadata fields. + """Get the most recent version of a file in GridFS. + The file is matched by ``"filename"`` or metadata fields. Equivalent to calling :meth:`get_version` with the default `version` (``-1``). @@ -292,8 +292,7 @@ async def delete(self, file_id: Any, session: AsyncClientSession | None = None) await self._chunks.delete_many({"files_id": {"$eq": file_id}}, session=session) async def list(self, session: AsyncClientSession | None = None) -> list[str]: - """List the names of all files stored in this instance of - :class:`GridFS`. + """List the names of all files stored in this instance of :class:`GridFS`. :param session: a :class:`~pymongo.client_session.AsyncClientSession` @@ -539,8 +538,7 @@ def open_upload_stream( metadata: Mapping[str, Any] | None = None, session: AsyncClientSession | None = None, ) -> AsyncGridIn: - """Opens a Stream that the application can write the contents of the - file to. + """Open a Stream that the application can write the contents of the file to. The user must specify the filename, and can choose to add any additional information in the metadata field of the file document or @@ -594,8 +592,7 @@ def open_upload_stream_with_id( metadata: Mapping[str, Any] | None = None, session: AsyncClientSession | None = None, ) -> AsyncGridIn: - """Opens a Stream that the application can write the contents of the - file to. + """Open a Stream that the application can write the contents of the file to. The user must specify the file id and filename, and can choose to add any additional information in the metadata field of the file document @@ -655,7 +652,7 @@ async def upload_from_stream( metadata: Mapping[str, Any] | None = None, session: AsyncClientSession | None = None, ) -> ObjectId: - """Uploads a user file to a GridFS bucket. + """Upload a user file to a GridFS bucket. Reads the contents of the user file from `source` and uploads it to the file `filename`. Source can be a string or file-like object. @@ -706,7 +703,7 @@ async def upload_from_stream_with_id( metadata: Mapping[str, Any] | None = None, session: AsyncClientSession | None = None, ) -> None: - """Uploads a user file to a GridFS bucket with a custom file id. + """Upload a user file to a GridFS bucket with a custom file id. Reads the contents of the user file from `source` and uploads it to the file `filename`. Source can be a string or file-like object. @@ -749,8 +746,7 @@ async def upload_from_stream_with_id( async def open_download_stream( self, file_id: Any, session: AsyncClientSession | None = None ) -> AsyncGridOut: - """Opens a Stream from which the application can read the contents of - the stored file specified by file_id. + """Open a Stream from which the application can read the stored file specified by file_id. For example:: @@ -782,8 +778,7 @@ async def open_download_stream( async def download_to_stream( self, file_id: Any, destination: Any, session: AsyncClientSession | None = None ) -> None: - """Downloads the contents of the stored file specified by file_id and - writes the contents to `destination`. + """Download the contents of the stored file specified by file_id to `destination`. For example:: @@ -816,8 +811,9 @@ async def download_to_stream( @_csot.apply async def delete(self, file_id: Any, session: AsyncClientSession | None = None) -> None: - """Given an file_id, delete this stored file's files collection document - and associated chunks from a GridFS bucket. + """Given an file_id, delete this stored file from a GridFS bucket. + + Deletes the stored file's files collection document and associated chunks. For example:: @@ -846,8 +842,9 @@ async def delete(self, file_id: Any, session: AsyncClientSession | None = None) async def delete_by_name( self, filename: str, session: AsyncClientSession | None = None ) -> None: - """Given a filename, delete this stored file's files collection document(s) - and associated chunks from a GridFS bucket. + """Given a filename, delete this stored file from a GridFS bucket. + + Deletes the stored file's files collection document(s) and associated chunks. For example:: @@ -872,7 +869,7 @@ async def delete_by_name( raise NoFile(f"no file could be deleted because none matched filename {filename!r}") def find(self, *args: Any, **kwargs: Any) -> AsyncGridOutCursor: - """Find and return the files collection documents that match ``filter`` + """Find and return the files collection documents that match ``filter``. Returns a cursor that iterates across files matching arbitrary queries on the files collection. Can be combined @@ -921,8 +918,7 @@ def find(self, *args: Any, **kwargs: Any) -> AsyncGridOutCursor: async def open_download_stream_by_name( self, filename: str, revision: int = -1, session: AsyncClientSession | None = None ) -> AsyncGridOut: - """Opens a Stream from which the application can read the contents of - `filename` and optional `revision`. + """Open a Stream from which the application can read `filename` and optional `revision`. For example:: @@ -980,8 +976,7 @@ async def download_to_stream_by_name( revision: int = -1, session: AsyncClientSession | None = None, ) -> None: - """Write the contents of `filename` (with optional `revision`) to - `destination`. + """Write the contents of `filename` (with optional `revision`) to `destination`. For example:: @@ -1028,7 +1023,7 @@ async def download_to_stream_by_name( async def rename( self, file_id: Any, new_filename: str, session: AsyncClientSession | None = None ) -> None: - """Renames the stored file with the specified file_id. + """Rename the stored file with the specified file_id. For example:: @@ -1060,7 +1055,7 @@ async def rename( async def rename_by_name( self, filename: str, new_filename: str, session: AsyncClientSession | None = None ) -> None: - """Renames the stored file with the specified filename. + """Rename the stored file with the specified filename. For example:: @@ -1096,7 +1091,7 @@ def __init__( session: AsyncClientSession | None = None, **kwargs: Any, ) -> None: - """Write a file to GridFS + """Write a file to GridFS. Application developers should generally not need to instantiate this class directly - instead see the methods @@ -1214,7 +1209,7 @@ async def abort(self) -> None: @property def closed(self) -> bool: - """Is this file closed?""" + """Whether this file is closed.""" return self._closed _id: Any = _a_grid_in_property("_id", "The ``'_id'`` value for this file.", read_only=True) @@ -1480,7 +1475,7 @@ def __init__( file_document: Any | None = None, session: AsyncClientSession | None = None, ) -> None: - """Read a file from GridFS + """Read a file from GridFS. Application developers should generally not need to instantiate this class directly - instead see the methods @@ -1624,8 +1619,10 @@ def readable(self) -> bool: return True async def readchunk(self) -> bytes: - """Reads a chunk at a time. If the current position is within a - chunk the remainder of the chunk is returned. + """Read a chunk at a time. + + If the current position is within a chunk the remainder of the + chunk is returned. """ await self.open() received = len(self._buffer) - self._buffer_pos @@ -1653,7 +1650,7 @@ async def readchunk(self) -> bytes: return chunk_data async def _read_size_or_line(self, size: int = -1, line: bool = False) -> bytes: - """Internal read() and readline() helper.""" + """Implement read() and readline().""" await self.open() remainder = int(self.length) - self._position if size < 0 or size > remainder: @@ -1704,8 +1701,7 @@ async def _read_size_or_line(self, size: int = -1, line: bool = False) -> bytes: return b"".join(data) async def read(self, size: int = -1) -> bytes: - """Read at most `size` bytes from the file (less if there - isn't enough data). + """Read at most `size` bytes from the file (less if there isn't enough data). The bytes are returned as an instance of :class:`bytes` If `size` is negative or omitted all data is read. @@ -1806,9 +1802,7 @@ def writable(self) -> bool: return False async def __aenter__(self) -> Self: - """Makes it possible to use :class:`AsyncGridOut` files - with the async context manager protocol. - """ + """Enable using :class:`AsyncGridOut` files with the async context manager protocol.""" return self async def __aexit__( @@ -1817,9 +1811,7 @@ async def __aexit__( exc_val: BaseException | None, exc_tb: TracebackType | None, ) -> Any: - """Makes it possible to use :class:`AsyncGridOut` files - with the async context manager protocol. - """ + """Enable using :class:`AsyncGridOut` files with the async context manager protocol.""" await self.close() return False @@ -1962,8 +1954,9 @@ async def next(self) -> bytes: class AsyncGridOutCursor(AsyncCursor): # type: ignore[type-arg] - """A cursor / iterator for returning GridOut objects as the result - of an arbitrary query against the GridFS files collection. + """A cursor / iterator for returning GridOut objects. + + The GridOut objects are the result of an arbitrary query against the GridFS files collection. """ def __init__( @@ -1977,8 +1970,7 @@ def __init__( batch_size: int = 0, session: AsyncClientSession | None = None, ) -> None: - """Create a new cursor, similar to the normal - :class:`~pymongo.cursor.Cursor`. + """Create a new cursor, similar to the normal :class:`~pymongo.cursor.Cursor`. Should not be called directly by application developers - see the :class:`~gridfs.GridFS` method :meth:`~gridfs.GridFS.find` instead. @@ -2027,5 +2019,5 @@ def remove_option(self, *args: Any, **kwargs: Any) -> NoReturn: raise NotImplementedError("Method does not exist for GridOutCursor") def _clone_base(self, session: AsyncClientSession | None) -> AsyncGridOutCursor: - """Creates an empty GridOutCursor for information to be copied into.""" + """Create an empty GridOutCursor for information to be copied into.""" return AsyncGridOutCursor(self._root_collection, session=session) diff --git a/gridfs/errors.py b/gridfs/errors.py index 3b9a83e783..cdd2bfe6f2 100644 --- a/gridfs/errors.py +++ b/gridfs/errors.py @@ -12,7 +12,7 @@ # See the License for the specific language governing permissions and # limitations under the License. -"""Exceptions raised by the :mod:`gridfs` package""" +"""Exceptions raised by the :mod:`gridfs` package.""" from __future__ import annotations diff --git a/gridfs/synchronous/grid_file.py b/gridfs/synchronous/grid_file.py index 52b4caaa28..0726f1c9bf 100644 --- a/gridfs/synchronous/grid_file.py +++ b/gridfs/synchronous/grid_file.py @@ -246,9 +246,9 @@ def get_last_version( session: ClientSession | None = None, **kwargs: Any, ) -> GridOut: - """Get the most recent version of a file in GridFS by ``"filename"`` - or metadata fields. + """Get the most recent version of a file in GridFS. + The file is matched by ``"filename"`` or metadata fields. Equivalent to calling :meth:`get_version` with the default `version` (``-1``). @@ -292,8 +292,7 @@ def delete(self, file_id: Any, session: ClientSession | None = None) -> None: self._chunks.delete_many({"files_id": {"$eq": file_id}}, session=session) def list(self, session: ClientSession | None = None) -> list[str]: - """List the names of all files stored in this instance of - :class:`GridFS`. + """List the names of all files stored in this instance of :class:`GridFS`. :param session: a :class:`~pymongo.client_session.ClientSession` @@ -537,8 +536,7 @@ def open_upload_stream( metadata: Mapping[str, Any] | None = None, session: ClientSession | None = None, ) -> GridIn: - """Opens a Stream that the application can write the contents of the - file to. + """Open a Stream that the application can write the contents of the file to. The user must specify the filename, and can choose to add any additional information in the metadata field of the file document or @@ -592,8 +590,7 @@ def open_upload_stream_with_id( metadata: Mapping[str, Any] | None = None, session: ClientSession | None = None, ) -> GridIn: - """Opens a Stream that the application can write the contents of the - file to. + """Open a Stream that the application can write the contents of the file to. The user must specify the file id and filename, and can choose to add any additional information in the metadata field of the file document @@ -653,7 +650,7 @@ def upload_from_stream( metadata: Mapping[str, Any] | None = None, session: ClientSession | None = None, ) -> ObjectId: - """Uploads a user file to a GridFS bucket. + """Upload a user file to a GridFS bucket. Reads the contents of the user file from `source` and uploads it to the file `filename`. Source can be a string or file-like object. @@ -702,7 +699,7 @@ def upload_from_stream_with_id( metadata: Mapping[str, Any] | None = None, session: ClientSession | None = None, ) -> None: - """Uploads a user file to a GridFS bucket with a custom file id. + """Upload a user file to a GridFS bucket with a custom file id. Reads the contents of the user file from `source` and uploads it to the file `filename`. Source can be a string or file-like object. @@ -743,8 +740,7 @@ def upload_from_stream_with_id( gin.write(source) def open_download_stream(self, file_id: Any, session: ClientSession | None = None) -> GridOut: - """Opens a Stream from which the application can read the contents of - the stored file specified by file_id. + """Open a Stream from which the application can read the stored file specified by file_id. For example:: @@ -776,8 +772,7 @@ def open_download_stream(self, file_id: Any, session: ClientSession | None = Non def download_to_stream( self, file_id: Any, destination: Any, session: ClientSession | None = None ) -> None: - """Downloads the contents of the stored file specified by file_id and - writes the contents to `destination`. + """Download the contents of the stored file specified by file_id to `destination`. For example:: @@ -810,8 +805,9 @@ def download_to_stream( @_csot.apply def delete(self, file_id: Any, session: ClientSession | None = None) -> None: - """Given an file_id, delete this stored file's files collection document - and associated chunks from a GridFS bucket. + """Given an file_id, delete this stored file from a GridFS bucket. + + Deletes the stored file's files collection document and associated chunks. For example:: @@ -838,8 +834,9 @@ def delete(self, file_id: Any, session: ClientSession | None = None) -> None: @_csot.apply def delete_by_name(self, filename: str, session: ClientSession | None = None) -> None: - """Given a filename, delete this stored file's files collection document(s) - and associated chunks from a GridFS bucket. + """Given a filename, delete this stored file from a GridFS bucket. + + Deletes the stored file's files collection document(s) and associated chunks. For example:: @@ -864,7 +861,7 @@ def delete_by_name(self, filename: str, session: ClientSession | None = None) -> raise NoFile(f"no file could be deleted because none matched filename {filename!r}") def find(self, *args: Any, **kwargs: Any) -> GridOutCursor: - """Find and return the files collection documents that match ``filter`` + """Find and return the files collection documents that match ``filter``. Returns a cursor that iterates across files matching arbitrary queries on the files collection. Can be combined @@ -913,8 +910,7 @@ def find(self, *args: Any, **kwargs: Any) -> GridOutCursor: def open_download_stream_by_name( self, filename: str, revision: int = -1, session: ClientSession | None = None ) -> GridOut: - """Opens a Stream from which the application can read the contents of - `filename` and optional `revision`. + """Open a Stream from which the application can read `filename` and optional `revision`. For example:: @@ -972,8 +968,7 @@ def download_to_stream_by_name( revision: int = -1, session: ClientSession | None = None, ) -> None: - """Write the contents of `filename` (with optional `revision`) to - `destination`. + """Write the contents of `filename` (with optional `revision`) to `destination`. For example:: @@ -1016,7 +1011,7 @@ def download_to_stream_by_name( destination.write(chunk) def rename(self, file_id: Any, new_filename: str, session: ClientSession | None = None) -> None: - """Renames the stored file with the specified file_id. + """Rename the stored file with the specified file_id. For example:: @@ -1048,7 +1043,7 @@ def rename(self, file_id: Any, new_filename: str, session: ClientSession | None def rename_by_name( self, filename: str, new_filename: str, session: ClientSession | None = None ) -> None: - """Renames the stored file with the specified filename. + """Rename the stored file with the specified filename. For example:: @@ -1084,7 +1079,7 @@ def __init__( session: ClientSession | None = None, **kwargs: Any, ) -> None: - """Write a file to GridFS + """Write a file to GridFS. Application developers should generally not need to instantiate this class directly - instead see the methods @@ -1196,7 +1191,7 @@ def abort(self) -> None: @property def closed(self) -> bool: - """Is this file closed?""" + """Whether this file is closed.""" return self._closed _id: Any = _grid_in_property("_id", "The ``'_id'`` value for this file.", read_only=True) @@ -1462,7 +1457,7 @@ def __init__( file_document: Any | None = None, session: ClientSession | None = None, ) -> None: - """Read a file from GridFS + """Read a file from GridFS. Application developers should generally not need to instantiate this class directly - instead see the methods @@ -1606,8 +1601,10 @@ def readable(self) -> bool: return True def readchunk(self) -> bytes: - """Reads a chunk at a time. If the current position is within a - chunk the remainder of the chunk is returned. + """Read a chunk at a time. + + If the current position is within a chunk the remainder of the + chunk is returned. """ self.open() received = len(self._buffer) - self._buffer_pos @@ -1635,7 +1632,7 @@ def readchunk(self) -> bytes: return chunk_data def _read_size_or_line(self, size: int = -1, line: bool = False) -> bytes: - """Internal read() and readline() helper.""" + """Implement read() and readline().""" self.open() remainder = int(self.length) - self._position if size < 0 or size > remainder: @@ -1686,8 +1683,7 @@ def _read_size_or_line(self, size: int = -1, line: bool = False) -> bytes: return b"".join(data) def read(self, size: int = -1) -> bytes: - """Read at most `size` bytes from the file (less if there - isn't enough data). + """Read at most `size` bytes from the file (less if there isn't enough data). The bytes are returned as an instance of :class:`bytes` If `size` is negative or omitted all data is read. @@ -1788,9 +1784,7 @@ def writable(self) -> bool: return False def __enter__(self) -> Self: - """Makes it possible to use :class:`GridOut` files - with the async context manager protocol. - """ + """Enable using :class:`GridOut` files with the async context manager protocol.""" return self def __exit__( @@ -1799,9 +1793,7 @@ def __exit__( exc_val: BaseException | None, exc_tb: TracebackType | None, ) -> Any: - """Makes it possible to use :class:`GridOut` files - with the async context manager protocol. - """ + """Enable using :class:`GridOut` files with the async context manager protocol.""" self.close() return False @@ -1942,8 +1934,9 @@ def next(self) -> bytes: class GridOutCursor(Cursor): # type: ignore[type-arg] - """A cursor / iterator for returning GridOut objects as the result - of an arbitrary query against the GridFS files collection. + """A cursor / iterator for returning GridOut objects. + + The GridOut objects are the result of an arbitrary query against the GridFS files collection. """ def __init__( @@ -1957,8 +1950,7 @@ def __init__( batch_size: int = 0, session: ClientSession | None = None, ) -> None: - """Create a new cursor, similar to the normal - :class:`~pymongo.cursor.Cursor`. + """Create a new cursor, similar to the normal :class:`~pymongo.cursor.Cursor`. Should not be called directly by application developers - see the :class:`~gridfs.GridFS` method :meth:`~gridfs.GridFS.find` instead. @@ -2007,5 +1999,5 @@ def remove_option(self, *args: Any, **kwargs: Any) -> NoReturn: raise NotImplementedError("Method does not exist for GridOutCursor") def _clone_base(self, session: ClientSession | None) -> GridOutCursor: - """Creates an empty GridOutCursor for information to be copied into.""" + """Create an empty GridOutCursor for information to be copied into.""" return GridOutCursor(self._root_collection, session=session) diff --git a/pymongo/_asyncio_lock.py b/pymongo/_asyncio_lock.py index 4d26db8b1d..d67ef60d8c 100644 --- a/pymongo/_asyncio_lock.py +++ b/pymongo/_asyncio_lock.py @@ -1,6 +1,8 @@ # Copyright (c) 2001-2024 Python Software Foundation; All Rights Reserved -"""Lock and Condition classes vendored from https://github.com/python/cpython/blob/main/Lib/asyncio/locks.py +"""Lock and Condition classes vendored from CPython's asyncio.locks. + +Vendored from https://github.com/python/cpython/blob/main/Lib/asyncio/locks.py to port 3.13 fixes to older versions of Python. Can be removed once we drop Python 3.12 support. """ @@ -285,6 +287,7 @@ async def wait_for(self, predicate: Any) -> Coroutine[Any, Any, Any]: def notify(self, n: int = 1) -> None: """By default, wake up one task waiting on this condition, if any. + If the calling task has not acquired the lock when this method is called, a RuntimeError is raised. @@ -310,9 +313,10 @@ def _notify(self, n: int) -> None: fut.set_result(False) def notify_all(self) -> None: - """Wake up all tasks waiting on this condition. This method acts - like notify(), but wakes up all waiting tasks instead of one. If the - calling task has not acquired the lock when this method is called, - a RuntimeError is raised. + """Wake up all tasks waiting on this condition. + + This method acts like notify(), but wakes up all waiting tasks + instead of one. If the calling task has not acquired the lock when + this method is called, a RuntimeError is raised. """ self.notify(len(self._waiters)) diff --git a/pymongo/_csot.py b/pymongo/_csot.py index 25654240ed..777fd3d6a9 100644 --- a/pymongo/_csot.py +++ b/pymongo/_csot.py @@ -110,7 +110,10 @@ def __exit__( def apply(func: F) -> F: - """Apply the client's timeoutMS to this operation. Can wrap both asynchronous and synchronous methods""" + """Apply the client's timeoutMS to this operation. + + Can wrap both asynchronous and synchronous methods. + """ if inspect.iscoroutinefunction(func): @functools.wraps(func) diff --git a/pymongo/asynchronous/aggregation.py b/pymongo/asynchronous/aggregation.py index 586aaef317..7ffd5031b5 100644 --- a/pymongo/asynchronous/aggregation.py +++ b/pymongo/asynchronous/aggregation.py @@ -117,7 +117,7 @@ def _cursor_namespace(self) -> str: raise NotImplementedError def _cursor_collection(self, cursor_doc: Mapping[str, Any]) -> AsyncCollection[Any]: - """The AsyncCollection used for the aggregate command cursor.""" + """Return the AsyncCollection used for the aggregate command cursor.""" raise NotImplementedError @property @@ -215,7 +215,7 @@ def _cursor_namespace(self) -> str: return self._target.full_name def _cursor_collection(self, cursor: Mapping[str, Any]) -> AsyncCollection[Any]: - """The AsyncCollection used for the aggregate command cursor.""" + """Return the AsyncCollection used for the aggregate command cursor.""" return self._target @property @@ -248,7 +248,7 @@ def _database(self) -> AsyncDatabase[Any]: return self._target def _cursor_collection(self, cursor: Mapping[str, Any]) -> AsyncCollection[Any]: - """The AsyncCollection used for the aggregate command cursor.""" + """Return the AsyncCollection used for the aggregate command cursor.""" # AsyncCollection level aggregate may not always return the "ns" field # according to our MockupDB tests. Let's handle that case for db level # aggregate too by defaulting to the .$cmd.aggregate namespace. diff --git a/pymongo/asynchronous/auth.py b/pymongo/asynchronous/auth.py index 64008c7e2f..5feff06120 100644 --- a/pymongo/asynchronous/auth.py +++ b/pymongo/asynchronous/auth.py @@ -303,7 +303,7 @@ async def _authenticate_gssapi(credentials: MongoCredential, conn: AsyncConnecti async def _authenticate_plain(credentials: MongoCredential, conn: AsyncConnection) -> None: - """Authenticate using SASL PLAIN (RFC 4616)""" + """Authenticate using SASL PLAIN (RFC 4616).""" source = credentials.source username = credentials.username password = credentials.password diff --git a/pymongo/asynchronous/change_stream.py b/pymongo/asynchronous/change_stream.py index 868b330802..e5253015bf 100644 --- a/pymongo/asynchronous/change_stream.py +++ b/pymongo/asynchronous/change_stream.py @@ -69,8 +69,9 @@ async def _initialize_cursor(self) -> None: self._cursor = await self._create_cursor() async def _run_aggregation_cmd(self, session: AsyncClientSession | None) -> AsyncCommandCursor: # type: ignore[type-arg] - """Run the full aggregation pipeline for this AsyncChangeStream and return - the corresponding AsyncCommandCursor. + """Run the full aggregation pipeline for this AsyncChangeStream. + + Return the corresponding AsyncCommandCursor. """ cmd = self._aggregation_command_class( self._target, diff --git a/pymongo/asynchronous/client_bulk.py b/pymongo/asynchronous/client_bulk.py index 7b2b1833ae..ef4efe3c69 100644 --- a/pymongo/asynchronous/client_bulk.py +++ b/pymongo/asynchronous/client_bulk.py @@ -148,7 +148,7 @@ async def _execute_batch_unack( ops: list[tuple[str, Mapping[str, Any]]], namespaces: list[str], ) -> tuple[list[Mapping[str, Any]], list[Mapping[str, Any]]]: - """Executes a batch of bulkWrite server commands (unack).""" + """Execute a batch of bulkWrite server commands (unack).""" request_id, msg, to_send_ops, to_send_ns = bwc.batch_command(cmd, ops, namespaces) await self.unack_write(bwc, cmd, request_id, msg, to_send_ops, to_send_ns, self.client) # type: ignore[arg-type] return to_send_ops, to_send_ns @@ -160,7 +160,7 @@ async def _execute_batch( ops: list[tuple[str, Mapping[str, Any]]], namespaces: list[str], ) -> tuple[dict[str, Any], list[Mapping[str, Any]], list[Mapping[str, Any]]]: - """Executes a batch of bulkWrite server commands (ack).""" + """Execute a batch of bulkWrite server commands (ack).""" request_id, msg, to_send_ops, to_send_ns = bwc.batch_command(cmd, ops, namespaces) result = await self.write_command( bwc, cmd, request_id, msg, to_send_ops, to_send_ns, self.client @@ -174,7 +174,7 @@ async def _process_results_cursor( conn: AsyncConnection, session: AsyncClientSession | None, ) -> None: - """Internal helper for processing the server reply command cursor.""" + """Process the server reply command cursor (internal helper).""" if result.get("cursor"): if session: session._leave_alive = True @@ -229,7 +229,7 @@ async def _execute_command( full_result: MutableMapping[str, Any], final_write_concern: WriteConcern | None = None, ) -> None: - """Internal helper for executing batches of bulkWrite commands.""" + """Execute batches of bulkWrite commands (internal helper).""" db_name = "admin" cmd_name = "bulkWrite" listeners = self.client._event_listeners diff --git a/pymongo/asynchronous/collection.py b/pymongo/asynchronous/collection.py index 3a8b7f83b8..8778739fed 100644 --- a/pymongo/asynchronous/collection.py +++ b/pymongo/asynchronous/collection.py @@ -100,9 +100,10 @@ class ReturnDocument: - """An enum used with - :meth:`~pymongo.asynchronous.collection.AsyncCollection.find_one_and_replace` and - :meth:`~pymongo.asynchronous.collection.AsyncCollection.find_one_and_update`. + """An enum used with the find_one_and_replace and find_one_and_update methods. + + See :meth:`~pymongo.asynchronous.collection.AsyncCollection.find_one_and_replace` + and :meth:`~pymongo.asynchronous.collection.AsyncCollection.find_one_and_update`. """ BEFORE = False @@ -328,8 +329,10 @@ def name(self) -> str: @property def database(self) -> AsyncDatabase[_DocumentType]: - """The :class:`~pymongo.asynchronous.database.AsyncDatabase` that this - :class:`AsyncCollection` is a part of. + """Return the collection's :class:`~pymongo.asynchronous.database.AsyncDatabase`. + + This is the :class:`~pymongo.asynchronous.database.AsyncDatabase` that + this :class:`AsyncCollection` is a part of. """ return self._database @@ -405,7 +408,7 @@ def __next__(self) -> NoReturn: next = __next__ def __call__(self, *args: Any, **kwargs: Any) -> NoReturn: - """This is only here so that some API misusages are easier to debug.""" + """Raise an error so that some API misusages are easier to debug.""" if "." not in self._name: raise TypeError( f"'{type(self).__name__}' object is not callable. If you " @@ -575,7 +578,7 @@ async def _command( retryable_write: bool = False, user_fields: Any | None = None, ) -> Mapping[str, Any]: - """Internal command helper. + """Run a command (internal helper). :param conn` - A AsyncConnection instance. :param command` - The command itself, as a :class:`~bson.son.SON` instance. @@ -627,7 +630,7 @@ async def _create_helper( encrypted_fields: Mapping[str, Any] | None = None, qev2_required: bool = False, ) -> None: - """Sends a create command with the given options.""" + """Send a create command with the given options.""" cmd: dict[str, Any] = {"create": name} if encrypted_fields: cmd["encryptedFields"] = encrypted_fields @@ -793,7 +796,7 @@ async def _insert_one( session: AsyncClientSession | None, comment: Any | None = None, ) -> Any: - """Internal helper for inserting a single document.""" + """Insert a single document (internal helper).""" write_concern = write_concern or self.write_concern acknowledged = write_concern.acknowledged command = {"insert": self.name, "ordered": ordered, "documents": [doc]} @@ -950,7 +953,7 @@ async def insert_many( inserted_ids: list[ObjectId] = [] def gen() -> Iterator[tuple[int, Mapping[str, Any]]]: - """A generator that validates documents and handles _ids.""" + """Validate documents and handle _ids.""" for document in documents: common.validate_is_document_type("document", document) if not isinstance(document, RawBSONDocument): @@ -985,7 +988,7 @@ async def _update( sort: Mapping[str, Any] | None = None, comment: Any | None = None, ) -> Mapping[str, Any] | None: - """Internal update / replace helper.""" + """Update or replace a document (internal helper).""" validate_boolean("upsert", upsert) collation = validate_collation_or_none(collation) write_concern = write_concern or self.write_concern @@ -1076,7 +1079,7 @@ async def _update_retryable( sort: Mapping[str, Any] | None = None, comment: Any | None = None, ) -> Mapping[str, Any] | None: - """Internal update / replace helper.""" + """Update or replace a document (internal helper).""" async def _update( session: AsyncClientSession | None, conn: AsyncConnection, retryable_write: bool @@ -1493,7 +1496,7 @@ async def _delete( let: Mapping[str, Any] | None = None, comment: Any | None = None, ) -> Mapping[str, Any]: - """Internal delete helper.""" + """Delete documents (internal helper).""" common.validate_is_mapping("filter", criteria) write_concern = write_concern or self.write_concern acknowledged = write_concern.acknowledged @@ -1543,7 +1546,7 @@ async def _delete_retryable( let: Mapping[str, Any] | None = None, comment: Any | None = None, ) -> Mapping[str, Any]: - """Internal delete helper.""" + """Delete documents (internal helper).""" async def _delete( session: AsyncClientSession | None, conn: AsyncConnection, retryable_write: bool @@ -1983,7 +1986,7 @@ async def _count_cmd( cmd: dict[str, Any], collation: Collation | None, ) -> int: - """Internal count command helper.""" + """Run a count command (internal helper).""" res = await self._command( conn, cmd, @@ -2003,7 +2006,7 @@ async def _aggregate_one_result( collation: _CollationIn | None, session: AsyncClientSession | None, ) -> Mapping[str, Any] | None: - """Internal helper to run an aggregate that returns a single result.""" + """Run an aggregate that returns a single result (internal helper).""" result = await self._command( conn, cmd, @@ -2021,8 +2024,9 @@ async def _aggregate_one_result( return batch[0] if batch else None async def estimated_document_count(self, comment: Any | None = None, **kwargs: Any) -> int: - """Get an estimate of the number of documents in this collection using - collection metadata. + """Get an estimate of the number of documents in this collection. + + Uses collection metadata. The :meth:`estimated_document_count` method is **not** supported in a transaction. @@ -2220,7 +2224,7 @@ async def create_indexes( async def _create_indexes( self, indexes: Sequence[IndexModel], session: AsyncClientSession | None, **kwargs: Any ) -> list[str]: - """Internal createIndexes helper. + """Create indexes (internal helper). :param indexes: A list of :class:`~pymongo.operations.IndexModel` instances. @@ -2267,7 +2271,7 @@ async def create_index( comment: Any | None = None, **kwargs: Any, ) -> str: - """Creates an index on this collection. + """Create an index on this collection. Takes either a single key or a list containing (key, direction) pairs or keys. If no direction is given, :data:`~pymongo.ASCENDING` will @@ -2384,7 +2388,7 @@ async def drop_indexes( comment: Any | None = None, **kwargs: Any, ) -> None: - """Drops all indexes on this collection. + """Drop all indexes on this collection. Can be used on non-existent collections or collections with no indexes. Raises OperationFailure on an error. @@ -2418,7 +2422,7 @@ async def drop_index( comment: Any | None = None, **kwargs: Any, ) -> None: - """Drops the specified index on this collection. + """Drop the specified index on this collection. Can be used on non-existent collections or collections with no indexes. Raises OperationFailure on an error (e.g. trying to @@ -2939,8 +2943,7 @@ async def aggregate( comment: Any | None = None, **kwargs: Any, ) -> AsyncCommandCursor[_DocumentType]: - """Perform an aggregation using the aggregation framework on this - collection. + """Perform an aggregation using the aggregation framework on this collection. The :meth:`aggregate` method obeys the :attr:`read_preference` of this :class:`AsyncCollection`, except when ``$out`` or ``$merge`` are used on @@ -3159,8 +3162,7 @@ async def distinct( hint: _IndexKeyHint | None = None, **kwargs: Any, ) -> list[Any]: - """Get a list of distinct values for `key` among all documents - in this collection. + """Get a list of distinct values for `key` among all documents in this collection. Raises :class:`TypeError` if `key` is not an instance of :class:`str`. @@ -3250,7 +3252,7 @@ async def _find_and_modify( let: Mapping[str, Any] | None = None, **kwargs: Any, ) -> Any: - """Internal findAndModify helper.""" + """Run a findAndModify command (internal helper).""" common.validate_is_mapping("filter", filter) if not isinstance(return_document, bool): raise TypeError( @@ -3318,7 +3320,7 @@ async def find_one_and_delete( comment: Any | None = None, **kwargs: Any, ) -> _DocumentType | None: - """Finds a single document and deletes it, returning the document. + """Find a single document and delete it, returning the document. >>> await db.test.count_documents({'x': 1}) 2 @@ -3414,8 +3416,9 @@ async def find_one_and_replace( comment: Any | None = None, **kwargs: Any, ) -> _DocumentType | None: - """Finds a single document and replaces it, returning either the - original or the replaced document. + """Find a single document and replace it. + + Return either the original or the replaced document. >>> await db.test.find_one({'x': 1}) {'_id': 0, 'x': 1} @@ -3534,8 +3537,9 @@ async def find_one_and_update( comment: Any | None = None, **kwargs: Any, ) -> _DocumentType | None: - """Finds a single document and updates it, returning either the - original or the updated document. + """Find a single document and update it. + + Return either the original or the updated document. >>> await db.test.find_one({'_id': 665}) {'_id': 665, 'done': False, 'count': 25} diff --git a/pymongo/asynchronous/command_cursor.py b/pymongo/asynchronous/command_cursor.py index 370ef98af3..ed62877051 100644 --- a/pymongo/asynchronous/command_cursor.py +++ b/pymongo/asynchronous/command_cursor.py @@ -45,6 +45,7 @@ class AsyncCommandCursor( _AgnosticCommandCursorBase[_DocumentType], _AsyncCursorBase[_DocumentType] ): """An asynchronous cursor / iterator over command cursors. + Used by :meth:`~pymongo.asynchronous.collection.AsyncCollection.aggregate`, :meth:`~pymongo.asynchronous.database.AsyncDatabase.aggregate`, :meth:`~pymongo.asynchronous.collection.AsyncCollection.list_indexes`, @@ -113,7 +114,7 @@ async def _send_message(self, operation: _GetMore) -> None: self._data = deque(documents) async def _refresh(self) -> int: - """Refreshes the cursor with more data from the server. + """Refresh the cursor with more data from the server. Returns the length of self._data after refresh. Will exit early if self._data is already non-empty. Raises OperationFailure when the diff --git a/pymongo/asynchronous/command_runner.py b/pymongo/asynchronous/command_runner.py index b1c5421537..552f92badd 100644 --- a/pymongo/asynchronous/command_runner.py +++ b/pymongo/asynchronous/command_runner.py @@ -101,8 +101,9 @@ async def _run_command( unpack_res: Callable[..., Any] | None = None, cursor_id: int | None = None, ) -> tuple[list[dict[str, Any]], _OpMsg | None, float]: - """Send ``msg`` over ``conn`` and return ``(docs, reply, duration_s)``, - where ``duration_s`` is the round-trip duration in seconds. + """Send ``msg`` over ``conn`` and return ``(docs, reply, duration_s)``. + + ``duration_s`` is the round-trip duration in seconds. Private shared implementation. Should not be called directly outside this module. Use :func:`run_command`, :func:`run_bulk_write_command`, or :func:`run_cursor_command` instead. diff --git a/pymongo/asynchronous/cursor.py b/pymongo/asynchronous/cursor.py index b0b4abfc94..367be3b5cb 100644 --- a/pymongo/asynchronous/cursor.py +++ b/pymongo/asynchronous/cursor.py @@ -57,8 +57,9 @@ class AsyncCursor(_AgnosticCursor[_DocumentType], _AsyncCursorBase[_DocumentType]): @property def collection(self) -> AsyncCollection[_DocumentType]: - """The :class:`~pymongo.asynchronous.collection.AsyncCollection` that this - :class:`AsyncCursor` is iterating. + """The :class:`~pymongo.asynchronous.collection.AsyncCollection` being iterated. + + The collection that this :class:`AsyncCursor` is iterating. """ return self._collection @@ -169,7 +170,7 @@ def __getitem__(self, index: int | slice) -> _DocumentType | AsyncCursor[_Docume raise IndexError("AsyncCursor does not support indexing") async def explain(self) -> _DocumentType: - """Returns an explain plan record for this cursor. + """Return an explain plan record for this cursor. .. note:: This method uses the default verbosity mode of the `explain command @@ -191,8 +192,9 @@ async def explain(self) -> _DocumentType: return await anext(c) async def distinct(self, key: str) -> list[Any]: - """Get a list of distinct values for `key` among all documents - in the result set of this query. + """Get a list of distinct values for `key` among all documents. + + The distinct values are drawn from the result set of this query. Raises :class:`TypeError` if `key` is not an instance of :class:`str`. @@ -296,7 +298,7 @@ async def _send_message(self, operation: _Query | _GetMore) -> None: await self.close() async def _refresh(self) -> int: - """Refreshes the cursor with more data from Mongo. + """Refresh the cursor with more data from Mongo. Returns the length of self._data after refresh. Will exit early if self._data is already non-empty. Raises OperationFailure when the @@ -447,7 +449,7 @@ def _unpack_response( return cast("list[_DocumentOut]", raw_response) async def explain(self) -> _DocumentType: - """Returns an explain plan record for this cursor. + """Return an explain plan record for this cursor. .. seealso:: The MongoDB documentation on `explain `_. """ diff --git a/pymongo/asynchronous/cursor_base.py b/pymongo/asynchronous/cursor_base.py index ac1410ddcb..c96e81f195 100644 --- a/pymongo/asynchronous/cursor_base.py +++ b/pymongo/asynchronous/cursor_base.py @@ -166,7 +166,7 @@ async def _run_with_conn( ) async def _die_lock(self) -> None: - """Closes this cursor.""" + """Close this cursor.""" try: already_killed = self._killed except AttributeError: @@ -199,7 +199,7 @@ async def __aexit__( @_csot.apply async def to_list(self, length: int | None = None) -> list[_DocumentType]: - """Converts the contents of this cursor to a list more efficiently than ``[doc async for doc in cursor]``. + """Convert this cursor's contents to a list more efficiently than iterating over it. To use:: diff --git a/pymongo/asynchronous/database.py b/pymongo/asynchronous/database.py index 0a0f97c71b..40f97830b5 100644 --- a/pymongo/asynchronous/database.py +++ b/pymongo/asynchronous/database.py @@ -253,12 +253,11 @@ def get_collection( write_concern: WriteConcern | None = None, read_concern: ReadConcern | None = None, ) -> AsyncCollection[_DocumentType]: - """Get a :class:`~pymongo.asynchronous.collection.AsyncCollection` with the given name - and options. + """Get a :class:`~pymongo.asynchronous.collection.AsyncCollection`. - Useful for creating a :class:`~pymongo.asynchronous.collection.AsyncCollection` with - different codec options, read preference, and/or write concern from - this :class:`AsyncDatabase`. + The returned collection uses the given name and options. Useful for creating a + :class:`~pymongo.asynchronous.collection.AsyncCollection` with different codec + options, read preference, and/or write concern from this :class:`AsyncDatabase`. >>> db.read_preference Primary() @@ -484,8 +483,7 @@ async def create_collection( check_exists: bool | None = True, **kwargs: Any, ) -> AsyncCollection[_DocumentType]: - """Create a new :class:`~pymongo.asynchronous.collection.AsyncCollection` in this - database. + """Create a new :class:`~pymongo.asynchronous.collection.AsyncCollection` in this database. Normally collection creation is automatic. This method should only be used to specify options on @@ -762,7 +760,7 @@ async def _command( session: AsyncClientSession | None = None, **kwargs: Any, ) -> dict[str, Any] | _CodecDocumentType: - """Internal command helper.""" + """Run an internal command.""" if isinstance(command, str): command = {command: value} @@ -1059,7 +1057,7 @@ async def _retryable_read_command( operation: str, session: AsyncClientSession | None = None, ) -> dict[str, Any]: - """Same as command but used for retryable read commands.""" + """Run the given command as a retryable read.""" read_preference = (session and session._txn_read_preference()) or ReadPreference.PRIMARY async def _cmd( @@ -1084,7 +1082,7 @@ async def _list_collections( read_preference: _ServerMode, **kwargs: Any, ) -> AsyncCommandCursor[MutableMapping[str, Any]]: - """Internal listCollections helper.""" + """Run the internal listCollections helper.""" coll = cast( "AsyncCollection[MutableMapping[str, Any]]", self.get_collection("$cmd", read_preference=read_preference), @@ -1437,8 +1435,7 @@ async def dereference( comment: Any | None = None, **kwargs: Any, ) -> _DocumentType | None: - """Dereference a :class:`~bson.dbref.DBRef`, getting the - document it points to. + """Dereference a :class:`~bson.dbref.DBRef`, getting the document it points to. Raises :class:`TypeError` if `dbref` is not an instance of :class:`~bson.dbref.DBRef`. Returns a document, or ``None`` if diff --git a/pymongo/asynchronous/encryption.py b/pymongo/asynchronous/encryption.py index 113b7b6612..310e0157ec 100644 --- a/pymongo/asynchronous/encryption.py +++ b/pymongo/asynchronous/encryption.py @@ -120,7 +120,7 @@ def __init__( mongocryptd_client: AsyncMongoClient[_DocumentTypeArg] | None, opts: AutoEncryptionOpts, ): - """Internal class to perform I/O on behalf of pymongocrypt.""" + """Perform I/O on behalf of pymongocrypt (internal class).""" self.client_ref: Any # Use a weak ref to break reference cycle. if client is not None: @@ -291,7 +291,7 @@ async def mark_command(self, database: str, cmd: bytes) -> bytes | memoryview: return res.raw async def fetch_keys(self, filter: bytes) -> AsyncGenerator[bytes | memoryview, None]: - """Yields one or more keys from the key vault. + """Yield one or more keys from the key vault. :param filter: The filter to pass to find. diff --git a/pymongo/asynchronous/mongo_client.py b/pymongo/asynchronous/mongo_client.py index 366582cf11..dff15a6f22 100644 --- a/pymongo/asynchronous/mongo_client.py +++ b/pymongo/asynchronous/mongo_client.py @@ -1158,7 +1158,7 @@ async def target() -> bool: self._opened = False def append_metadata(self, driver_info: DriverInfo) -> None: - """Appends the given metadata to existing driver metadata. + """Append the given metadata to existing driver metadata. :param driver_info: a :class:`~pymongo.driver_info.DriverInfo` @@ -1174,7 +1174,7 @@ def _should_pin_cursor(self, session: AsyncClientSession | None) -> bool | None: return self._options.load_balanced and not (session and session.in_transaction) def _after_fork(self) -> None: - """Resets topology in a child after successfully forking.""" + """Reset topology in a child after successfully forking.""" self._init_background(self._topology._pid) # Reset the session pool to avoid duplicate sessions in the child process. self._topology._session_pool.reset() @@ -1620,12 +1620,11 @@ def get_database( write_concern: WriteConcern | None = None, read_concern: ReadConcern | None = None, ) -> database.AsyncDatabase[_DocumentType]: - """Get a :class:`~pymongo.asynchronous.database.AsyncDatabase` with the given name and - options. + """Get a :class:`~pymongo.asynchronous.database.AsyncDatabase`. - Useful for creating a :class:`~pymongo.asynchronous.database.AsyncDatabase` with - different codec options, read preference, and/or write concern from - this :class:`AsyncMongoClient`. + The returned database uses the given name and options. Useful for creating a + :class:`~pymongo.asynchronous.database.AsyncDatabase` with different codec + options, read preference, and/or write concern from this :class:`AsyncMongoClient`. >>> client.read_preference Primary() @@ -1700,7 +1699,7 @@ def __next__(self) -> NoReturn: next = __next__ async def _server_property(self, attr_name: str) -> Any: - """An attribute of the current server's description. + """Get an attribute of the current server's description. If the client is not connected, this will block until a connection is established or raise ServerSelectionTimeoutError if no server is @@ -1798,9 +1797,11 @@ async def is_primary(self) -> bool: @property async def is_mongos(self) -> bool: - """If this client is connected to mongos. If the client is not - connected, this will block until a connection is established or raise - ServerSelectionTimeoutError if no server is available. + """Whether this client is connected to mongos. + + If the client is not connected, this will block until a connection is + established or raise ServerSelectionTimeoutError if no server is + available. """ return await self._server_property("server_type") == SERVER_TYPE.Mongos @@ -2007,7 +2008,7 @@ async def _retry_with_session( operation: str, operation_id: int | None = None, ) -> T: - """Execute an operation with at most one consecutive retries + """Execute an operation with at most one consecutive retries. Returns func()'s return value on success. On error retries the same command. @@ -2044,7 +2045,7 @@ async def _retry_internal( is_aggregate_write: bool = False, conn_mgr: Any = None, ) -> T: - """Internal retryable helper for all client transactions. + """Run the internal retryable helper for all client transactions. :param func: Callback function we want to retry :param session: Client Session on which the transaction should occur @@ -2090,7 +2091,7 @@ async def _retryable_read( is_aggregate_write: bool = False, conn_mgr: Any = None, ) -> T: - """Execute an operation with consecutive retries if possible + """Execute an operation with consecutive retries if possible. Returns func()'s return value on success. On error retries the same command. @@ -2139,7 +2140,7 @@ async def _retryable_write( bulk: _AsyncBulk | _AsyncClientBulk | None = None, operation_id: int | None = None, ) -> T: - """Execute an operation with consecutive retries if possible + """Execute an operation with consecutive retries if possible. Returns func()'s return value on success. On error retries the same command. @@ -2312,9 +2313,7 @@ async def _process_kill_cursors(self) -> None: # This method is run periodically by a background thread. async def _process_periodic_tasks(self) -> None: - """Process any pending kill cursors requests and - maintain connection pool parameters. - """ + """Process any pending kill cursors requests and maintain connection pool parameters.""" try: await self._process_kill_cursors() await self._topology.update_pool() @@ -2325,7 +2324,7 @@ async def _process_periodic_tasks(self) -> None: _log_client_error() def _return_server_session(self, server_session: _ServerSession | _EmptyServerSession) -> None: - """Internal: return a _ServerSession to the pool.""" + """Return a _ServerSession to the pool.""" if isinstance(server_session, _EmptyServerSession): return None return self._topology.return_server_session(server_session) @@ -2864,7 +2863,7 @@ async def __aenter__(self) -> tuple[AsyncConnection, _ServerMode]: # type: igno class _ClientConnectionRetryable( _AgnosticClientConnectionRetryableBase[T, "Server", _WriteCall[T] | _ReadCall[T]] ): - """Responsible for executing retryable connections on read or write operations""" + """Responsible for executing retryable connections on read or write operations.""" __slots__ = () @@ -2872,7 +2871,7 @@ class _ClientConnectionRetryable( _session: AsyncClientSession | None async def run(self) -> T: - """Runs the supplied func() and attempts a retry + """Run the supplied func() and attempt a retry. :raises: self._last_error: Last exception raised @@ -3031,7 +3030,7 @@ async def run(self) -> T: await asyncio.sleep(delay) async def _get_server(self) -> Server: - """Retrieves a server object based on provided object context + """Retrieve a server object based on provided object context. :return: Abstraction to connect to server """ @@ -3045,7 +3044,7 @@ async def _get_server(self) -> Server: ) async def _write(self) -> T: - """Wrapper method for write-type retryable client executions + """Wrap write-type retryable client executions. :return: Output for func()'s call """ @@ -3077,7 +3076,7 @@ async def _write(self) -> T: raise async def _read(self) -> T: - """Wrapper method for read-type retryable client executions + """Wrap read-type retryable client executions. :return: Output for func()'s call """ diff --git a/pymongo/asynchronous/monitor.py b/pymongo/asynchronous/monitor.py index a3aebb80b0..7448109fa2 100644 --- a/pymongo/asynchronous/monitor.py +++ b/pymongo/asynchronous/monitor.py @@ -56,7 +56,7 @@ def _sanitize(error: Exception) -> None: class MonitorBase: def __init__(self, topology: Topology, name: str, interval: int, min_interval: float): - """Base class to do periodic work on a background thread. + """Do periodic work on a background thread (base class). The background thread is signaled to stop when the Topology or this instance is freed. @@ -270,7 +270,7 @@ async def _check_server(self) -> ServerDescription: return ServerDescription(address, error=error) async def _check_once(self) -> ServerDescription: - """A single attempt to call hello. + """Make a single attempt to call hello. Returns a ServerDescription, or raises an exception. """ diff --git a/pymongo/asynchronous/pool.py b/pymongo/asynchronous/pool.py index 2cccd57c56..6e3fba6f5a 100644 --- a/pymongo/asynchronous/pool.py +++ b/pymongo/asynchronous/pool.py @@ -431,7 +431,8 @@ def __init__( is_sdam: bool = False, client_id: ObjectId | None = None, ): - """ + """Initialize a new connection pool. + :param address: a (hostname, port) tuple :param options: a PoolOptions instance :param is_sdam: whether to call hello for each new connection @@ -530,9 +531,7 @@ async def _reset( await conn.close_conn(ConnectionClosedReason.STALE) async def update_is_writable(self, is_writable: bool | None) -> None: - """Updates the is_writable attribute on all sockets currently in the - Pool. - """ + """Update the is_writable attribute on all sockets currently in the Pool.""" self.is_writable = is_writable async with self.lock: for _socket in self.conns: @@ -552,10 +551,10 @@ async def close(self) -> None: await self._reset(close=True) async def remove_stale_sockets(self, reference_generation: int) -> None: - """Removes stale sockets then adds new ones if pool is too small and - has not been reset. The `reference_generation` argument specifies the - `generation` at the point in time this operation was requested on the - pool. + """Remove stale sockets then add new ones if pool is too small and has not been reset. + + The `reference_generation` argument specifies the `generation` at the + point in time this operation was requested on the pool. """ # Take the lock to avoid the race condition described in PYTHON-2699. async with self.lock: @@ -689,7 +688,9 @@ async def connect(self, handler: _ClientCheckout | None = None) -> AsyncConnecti return conn def checkout(self, handler: _ClientCheckout | None = None) -> _PoolCheckout: - """Get a connection from the pool. Always use in an async with statement:: + """Get a connection from the pool. + + Always use in an async with statement:: async with pool.checkout() as connection: connection.send_message(msg) diff --git a/pymongo/asynchronous/topology.py b/pymongo/asynchronous/topology.py index 1471830ddf..93bbcd8386 100644 --- a/pymongo/asynchronous/topology.py +++ b/pymongo/asynchronous/topology.py @@ -433,9 +433,7 @@ async def on_change( await server.pool.reset(interrupt_connections=interrupt_connections) async def _process_srv_update(self, seedlist: list[tuple[str, Any]]) -> None: - """Process a new seedlist on an opened topology. - Hold the lock when calling this. - """ + """Process a new seedlist on an opened topology. Hold the lock when calling this.""" td_old = self._description if td_old.topology_type not in SRV_POLLING_TOPOLOGIES: return @@ -512,8 +510,9 @@ async def update_pool(self) -> None: raise async def close(self) -> None: - """Clear pools and terminate monitors. Topology does not reopen on - demand. Any further operations will raise + """Clear pools and terminate monitors. + + Topology does not reopen on demand. Any further operations will raise :exc:`~.errors.InvalidOperation`. """ async with self._lock: diff --git a/pymongo/bulk_shared.py b/pymongo/bulk_shared.py index 0d54b73977..560f61e7ba 100644 --- a/pymongo/bulk_shared.py +++ b/pymongo/bulk_shared.py @@ -273,8 +273,9 @@ def add_delete( self.ops.append((_DELETE, cmd)) def gen_ordered(self) -> Iterator[_Run | None]: - """Generate batches of operations, batched by type of - operation, in the order **provided**. + """Generate batches of operations, batched by type of operation. + + The batches are in the order **provided**. """ run = None for idx, (op_type, operation) in enumerate(self.ops): @@ -287,9 +288,7 @@ def gen_ordered(self) -> Iterator[_Run | None]: yield run def gen_unordered(self) -> Iterator[_Run]: - """Generate batches of operations, batched by type of - operation, in arbitrary order. - """ + """Generate batches of operations, batched by type of operation, in arbitrary order.""" operations = [_Run(_INSERT), _Run(_UPDATE), _Run(_DELETE)] for idx, (op_type, operation) in enumerate(self.ops): operations[op_type].add(idx, operation) diff --git a/pymongo/change_stream_shared.py b/pymongo/change_stream_shared.py index 427f0ac354..b9d8d564e1 100644 --- a/pymongo/change_stream_shared.py +++ b/pymongo/change_stream_shared.py @@ -120,9 +120,7 @@ def _aggregation_command_class(self) -> type[Any]: @property def _client(self) -> _ClientT: - """The client against which the aggregation commands for - this ChangeStream will be run. - """ + """The client against which the aggregation commands for this ChangeStream will be run.""" raise NotImplementedError def _change_stream_options(self) -> dict[str, Any]: @@ -166,8 +164,9 @@ def _aggregation_pipeline(self) -> list[dict[str, Any]]: return full_pipeline def _process_result(self, result: Mapping[str, Any]) -> None: - """Callback that caches the postBatchResumeToken or - startAtOperationTime from a changeStream aggregate command response + """Cache the postBatchResumeToken or startAtOperationTime. + + The values come from a changeStream aggregate command response containing an empty batch of change documents. """ if not result["cursor"]["firstBatch"]: @@ -187,8 +186,7 @@ def _process_result(self, result: Mapping[str, Any]) -> None: @property def resume_token(self) -> Mapping[str, Any] | None: - """The cached resume token that will be used to resume after the most - recently returned change. + """The cached resume token used to resume after the most recent change. .. versionadded:: 3.9 """ @@ -196,7 +194,7 @@ def resume_token(self) -> Mapping[str, Any] | None: @property def alive(self) -> bool: - """Does this cursor have the potential to return more data? + """Check whether this cursor has the potential to return more data. .. note:: Even if :attr:`alive` is ``True``, :meth:`next` can raise :exc:`StopIteration` (sync) or :exc:`StopAsyncIteration` (async), diff --git a/pymongo/client_session_shared.py b/pymongo/client_session_shared.py index 1c285d1e1b..f98e9ee42b 100644 --- a/pymongo/client_session_shared.py +++ b/pymongo/client_session_shared.py @@ -67,7 +67,9 @@ class SessionOptions: - """Options for a new :class:`~pymongo.asynchronous.client_session.AsyncClientSession` + """Options for a new client session. + + For :class:`~pymongo.asynchronous.client_session.AsyncClientSession` or :class:`~pymongo.client_session.ClientSession`. :param causal_consistency: If True, read operations are causally @@ -112,8 +114,7 @@ def causal_consistency(self) -> bool: @property def default_transaction_options(self) -> TransactionOptions | None: - """The default TransactionOptions to use for transactions started on - this session. + """The default TransactionOptions for transactions started on this session. .. versionadded:: 3.7 """ @@ -129,7 +130,9 @@ def snapshot(self) -> bool | None: class TransactionOptions: - """Options for :meth:`~pymongo.asynchronous.client_session.AsyncClientSession.start_transaction` + """Options for a new transaction. + + For :meth:`~pymongo.asynchronous.client_session.AsyncClientSession.start_transaction` or :meth:`~pymongo.client_session.ClientSession.start_transaction`. :param read_concern: The @@ -283,7 +286,7 @@ def _max_time_expired_error(exc: PyMongoError) -> bool: def _within_time_limit(start_time: float, backoff: float = 0) -> bool: - """Are we within the with_transaction retry limit?""" + """Check whether we are within the with_transaction retry limit.""" remaining = _csot.remaining() if remaining is not None and remaining <= 0: return False @@ -488,9 +491,10 @@ def bind(self, end_session: bool = True) -> _BoundSessionContextT: @property def client(self) -> _ClientT: - """The :class:`~pymongo.mongo_client.MongoClient` or - :class:`~pymongo.asynchronous.mongo_client.AsyncMongoClient` this session was - created from. + """The client from which this session was created. + + One of :class:`~pymongo.mongo_client.MongoClient` or + :class:`~pymongo.asynchronous.mongo_client.AsyncMongoClient`. """ return self._client @@ -514,16 +518,12 @@ def _transaction_id(self) -> Int64: @property def cluster_time(self) -> ClusterTime | None: - """The cluster time returned by the last operation executed - in this session. - """ + """The cluster time returned by the last operation executed in this session.""" return self._cluster_time @property def operation_time(self) -> Timestamp | None: - """The operation time returned by the last operation executed - in this session. - """ + """The operation time returned by the last operation executed in this session.""" return self._operation_time def _inherit_option(self, name: str, val: _T) -> _T: @@ -537,7 +537,7 @@ def _inherit_option(self, name: str, val: _T) -> _T: return getattr(self.client, name) def _advance_cluster_time(self, cluster_time: Mapping[str, Any] | None) -> None: - """Internal cluster time helper.""" + """Update the internal cluster time.""" if self._cluster_time is None: self._cluster_time = cluster_time elif cluster_time is not None: @@ -561,7 +561,7 @@ def advance_cluster_time(self, cluster_time: Mapping[str, Any]) -> None: self._advance_cluster_time(cluster_time) def _advance_operation_time(self, operation_time: Timestamp | None) -> None: - """Internal operation time helper.""" + """Update the internal operation time.""" if self._operation_time is None: self._operation_time = operation_time elif operation_time is not None: diff --git a/pymongo/collation.py b/pymongo/collation.py index 396560bcd2..b5a86f4ea4 100644 --- a/pymongo/collation.py +++ b/pymongo/collation.py @@ -31,10 +31,7 @@ class CollationStrength: - """ - An enum that defines values for `strength` on a - :class:`~pymongo.collation.Collation`. - """ + """An enum that defines values for `strength` on a :class:`~pymongo.collation.Collation`.""" PRIMARY = 1 """Differentiate base (unadorned) characters.""" @@ -53,10 +50,7 @@ class CollationStrength: class CollationAlternate: - """ - An enum that defines values for `alternate` on a - :class:`~pymongo.collation.Collation`. - """ + """An enum that defines values for `alternate` on a :class:`~pymongo.collation.Collation`.""" NON_IGNORABLE = "non-ignorable" """Spaces and punctuation are treated as base characters.""" @@ -72,10 +66,7 @@ class CollationAlternate: class CollationMaxVariable: - """ - An enum that defines values for `max_variable` on a - :class:`~pymongo.collation.Collation`. - """ + """An enum that defines values for `max_variable` on a :class:`~pymongo.collation.Collation`.""" PUNCT = "punct" """Both punctuation and spaces are ignored.""" @@ -85,10 +76,7 @@ class CollationMaxVariable: class CollationCaseFirst: - """ - An enum that defines values for `case_first` on a - :class:`~pymongo.collation.Collation`. - """ + """An enum that defines values for `case_first` on a :class:`~pymongo.collation.Collation`.""" UPPER = "upper" """Sort uppercase characters first.""" @@ -101,7 +89,7 @@ class CollationCaseFirst: class Collation: - """Collation + """Collation. :param locale: (string) The locale of the collation. This should be a string that identifies an `ICU locale ID` exactly. For example, ``en_US`` is diff --git a/pymongo/common.py b/pymongo/common.py index d160e28235..d16af456c5 100644 --- a/pymongo/common.py +++ b/pymongo/common.py @@ -190,7 +190,7 @@ def raise_config_error(key: str, suggestions: list[str] | None = None) -> NoRetu def validate_boolean_or_string(option: str, value: Any) -> bool: - """Validates that value is True, False, 'true', or 'false'.""" + """Validate that value is True, False, 'true', or 'false'.""" if isinstance(value, str): if value not in ("true", "false"): raise ValueError(f"The value of {option} must be 'true' or 'false'") @@ -199,7 +199,7 @@ def validate_boolean_or_string(option: str, value: Any) -> bool: def validate_integer(option: str, value: Any) -> int: - """Validates that 'value' is an integer (or basestring representation).""" + """Validate that 'value' is an integer (or basestring representation).""" if isinstance(value, int): return value elif isinstance(value, str): @@ -227,7 +227,7 @@ def validate_non_negative_integer(option: str, value: Any) -> int: def validate_readable(option: str, value: Any) -> str | None: - """Validates that 'value' is file-like and readable.""" + """Validate that 'value' is file-like and readable.""" if value is None: return value # First make sure its a string py3.3 open(True, 'r') succeeds @@ -245,21 +245,21 @@ def validate_non_negative_integer_or_none(option: str, value: Any) -> int | None def validate_string(option: str, value: Any) -> str: - """Validates that 'value' is an instance of `str`.""" + """Validate that 'value' is an instance of `str`.""" if isinstance(value, str): return value raise TypeError(f"Wrong type for {option}, value must be an instance of str, not {type(value)}") def validate_string_or_none(option: str, value: Any) -> str | None: - """Validates that 'value' is an instance of `basestring` or `None`.""" + """Validate that 'value' is an instance of `basestring` or `None`.""" if value is None: return value return validate_string(option, value) def validate_non_negative_int_or_basestring(option: Any, value: Any) -> int | str: - """Validates that 'value' is an integer or string.""" + """Validate that 'value' is an integer or string.""" if isinstance(value, int): return value elif isinstance(value, str): @@ -274,9 +274,7 @@ def validate_non_negative_int_or_basestring(option: Any, value: Any) -> int | st def validate_positive_float(option: str, value: Any) -> float: - """Validates that 'value' is a float, or can be converted to one, and is - positive. - """ + """Validate that 'value' is a float, or can be converted to one, and is positive.""" errmsg = f"{option} must be an integer or float" try: value = float(value) @@ -293,28 +291,25 @@ def validate_positive_float(option: str, value: Any) -> float: def validate_positive_float_or_zero(option: str, value: Any) -> float: - """Validates that 'value' is 0 or a positive float, or can be converted to - 0 or a positive float. - """ + """Validate that 'value' is 0 or a positive float, or can be converted to either.""" if value in (0, "0"): return 0 return validate_positive_float(option, value) def validate_timeout_or_none(option: str, value: Any) -> float | None: - """Validates a timeout specified in milliseconds returning - a value in floating point seconds. - """ + """Validate a timeout specified in milliseconds returning a value in floating point seconds.""" if value is None: return value return validate_positive_float(option, value) / 1000.0 def validate_timeout_or_zero(option: str, value: Any) -> float: - """Validates a timeout specified in milliseconds returning - a value in floating point seconds for the case where None is an error - and 0 is valid. Setting the timeout to nothing in the URI string is a - config error. + """Validate a timeout specified in milliseconds. + + Returns a value in floating point seconds for the case where None is + an error and 0 is valid. Setting the timeout to nothing in the URI + string is a config error. """ if value is None: raise ConfigurationError(f"{option} cannot be None") @@ -324,9 +319,10 @@ def validate_timeout_or_zero(option: str, value: Any) -> float: def validate_timeout_or_none_or_zero(option: Any, value: Any) -> float | None: - """Validates a timeout specified in milliseconds returning - a value in floating point seconds. value=0 and value="0" are treated the - same as value=None which means unlimited timeout. + """Validate a timeout specified in milliseconds. + + Returns a value in floating point seconds. value=0 and value="0" are + treated the same as value=None which means unlimited timeout. """ if value in (None, 0, "0"): return None @@ -334,16 +330,14 @@ def validate_timeout_or_none_or_zero(option: Any, value: Any) -> float | None: def validate_timeoutms(option: Any, value: Any) -> float | None: - """Validates a timeout specified in milliseconds returning - a value in floating point seconds. - """ + """Validate a timeout specified in milliseconds returning a value in floating point seconds.""" if value is None: return None return validate_positive_float_or_zero(option, value) / 1000.0 def validate_max_staleness(option: str, value: Any) -> int: - """Validates maxStalenessSeconds according to the Max Staleness Spec.""" + """Validate maxStalenessSeconds according to the Max Staleness Spec.""" if value in (-1, "-1"): # Default: No maximum staleness. return -1 @@ -538,21 +532,21 @@ def validate_type_registry(option: Any, value: Any) -> TypeRegistry | None: def validate_list(option: str, value: Any) -> list[Any]: - """Validates that 'value' is a list.""" + """Validate that 'value' is a list.""" if not isinstance(value, list): raise TypeError(f"{option} must be a list, not {type(value)}") return value def validate_list_or_none(option: Any, value: Any) -> list[Any] | None: - """Validates that 'value' is a list or None.""" + """Validate that 'value' is a list or None.""" if value is None: return value return validate_list(option, value) def validate_list_or_mapping(option: Any, value: Any) -> None: - """Validates that 'value' is a list or a document.""" + """Validate that 'value' is a list or a document.""" if not isinstance(value, (abc.Mapping, list)): raise TypeError( f"{option} must either be a list or an instance of dict, " @@ -612,7 +606,7 @@ def validate_server_api_or_none(option: Any, value: Any) -> ServerApi | None: def validate_is_callable_or_none(option: Any, value: Any) -> Callable[..., Any] | None: - """Validates that 'value' is a callable.""" + """Validate that 'value' is a callable.""" if value is None: return value if not callable(value): @@ -658,7 +652,7 @@ def validate_unicode_decode_error_handler(dummy: Any, value: str) -> str: def validate_tzinfo(dummy: Any, value: Any) -> datetime.tzinfo | None: - """Validate the tzinfo option""" + """Validate the tzinfo option.""" if value is not None and not isinstance(value, datetime.tzinfo): raise TypeError(f"{value} must be an instance of datetime.tzinfo") return value @@ -849,7 +843,7 @@ def _get_validator( def validate(option: str, value: Any) -> tuple[str, Any]: - """Generic validation function.""" + """Validate a generic option and value pair.""" validator = _get_validator(option, VALIDATORS, normed_key=option.lower()) value = validator(option, value) return option, value @@ -859,6 +853,7 @@ def get_validated_options( options: Mapping[str, Any], warn: bool = True ) -> MutableMapping[str, Any]: """Validate each entry in options and raise a warning if it is not valid. + Returns a copy of options with invalid entries removed. :param opts: A dict containing MongoDB URI options. @@ -919,8 +914,7 @@ def _ecoc_coll_name(encrypted_fields: Mapping[str, Any], name: str) -> Any: class BaseObject: - """A base class that provides attributes and methods common - to multiple pymongo classes. + """A base class providing attributes and methods common to pymongo classes. SHOULD NOT BE USED BY DEVELOPERS EXTERNAL TO MONGODB. """ @@ -958,15 +952,12 @@ def __init__( @property def codec_options(self) -> CodecOptions[Any]: - """Read only access to the :class:`~bson.codec_options.CodecOptions` - of this instance. - """ + """Read only access to the :class:`~bson.codec_options.CodecOptions` of this instance.""" return self._codec_options @property def write_concern(self) -> WriteConcern: - """Read only access to the :class:`~pymongo.write_concern.WriteConcern` - of this instance. + """Read only access to the :class:`~pymongo.write_concern.WriteConcern` of this instance. .. versionchanged:: 3.0 The :attr:`write_concern` attribute is now read only. @@ -1007,8 +998,7 @@ def _read_preference_for(self, session: _AgnosticClientSession | None) -> _Serve @property def read_concern(self) -> ReadConcern: - """Read only access to the :class:`~pymongo.read_concern.ReadConcern` - of this instance. + """Read only access to the :class:`~pymongo.read_concern.ReadConcern` of this instance. .. versionadded:: 3.2 """ @@ -1104,7 +1094,7 @@ def cased_key(self, key: str) -> Any: def has_c() -> bool: - """Is the C extension installed?""" + """Check if the C extension is installed.""" try: from pymongo import _cmessage # type: ignore[attr-defined] # noqa: F401 diff --git a/pymongo/cursor_shared.py b/pymongo/cursor_shared.py index 6fdf784750..fcbb416f78 100644 --- a/pymongo/cursor_shared.py +++ b/pymongo/cursor_shared.py @@ -69,8 +69,8 @@ def _split_message( class _AgnosticCursorBase(ABC, Generic[_DocumentType]): - """ - Shared IO-agnostic cursor base used by both async and sync cursor classes. + """Shared IO-agnostic cursor base used by both async and sync cursor classes. + All IO-specific behavior is implemented in subclasses. """ @@ -105,7 +105,7 @@ def __del__(self) -> None: @property def alive(self) -> bool: - """Does this cursor have the potential to return more data? + """Check whether this cursor has the potential to return more data. This is mostly useful with `tailable cursors `_ @@ -160,7 +160,7 @@ def _prepare_to_die(self, already_killed: bool) -> tuple[int, _CursorAddress | N return cursor_id, address def _die_no_lock(self) -> None: - """Closes this cursor without acquiring a lock.""" + """Close this cursor without acquiring a lock.""" try: already_killed = self._killed except AttributeError: @@ -179,9 +179,10 @@ def _die_no_lock(self) -> None: class _AgnosticCommandCursorBase(_AgnosticCursorBase[_DocumentType]): """An agnostic cursor / iterator over command cursors. - Used by aggregate, list_indexes, list_search_indexes, list_collections, cursor_command, - and list_databases helpers on both synchronous and asynchronous APIs to iterate MongoDB - command results. + + Used by aggregate, list_indexes, list_search_indexes, list_collections, + cursor_command, and list_databases helpers on both synchronous and + asynchronous APIs to iterate MongoDB command results. Should not be called directly by application developers. """ @@ -234,9 +235,10 @@ def _get_namespace(self) -> str: return self._ns def batch_size(self, batch_size: int) -> Self: - """Limits the number of documents returned in one batch. Each batch - requires a round trip to the server. It can be adjusted to optimize - performance and limit data transfer. + """Limit the number of documents returned in one batch. + + Each batch requires a round trip to the server. It can be adjusted to + optimize performance and limit data transfer. .. note:: batch_size can not override MongoDB's internal limits on the amount of data it will return to the client in a single batch (i.e @@ -257,15 +259,14 @@ def batch_size(self, batch_size: int) -> Self: return self def _has_next(self) -> bool: - """Returns `True` if the cursor has documents remaining from the - previous batch. - """ + """Return `True` if the cursor has documents remaining from the previous batch.""" return len(self._data) > 0 @property def _post_batch_resume_token(self) -> Mapping[str, Any] | None: - """Retrieve the postBatchResumeToken from the response to a - changeStream aggregate or getMore. + """Retrieve the postBatchResumeToken from a changeStream response. + + Applies to a changeStream aggregate or getMore response. """ return self._postbatchresumetoken @@ -397,6 +398,7 @@ def __init__( let: Mapping[str, Any] | None = None, ) -> None: """Create a new cursor. + Used by a collection's ``find()`` method to iterate over MongoDB query results. Should not be called directly by application developers. @@ -544,7 +546,7 @@ def clone(self) -> Self: return self._clone(True) def _clone(self, deepcopy: bool = True, base: Any | None = None) -> Self: - """Internal clone helper.""" + """Return a new cursor with the same query and options.""" if not base: if self._session and not self._session._implicit: base = self._clone_base(self._session) @@ -586,7 +588,7 @@ def _clone(self, deepcopy: bool = True, base: Any | None = None) -> Self: return base def _clone_base(self, session: Any | None) -> Self: - """Creates an empty cursor object for information to be copied into.""" + """Create an empty cursor object for information to be copied into.""" return self.__class__(self._collection, session=session) def _query_spec(self) -> Mapping[str, Any]: @@ -661,8 +663,7 @@ def remove_option(self, mask: int) -> Self: return self def allow_disk_use(self, allow_disk_use: bool) -> Self: - """Specifies whether MongoDB can use temporary disk files while - processing a blocking sort operation. + """Specify whether MongoDB can use temporary disk files for a sort. Raises :exc:`TypeError` if `allow_disk_use` is not a boolean. @@ -704,9 +705,10 @@ def limit(self, limit: int) -> Self: return self def batch_size(self, batch_size: int) -> Self: - """Limits the number of documents returned in one batch. Each batch - requires a round trip to the server. It can be adjusted to optimize - performance and limit data transfer. + """Limit the number of documents returned in one batch. + + Each batch requires a round trip to the server. It can be adjusted to + optimize performance and limit data transfer. .. note:: batch_size can not override MongoDB's internal limits on the amount of data it will return to the client in a single batch (i.e @@ -751,8 +753,9 @@ def skip(self, skip: int) -> Self: return self def max_time_ms(self, max_time_ms: int | None) -> Self: - """Specifies a time limit for a query operation. If the specified - time is exceeded, the operation will be aborted and + """Specify a time limit for a query operation. + + If the specified time is exceeded, the operation will be aborted and :exc:`~pymongo.errors.ExecutionTimeout` is raised. If `max_time_ms` is ``None`` no limit is applied. @@ -770,9 +773,10 @@ def max_time_ms(self, max_time_ms: int | None) -> Self: return self def max_await_time_ms(self, max_await_time_ms: int | None) -> Self: - """Specifies a time limit for a getMore operation on a - :attr:`~pymongo.cursor.CursorType.TAILABLE_AWAIT` cursor. For all other - types of cursor max_await_time_ms is ignored. + """Specify a time limit for a getMore operation. + + The limit applies to a :attr:`~pymongo.cursor.CursorType.TAILABLE_AWAIT` + cursor. For all other types of cursor max_await_time_ms is ignored. Raises :exc:`TypeError` if `max_await_time_ms` is not an integer or ``None``. Raises :exc:`~pymongo.errors.InvalidOperation` if this @@ -798,11 +802,10 @@ def max_await_time_ms(self, max_await_time_ms: int | None) -> Self: return self def max_scan(self, max_scan: int | None) -> Self: - """**DEPRECATED** - Limit the number of documents to scan when - performing the query. + """Limit the number of documents to scan when performing the query. - Raises :class:`~pymongo.errors.InvalidOperation` if this - cursor has already been used. Only the last :meth:`max_scan` + **DEPRECATED**. Raises :class:`~pymongo.errors.InvalidOperation` if + this cursor has already been used. Only the last :meth:`max_scan` applied to this cursor has any effect. :param max_scan: the maximum number of documents to scan @@ -817,7 +820,7 @@ def max_scan(self, max_scan: int | None) -> Self: return self def max(self, spec: _Sort) -> Self: - """Adds ``max`` operator that specifies upper bound for specific index. + """Add a ``max`` operator specifying the upper bound for a specific index. When using ``max``, :meth:`~hint` is required to ensure the query uses the expected index. @@ -838,7 +841,7 @@ def max(self, spec: _Sort) -> Self: return self def min(self, spec: _Sort) -> Self: - """Adds ``min`` operator that specifies lower bound for specific index. + """Add a ``min`` operator specifying the lower bound for a specific index. When using ``min``, :meth:`~hint` is required to ensure the query uses the expected index. @@ -932,7 +935,7 @@ def _set_hint(self, index: _Hint | None) -> None: self._hint = helpers_shared._index_document(index) def hint(self, index: _Hint | None) -> Self: - """Adds a 'hint', telling Mongo the proper index to use for the query. + """Add a 'hint', telling Mongo the proper index to use for the query. Judicious use of hints can greatly improve query performance. When doing a query on multiple fields (at least @@ -955,7 +958,7 @@ def hint(self, index: _Hint | None) -> Self: return self def comment(self, comment: Any) -> Self: - """Adds a 'comment' to the cursor. + """Add a 'comment' to the cursor. http://mongodb.com/docs/manual/reference/operator/comment/ @@ -969,7 +972,7 @@ def comment(self, comment: Any) -> Self: return self def where(self, code: str | Code) -> Self: - """Adds a `$where`_ clause to this query. + """Add a `$where`_ clause to this query. The `code` argument must be an instance of :class:`str` or :class:`~bson.code.Code` containing a JavaScript expression. @@ -1016,7 +1019,7 @@ def where(self, code: str | Code) -> Self: return self def collation(self, collation: _CollationIn | None) -> Self: - """Adds a :class:`~pymongo.collation.Collation` to this query. + """Add a :class:`~pymongo.collation.Collation` to this query. Raises :exc:`TypeError` if `collation` is not an instance of :class:`~pymongo.collation.Collation` or a ``dict``. Raises diff --git a/pymongo/encryption_shared.py b/pymongo/encryption_shared.py index 28909f428b..cd5e73d2f3 100644 --- a/pymongo/encryption_shared.py +++ b/pymongo/encryption_shared.py @@ -50,8 +50,10 @@ def _wrap_encryption_errors() -> Iterator[None]: class RewrapManyDataKeyResult: - """Result object returned by a - :meth:`~pymongo.encryption.ClientEncryption.rewrap_many_data_key` or :meth:`~pymongo.asynchronous.encryption.AsyncClientEncryption.rewrap_many_data_key` operation. + """Result of a rewrap_many_data_key operation. + + Returned by :meth:`~pymongo.encryption.ClientEncryption.rewrap_many_data_key` or + :meth:`~pymongo.asynchronous.encryption.AsyncClientEncryption.rewrap_many_data_key`. .. versionadded:: 4.2 """ @@ -61,8 +63,9 @@ def __init__(self, bulk_write_result: BulkWriteResult | None = None) -> None: @property def bulk_write_result(self) -> BulkWriteResult | None: - """The result of the bulk write operation used to update the key vault - collection with one or more rewrapped data keys. If + """The result of the bulk write used to update the key vault collection. + + The bulk write updates the key vault collection with one or more rewrapped data keys. If :meth:`~pymongo.encryption.ClientEncryption.rewrap_many_data_key` or :meth:`~pymongo.asynchronous.encryption.AsyncClientEncryption.rewrap_many_data_key` does not find any matching keys to rewrap, no bulk write operation will be executed and this field will be ``None``. diff --git a/pymongo/errors.py b/pymongo/errors.py index 70d436923c..d5a029dd9a 100644 --- a/pymongo/errors.py +++ b/pymongo/errors.py @@ -85,8 +85,9 @@ def timeout(self) -> bool: class AutoReconnect(ConnectionFailure): - """Raised when a connection to the database is lost and an attempt to - auto-reconnect will be made. + """Raised when a connection to the database is lost. + + An attempt to auto-reconnect will be made. In order to auto-reconnect you must handle this exception, recognizing that the operation which caused it has not necessarily succeeded. Future @@ -154,7 +155,7 @@ def __init__( class ServerSelectionTimeoutError(AutoReconnect): - """Thrown when no MongoDB server is available for an operation + """Thrown when no MongoDB server is available for an operation. If there is no suitable server for an operation PyMongo tries for ``serverSelectionTimeoutMS`` (default 30 seconds) to find one, then @@ -230,16 +231,17 @@ def _base_backoff_ms(self) -> float | None: class CursorNotFound(OperationFailure): - """Raised while iterating query results if the cursor is - invalidated on the server. + """Raised while iterating query results if the cursor is invalidated on the server. .. versionadded:: 2.7 """ class ExecutionTimeout(OperationFailure): - """Raised when a database operation times out, exceeding the $maxTimeMS - set in the query or command option. + """Raised when a database operation times out. + + The operation exceeded the $maxTimeMS set in the query or command + option. .. note:: Requires server version **>= 2.6.0** @@ -266,8 +268,7 @@ class WriteError(OperationFailure): class WTimeoutError(WriteConcernError): - """Raised when a database operation times out (i.e. wtimeout expires) - before replication completes. + """Raised when a database operation times out (wtimeout expires) before replication completes. With newer versions of MongoDB the `details` attribute may include write concern fields like 'n', 'updatedExisting', or 'writtenTo'. @@ -330,11 +331,11 @@ def __reduce__(self) -> tuple[Any, Any]: @property def error(self) -> Any | None: - """A top-level error that occurred when attempting to - communicate with the server or execute the bulk write. + """A top-level error that occurred during this operation. - This value may not be populated if the exception was - thrown due to errors occurring on individual writes. + The error occurred when attempting to communicate with the server + or execute the bulk write. This value may not be populated if the + exception was thrown due to errors occurring on individual writes. """ return self.details.get("error", None) @@ -357,8 +358,10 @@ def write_errors(self) -> list[WriteError] | None: @property def partial_result(self) -> ClientBulkWriteResult | None: - """The results of any successful operations that were - performed before the error was encountered. + """The results of successful operations performed before the error. + + The results are from operations that ran before the error was + encountered. """ from pymongo.results import ClientBulkWriteResult diff --git a/pymongo/helpers_shared.py b/pymongo/helpers_shared.py index 594f55fb26..1961b46e85 100644 --- a/pymongo/helpers_shared.py +++ b/pymongo/helpers_shared.py @@ -196,7 +196,7 @@ def _gen_index_name(keys: _IndexList) -> str: def _index_list( key_or_list: _Hint, direction: int | str | None = None ) -> Sequence[tuple[str, int | str | Mapping[str, Any]]]: - """Helper to generate a list of (key, direction) pairs. + """Generate a list of (key, direction) pairs. Takes such a list, or a single key, or a single key and direction. """ @@ -224,7 +224,7 @@ def _index_list( def _index_document(index_list: _IndexList) -> dict[str, Any]: - """Helper to generate an index specifying document. + """Generate an index specifying document. Takes a list of (key, direction) pairs. """ @@ -371,7 +371,7 @@ def _check_write_command_response(result: Mapping[str, Any]) -> None: def _fields_list_to_dict( fields: Mapping[str, Any] | Iterable[str], option_name: str ) -> Mapping[str, Any]: - """Takes a sequence of field names and returns a matching dictionary. + """Convert a sequence of field names into a matching dictionary. ["a", "b"] becomes {"a": 1, "b": 1} diff --git a/pymongo/lock.py b/pymongo/lock.py index 9f844bf8e3..36df97c5af 100644 --- a/pymongo/lock.py +++ b/pymongo/lock.py @@ -42,8 +42,9 @@ def _create_lock() -> threading.Lock: - """Represents a lock that is tracked upon instantiation using a WeakSet and - reset by pymongo upon forking. + """Create a lock that is tracked upon instantiation using a WeakSet. + + The lock is reset by pymongo upon forking. """ lock = threading.Lock() if _HAS_REGISTER_AT_FORK: @@ -52,21 +53,21 @@ def _create_lock() -> threading.Lock: def _async_create_lock() -> Lock: - """Represents an asyncio.Lock.""" + """Create an asyncio.Lock.""" return Lock() def _create_condition( lock: threading.Lock, condition_class: Any | None = None ) -> threading.Condition: - """Represents a threading.Condition.""" + """Create a threading.Condition.""" if condition_class: return condition_class(lock) return threading.Condition(lock) def _async_create_condition(lock: Lock, condition_class: Any | None = None) -> Condition: - """Represents an asyncio.Condition.""" + """Create an asyncio.Condition.""" if condition_class: return condition_class(lock) return Condition(lock) diff --git a/pymongo/message.py b/pymongo/message.py index 18c4ae162a..73426d35e4 100644 --- a/pymongo/message.py +++ b/pymongo/message.py @@ -12,9 +12,10 @@ # See the License for the specific language governing permissions and # limitations under the License. -"""Tools for creating `messages -`_ to be sent to -MongoDB. +"""Tools for creating messages to be sent to MongoDB. + +The messages follow the `MongoDB wire protocol +`_. .. note:: This module is for internal use and is generally not needed by application developers. @@ -132,8 +133,9 @@ def _convert_exception(exception: Exception) -> dict[str, Any]: def _convert_client_bulk_exception(exception: Exception) -> dict[str, Any]: - """Convert an Exception into a failure document for publishing, - for use in client-level bulk write API. + """Convert an Exception into a failure document for publishing. + + Used in the client-level bulk write API. """ return { "errmsg": str(exception), @@ -247,7 +249,7 @@ def _gen_get_more_command( def _compress( operation: int, data: bytes, ctx: SnappyContext | ZlibContext | ZstdContext ) -> tuple[int, bytes]: - """Takes message data, compresses it, and adds an OP_COMPRESSED header.""" + """Compress the message data and add an OP_COMPRESSED header.""" compressed = ctx.compress(data) request_id = _randint() @@ -267,7 +269,7 @@ def _compress( def __pack_message(operation: int, data: bytes) -> tuple[int, bytes]: - """Takes message data and adds a message header based on the operation. + """Add a message header to the message data based on the operation. Returns the resultant message string. """ @@ -321,7 +323,7 @@ def _op_msg_compressed( opts: CodecOptions[Any], ctx: SnappyContext | ZlibContext | ZstdContext, ) -> tuple[int, bytes, int, int]: - """Internal OP_MSG message helper.""" + """Build a compressed OP_MSG message (internal helper).""" msg, total_size, max_bson_size = _op_msg_no_header(flags, command, identifier, docs, opts) rid, msg = _compress(2013, msg, ctx) return rid, msg, total_size, max_bson_size @@ -334,7 +336,7 @@ def _op_msg_uncompressed( docs: list[Mapping[str, Any]] | None, opts: CodecOptions[Any], ) -> tuple[int, bytes, int, int]: - """Internal compressed OP_MSG message helper.""" + """Build an uncompressed OP_MSG message (internal helper).""" data, total_size, max_bson_size = _op_msg_no_header(flags, command, identifier, docs, opts) request_id, op_message = __pack_message(2013, data) return request_id, op_message, total_size, max_bson_size @@ -512,7 +514,7 @@ def max_split_size(self) -> int: def _raise_document_too_large(operation: str, doc_size: int, max_size: int) -> NoReturn: - """Internal helper for raising DocumentTooLarge.""" + """Raise DocumentTooLarge.""" if operation == "insert": raise DocumentTooLarge( f"BSON document too large ({doc_size} bytes)" @@ -607,9 +609,7 @@ def _encode_batched_op_msg( opts: CodecOptions[Any], ctx: _BulkWriteContext, ) -> tuple[bytes, list[Mapping[str, Any]]]: - """Encode the next batched insert, update, or delete operation - as OP_MSG. - """ + """Encode the next batched insert, update, or delete operation as OP_MSG.""" buf = _BytesIO() to_send, _ = _batched_op_msg_impl(operation, command, docs, ack, opts, ctx, buf) @@ -628,9 +628,7 @@ def _batched_op_msg_compressed( opts: CodecOptions[Any], ctx: _BulkWriteContext, ) -> tuple[int, bytes, list[Mapping[str, Any]]]: - """Create the next batched insert, update, or delete operation - with OP_MSG, compressed. - """ + """Create the next batched insert, update, or delete operation with OP_MSG, compressed.""" data, to_send = _encode_batched_op_msg(operation, command, docs, ack, opts, ctx) assert ctx.conn.compression_context is not None @@ -678,9 +676,7 @@ def _do_batched_op_msg( opts: CodecOptions[Any], ctx: _BulkWriteContext, ) -> tuple[int, bytes, list[Mapping[str, Any]]]: - """Create the next batched insert, update, or delete operation - using OP_MSG. - """ + """Create the next batched insert, update, or delete operation using OP_MSG.""" command["$db"] = namespace.split(".", 1)[0] if "writeConcern" in command: ack = bool(command["writeConcern"].get("w", 1)) @@ -905,9 +901,7 @@ def _client_encode_batched_op_msg( opts: CodecOptions[Any], ctx: _ClientBulkWriteContext, ) -> tuple[bytes, list[Mapping[str, Any]], list[Mapping[str, Any]]]: - """Encode the next batched client-level bulkWrite - operation as OP_MSG. - """ + """Encode the next batched client-level bulkWrite operation as OP_MSG.""" buf = _BytesIO() to_send_ops, to_send_ns, _ = _client_batched_op_msg_impl( @@ -924,9 +918,7 @@ def _client_batched_op_msg_compressed( opts: CodecOptions[Any], ctx: _ClientBulkWriteContext, ) -> tuple[int, bytes, list[Mapping[str, Any]], list[Mapping[str, Any]]]: - """Create the next batched client-level bulkWrite operation - with OP_MSG, compressed. - """ + """Create the next batched client-level bulkWrite operation with OP_MSG, compressed.""" data, to_send_ops, to_send_ns = _client_encode_batched_op_msg( command, operations, namespaces, ack, opts, ctx ) @@ -973,9 +965,7 @@ def _client_do_batched_op_msg( opts: CodecOptions[Any], ctx: _ClientBulkWriteContext, ) -> tuple[int, bytes, list[Mapping[str, Any]], list[Mapping[str, Any]]]: - """Create the next batched client-level bulkWrite - operation using OP_MSG. - """ + """Create the next batched client-level bulkWrite operation using OP_MSG.""" command["$db"] = "admin" if "writeConcern" in command: ack = bool(command["writeConcern"].get("w", 1)) @@ -1103,9 +1093,10 @@ def raw_response( cursor_id: int | None = None, user_fields: Mapping[str, Any] | None = {}, ) -> list[Mapping[str, Any]]: - """ - cursor_id is ignored - user_fields is used to determine which fields must not be decoded + """Return the raw response. + + cursor_id is ignored. user_fields is used to determine which fields + must not be decoded. """ inflated_response = bson._decode_selective( RawBSONDocument(self.payload_document), user_fields, _RAW_ARRAY_BSON_OPTIONS @@ -1142,7 +1133,7 @@ def raw_command_response(self) -> bytes | memoryview: @property def more_to_come(self) -> bool: - """Is the moreToCome bit set on this response?""" + """Whether the moreToCome bit is set on this response.""" return bool(self.flags & self.MORE_TO_COME) @classmethod @@ -1305,7 +1296,7 @@ def as_command( def get_message( self, read_preference: _ServerMode, conn: _AgnosticConnection ) -> tuple[int, bytes, int]: - """Get a query message""" + """Get a query message.""" # Use the read_preference decided by _socket_from_server. self.read_preference = read_preference diff --git a/pymongo/mongo_client_shared.py b/pymongo/mongo_client_shared.py index f0578f2de0..381fc8a22a 100644 --- a/pymongo/mongo_client_shared.py +++ b/pymongo/mongo_client_shared.py @@ -94,9 +94,7 @@ def _add_retryable_write_error(exc: PyMongoError) -> None: def _after_fork_child(clients: Mapping[Any, Any]) -> None: - """Releases the locks in child process and resets the - topologies in the passed clients. - """ + """Releases the locks in child process and resets the topologies in the passed clients.""" # Reinitialize locks _release_locks() @@ -106,7 +104,7 @@ def _after_fork_child(clients: Mapping[Any, Any]) -> None: def _detect_external_db(entity: str) -> bool: - """Detects external database hosts and logs an informational message at the INFO level.""" + """Detect external database hosts and log an informational message at the INFO level.""" entity = entity.lower() cosmos_db_hosts = [".cosmos.azure.com"] document_db_hosts = [".docdb.amazonaws.com", ".docdb-elastic.amazonaws.com"] @@ -131,7 +129,7 @@ def _detect_external_db(entity: str) -> bool: class _AgnosticClientConnectionRetryableBase(Generic[T, _ServerT, _FuncT]): - """Responsible for executing retryable connections on read or write operations""" + """Responsible for executing retryable connections on read or write operations.""" __slots__ = ( "_address", @@ -205,17 +203,17 @@ def __init__( self._conn_mgr = conn_mgr def _is_not_eligible_for_retry(self) -> bool: - """Checks if the exchange is not eligible for retry""" + """Check if the exchange is not eligible for retry.""" return not self._retryable or ( self._is_retrying() and self._attempt_number >= self._max_retries ) def _is_retrying(self) -> bool: - """Checks if the exchange is currently undergoing a retry""" + """Check if the exchange is currently undergoing a retry.""" return self._bulk.retrying if self._bulk else self._retrying def _is_session_state_retryable(self) -> bool: - """Checks if provided session is eligible for retry + """Check if provided session is eligible for retry. reads: Make sure there is no ongoing transaction (if provided a session) writes: Make sure there is a session without an active transaction @@ -225,8 +223,9 @@ def _is_session_state_retryable(self) -> bool: return bool(self._session and not self._session.in_transaction) def _check_last_error(self, check_csot: bool = False) -> None: - """Checks if the ongoing client exchange experienced a exception previously. - If so, raise last error + """Check if the ongoing client exchange experienced an exception previously. + + If so, raise the last error. :param check_csot: Checks CSOT to ensure we are retrying with time remaining defaults to False """ diff --git a/pymongo/monitoring.py b/pymongo/monitoring.py index 52a63b7cd8..80543417e9 100644 --- a/pymongo/monitoring.py +++ b/pymongo/monitoring.py @@ -405,6 +405,7 @@ def failed(self, event: ServerHeartbeatFailedEvent) -> None: class TopologyListener(_EventListener): """Abstract base class for topology monitoring listeners. + Handles `TopologyOpenedEvent`, `TopologyDescriptionChangedEvent`, and `TopologyClosedEvent`. @@ -435,6 +436,7 @@ def closed(self, event: TopologyClosedEvent) -> None: class ServerListener(_EventListener): """Abstract base class for server listeners. + Handles `ServerOpeningEvent`, `ServerDescriptionChangedEvent`, and `ServerClosedEvent`. @@ -471,7 +473,7 @@ def _to_micros(dur: timedelta) -> int: def _validate_event_listeners( option: str, listeners: Sequence[_EventListeners] ) -> Sequence[_EventListeners]: - """Validate event listeners""" + """Validate event listeners.""" if not isinstance(listeners, abc.Sequence): raise TypeError(f"{option} must be a list or tuple, not {type(listeners)}") for listener in listeners: @@ -781,9 +783,7 @@ def __init__(self, address: _Address) -> None: @property def address(self) -> _Address: - """The address (host, port) pair of the server the pool is attempting - to connect to. - """ + """The address (host, port) pair of the server the pool is attempting to connect to.""" return self.__address def __repr__(self) -> str: @@ -884,8 +884,7 @@ class PoolClosedEvent(_PoolEvent): class ConnectionClosedReason: - """An enum that defines values for `reason` on a - :class:`ConnectionClosedEvent`. + """An enum that defines values for `reason` on a :class:`ConnectionClosedEvent`. .. versionadded:: 3.9 """ @@ -905,8 +904,7 @@ class ConnectionClosedReason: class ConnectionCheckOutFailedReason: - """An enum that defines values for `reason` on a - :class:`ConnectionCheckOutFailedEvent`. + """An enum that defines values for `reason` on a :class:`ConnectionCheckOutFailedEvent`. .. versionadded:: 3.9 """ @@ -933,9 +931,7 @@ def __init__(self, address: _Address) -> None: @property def address(self) -> _Address: - """The address (host, port) pair of the server this connection is - attempting to connect to. - """ + """The (host, port) pair of the server this connection is attempting to connect to.""" return self.__address def __repr__(self) -> str: @@ -1118,7 +1114,7 @@ def __init__(self, server_address: _Address, topology_id: ObjectId) -> None: @property def server_address(self) -> _Address: - """The address (host, port) pair of the server""" + """The address (host, port) pair of the server.""" return self.__server_address @property @@ -1150,16 +1146,12 @@ def __init__( @property def previous_description(self) -> ServerDescription: - """The previous - :class:`~pymongo.server_description.ServerDescription`. - """ + """The previous :class:`~pymongo.server_description.ServerDescription`.""" return self.__previous_description @property def new_description(self) -> ServerDescription: - """The new - :class:`~pymongo.server_description.ServerDescription`. - """ + """The new :class:`~pymongo.server_description.ServerDescription`.""" return self.__new_description def __repr__(self) -> str: @@ -1221,16 +1213,12 @@ def __init__( @property def previous_description(self) -> TopologyDescription: - """The previous - :class:`~pymongo.topology_description.TopologyDescription`. - """ + """The previous :class:`~pymongo.topology_description.TopologyDescription`.""" return self.__previous_description @property def new_description(self) -> TopologyDescription: - """The new - :class:`~pymongo.topology_description.TopologyDescription`. - """ + """The new :class:`~pymongo.topology_description.TopologyDescription`.""" return self.__new_description def __repr__(self) -> str: @@ -1266,9 +1254,7 @@ def __init__(self, connection_id: _Address, awaited: bool = False) -> None: @property def connection_id(self) -> _Address: - """The address (host, port) of the server this heartbeat was sent - to. - """ + """The address (host, port) of the server this heartbeat was sent to.""" return self.__connection_id @property @@ -1338,8 +1324,7 @@ def __repr__(self) -> str: class ServerHeartbeatFailedEvent(_ServerHeartbeatEvent): - """Fired when the server heartbeat fails, either with an "ok: 0" - or a socket exception. + """Fired when the server heartbeat fails, either with an "ok: 0" or a socket exception. .. versionadded:: 3.3 """ @@ -1414,27 +1399,27 @@ def __init__(self, listeners: Sequence[_EventListener] | None): @property def enabled_for_commands(self) -> bool: - """Are any CommandListener instances registered?""" + """Whether any CommandListener instances are registered.""" return self.__enabled_for_commands @property def enabled_for_server(self) -> bool: - """Are any ServerListener instances registered?""" + """Whether any ServerListener instances are registered.""" return self.__enabled_for_server @property def enabled_for_server_heartbeat(self) -> bool: - """Are any ServerHeartbeatListener instances registered?""" + """Whether any ServerHeartbeatListener instances are registered.""" return self.__enabled_for_server_heartbeat @property def enabled_for_topology(self) -> bool: - """Are any TopologyListener instances registered?""" + """Whether any TopologyListener instances are registered.""" return self.__enabled_for_topology @property def enabled_for_cmap(self) -> bool: - """Are any ConnectionPoolListener instances registered?""" + """Whether any ConnectionPoolListener instances are registered.""" return self.__enabled_for_cmap def event_listeners(self) -> list[_EventListeners]: @@ -1579,8 +1564,7 @@ def publish_command_failure( _handle_exception() def publish_server_heartbeat_started(self, connection_id: _Address, awaited: bool) -> None: - """Publish a ServerHeartbeatStartedEvent to all server heartbeat - listeners. + """Publish a ServerHeartbeatStartedEvent to all server heartbeat listeners. :param connection_id: The address (host, port) pair of the connection. :param awaited: True if this heartbeat is part of an awaitable hello command. @@ -1595,8 +1579,7 @@ def publish_server_heartbeat_started(self, connection_id: _Address, awaited: boo def publish_server_heartbeat_succeeded( self, connection_id: _Address, duration: float, reply: Hello[dict[str, Any]], awaited: bool ) -> None: - """Publish a ServerHeartbeatSucceededEvent to all server heartbeat - listeners. + """Publish a ServerHeartbeatSucceededEvent to all server heartbeat listeners. :param connection_id: The address (host, port) pair of the connection. :param duration: The execution time of the event in the highest possible @@ -1614,8 +1597,7 @@ def publish_server_heartbeat_succeeded( def publish_server_heartbeat_failed( self, connection_id: _Address, duration: float, reply: Exception, awaited: bool ) -> None: - """Publish a ServerHeartbeatFailedEvent to all server heartbeat - listeners. + """Publish a ServerHeartbeatFailedEvent to all server heartbeat listeners. :param connection_id: The address (host, port) pair of the connection. :param duration: The execution time of the event in the highest possible @@ -1770,9 +1752,7 @@ def publish_pool_closed(self, address: _Address) -> None: _handle_exception() def publish_connection_created(self, address: _Address, connection_id: int) -> None: - """Publish a :class:`ConnectionCreatedEvent` to all connection - listeners. - """ + """Publish a :class:`ConnectionCreatedEvent` to all connection listeners.""" event = ConnectionCreatedEvent(address, connection_id) for subscriber in self.__cmap_listeners: try: @@ -1792,9 +1772,7 @@ def publish_connection_ready( _handle_exception() def publish_connection_closed(self, address: _Address, connection_id: int, reason: str) -> None: - """Publish a :class:`ConnectionClosedEvent` to all connection - listeners. - """ + """Publish a :class:`ConnectionClosedEvent` to all connection listeners.""" event = ConnectionClosedEvent(address, connection_id, reason) for subscriber in self.__cmap_listeners: try: @@ -1803,9 +1781,7 @@ def publish_connection_closed(self, address: _Address, connection_id: int, reaso _handle_exception() def publish_connection_check_out_started(self, address: _Address) -> None: - """Publish a :class:`ConnectionCheckOutStartedEvent` to all connection - listeners. - """ + """Publish a :class:`ConnectionCheckOutStartedEvent` to all connection listeners.""" event = ConnectionCheckOutStartedEvent(address) for subscriber in self.__cmap_listeners: try: @@ -1816,9 +1792,7 @@ def publish_connection_check_out_started(self, address: _Address) -> None: def publish_connection_check_out_failed( self, address: _Address, reason: str, duration: float ) -> None: - """Publish a :class:`ConnectionCheckOutFailedEvent` to all connection - listeners. - """ + """Publish a :class:`ConnectionCheckOutFailedEvent` to all connection listeners.""" event = ConnectionCheckOutFailedEvent(address, reason, duration) for subscriber in self.__cmap_listeners: try: @@ -1829,9 +1803,7 @@ def publish_connection_check_out_failed( def publish_connection_checked_out( self, address: _Address, connection_id: int, duration: float ) -> None: - """Publish a :class:`ConnectionCheckedOutEvent` to all connection - listeners. - """ + """Publish a :class:`ConnectionCheckedOutEvent` to all connection listeners.""" event = ConnectionCheckedOutEvent(address, connection_id, duration) for subscriber in self.__cmap_listeners: try: @@ -1840,9 +1812,7 @@ def publish_connection_checked_out( _handle_exception() def publish_connection_checked_in(self, address: _Address, connection_id: int) -> None: - """Publish a :class:`ConnectionCheckedInEvent` to all connection - listeners. - """ + """Publish a :class:`ConnectionCheckedInEvent` to all connection listeners.""" event = ConnectionCheckedInEvent(address, connection_id) for subscriber in self.__cmap_listeners: try: diff --git a/pymongo/network_layer.py b/pymongo/network_layer.py index 931ec26112..a82dff7d6c 100644 --- a/pymongo/network_layer.py +++ b/pymongo/network_layer.py @@ -477,8 +477,10 @@ def gettimeout(self) -> float | None: return self._timeout def connection_made(self, transport: BaseTransport) -> None: - """Called exactly once when a connection is made. - The transport argument is the transport representing the write side of the connection. + """Handle a new connection. + + Called exactly once when a connection is made. The transport argument is + the transport representing the write side of the connection. """ self.transport = transport # type: ignore[assignment] self.transport.set_write_buffer_limits(MAX_MESSAGE_SIZE, MAX_MESSAGE_SIZE) @@ -525,7 +527,8 @@ async def read(self, request_id: int | None, max_message_size: int) -> tuple[byt raise OSError("connection closed") def get_buffer(self, sizehint: int) -> memoryview: - """Called to allocate a new receive buffer. + """Allocate a new receive buffer. + The asyncio loop calls this method expecting to receive a non-empty buffer to fill with data. If any data does not fit into the returned buffer, this method will be called again until either no data remains or an empty buffer is returned. @@ -546,7 +549,7 @@ def get_buffer(self, sizehint: int) -> memoryview: return self._message[self._message_index :] # type: ignore[index] def buffer_updated(self, nbytes: int) -> None: - """Called when the buffer was updated with the received data""" + """Handle received data once the buffer has been updated.""" # Wrote 0 bytes into a non-empty buffer, signal connection closed if nbytes == 0: self.close(OSError("connection closed")) diff --git a/pymongo/ocsp_support.py b/pymongo/ocsp_support.py index 9c7f3ecab8..5acb228756 100644 --- a/pymongo/ocsp_support.py +++ b/pymongo/ocsp_support.py @@ -351,7 +351,7 @@ def _get_ocsp_response( def _ocsp_callback(conn: Connection, ocsp_bytes: bytes, user_data: _CallbackData | None) -> bool: - """Callback for use with OpenSSL.SSL.Context.set_ocsp_client_callback.""" + """Act as the callback for use with OpenSSL.SSL.Context.set_ocsp_client_callback.""" # always pass in user_data but OpenSSL requires it be optional assert user_data cert = conn.get_peer_certificate(as_cryptography=True) diff --git a/pymongo/operations.py b/pymongo/operations.py index 1a737c05fc..9e7814c9b0 100644 --- a/pymongo/operations.py +++ b/pymongo/operations.py @@ -548,7 +548,7 @@ def __init__( namespace: str | None = None, sort: Mapping[str, Any] | None = None, ) -> None: - """Represents an update_one operation. + """Represent an update_one operation. For use with :meth:`~pymongo.asynchronous.collection.AsyncCollection.bulk_write`, :meth:`~pymongo.collection.Collection.bulk_write`, :meth:`~pymongo.asynchronous.mongo_client.AsyncMongoClient.bulk_write` and :meth:`~pymongo.mongo_client.MongoClient.bulk_write`. @@ -772,9 +772,7 @@ def __init__(self, keys: _IndexKeyHint, **kwargs: Any) -> None: @property def document(self) -> dict[str, Any]: - """An index document suitable for passing to the createIndexes - command. - """ + """An index document suitable for passing to the createIndexes command.""" return self.__document def __repr__(self) -> str: diff --git a/pymongo/pool_options.py b/pymongo/pool_options.py index 98ca7f657d..40a48a6f7a 100644 --- a/pymongo/pool_options.py +++ b/pymongo/pool_options.py @@ -106,7 +106,8 @@ def get_container_env_info() -> dict[str, str]: - """Returns the runtime and orchestrator of a container. + """Return the runtime and orchestrator of a container. + If neither value is present, the metadata client.env.container field will be omitted. """ container = {} @@ -491,7 +492,7 @@ def __init__( _truncate_metadata(self.__metadata) def _update_metadata(self, driver: DriverInfo) -> None: - """Updates the client's metadata.""" + """Update the client's metadata.""" with self.__metadata_lock: driver = _normalize_driver(driver) if driver in self.__appended_drivers: @@ -553,8 +554,9 @@ def non_default_options(self) -> dict[str, Any]: @property def max_pool_size(self) -> float: - """The maximum allowable number of concurrent connections to each - connected server. Requests to a server will block if there are + """The maximum allowable number of concurrent connections to each connected server. + + Requests to a server will block if there are `maxPoolSize` outstanding connections to the requested server. Defaults to 100. A value of 0 or ``None`` means no limit. @@ -568,16 +570,16 @@ def max_pool_size(self) -> float: @property def min_pool_size(self) -> int: - """The minimum required number of concurrent connections that the pool - will maintain to each connected server. Default is 0. + """The minimum required number of concurrent connections to each connected server. + + The pool will maintain at least this many connections to each + connected server. Default is 0. """ return self.__min_pool_size @property def max_connecting(self) -> int: - """The maximum number of concurrent connection creation attempts per - pool. Defaults to 2. - """ + """The maximum number of concurrent connection creation attempts per pool. Defaults to 2.""" return self.__max_connecting @property @@ -586,8 +588,9 @@ def pause_enabled(self) -> bool: @property def max_idle_time_seconds(self) -> int | None: - """The maximum number of seconds that a connection can remain - idle in the pool before being removed and replaced. Defaults to + """The maximum number of seconds that a connection can remain idle in the pool. + + The connection is removed and replaced after this time. Defaults to `None` (no limit). """ return self.__max_idle_time_seconds @@ -604,8 +607,9 @@ def socket_timeout(self) -> float | None: @property def wait_queue_timeout(self) -> int | None: - """How long a thread will wait for a socket from the pool if the pool - has no free sockets. + """How long a thread will wait for a socket from the pool. + + This only applies if the pool has no free sockets. """ return self.__wait_queue_timeout diff --git a/pymongo/pool_shared.py b/pymongo/pool_shared.py index a7a221f269..d5b1e0f02a 100644 --- a/pymongo/pool_shared.py +++ b/pymongo/pool_shared.py @@ -273,7 +273,8 @@ def __init__( is_sdam: bool = False, client_id: ObjectId | None = None, ): - """ + """Create a new pool. + :param address: a (hostname, port) tuple :param options: a PoolOptions instance :param is_sdam: whether to call hello for each new connection @@ -448,7 +449,7 @@ def _set_non_inheritable_non_atomic(fd: int) -> None: # (Jython, IronPython, ..), systems that don't provide # everything we need from fcntl, etc. def _set_non_inheritable_non_atomic(fd: int) -> None: - """Dummy function for platforms that don't provide fcntl.""" + """Do nothing on platforms that don't provide fcntl.""" _MAX_TCP_KEEPIDLE = 120 @@ -545,14 +546,12 @@ def cancel(self) -> None: @property def cancelled(self) -> bool: - """Was cancel called?""" + """Whether cancel was called.""" return self._cancelled class _PoolClosedError(PyMongoError): - """Internal error raised when a thread tries to get a connection from a - closed pool. - """ + """Internal error raised when a thread tries to get a connection from a closed pool.""" class _PoolGeneration: diff --git a/pymongo/pyopenssl_context.py b/pymongo/pyopenssl_context.py index 7fc8086e93..838e57ac74 100644 --- a/pymongo/pyopenssl_context.py +++ b/pymongo/pyopenssl_context.py @@ -12,8 +12,7 @@ # implied. See the License for the specific language governing # permissions and limitations under the License. -"""A CPython compatible SSLContext implementation wrapping PyOpenSSL's -context. +"""A CPython compatible SSLContext implementation wrapping PyOpenSSL's context. Due to limitations of the CPython asyncio.Protocol implementation for SSL, the async API does not support PyOpenSSL. """ @@ -203,9 +202,7 @@ def __init__(self) -> None: class SSLContext: - """A CPython compatible SSLContext implementation wrapping PyOpenSSL's - context. - """ + """A CPython compatible SSLContext implementation wrapping PyOpenSSL's context.""" __slots__ = ("_callback_data", "_check_hostname", "_ctx", "_options", "_protocol") @@ -227,14 +224,16 @@ def __init__(self, protocol: int): @property def protocol(self) -> int: """The protocol version chosen when constructing the context. + This attribute is read-only. """ return self._protocol def __get_verify_mode(self) -> VerifyMode: - """Whether to try to verify other peers' certificates and how to - behave if verification fails. This attribute must be one of - ssl.CERT_NONE, ssl.CERT_OPTIONAL or ssl.CERT_REQUIRED. + """Whether to verify other peers' certificates and how to behave if verification fails. + + This attribute must be one of ssl.CERT_NONE, ssl.CERT_OPTIONAL or + ssl.CERT_REQUIRED. """ return _REVERSE_VERIFY_MAP[self._ctx.get_verify_mode()] @@ -280,8 +279,9 @@ def load_cert_chain( keyfile: str | bytes | None = None, password: str | None = None, ) -> None: - """Load a private key and the corresponding certificate. The certfile - string must be the path to a single file in PEM format containing the + """Load a private key and the corresponding certificate. + + The certfile string must be the path to a single file in PEM format containing the certificate as well as any number of CA certificates needed to establish the certificate's authenticity. The keyfile string, if present, must point to a file containing the private key. Otherwise @@ -305,9 +305,10 @@ def _pwcb(_max_length: int, _prompt_twice: bool, _user_data: bytes | None) -> by self._ctx.check_privatekey() def load_verify_locations(self, cafile: str | None = None, capath: str | None = None) -> None: - """Load a set of "certification authority"(CA) certificates used to - validate other peers' certificates when `~verify_mode` is other than - ssl.CERT_NONE. + """Load a set of "certification authority"(CA) certificates. + + They are used to validate other peers' certificates when + `~verify_mode` is other than ssl.CERT_NONE. """ self._ctx.load_verify_locations(cafile, capath) @@ -337,7 +338,7 @@ def _load_wincerts(self, store: str) -> None: ) def load_default_certs(self) -> None: - """A PyOpenSSL version of load_default_certs from CPython.""" + """Provide a PyOpenSSL version of load_default_certs from CPython.""" # PyOpenSSL is incapable of loading CA certs from Windows, and mostly # incapable on macOS. # https://www.pyopenssl.org/en/stable/api/ssl.html#OpenSSL.SSL.Context.set_default_verify_paths @@ -353,9 +354,7 @@ def load_default_certs(self) -> None: self._ctx.set_default_verify_paths() def set_default_verify_paths(self) -> None: - """Specify that the platform provided CA certificates are to be used - for verification purposes. - """ + """Specify that the platform's CA certificates are used for verification purposes.""" # Note: See PyOpenSSL's docs for limitations, which are similar # but not that same as CPython's. self._ctx.set_default_verify_paths() @@ -369,9 +368,7 @@ def wrap_socket( server_hostname: str | None = None, session: _SSL.Session | None = None, ) -> _sslConn: - """Wrap an existing Python socket connection and return a TLS socket - object. - """ + """Wrap an existing Python socket connection and return a TLS socket object.""" ssl_conn = _sslConn(self._ctx, sock, suppress_ragged_eofs) if session: ssl_conn.set_session(session) diff --git a/pymongo/read_concern.py b/pymongo/read_concern.py index 21e66aa52c..893992cc1f 100644 --- a/pymongo/read_concern.py +++ b/pymongo/read_concern.py @@ -23,7 +23,7 @@ class ReadConcern: - """ReadConcern + """ReadConcern. :param level: (string) The read concern level specifies the level of isolation for read operations. For example, a read operation using a @@ -48,9 +48,7 @@ def level(self) -> str | None: @property def ok_for_legacy(self) -> bool: - """Return ``True`` if this read concern is compatible with - old wire protocol versions. - """ + """Return ``True`` if this read concern is compatible with old wire protocol versions.""" return self.level is None or self.level == "local" @property diff --git a/pymongo/read_preferences.py b/pymongo/read_preferences.py index 721725563e..e572df0d7e 100644 --- a/pymongo/read_preferences.py +++ b/pymongo/read_preferences.py @@ -160,13 +160,15 @@ def mode(self) -> int: @property def tag_sets(self) -> _TagSets: - """Set ``tag_sets`` to a list of dictionaries like [{'dc': 'ny'}] to - read only from members whose ``dc`` tag has the value ``"ny"``. + """Set ``tag_sets`` to a list of dictionaries like ``[{'dc': 'ny'}]``. + + Reads only from members whose ``dc`` tag has the value ``"ny"``. To specify a priority-order for tag sets, provide a list of tag sets: ``[{'dc': 'ny'}, {'dc': 'la'}, {}]``. A final, empty tag set, ``{}``, means "read from any member that matches the mode, ignoring tags." MongoClient tries each set of tags in turn until it finds a set of tags with at least one matching member. + For example, to only send a query to an analytic node:: Nearest(tag_sets=[{"node":"analytics"}]) @@ -182,9 +184,11 @@ def tag_sets(self) -> _TagSets: @property def max_staleness(self) -> int: - """The maximum estimated length of time (in seconds) a replica set - secondary can fall behind the primary in replication before it will - no longer be selected for operations, or -1 for no maximum. + """The maximum estimated time (in seconds) a secondary can fall behind. + + This is the estimated length of time a replica set secondary can fall + behind the primary in replication before it will no longer be selected + for operations, or -1 for no maximum. """ return self.__max_staleness diff --git a/pymongo/response.py b/pymongo/response.py index 366d3fee93..3b19a322a4 100644 --- a/pymongo/response.py +++ b/pymongo/response.py @@ -116,7 +116,8 @@ def conn(self) -> _AgnosticConnection: @property def more_to_come(self) -> bool: - """If true, server is ready to send batches on the socket until the - result set is exhausted or there is an error. + """If true, server is ready to send batches on the socket. + + Batches are sent until the result set is exhausted or there is an error. """ return self._more_to_come diff --git a/pymongo/results.py b/pymongo/results.py index f34de54309..fbb04bf0b6 100644 --- a/pymongo/results.py +++ b/pymongo/results.py @@ -50,7 +50,7 @@ def _raise_if_unacknowledged(self, property_name: str) -> None: @property def acknowledged(self) -> bool: - """Is this the result of an acknowledged write operation? + """Whether this is the result of an acknowledged write operation. The :attr:`acknowledged` attribute will be ``False`` when using ``WriteConcern(w=0)``, otherwise ``True``. @@ -69,8 +69,9 @@ def acknowledged(self) -> bool: class InsertOneResult(_WriteResult): - """The return type for :meth:`~pymongo.collection.Collection.insert_one` - and as part of :meth:`~pymongo.mongo_client.MongoClient.bulk_write`. + """The return type for :meth:`~pymongo.collection.Collection.insert_one`. + + Also used as part of :meth:`~pymongo.mongo_client.MongoClient.bulk_write`. """ __slots__ = ("__inserted_id",) @@ -117,9 +118,10 @@ def inserted_ids(self) -> list[Any]: class UpdateResult(_WriteResult): - """The return type for :meth:`~pymongo.collection.Collection.update_one`, - :meth:`~pymongo.collection.Collection.update_many`, and - :meth:`~pymongo.collection.Collection.replace_one`, and as part of + """The return type for :meth:`~pymongo.collection.Collection.update_one`. + + Also the return type for :meth:`~pymongo.collection.Collection.update_many` + and :meth:`~pymongo.collection.Collection.replace_one`, and used as part of :meth:`~pymongo.mongo_client.MongoClient.bulk_write`. """ @@ -164,9 +166,7 @@ def modified_count(self) -> int: @property def upserted_id(self) -> Any: - """The _id of the inserted document if an upsert took place. Otherwise - ``None``. - """ + """The _id of the inserted document if an upsert took place. Otherwise ``None``.""" self._raise_if_unacknowledged("upserted_id") assert self.__raw_result is not None if self.__in_client_bulk and self.__raw_result.get("upserted"): @@ -184,9 +184,10 @@ def did_upsert(self) -> bool: class DeleteResult(_WriteResult): - """The return type for :meth:`~pymongo.collection.Collection.delete_one` - and :meth:`~pymongo.collection.Collection.delete_many` - and as part of :meth:`~pymongo.mongo_client.MongoClient.bulk_write`. + """The return type for :meth:`~pymongo.collection.Collection.delete_one`. + + Also the return type for :meth:`~pymongo.collection.Collection.delete_many`, + and used as part of :meth:`~pymongo.mongo_client.MongoClient.bulk_write`. """ __slots__ = ("__raw_result",) diff --git a/pymongo/saslprep.py b/pymongo/saslprep.py index 7ed3c69bf9..ef1c753dab 100644 --- a/pymongo/saslprep.py +++ b/pymongo/saslprep.py @@ -27,7 +27,7 @@ def saslprep( data: Any, prohibit_unassigned_code_points: bool | None = True, # noqa: ARG001 ) -> Any: - """SASLprep dummy""" + """SASLprep dummy.""" if isinstance(data, str): raise TypeError( "The stringprep module is not available. Usernames and " @@ -56,7 +56,7 @@ def saslprep( ) def saslprep(data: Any, prohibit_unassigned_code_points: bool | None = True) -> Any: - """An implementation of RFC4013 SASLprep. + """Perform SASLprep per RFC4013. :param data: The string to SASLprep. Unicode strings (:class:`str`) are supported. Byte strings diff --git a/pymongo/server_api.py b/pymongo/server_api.py index 736b654bb9..12018c92c2 100644 --- a/pymongo/server_api.py +++ b/pymongo/server_api.py @@ -163,7 +163,7 @@ def deprecation_errors(self) -> bool | None: def _add_to_command(cmd: MutableMapping[str, Any], server_api: ServerApi | None) -> None: - """Internal helper which adds API versioning options to a command. + """Add API versioning options to a command. :param cmd: The command. :param server_api: A :class:`ServerApi` or ``None``. diff --git a/pymongo/settings_shared.py b/pymongo/settings_shared.py index d36876006d..d32557ce31 100644 --- a/pymongo/settings_shared.py +++ b/pymongo/settings_shared.py @@ -139,7 +139,7 @@ def fqdn(self) -> str | None: @property def direct(self) -> bool | None: - """Connect directly to a single server, or use a set of servers? + """Connect directly to a single server instead of a set of servers. True if there is one seed and no replica_set_name. """ @@ -186,5 +186,5 @@ def get_topology_type(self) -> int: return TOPOLOGY_TYPE.Unknown def get_server_descriptions(self) -> dict[tuple[str, int] | Any, ServerDescription]: - """Initial dict of (address, ServerDescription) for all seeds.""" + """Get the (address, ServerDescription) dict for all seeds.""" return {address: ServerDescription(address) for address in self.seeds} diff --git a/pymongo/socket_checker.py b/pymongo/socket_checker.py index 1f81acabe7..a3f9b07565 100644 --- a/pymongo/socket_checker.py +++ b/pymongo/socket_checker.py @@ -12,7 +12,7 @@ # See the License for the specific language governing permissions and # limitations under the License. -"""Select / poll helper""" +"""Select / poll helper.""" from __future__ import annotations diff --git a/pymongo/synchronous/aggregation.py b/pymongo/synchronous/aggregation.py index 3c81078eff..02a3e4953e 100644 --- a/pymongo/synchronous/aggregation.py +++ b/pymongo/synchronous/aggregation.py @@ -117,7 +117,7 @@ def _cursor_namespace(self) -> str: raise NotImplementedError def _cursor_collection(self, cursor_doc: Mapping[str, Any]) -> Collection[Any]: - """The Collection used for the aggregate command cursor.""" + """Return the Collection used for the aggregate command cursor.""" raise NotImplementedError @property @@ -213,7 +213,7 @@ def _cursor_namespace(self) -> str: return self._target.full_name def _cursor_collection(self, cursor: Mapping[str, Any]) -> Collection[Any]: - """The Collection used for the aggregate command cursor.""" + """Return the Collection used for the aggregate command cursor.""" return self._target @property @@ -246,7 +246,7 @@ def _database(self) -> Database[Any]: return self._target def _cursor_collection(self, cursor: Mapping[str, Any]) -> Collection[Any]: - """The Collection used for the aggregate command cursor.""" + """Return the Collection used for the aggregate command cursor.""" # Collection level aggregate may not always return the "ns" field # according to our MockupDB tests. Let's handle that case for db level # aggregate too by defaulting to the .$cmd.aggregate namespace. diff --git a/pymongo/synchronous/auth.py b/pymongo/synchronous/auth.py index 1fc037c47b..30a9f81f95 100644 --- a/pymongo/synchronous/auth.py +++ b/pymongo/synchronous/auth.py @@ -301,7 +301,7 @@ def _authenticate_gssapi(credentials: MongoCredential, conn: Connection) -> None def _authenticate_plain(credentials: MongoCredential, conn: Connection) -> None: - """Authenticate using SASL PLAIN (RFC 4616)""" + """Authenticate using SASL PLAIN (RFC 4616).""" source = credentials.source username = credentials.username password = credentials.password diff --git a/pymongo/synchronous/change_stream.py b/pymongo/synchronous/change_stream.py index 3336b4f6e6..564b67f57f 100644 --- a/pymongo/synchronous/change_stream.py +++ b/pymongo/synchronous/change_stream.py @@ -69,8 +69,9 @@ def _initialize_cursor(self) -> None: self._cursor = self._create_cursor() def _run_aggregation_cmd(self, session: ClientSession | None) -> CommandCursor: # type: ignore[type-arg] - """Run the full aggregation pipeline for this ChangeStream and return - the corresponding CommandCursor. + """Run the full aggregation pipeline for this ChangeStream. + + Return the corresponding CommandCursor. """ cmd = self._aggregation_command_class( self._target, diff --git a/pymongo/synchronous/client_bulk.py b/pymongo/synchronous/client_bulk.py index 097df34f89..c345cdd3db 100644 --- a/pymongo/synchronous/client_bulk.py +++ b/pymongo/synchronous/client_bulk.py @@ -148,7 +148,7 @@ def _execute_batch_unack( ops: list[tuple[str, Mapping[str, Any]]], namespaces: list[str], ) -> tuple[list[Mapping[str, Any]], list[Mapping[str, Any]]]: - """Executes a batch of bulkWrite server commands (unack).""" + """Execute a batch of bulkWrite server commands (unack).""" request_id, msg, to_send_ops, to_send_ns = bwc.batch_command(cmd, ops, namespaces) self.unack_write(bwc, cmd, request_id, msg, to_send_ops, to_send_ns, self.client) # type: ignore[arg-type] return to_send_ops, to_send_ns @@ -160,7 +160,7 @@ def _execute_batch( ops: list[tuple[str, Mapping[str, Any]]], namespaces: list[str], ) -> tuple[dict[str, Any], list[Mapping[str, Any]], list[Mapping[str, Any]]]: - """Executes a batch of bulkWrite server commands (ack).""" + """Execute a batch of bulkWrite server commands (ack).""" request_id, msg, to_send_ops, to_send_ns = bwc.batch_command(cmd, ops, namespaces) result = self.write_command(bwc, cmd, request_id, msg, to_send_ops, to_send_ns, self.client) # type: ignore[arg-type] return result, to_send_ops, to_send_ns # type: ignore[return-value] @@ -172,7 +172,7 @@ def _process_results_cursor( conn: Connection, session: ClientSession | None, ) -> None: - """Internal helper for processing the server reply command cursor.""" + """Process the server reply command cursor (internal helper).""" if result.get("cursor"): if session: session._leave_alive = True @@ -227,7 +227,7 @@ def _execute_command( full_result: MutableMapping[str, Any], final_write_concern: WriteConcern | None = None, ) -> None: - """Internal helper for executing batches of bulkWrite commands.""" + """Execute batches of bulkWrite commands (internal helper).""" db_name = "admin" cmd_name = "bulkWrite" listeners = self.client._event_listeners diff --git a/pymongo/synchronous/collection.py b/pymongo/synchronous/collection.py index 34b00cec50..4f63e8c717 100644 --- a/pymongo/synchronous/collection.py +++ b/pymongo/synchronous/collection.py @@ -100,9 +100,10 @@ class ReturnDocument: - """An enum used with - :meth:`~pymongo.collection.Collection.find_one_and_replace` and - :meth:`~pymongo.collection.Collection.find_one_and_update`. + """An enum used with the find_one_and_replace and find_one_and_update methods. + + See :meth:`~pymongo.collection.Collection.find_one_and_replace` + and :meth:`~pymongo.collection.Collection.find_one_and_update`. """ BEFORE = False @@ -329,8 +330,10 @@ def name(self) -> str: @property def database(self) -> Database[_DocumentType]: - """The :class:`~pymongo.database.Database` that this - :class:`Collection` is a part of. + """Return the collection's :class:`~pymongo.database.Database`. + + This is the :class:`~pymongo.database.Database` that + this :class:`Collection` is a part of. """ return self._database @@ -406,7 +409,7 @@ def __next__(self) -> NoReturn: next = __next__ def __call__(self, *args: Any, **kwargs: Any) -> NoReturn: - """This is only here so that some API misusages are easier to debug.""" + """Raise an error so that some API misusages are easier to debug.""" if "." not in self._name: raise TypeError( f"'{type(self).__name__}' object is not callable. If you " @@ -576,7 +579,7 @@ def _command( retryable_write: bool = False, user_fields: Any | None = None, ) -> Mapping[str, Any]: - """Internal command helper. + """Run a command (internal helper). :param conn` - A Connection instance. :param command` - The command itself, as a :class:`~bson.son.SON` instance. @@ -628,7 +631,7 @@ def _create_helper( encrypted_fields: Mapping[str, Any] | None = None, qev2_required: bool = False, ) -> None: - """Sends a create command with the given options.""" + """Send a create command with the given options.""" cmd: dict[str, Any] = {"create": name} if encrypted_fields: cmd["encryptedFields"] = encrypted_fields @@ -790,7 +793,7 @@ def _insert_one( session: ClientSession | None, comment: Any | None = None, ) -> Any: - """Internal helper for inserting a single document.""" + """Insert a single document (internal helper).""" write_concern = write_concern or self.write_concern acknowledged = write_concern.acknowledged command = {"insert": self.name, "ordered": ordered, "documents": [doc]} @@ -947,7 +950,7 @@ def insert_many( inserted_ids: list[ObjectId] = [] def gen() -> Iterator[tuple[int, Mapping[str, Any]]]: - """A generator that validates documents and handles _ids.""" + """Validate documents and handle _ids.""" for document in documents: common.validate_is_document_type("document", document) if not isinstance(document, RawBSONDocument): @@ -982,7 +985,7 @@ def _update( sort: Mapping[str, Any] | None = None, comment: Any | None = None, ) -> Mapping[str, Any] | None: - """Internal update / replace helper.""" + """Update or replace a document (internal helper).""" validate_boolean("upsert", upsert) collation = validate_collation_or_none(collation) write_concern = write_concern or self.write_concern @@ -1073,7 +1076,7 @@ def _update_retryable( sort: Mapping[str, Any] | None = None, comment: Any | None = None, ) -> Mapping[str, Any] | None: - """Internal update / replace helper.""" + """Update or replace a document (internal helper).""" def _update( session: ClientSession | None, conn: Connection, retryable_write: bool @@ -1490,7 +1493,7 @@ def _delete( let: Mapping[str, Any] | None = None, comment: Any | None = None, ) -> Mapping[str, Any]: - """Internal delete helper.""" + """Delete documents (internal helper).""" common.validate_is_mapping("filter", criteria) write_concern = write_concern or self.write_concern acknowledged = write_concern.acknowledged @@ -1540,7 +1543,7 @@ def _delete_retryable( let: Mapping[str, Any] | None = None, comment: Any | None = None, ) -> Mapping[str, Any]: - """Internal delete helper.""" + """Delete documents (internal helper).""" def _delete( session: ClientSession | None, conn: Connection, retryable_write: bool @@ -1980,7 +1983,7 @@ def _count_cmd( cmd: dict[str, Any], collation: Collation | None, ) -> int: - """Internal count command helper.""" + """Run a count command (internal helper).""" res = self._command( conn, cmd, @@ -2000,7 +2003,7 @@ def _aggregate_one_result( collation: _CollationIn | None, session: ClientSession | None, ) -> Mapping[str, Any] | None: - """Internal helper to run an aggregate that returns a single result.""" + """Run an aggregate that returns a single result (internal helper).""" result = self._command( conn, cmd, @@ -2018,8 +2021,9 @@ def _aggregate_one_result( return batch[0] if batch else None def estimated_document_count(self, comment: Any | None = None, **kwargs: Any) -> int: - """Get an estimate of the number of documents in this collection using - collection metadata. + """Get an estimate of the number of documents in this collection. + + Uses collection metadata. The :meth:`estimated_document_count` method is **not** supported in a transaction. @@ -2215,7 +2219,7 @@ def create_indexes( def _create_indexes( self, indexes: Sequence[IndexModel], session: ClientSession | None, **kwargs: Any ) -> list[str]: - """Internal createIndexes helper. + """Create indexes (internal helper). :param indexes: A list of :class:`~pymongo.operations.IndexModel` instances. @@ -2260,7 +2264,7 @@ def create_index( comment: Any | None = None, **kwargs: Any, ) -> str: - """Creates an index on this collection. + """Create an index on this collection. Takes either a single key or a list containing (key, direction) pairs or keys. If no direction is given, :data:`~pymongo.ASCENDING` will @@ -2377,7 +2381,7 @@ def drop_indexes( comment: Any | None = None, **kwargs: Any, ) -> None: - """Drops all indexes on this collection. + """Drop all indexes on this collection. Can be used on non-existent collections or collections with no indexes. Raises OperationFailure on an error. @@ -2411,7 +2415,7 @@ def drop_index( comment: Any | None = None, **kwargs: Any, ) -> None: - """Drops the specified index on this collection. + """Drop the specified index on this collection. Can be used on non-existent collections or collections with no indexes. Raises OperationFailure on an error (e.g. trying to @@ -2924,8 +2928,7 @@ def aggregate( comment: Any | None = None, **kwargs: Any, ) -> CommandCursor[_DocumentType]: - """Perform an aggregation using the aggregation framework on this - collection. + """Perform an aggregation using the aggregation framework on this collection. The :meth:`aggregate` method obeys the :attr:`read_preference` of this :class:`Collection`, except when ``$out`` or ``$merge`` are used on @@ -3144,8 +3147,7 @@ def distinct( hint: _IndexKeyHint | None = None, **kwargs: Any, ) -> list[Any]: - """Get a list of distinct values for `key` among all documents - in this collection. + """Get a list of distinct values for `key` among all documents in this collection. Raises :class:`TypeError` if `key` is not an instance of :class:`str`. @@ -3235,7 +3237,7 @@ def _find_and_modify( let: Mapping[str, Any] | None = None, **kwargs: Any, ) -> Any: - """Internal findAndModify helper.""" + """Run a findAndModify command (internal helper).""" common.validate_is_mapping("filter", filter) if not isinstance(return_document, bool): raise TypeError( @@ -3303,7 +3305,7 @@ def find_one_and_delete( comment: Any | None = None, **kwargs: Any, ) -> _DocumentType | None: - """Finds a single document and deletes it, returning the document. + """Find a single document and delete it, returning the document. >>> db.test.count_documents({'x': 1}) 2 @@ -3399,8 +3401,9 @@ def find_one_and_replace( comment: Any | None = None, **kwargs: Any, ) -> _DocumentType | None: - """Finds a single document and replaces it, returning either the - original or the replaced document. + """Find a single document and replace it. + + Return either the original or the replaced document. >>> db.test.find_one({'x': 1}) {'_id': 0, 'x': 1} @@ -3519,8 +3522,9 @@ def find_one_and_update( comment: Any | None = None, **kwargs: Any, ) -> _DocumentType | None: - """Finds a single document and updates it, returning either the - original or the updated document. + """Find a single document and update it. + + Return either the original or the updated document. >>> db.test.find_one({'_id': 665}) {'_id': 665, 'done': False, 'count': 25} diff --git a/pymongo/synchronous/command_cursor.py b/pymongo/synchronous/command_cursor.py index 43a8ce73ee..f3351d4c44 100644 --- a/pymongo/synchronous/command_cursor.py +++ b/pymongo/synchronous/command_cursor.py @@ -43,6 +43,7 @@ class CommandCursor(_AgnosticCommandCursorBase[_DocumentType], _CursorBase[_DocumentType]): """A cursor / iterator over command cursors. + Used by :meth:`~pymongo.collection.Collection.aggregate`, :meth:`~pymongo.database.Database.aggregate`, :meth:`~pymongo.collection.Collection.list_indexes`, @@ -109,7 +110,7 @@ def _send_message(self, operation: _GetMore) -> None: self._data = deque(documents) def _refresh(self) -> int: - """Refreshes the cursor with more data from the server. + """Refresh the cursor with more data from the server. Returns the length of self._data after refresh. Will exit early if self._data is already non-empty. Raises OperationFailure when the diff --git a/pymongo/synchronous/command_runner.py b/pymongo/synchronous/command_runner.py index 3381f117a2..2a009bc2c5 100644 --- a/pymongo/synchronous/command_runner.py +++ b/pymongo/synchronous/command_runner.py @@ -101,8 +101,9 @@ def _run_command( unpack_res: Callable[..., Any] | None = None, cursor_id: int | None = None, ) -> tuple[list[dict[str, Any]], _OpMsg | None, float]: - """Send ``msg`` over ``conn`` and return ``(docs, reply, duration_s)``, - where ``duration_s`` is the round-trip duration in seconds. + """Send ``msg`` over ``conn`` and return ``(docs, reply, duration_s)``. + + ``duration_s`` is the round-trip duration in seconds. Private shared implementation. Should not be called directly outside this module. Use :func:`run_command`, :func:`run_bulk_write_command`, or :func:`run_cursor_command` instead. diff --git a/pymongo/synchronous/cursor.py b/pymongo/synchronous/cursor.py index b492372932..9b1ae2519e 100644 --- a/pymongo/synchronous/cursor.py +++ b/pymongo/synchronous/cursor.py @@ -57,8 +57,9 @@ class Cursor(_AgnosticCursor[_DocumentType], _CursorBase[_DocumentType]): @property def collection(self) -> Collection[_DocumentType]: - """The :class:`~pymongo.collection.Collection` that this - :class:`Cursor` is iterating. + """The :class:`~pymongo.collection.Collection` being iterated. + + The collection that this :class:`Cursor` is iterating. """ return self._collection @@ -169,7 +170,7 @@ def __getitem__(self, index: int | slice) -> _DocumentType | Cursor[_DocumentTyp raise IndexError("Cursor does not support indexing") def explain(self) -> _DocumentType: - """Returns an explain plan record for this cursor. + """Return an explain plan record for this cursor. .. note:: This method uses the default verbosity mode of the `explain command @@ -191,8 +192,9 @@ def explain(self) -> _DocumentType: return next(c) def distinct(self, key: str) -> list[Any]: - """Get a list of distinct values for `key` among all documents - in the result set of this query. + """Get a list of distinct values for `key` among all documents. + + The distinct values are drawn from the result set of this query. Raises :class:`TypeError` if `key` is not an instance of :class:`str`. @@ -294,7 +296,7 @@ def _send_message(self, operation: _Query | _GetMore) -> None: self.close() def _refresh(self) -> int: - """Refreshes the cursor with more data from Mongo. + """Refresh the cursor with more data from Mongo. Returns the length of self._data after refresh. Will exit early if self._data is already non-empty. Raises OperationFailure when the @@ -443,7 +445,7 @@ def _unpack_response( return cast("list[_DocumentOut]", raw_response) def explain(self) -> _DocumentType: - """Returns an explain plan record for this cursor. + """Return an explain plan record for this cursor. .. seealso:: The MongoDB documentation on `explain `_. """ diff --git a/pymongo/synchronous/cursor_base.py b/pymongo/synchronous/cursor_base.py index b123c57880..d5b00654ab 100644 --- a/pymongo/synchronous/cursor_base.py +++ b/pymongo/synchronous/cursor_base.py @@ -166,7 +166,7 @@ def _run_with_conn( ) def _die_lock(self) -> None: - """Closes this cursor.""" + """Close this cursor.""" try: already_killed = self._killed except AttributeError: @@ -199,7 +199,7 @@ def __exit__( @_csot.apply def to_list(self, length: int | None = None) -> list[_DocumentType]: - """Converts the contents of this cursor to a list more efficiently than ``[doc for doc in cursor]``. + """Convert this cursor's contents to a list more efficiently than iterating over it. To use:: diff --git a/pymongo/synchronous/database.py b/pymongo/synchronous/database.py index 746665f9b1..9654692078 100644 --- a/pymongo/synchronous/database.py +++ b/pymongo/synchronous/database.py @@ -253,12 +253,11 @@ def get_collection( write_concern: WriteConcern | None = None, read_concern: ReadConcern | None = None, ) -> Collection[_DocumentType]: - """Get a :class:`~pymongo.collection.Collection` with the given name - and options. + """Get a :class:`~pymongo.collection.Collection`. - Useful for creating a :class:`~pymongo.collection.Collection` with - different codec options, read preference, and/or write concern from - this :class:`Database`. + The returned collection uses the given name and options. Useful for creating a + :class:`~pymongo.collection.Collection` with different codec + options, read preference, and/or write concern from this :class:`Database`. >>> db.read_preference Primary() @@ -484,8 +483,7 @@ def create_collection( check_exists: bool | None = True, **kwargs: Any, ) -> Collection[_DocumentType]: - """Create a new :class:`~pymongo.collection.Collection` in this - database. + """Create a new :class:`~pymongo.collection.Collection` in this database. Normally collection creation is automatic. This method should only be used to specify options on @@ -762,7 +760,7 @@ def _command( session: ClientSession | None = None, **kwargs: Any, ) -> dict[str, Any] | _CodecDocumentType: - """Internal command helper.""" + """Run an internal command.""" if isinstance(command, str): command = {command: value} @@ -1059,7 +1057,7 @@ def _retryable_read_command( operation: str, session: ClientSession | None = None, ) -> dict[str, Any]: - """Same as command but used for retryable read commands.""" + """Run the given command as a retryable read.""" read_preference = (session and session._txn_read_preference()) or ReadPreference.PRIMARY def _cmd( @@ -1084,7 +1082,7 @@ def _list_collections( read_preference: _ServerMode, **kwargs: Any, ) -> CommandCursor[MutableMapping[str, Any]]: - """Internal listCollections helper.""" + """Run the internal listCollections helper.""" coll = cast( "Collection[MutableMapping[str, Any]]", self.get_collection("$cmd", read_preference=read_preference), @@ -1434,8 +1432,7 @@ def dereference( comment: Any | None = None, **kwargs: Any, ) -> _DocumentType | None: - """Dereference a :class:`~bson.dbref.DBRef`, getting the - document it points to. + """Dereference a :class:`~bson.dbref.DBRef`, getting the document it points to. Raises :class:`TypeError` if `dbref` is not an instance of :class:`~bson.dbref.DBRef`. Returns a document, or ``None`` if diff --git a/pymongo/synchronous/encryption.py b/pymongo/synchronous/encryption.py index 774e3347c2..1dd494ce43 100644 --- a/pymongo/synchronous/encryption.py +++ b/pymongo/synchronous/encryption.py @@ -119,7 +119,7 @@ def __init__( mongocryptd_client: MongoClient[_DocumentTypeArg] | None, opts: AutoEncryptionOpts, ): - """Internal class to perform I/O on behalf of pymongocrypt.""" + """Perform I/O on behalf of pymongocrypt (internal class).""" self.client_ref: Any # Use a weak ref to break reference cycle. if client is not None: @@ -288,7 +288,7 @@ def mark_command(self, database: str, cmd: bytes) -> bytes | memoryview: return res.raw def fetch_keys(self, filter: bytes) -> Generator[bytes | memoryview, None]: - """Yields one or more keys from the key vault. + """Yield one or more keys from the key vault. :param filter: The filter to pass to find. diff --git a/pymongo/synchronous/mongo_client.py b/pymongo/synchronous/mongo_client.py index 7e13d7c6fb..33c453b5b3 100644 --- a/pymongo/synchronous/mongo_client.py +++ b/pymongo/synchronous/mongo_client.py @@ -1158,7 +1158,7 @@ def target() -> bool: self._opened = False def append_metadata(self, driver_info: DriverInfo) -> None: - """Appends the given metadata to existing driver metadata. + """Append the given metadata to existing driver metadata. :param driver_info: a :class:`~pymongo.driver_info.DriverInfo` @@ -1174,7 +1174,7 @@ def _should_pin_cursor(self, session: ClientSession | None) -> bool | None: return self._options.load_balanced and not (session and session.in_transaction) def _after_fork(self) -> None: - """Resets topology in a child after successfully forking.""" + """Reset topology in a child after successfully forking.""" self._init_background(self._topology._pid) # Reset the session pool to avoid duplicate sessions in the child process. self._topology._session_pool.reset() @@ -1618,12 +1618,11 @@ def get_database( write_concern: WriteConcern | None = None, read_concern: ReadConcern | None = None, ) -> database.Database[_DocumentType]: - """Get a :class:`~pymongo.database.Database` with the given name and - options. + """Get a :class:`~pymongo.database.Database`. - Useful for creating a :class:`~pymongo.database.Database` with - different codec options, read preference, and/or write concern from - this :class:`MongoClient`. + The returned database uses the given name and options. Useful for creating a + :class:`~pymongo.database.Database` with different codec + options, read preference, and/or write concern from this :class:`MongoClient`. >>> client.read_preference Primary() @@ -1698,7 +1697,7 @@ def __next__(self) -> NoReturn: next = __next__ def _server_property(self, attr_name: str) -> Any: - """An attribute of the current server's description. + """Get an attribute of the current server's description. If the client is not connected, this will block until a connection is established or raise ServerSelectionTimeoutError if no server is @@ -1794,9 +1793,11 @@ def is_primary(self) -> bool: @property def is_mongos(self) -> bool: - """If this client is connected to mongos. If the client is not - connected, this will block until a connection is established or raise - ServerSelectionTimeoutError if no server is available. + """Whether this client is connected to mongos. + + If the client is not connected, this will block until a connection is + established or raise ServerSelectionTimeoutError if no server is + available. """ return self._server_property("server_type") == SERVER_TYPE.Mongos @@ -2001,7 +2002,7 @@ def _retry_with_session( operation: str, operation_id: int | None = None, ) -> T: - """Execute an operation with at most one consecutive retries + """Execute an operation with at most one consecutive retries. Returns func()'s return value on success. On error retries the same command. @@ -2038,7 +2039,7 @@ def _retry_internal( is_aggregate_write: bool = False, conn_mgr: Any = None, ) -> T: - """Internal retryable helper for all client transactions. + """Run the internal retryable helper for all client transactions. :param func: Callback function we want to retry :param session: Client Session on which the transaction should occur @@ -2084,7 +2085,7 @@ def _retryable_read( is_aggregate_write: bool = False, conn_mgr: Any = None, ) -> T: - """Execute an operation with consecutive retries if possible + """Execute an operation with consecutive retries if possible. Returns func()'s return value on success. On error retries the same command. @@ -2133,7 +2134,7 @@ def _retryable_write( bulk: _Bulk | _ClientBulk | None = None, operation_id: int | None = None, ) -> T: - """Execute an operation with consecutive retries if possible + """Execute an operation with consecutive retries if possible. Returns func()'s return value on success. On error retries the same command. @@ -2306,9 +2307,7 @@ def _process_kill_cursors(self) -> None: # This method is run periodically by a background thread. def _process_periodic_tasks(self) -> None: - """Process any pending kill cursors requests and - maintain connection pool parameters. - """ + """Process any pending kill cursors requests and maintain connection pool parameters.""" try: self._process_kill_cursors() self._topology.update_pool() @@ -2319,7 +2318,7 @@ def _process_periodic_tasks(self) -> None: _log_client_error() def _return_server_session(self, server_session: _ServerSession | _EmptyServerSession) -> None: - """Internal: return a _ServerSession to the pool.""" + """Return a _ServerSession to the pool.""" if isinstance(server_session, _EmptyServerSession): return None return self._topology.return_server_session(server_session) @@ -2850,7 +2849,7 @@ def __enter__(self) -> tuple[Connection, _ServerMode]: # type: ignore[override] class _ClientConnectionRetryable( _AgnosticClientConnectionRetryableBase[T, "Server", _WriteCall[T] | _ReadCall[T]] ): - """Responsible for executing retryable connections on read or write operations""" + """Responsible for executing retryable connections on read or write operations.""" __slots__ = () @@ -2858,7 +2857,7 @@ class _ClientConnectionRetryable( _session: ClientSession | None def run(self) -> T: - """Runs the supplied func() and attempts a retry + """Run the supplied func() and attempt a retry. :raises: self._last_error: Last exception raised @@ -3017,7 +3016,7 @@ def run(self) -> T: time.sleep(delay) def _get_server(self) -> Server: - """Retrieves a server object based on provided object context + """Retrieve a server object based on provided object context. :return: Abstraction to connect to server """ @@ -3031,7 +3030,7 @@ def _get_server(self) -> Server: ) def _write(self) -> T: - """Wrapper method for write-type retryable client executions + """Wrap write-type retryable client executions. :return: Output for func()'s call """ @@ -3063,7 +3062,7 @@ def _write(self) -> T: raise def _read(self) -> T: - """Wrapper method for read-type retryable client executions + """Wrap read-type retryable client executions. :return: Output for func()'s call """ diff --git a/pymongo/synchronous/monitor.py b/pymongo/synchronous/monitor.py index 436e9eed8b..aca19b1395 100644 --- a/pymongo/synchronous/monitor.py +++ b/pymongo/synchronous/monitor.py @@ -56,7 +56,7 @@ def _sanitize(error: Exception) -> None: class MonitorBase: def __init__(self, topology: Topology, name: str, interval: int, min_interval: float): - """Base class to do periodic work on a background thread. + """Do periodic work on a background thread (base class). The background thread is signaled to stop when the Topology or this instance is freed. @@ -268,7 +268,7 @@ def _check_server(self) -> ServerDescription: return ServerDescription(address, error=error) def _check_once(self) -> ServerDescription: - """A single attempt to call hello. + """Make a single attempt to call hello. Returns a ServerDescription, or raises an exception. """ diff --git a/pymongo/synchronous/pool.py b/pymongo/synchronous/pool.py index c919f9409e..28a8811b03 100644 --- a/pymongo/synchronous/pool.py +++ b/pymongo/synchronous/pool.py @@ -431,7 +431,8 @@ def __init__( is_sdam: bool = False, client_id: ObjectId | None = None, ): - """ + """Initialize a new connection pool. + :param address: a (hostname, port) tuple :param options: a PoolOptions instance :param is_sdam: whether to call hello for each new connection @@ -530,9 +531,7 @@ def _reset( conn.close_conn(ConnectionClosedReason.STALE) def update_is_writable(self, is_writable: bool | None) -> None: - """Updates the is_writable attribute on all sockets currently in the - Pool. - """ + """Update the is_writable attribute on all sockets currently in the Pool.""" self.is_writable = is_writable with self.lock: for _socket in self.conns: @@ -550,10 +549,10 @@ def close(self) -> None: self._reset(close=True) def remove_stale_sockets(self, reference_generation: int) -> None: - """Removes stale sockets then adds new ones if pool is too small and - has not been reset. The `reference_generation` argument specifies the - `generation` at the point in time this operation was requested on the - pool. + """Remove stale sockets then add new ones if pool is too small and has not been reset. + + The `reference_generation` argument specifies the `generation` at the + point in time this operation was requested on the pool. """ # Take the lock to avoid the race condition described in PYTHON-2699. with self.lock: @@ -687,7 +686,9 @@ def connect(self, handler: _ClientCheckout | None = None) -> Connection: return conn def checkout(self, handler: _ClientCheckout | None = None) -> _PoolCheckout: - """Get a connection from the pool. Always use in a with statement:: + """Get a connection from the pool. + + Always use in a with statement:: with pool.checkout() as connection: connection.send_message(msg) diff --git a/pymongo/synchronous/topology.py b/pymongo/synchronous/topology.py index b7a9bd366c..43ca487d7d 100644 --- a/pymongo/synchronous/topology.py +++ b/pymongo/synchronous/topology.py @@ -433,9 +433,7 @@ def on_change( server.pool.reset(interrupt_connections=interrupt_connections) def _process_srv_update(self, seedlist: list[tuple[str, Any]]) -> None: - """Process a new seedlist on an opened topology. - Hold the lock when calling this. - """ + """Process a new seedlist on an opened topology. Hold the lock when calling this.""" td_old = self._description if td_old.topology_type not in SRV_POLLING_TOPOLOGIES: return @@ -510,8 +508,9 @@ def update_pool(self) -> None: raise def close(self) -> None: - """Clear pools and terminate monitors. Topology does not reopen on - demand. Any further operations will raise + """Clear pools and terminate monitors. + + Topology does not reopen on demand. Any further operations will raise :exc:`~.errors.InvalidOperation`. """ with self._lock: diff --git a/pymongo/topology_description.py b/pymongo/topology_description.py index af4619456b..ae2638e9f4 100644 --- a/pymongo/topology_description.py +++ b/pymongo/topology_description.py @@ -113,7 +113,7 @@ def __init__( ) def _init_incompatible_err(self) -> None: - """Internal compatibility check for non-load balanced topologies.""" + """Check compatibility of non-load balanced topologies.""" for s in self._server_descriptions.values(): if not s.is_server_type_known: continue @@ -162,12 +162,12 @@ def has_server(self, address: _Address) -> bool: return address in self._server_descriptions def reset_server(self, address: _Address) -> TopologyDescription: - """A copy of this description, with one server marked Unknown.""" + """Return a copy of this description, with one server marked Unknown.""" unknown_sd = self._server_descriptions[address].to_unknown() return updated_topology_description(self, unknown_sd) def reset(self) -> TopologyDescription: - """A copy of this description, with all servers marked Unknown.""" + """Return a copy of this description, with all servers marked Unknown.""" if self._topology_type == TOPOLOGY_TYPE.ReplicaSetWithPrimary: topology_type = TOPOLOGY_TYPE.ReplicaSetNoPrimary else: @@ -370,8 +370,9 @@ def apply_selector( return self._apply_local_threshold(selection) def has_readable_server(self, read_preference: _ServerMode = ReadPreference.PRIMARY) -> bool: - """Does this topology have any readable servers available matching the - given read preference? + """Check if this topology has any readable servers available. + + The servers must match the given read preference. :param read_preference: an instance of a read preference from :mod:`~pymongo.read_preferences`. Defaults to @@ -386,7 +387,7 @@ def has_readable_server(self, read_preference: _ServerMode = ReadPreference.PRIM return any(self.apply_selector(read_preference)) def has_writable_server(self) -> bool: - """Does this topology have a writable server available? + """Check if this topology has a writable server available. .. note:: When connected directly to a single server this method always returns ``True``. @@ -702,7 +703,7 @@ def _update_rs_no_primary_from_member( def _check_has_primary(sds: Mapping[_Address, ServerDescription]) -> int: - """Current topology type is ReplicaSetWithPrimary. Is primary still known? + """Check if the primary is still known when the topology type is ReplicaSetWithPrimary. Pass in a dict of ServerDescriptions. diff --git a/pymongo/topology_shared.py b/pymongo/topology_shared.py index ce5bd5f9a8..cff86626da 100644 --- a/pymongo/topology_shared.py +++ b/pymongo/topology_shared.py @@ -211,7 +211,7 @@ def return_server_session(self, server_session: _ServerSession) -> None: self._session_pool.return_server_session(server_session) def _new_selection(self) -> Selection: - """A Selection object, initially including all known servers. + """Return a Selection object, initially including all known servers. Hold the lock when calling this. """ @@ -331,8 +331,9 @@ def __repr__(self) -> str: return f"<{self.__class__.__name__} {msg}{self._description!r}>" def eq_props(self) -> tuple[tuple[_Address, ...], str | None, str | None, str]: - """The properties to use for MongoClient/AsyncMongoClient and Topology - equality checks. + """Return the properties used for equality checks. + + These properties are used by MongoClient/AsyncMongoClient and Topology. """ ts = self._settings return (tuple(sorted(ts.seeds)), ts.replica_set_name, ts.fqdn, ts.srv_service_name) diff --git a/pymongo/typings.py b/pymongo/typings.py index aca6fd7da8..3ab09fe5f4 100644 --- a/pymongo/typings.py +++ b/pymongo/typings.py @@ -12,7 +12,7 @@ # See the License for the specific language governing permissions and # limitations under the License. -"""Type aliases used by PyMongo""" +"""Type aliases used by PyMongo.""" from __future__ import annotations @@ -68,8 +68,9 @@ def strip_optional(elem: _T | None) -> _T: - """This function is to allow us to cast all the elements of an iterator from Optional[_T] to _T - while inside a list comprehension. + """Cast all the elements of an iterator from Optional[_T] to _T. + + This is for use inside a list comprehension. """ assert elem is not None return elem diff --git a/pymongo/uri_parser_shared.py b/pymongo/uri_parser_shared.py index f4af8c20fc..699a3ea9d7 100644 --- a/pymongo/uri_parser_shared.py +++ b/pymongo/uri_parser_shared.py @@ -131,7 +131,8 @@ def _unquoted_percent(s: str) -> bool: def parse_userinfo(userinfo: str) -> tuple[str, str]: - """Validates the format of user information in a MongoDB URI. + """Validate the format of user information in a MongoDB URI. + Reserved characters that are gen-delimiters (":", "/", "?", "#", "[", "]", "@") as per RFC 3986 must be escaped. @@ -155,7 +156,7 @@ def parse_userinfo(userinfo: str) -> tuple[str, str]: def parse_ipv6_literal_host(entity: str, default_port: int | None) -> tuple[str, str | int | None]: - """Validates an IPv6 literal host:port string. + """Validate an IPv6 literal host:port string. Returns a 2-tuple of IPv6 literal followed by port where port is default_port if it wasn't specified in entity. @@ -176,7 +177,7 @@ def parse_ipv6_literal_host(entity: str, default_port: int | None) -> tuple[str, def parse_host(entity: str, default_port: int | None = DEFAULT_PORT) -> _Address: - """Validates a host string + """Validate a host string. Returns a 2-tuple of host followed by port where port is default_port if it wasn't specified in the string. @@ -235,7 +236,8 @@ def parse_host(entity: str, default_port: int | None = DEFAULT_PORT) -> _Address def _parse_options(opts: str, delim: str | None) -> _CaseInsensitiveDictionary: - """Helper method for split_options which creates the options dict. + """Create the options dict for split_options. + Also handles the creation of a list for the URI tag_sets/ readpreferencetags portion, and the use of a unicode options string. """ @@ -257,8 +259,7 @@ def _parse_options(opts: str, delim: str | None) -> _CaseInsensitiveDictionary: def _handle_security_options(options: _CaseInsensitiveDictionary) -> _CaseInsensitiveDictionary: - """Raise appropriate errors when conflicting TLS options are present in - the options dictionary. + """Raise errors when conflicting TLS options are present in the options dictionary. :param options: Instance of _CaseInsensitiveDictionary containing MongoDB URI options. @@ -310,9 +311,10 @@ def truth_value(val: Any) -> Any: def _handle_option_deprecations(options: _CaseInsensitiveDictionary) -> _CaseInsensitiveDictionary: - """Issue appropriate warnings when deprecated options are present in the - options dictionary. Removes deprecated option key, value pairs if the - options dictionary is found to also have the renamed option. + """Issue warnings for deprecated options present in the options dictionary. + + Removes deprecated option key, value pairs if the options dictionary is + found to also have the renamed option. :param options: Instance of _CaseInsensitiveDictionary containing MongoDB URI options. @@ -349,8 +351,9 @@ def _handle_option_deprecations(options: _CaseInsensitiveDictionary) -> _CaseIns def _normalize_options(options: _CaseInsensitiveDictionary) -> _CaseInsensitiveDictionary: - """Normalizes option names in the options dictionary by converting them to - their internally-used names. + """Normalize option names in the options dictionary. + + Option names are converted to their internally-used names. :param options: Instance of _CaseInsensitiveDictionary containing MongoDB URI options. @@ -371,7 +374,7 @@ def _normalize_options(options: _CaseInsensitiveDictionary) -> _CaseInsensitiveD def validate_options(opts: Mapping[str, Any], warn: bool = False) -> MutableMapping[str, Any]: - """Validates and normalizes options passed in a MongoDB URI. + """Validate and normalize options passed in a MongoDB URI. Returns a new dictionary of validated and normalized options. If warn is False then errors will be thrown for invalid options, otherwise they will @@ -388,8 +391,7 @@ def validate_options(opts: Mapping[str, Any], warn: bool = False) -> MutableMapp def split_options( opts: str, validate: bool = True, warn: bool = False, normalize: bool = True ) -> MutableMapping[str, Any]: - """Takes the options portion of a MongoDB URI, validates each option - and returns the options in a dictionary. + """Take the options portion of a MongoDB URI and return the options in a dictionary. :param opt: A string representing MongoDB URI options. :param validate: If ``True`` (the default), validate and normalize all @@ -431,9 +433,9 @@ def split_options( def split_hosts(hosts: str, default_port: int | None = DEFAULT_PORT) -> list[_Address]: - """Takes a string of the form host1[:port],host2[:port]... and - splits it into (host, port) tuples. If [:port] isn't present the - default_port is used. + """Split a string of the form host1[:port],host2[:port]... into (host, port) tuples. + + If [:port] isn't present the default_port is used. Returns a set of 2-tuples containing the host name (or IP) followed by port number. diff --git a/pymongo/write_concern.py b/pymongo/write_concern.py index 8b0450d722..ef47f24895 100644 --- a/pymongo/write_concern.py +++ b/pymongo/write_concern.py @@ -26,14 +26,14 @@ # Duplicated here to avoid a circular import. def validate_boolean(option: str, value: Any) -> bool: - """Validates that 'value' is True or False.""" + """Validate that 'value' is True or False.""" if isinstance(value, bool): return value raise TypeError(f"{option} must be True or False, was: {option}={value}") class WriteConcern: - """WriteConcern + """WriteConcern. :param w: (integer or string) Used with replication, write operations will block until they have been replicated to the specified number @@ -121,9 +121,7 @@ def document(self) -> dict[str, Any]: @property def acknowledged(self) -> bool: - """If ``True`` write operations will wait for acknowledgement before - returning. - """ + """If ``True`` write operations will wait for acknowledgement before returning.""" return self.__acknowledged def __repr__(self) -> str: diff --git a/pyproject.toml b/pyproject.toml index a7c4cdce84..0530a7f9ec 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -227,8 +227,11 @@ extend-select = [ "PLR2044", # pylint: empty comment "PLR5501", # pylint: `else: if` should be `elif` "D202", # pydocstyle: no blank lines between docstring and function body + "D205", # pydocstyle: 1 blank line required between summary line and description "D209", # pydocstyle: closing quotes go on their own line "D301", # pydocstyle: docstrings containing \ are defined as string literals + "D400", # pydocstyle: first line should end with a period + "D401", # pydocstyle: first line should be in imperative mood "D403", # pydocstyle: docstrings start with a capital letter ] ignore = [ diff --git a/test/__init__.py b/test/__init__.py index 2bdfb8332f..dc49587eca 100644 --- a/test/__init__.py +++ b/test/__init__.py @@ -566,8 +566,9 @@ def require_replica_set(self, func: Any) -> Any: return self._require(lambda: self.is_rs, "Not connected to a replica set", func=func) def require_secondaries_count(self, count): - """Run a test only if the client is connected to a replica set that has - `count` secondaries. + """Run a test only if the client is connected to a replica set. + + The replica set must have `count` secondaries. """ def sec_count(): @@ -589,8 +590,9 @@ def supports_secondary_read_pref(self): return False def require_secondary_read_pref(self): - """Run a test only if the client is connected to a cluster that - supports secondary read preference + """Run a test only if the client is connected to a cluster. + + The cluster must support secondary read preference. """ return self._require( lambda: self.supports_secondary_read_pref, @@ -618,8 +620,9 @@ def require_mongos(self, func): return self._require(lambda: self.is_mongos, "Must be connected to a mongos", func=func) def require_multiple_mongoses(self, func): - """Run a test only if the client is connected to a sharded cluster - that has 2 mongos nodes. + """Run a test only if the client is connected to a sharded cluster. + + The cluster must have 2 mongos nodes. """ return self._require( lambda: len(self.mongoses) > 1, "Must have multiple mongoses available", func=func @@ -679,9 +682,10 @@ def is_topology_type(self, topologies): return False def require_cluster_type(self, topologies=None): - """Run a test only if the client is connected to a cluster that - conforms to one of the specified topologies. Acceptable topologies - are 'single', 'replicaset', and 'sharded'. + """Run a test only if the client is connected to a conforming cluster. + + The cluster must conform to one of the specified topologies. + Acceptable topologies are 'single', 'replicaset', and 'sharded'. """ topologies = topologies or [] @@ -697,9 +701,7 @@ def require_test_commands(self, func): ) def require_failCommand_fail_point(self, func: Any) -> Any: - """Run a test only if the server supports the failCommand fail - point. - """ + """Run a test only if the server supports the failCommand fail point.""" return self._require( lambda: self.supports_failCommand_fail_point, "failCommand fail point must be supported", @@ -837,7 +839,7 @@ def mongos_seeds(self): @property def supports_failCommand_fail_point(self): - """Does the server support the failCommand fail point?""" + """Does the server support the failCommand fail point.""" return self.test_commands_enabled @property @@ -943,7 +945,7 @@ def fail_point(self, command_args): def fork( self, target: Callable, timeout: float = 60 ) -> Generator[multiprocessing.Process, None, None]: - """Helper for tests that use os.fork() + """Provide a helper for tests that use os.fork(). Use in a with statement: @@ -1316,7 +1318,7 @@ def _create_user(authdb, user, pwd=None, roles=None, **kwargs): def connected(client): - """Convenience to wait for a newly-constructed client to connect.""" + """Wait for a newly-constructed client to connect (convenience helper).""" with warnings.catch_warnings(): # Ignore warning that ping is always routed to primary even # if client's read preference isn't PRIMARY. diff --git a/test/asynchronous/__init__.py b/test/asynchronous/__init__.py index 4a899a016e..27bb5ce8b5 100644 --- a/test/asynchronous/__init__.py +++ b/test/asynchronous/__init__.py @@ -566,8 +566,9 @@ def require_replica_set(self, func: Any) -> Any: return self._require(lambda: self.is_rs, "Not connected to a replica set", func=func) def require_secondaries_count(self, count): - """Run a test only if the client is connected to a replica set that has - `count` secondaries. + """Run a test only if the client is connected to a replica set. + + The replica set must have `count` secondaries. """ async def sec_count(): @@ -589,8 +590,9 @@ async def supports_secondary_read_pref(self): return False def require_secondary_read_pref(self): - """Run a test only if the client is connected to a cluster that - supports secondary read preference + """Run a test only if the client is connected to a cluster. + + The cluster must support secondary read preference. """ return self._require( lambda: self.supports_secondary_read_pref, @@ -618,8 +620,9 @@ def require_mongos(self, func): return self._require(lambda: self.is_mongos, "Must be connected to a mongos", func=func) def require_multiple_mongoses(self, func): - """Run a test only if the client is connected to a sharded cluster - that has 2 mongos nodes. + """Run a test only if the client is connected to a sharded cluster. + + The cluster must have 2 mongos nodes. """ return self._require( lambda: len(self.mongoses) > 1, "Must have multiple mongoses available", func=func @@ -679,9 +682,10 @@ async def is_topology_type(self, topologies): return False def require_cluster_type(self, topologies=None): - """Run a test only if the client is connected to a cluster that - conforms to one of the specified topologies. Acceptable topologies - are 'single', 'replicaset', and 'sharded'. + """Run a test only if the client is connected to a conforming cluster. + + The cluster must conform to one of the specified topologies. + Acceptable topologies are 'single', 'replicaset', and 'sharded'. """ topologies = topologies or [] @@ -697,9 +701,7 @@ def require_test_commands(self, func): ) def require_failCommand_fail_point(self, func: Any) -> Any: - """Run a test only if the server supports the failCommand fail - point. - """ + """Run a test only if the server supports the failCommand fail point.""" return self._require( lambda: self.supports_failCommand_fail_point, "failCommand fail point must be supported", @@ -837,7 +839,7 @@ def mongos_seeds(self): @property def supports_failCommand_fail_point(self): - """Does the server support the failCommand fail point?""" + """Does the server support the failCommand fail point.""" return self.test_commands_enabled @property @@ -943,7 +945,7 @@ async def fail_point(self, command_args): def fork( self, target: Callable, timeout: float = 60 ) -> Generator[multiprocessing.Process, None, None]: - """Helper for tests that use os.fork() + """Provide a helper for tests that use os.fork(). Use in a with statement: @@ -1332,7 +1334,7 @@ async def _create_user(authdb, user, pwd=None, roles=None, **kwargs): async def connected(client): - """Convenience to wait for a newly-constructed client to connect.""" + """Wait for a newly-constructed client to connect (convenience helper).""" with warnings.catch_warnings(): # Ignore warning that ping is always routed to primary even # if client's read preference isn't PRIMARY. diff --git a/test/asynchronous/pymongo_mocks.py b/test/asynchronous/pymongo_mocks.py index e71be6a502..5b27f30727 100644 --- a/test/asynchronous/pymongo_mocks.py +++ b/test/asynchronous/pymongo_mocks.py @@ -106,7 +106,7 @@ def __init__( *args, **kwargs, ): - """An AsyncMongoClient connected to the default server, with a mock topology. + """Create an AsyncMongoClient connected to the default server, with a mock topology. standalones, members, mongoses, arbiters, and down_hosts determine the configuration of the topology. They are formatted like ['a:1', 'b:2']. diff --git a/test/asynchronous/test_change_stream.py b/test/asynchronous/test_change_stream.py index a2cfa8c67a..5b2098dacb 100644 --- a/test/asynchronous/test_change_stream.py +++ b/test/asynchronous/test_change_stream.py @@ -113,8 +113,9 @@ async def get_resume_token(self, invalidate=False): return (await cs.next())["_id"] async def get_start_at_operation_time(self): - """Get an operationTime. Advances the operation clock beyond the most - recently returned timestamp. + """Get an operationTime. + + Advances the operation clock beyond the most recently returned timestamp. """ optime = (await self.client.admin.command("ping"))["operationTime"] return Timestamp(optime.time, optime.inc + 1) @@ -292,9 +293,7 @@ async def _test_full_pipeline(self, expected_cs_stage): @no_type_check async def test_full_pipeline(self): - """$changeStream must be the first stage in a change stream pipeline - sent to the server. - """ + """$changeStream must be the first stage in a change stream pipeline sent to the server.""" await self._test_full_pipeline({}) @no_type_check @@ -333,7 +332,7 @@ def _test_next_blocks(self, change_stream): @no_type_check @async_client_context.require_sync async def test_next_blocks(self): - """Test that next blocks until a change is readable""" + """Test that next blocks until a change is readable.""" # Use a short wait time to speed up the test. async with await self.change_stream(max_await_time_ms=250) as change_stream: self._test_next_blocks(change_stream) @@ -501,9 +500,10 @@ async def _populate_and_exhaust_change_stream(self, change_stream, batch_size=3) return change def _get_expected_resume_token_legacy(self, stream, listener, previous_change=None): - """Predicts what the resume token should currently be for server - versions that don't support postBatchResumeToken. Assumes the stream - has never returned any changes if previous_change is None. + """Predicts what the resume token should currently be. + + For server versions that don't support postBatchResumeToken. Assumes + the stream has never returned any changes if previous_change is None. """ if previous_change is None: agg_cmd = listener.started_events[0] @@ -513,11 +513,12 @@ def _get_expected_resume_token_legacy(self, stream, listener, previous_change=No return previous_change["_id"] def _get_expected_resume_token(self, stream, listener, previous_change=None): - """Predicts what the resume token should currently be for server - versions that support postBatchResumeToken. Assumes the stream has - never returned any changes if previous_change is None. Assumes - listener is a AllowListEventListener that listens for aggregate and - getMore commands. + """Predicts what the resume token should currently be. + + For server versions that support postBatchResumeToken. Assumes the + stream has never returned any changes if previous_change is None. + Assumes listener is a AllowListEventListener that listens for + aggregate and getMore commands. """ if previous_change is None or stream._cursor._has_next(): token = self._get_expected_resume_token_legacy(stream, listener, previous_change) @@ -529,9 +530,7 @@ def _get_expected_resume_token(self, stream, listener, previous_change=None): @no_type_check async def _test_raises_error_on_missing_id(self, expected_exception): - """AsyncChangeStream will raise an exception if the server response is - missing the resume token. - """ + """AsyncChangeStream will raise an exception if the response is missing the resume token.""" async with await self.change_stream([{"$project": {"_id": 0}}]) as change_stream: await self.watched_collection().insert_one({}) with self.assertRaises(expected_exception): @@ -811,9 +810,7 @@ async def test_aggregate_cursor_blocks(self): self._test_next_blocks(change_stream) async def test_full_pipeline(self): - """$changeStream must be the first stage in a change stream pipeline - sent to the server. - """ + """$changeStream must be the first stage in a change stream pipeline sent to the server.""" await self._test_full_pipeline({"allChangesForCluster": True}) @@ -1084,9 +1081,7 @@ async def setFailPoint(self, scenario_dict): ) def assert_list_contents_are_subset(self, superlist, sublist): - """Check that each element in sublist is a subset of the corresponding - element in superlist. - """ + """Check that each sublist element is a subset of the corresponding superlist element.""" self.assertEqual(len(superlist), len(sublist)) for sup, sub in zip(superlist, sublist, strict=True): if isinstance(sub, dict): diff --git a/test/asynchronous/test_client.py b/test/asynchronous/test_client.py index 73b8417226..54dedc0d90 100644 --- a/test/asynchronous/test_client.py +++ b/test/asynchronous/test_client.py @@ -1096,8 +1096,9 @@ def contribute_socket(self, conn, completed_handshake=True): self.assertIsNone(session._transaction.conn_mgr) async def test_constants(self): - """This test uses AsyncMongoClient explicitly to make sure that host and - port are not overloaded. + """This test uses AsyncMongoClient explicitly. + + It makes sure that host and port are not overloaded. """ host, port = await async_client_context.host, await async_client_context.port kwargs: dict = async_client_context.default_client_options.copy() diff --git a/test/asynchronous/test_dns.py b/test/asynchronous/test_dns.py index 6077dbac93..4df4666e40 100644 --- a/test/asynchronous/test_dns.py +++ b/test/asynchronous/test_dns.py @@ -212,8 +212,8 @@ async def test_connect_case_insensitive(self): class TestInitialDnsSeedlistDiscovery(AsyncPyMongoTestCase): - """ - Initial DNS Seedlist Discovery prose tests + """Initial DNS Seedlist Discovery prose tests. + https://github.com/mongodb/specifications/blob/5036f26/source/initial-dns-seedlist-discovery/tests/README.md#prose-tests Numbered tests correspond to the numbered prose tests in the spec. The diff --git a/test/asynchronous/test_examples.py b/test/asynchronous/test_examples.py index 35e0171a86..9828bb2693 100644 --- a/test/asynchronous/test_examples.py +++ b/test/asynchronous/test_examples.py @@ -1427,7 +1427,8 @@ async def predicate_three(): # End Snapshot Query Example 2 async def check_for_snapshot(self, collection): - """Wait for snapshot reads to become available to prevent this error: + """Wait for snapshot reads to become available to prevent this error. + [246:SnapshotUnavailable]: Unable to read from a snapshot due to pending collection catalog changes; please retry the operation. Snapshot timestamp is Timestamp(1646666892, 4). Collection minimum is Timestamp(1646666892, 5) (on localhost:27017, modern retry, attempt 1) From https://github.com/mongodb/mongo-ruby-driver/commit/7c4117b58e3d12e237f7536f7521e18fc15f79ac """ diff --git a/test/asynchronous/test_hello_latched.py b/test/asynchronous/test_hello_latched.py index 20ad7cedff..f06f912b3e 100644 --- a/test/asynchronous/test_hello_latched.py +++ b/test/asynchronous/test_hello_latched.py @@ -12,7 +12,7 @@ # See the License for the specific language governing permissions and # limitations under the License. -"""Test that connection continues to use hello after ismaster returns hello_ok""" +"""Test that connection continues to use hello after ismaster returns hello_ok.""" from __future__ import annotations @@ -30,7 +30,7 @@ def setUp(self): self._sent = [] def create_connection(self) -> AsyncConnection: - """Returns a minimal connection object for _hello""" + """Return a minimal connection object for _hello.""" conn = object.__new__(AsyncConnection) conn.hello_ok = False conn.performed_handshake = True @@ -39,14 +39,14 @@ def create_connection(self) -> AsyncConnection: return conn async def test_hello_is_latched(self): - """ - Regression Test for PYTHON-5904 - Tests for connection hello_ok persistence when connection - Switches from ismaster to hello + """Regression test for PYTHON-5904. + + Tests for connection hello_ok persistence when the connection + switches from ismaster to hello. """ async def mock_conn_command(db, cmd, **kwargs): - """Returns mocked hello and ismaster results for conn.command""" + """Return mocked hello and ismaster results for conn.command.""" self._sent.append(cmd.copy()) if cmd.get("ismaster") == 1: return {"ok": 1, "helloOk": True, "ismaster": True, "maxWireVersion": 25} diff --git a/test/asynchronous/test_locks.py b/test/asynchronous/test_locks.py index 19166f309f..57db3971fe 100644 --- a/test/asynchronous/test_locks.py +++ b/test/asynchronous/test_locks.py @@ -11,7 +11,7 @@ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. -"""Tests for lock.py""" +"""Tests for lock.py.""" from __future__ import annotations diff --git a/test/asynchronous/test_monitor.py b/test/asynchronous/test_monitor.py index 9ad8f00ea3..1b537b7268 100644 --- a/test/asynchronous/test_monitor.py +++ b/test/asynchronous/test_monitor.py @@ -109,8 +109,10 @@ async def test_cleanup_executors_on_client_close(self): @async_client_context.require_sync def test_no_thread_start_runtime_err_on_shutdown(self): - """Test we silence noisy runtime errors fired when the AsyncMongoClient spawns a new thread - on process shutdown. + """Test we silence noisy runtime errors. + + The errors are fired when the AsyncMongoClient spawns a new thread on + process shutdown. """ command = [ sys.executable, diff --git a/test/asynchronous/test_pooling.py b/test/asynchronous/test_pooling.py index 30783a73f1..391e23ee84 100644 --- a/test/asynchronous/test_pooling.py +++ b/test/asynchronous/test_pooling.py @@ -899,11 +899,12 @@ async def test_max_pool_size_with_connection_failure(self): class TestPoolHandleConnectionError(unittest.TestCase): - """PYTHON-5919: PyOpenSSL raises OpenSSL.SSL.SysCallError/ZeroReturnError - (not ssl.SSLEOFError/ssl.SSLZeroReturnError) when the server closes the - socket during the TLS handshake, e.g. when an ingress rate limiter rejects - a connection. Pool._handle_connection_error must recognize these as - handshake-EOF errors and still add the SystemOverloadedError label. + """PYTHON-5919: PyOpenSSL raises OpenSSL.SSL.SysCallError/ZeroReturnError, not ssl.SSLEOFError/ssl.SSLZeroReturnError. + + These errors occur when the server closes the socket during the TLS + handshake, e.g. when an ingress rate limiter rejects a connection. + Pool._handle_connection_error must recognize these as handshake-EOF errors + and still add the SystemOverloadedError label. """ def _make_pool(self): diff --git a/test/asynchronous/test_read_preferences.py b/test/asynchronous/test_read_preferences.py index 8ac49032ef..17e388a361 100644 --- a/test/asynchronous/test_read_preferences.py +++ b/test/asynchronous/test_read_preferences.py @@ -113,14 +113,15 @@ async def asyncSetUp(self): self.addAsyncCleanup(self.db.coll.drop) async def read_from_which_host(self, client): - """Do a find() on the client and return which host was used""" + """Do a find() on the client and return which host was used.""" cursor = client.pymongo_test.coll.find() await anext(cursor) return cursor.address async def read_from_which_kind(self, client): - """Do a find() on the client and return 'primary' or 'secondary' - depending on which the client used. + """Do a find() on the client and return 'primary' or 'secondary'. + + Which one is returned depends on which the client used. """ address = await self.read_from_which_host(client) if address == await client.primary: diff --git a/test/asynchronous/test_retryable_writes.py b/test/asynchronous/test_retryable_writes.py index dc6d841aaf..b89e5f5051 100644 --- a/test/asynchronous/test_retryable_writes.py +++ b/test/asynchronous/test_retryable_writes.py @@ -254,9 +254,7 @@ async def test_server_selection_timeout_not_retried(self): @async_client_context.require_replica_set @async_client_context.require_test_commands async def test_retry_timeout_raises_original_error(self): - """A ServerSelectionTimeoutError on the retry attempt raises the - original error. - """ + """A ServerSelectionTimeoutError on the retry attempt raises the original error.""" listener = OvertCommandListener() client = await self.async_rs_or_single_client(retryWrites=True, event_listeners=[listener]) topology = client._topology @@ -594,8 +592,10 @@ async def test_returns_original_error_code( class TestRetryableWritesTxnNumber(IgnoreDeprecationsTest): @async_client_context.require_replica_set async def test_increment_transaction_id_without_sending_command(self): - """Test that the txnNumber field is properly incremented, even when - the first attempt fails before sending the command. + """Test that the txnNumber field is properly incremented. + + This holds even when the first attempt fails before sending the + command. """ listener = OvertCommandListener() client = await self.async_rs_or_single_client(retryWrites=True, event_listeners=[listener]) diff --git a/test/asynchronous/test_srv_polling.py b/test/asynchronous/test_srv_polling.py index b86adea950..cb26bc8113 100644 --- a/test/asynchronous/test_srv_polling.py +++ b/test/asynchronous/test_srv_polling.py @@ -137,9 +137,7 @@ def get_nodelist(self, client): return client._topology.description.server_descriptions().keys() async def assert_nodelist_change(self, expected_nodelist, client, timeout=(100 * WAIT_TIME)): - """Check if the client._topology eventually sees all nodes in the - expected_nodelist. - """ + """Check if the client._topology eventually sees all nodes in the expected_nodelist.""" def predicate(): nodelist = self.get_nodelist(client) @@ -150,10 +148,11 @@ def predicate(): await async_wait_until(predicate, "see expected nodelist", timeout=timeout) async def assert_nodelist_nochange(self, expected_nodelist, client, timeout=(100 * WAIT_TIME)): - """Check if the client._topology ever deviates from seeing all nodes - in the expected_nodelist. Consistency is checked after sleeping for - (WAIT_TIME * 10) seconds. Also check that the resolver is called at - least once. + """Check if the client._topology ever deviates from the expected_nodelist. + + The topology must continue to see all nodes in the expected_nodelist. + Consistency is checked after sleeping for (WAIT_TIME * 10) seconds. + Also check that the resolver is called at least once. """ def predicate(): diff --git a/test/asynchronous/unified_format.py b/test/asynchronous/unified_format.py index 6f320f6105..56d0706929 100644 --- a/test/asynchronous/unified_format.py +++ b/test/asynchronous/unified_format.py @@ -237,9 +237,7 @@ async def close(self): class EntityMapUtil: - """Utility class that implements an entity map as per the unified - test format specification. - """ + """Utility class that implements an entity map as per the unified test format specification.""" def __init__(self, test_class): self._entities: dict[str, Any] = {} @@ -476,7 +474,7 @@ def get_lsid_for_session(self, session_name): return self._session_lsids[session_name] async def advance_cluster_times(self, cluster_time) -> None: - """Manually synchronize entities when desired""" + """Manually synchronize entities when desired.""" for entity in self._entities.values(): if isinstance(entity, AsyncClientSession) and cluster_time: entity.advance_cluster_time(cluster_time) @@ -1644,13 +1642,16 @@ def generate_test_classes( bypass_test_generation_errors=False, **kwargs, ): - """Method for generating test classes. Returns a dictionary where keys are - the names of test classes and values are the test class objects. + """Generate test classes. + + Returns a dictionary where keys are the names of test classes and values + are the test class objects. """ test_klasses = {} def test_base_class_factory(test_spec): - """Utility that creates the base class to use for test generation. + """Create the base class to use for test generation. + This is needed to ensure that cls.TEST_SPEC is appropriately set when the metaclass __init__ is invoked. """ diff --git a/test/asynchronous/utils.py b/test/asynchronous/utils.py index ebdf70c038..6be25b75cd 100644 --- a/test/asynchronous/utils.py +++ b/test/asynchronous/utils.py @@ -88,9 +88,10 @@ async def async_wait_until(predicate, success_description, timeout=10): async def async_ensure_all_connected(client: AsyncMongoClient) -> None: - """Ensure that the client's connection pool has socket connections to all - members of a replica set. Raises ConfigurationError when called with a - non-replica set client. + """Ensure that the client's connection pool is connected to all members. + + The pool must have socket connections to all members of a replica set. + Raises ConfigurationError when called with a non-replica set client. Depending on the use-case, the caller may need to clear any event listeners that are configured on the client. @@ -126,10 +127,12 @@ async def predicate(): async def asyncAssertRaisesExactly(cls, fn, *args, **kwargs): - """ - Unlike the standard assertRaises, this checks that a function raises a - specific class of exception, and not a subclass. E.g., check that - MongoClient() raises ConnectionFailure but not its subclass, AutoReconnect. + """Check the exact exception class a function raises. + + Unlike the standard assertRaises, this checks that a function raises a specific + class of exception, and not a subclass. E.g., check that + MongoClient() raises ConnectionFailure but not its subclass, + AutoReconnect. """ try: await fn(*args, **kwargs) @@ -146,7 +149,7 @@ async def async_set_fail_point(client, command_args): async def async_joinall(tasks): - """Join threads with a 5-minute timeout, assert joins succeeded""" + """Join threads with a 5-minute timeout, assert joins succeeded.""" if _IS_SYNC: for t in tasks: t.join(300) diff --git a/test/asynchronous/utils_spec_runner.py b/test/asynchronous/utils_spec_runner.py index d36c010749..a0753a9df6 100644 --- a/test/asynchronous/utils_spec_runner.py +++ b/test/asynchronous/utils_spec_runner.py @@ -85,9 +85,7 @@ def __init__(self, create_test, test_class, test_path): self.test_path = test_path def _ensure_min_max_server_version(self, scenario_def, method): - """Test modifier that enforces a version range for the server on a - test case. - """ + """Test modifier that enforces a version range for the server on a test case.""" if "minServerVersion" in scenario_def: min_ver = tuple(int(elt) for elt in scenario_def["minServerVersion"].split(".")) if min_ver is not None: diff --git a/test/helpers_shared.py b/test/helpers_shared.py index 236f8be85c..0e2d567422 100644 --- a/test/helpers_shared.py +++ b/test/helpers_shared.py @@ -125,7 +125,7 @@ def is_server_resolvable(): - """Returns True if 'server' is resolvable.""" + """Return True if 'server' is resolvable.""" socket_timeout = socket.getdefaulttimeout() socket.setdefaulttimeout(1) try: diff --git a/test/lambda/mongodb/app.py b/test/lambda/mongodb/app.py index ca74bd2c3c..6ba1d256b8 100644 --- a/test/lambda/mongodb/app.py +++ b/test/lambda/mongodb/app.py @@ -1,5 +1,5 @@ """ -Lambda function for Python Driver testing +Lambda function for Python Driver testing. Creates the client that is cached for all requests, subscribes to relevant events, and forces the connection pool to get populated. @@ -149,10 +149,7 @@ def reset(): def lambda_handler(event, context): - """ - The handler function itself performs an insert/delete and returns the - id of the document in play. - """ + """Perform an insert/delete and return the id of the document in play.""" print("initializing") db = client.lambdaTest collection = db.test diff --git a/test/mockupdb/test_cursor.py b/test/mockupdb/test_cursor.py index 09ded813ac..addd157fa6 100644 --- a/test/mockupdb/test_cursor.py +++ b/test/mockupdb/test_cursor.py @@ -73,7 +73,7 @@ def test_getmore_load_balanced(self): class TestRetryableErrorCodeCatch(PyMongoTestCase): def _test_fail_on_operation_failure_with_code(self, code): - """Test reads on error codes that should not be retried""" + """Test reads on error codes that should not be retried.""" server = MockupDB() server.run() self.addCleanup(server.stop) diff --git a/test/mockupdb/test_slave_okay_sharded.py b/test/mockupdb/test_slave_okay_sharded.py index e83c715a4a..05a29785c8 100644 --- a/test/mockupdb/test_slave_okay_sharded.py +++ b/test/mockupdb/test_slave_okay_sharded.py @@ -12,8 +12,9 @@ # See the License for the specific language governing permissions and # limitations under the License. -"""Test PyMongo's SlaveOkay with: +"""Test PyMongo's SlaveOkay. +Runs against: - A direct connection to a standalone. - A direct connection to a slave. - A direct connection to a mongos. diff --git a/test/mockupdb/test_slave_okay_single.py b/test/mockupdb/test_slave_okay_single.py index 2830603b60..9aba98b3d4 100644 --- a/test/mockupdb/test_slave_okay_single.py +++ b/test/mockupdb/test_slave_okay_single.py @@ -12,8 +12,9 @@ # See the License for the specific language governing permissions and # limitations under the License. -"""Test PyMongo's SlaveOkay with: +"""Test PyMongo's SlaveOkay. +Runs against: - A direct connection to a standalone. - A direct connection to a slave. - A direct connection to a mongos. diff --git a/test/mod_wsgi_test/mod_wsgi_test.py b/test/mod_wsgi_test/mod_wsgi_test.py index 3aaf0da264..bea1379bfa 100644 --- a/test/mod_wsgi_test/mod_wsgi_test.py +++ b/test/mod_wsgi_test/mod_wsgi_test.py @@ -12,7 +12,7 @@ # See the License for the specific language governing permissions and # limitations under the License. -"""Minimal test of PyMongo in a WSGI application, see bug PYTHON-353""" +"""Minimal test of PyMongo in a WSGI application, see bug PYTHON-353.""" from __future__ import annotations diff --git a/test/pymongo_mocks.py b/test/pymongo_mocks.py index a3092bffe9..8d6e54e1ce 100644 --- a/test/pymongo_mocks.py +++ b/test/pymongo_mocks.py @@ -105,7 +105,7 @@ def __init__( *args, **kwargs, ): - """A MongoClient connected to the default server, with a mock topology. + """Create a MongoClient connected to the default server, with a mock topology. standalones, members, mongoses, arbiters, and down_hosts determine the configuration of the topology. They are formatted like ['a:1', 'b:2']. diff --git a/test/test_bson.py b/test/test_bson.py index 0380d1f22e..feee7e3ff8 100644 --- a/test/test_bson.py +++ b/test/test_bson.py @@ -967,7 +967,7 @@ def test_short_uuid_subtype_binary(self): self.assertEqual(decode_all(payload, standard), [doc]) def test_vector(self): - """Tests of subtype 9""" + """Tests of subtype 9.""" # We start with valid cases, across the 3 dtypes implemented. # Work with a simple vector that can be interpreted as int8, float32, or ubyte list_vector = [127, 8] @@ -1050,7 +1050,7 @@ def assertRepr(self, obj): self.assertEqual(repr(new_obj), repr(obj)) def test_binaryvector_repr(self): - """Tests of repr(BinaryVector)""" + """Tests of repr(BinaryVector).""" data = [1 / 127, -7 / 6] one = BinaryVector(data, BinaryVectorDtype.FLOAT32) self.assertEqual( @@ -1084,7 +1084,7 @@ def test_binaryvector_repr(self): self.assertRepr(zero) def test_binaryvector_equality(self): - """Tests of == __eq__""" + """Tests of == __eq__.""" self.assertEqual( BinaryVector([1.2, 1 - 1 / 3], BinaryVectorDtype.FLOAT32, 0), BinaryVector([1.2, 1 - 1.0 / 3.0], BinaryVectorDtype.FLOAT32, 0), @@ -1103,7 +1103,7 @@ def test_binaryvector_equality(self): @unittest.skipIf(not _NUMPY_AVAILABLE, "numpy optional-dependency not installed.") def test_vector_from_numpy(self): - """Follows test_vector except for input type numpy.ndarray""" + """Follows test_vector except for input type numpy.ndarray.""" # Simple data values could be treated as any of our BinaryVectorDtypes import numpy as np @@ -1162,6 +1162,7 @@ def test_vector_from_numpy(self): def test_unicode_regex(self): """Tests we do not get a segfault for C extension on unicode RegExs. + This had been happening. """ regex = re.compile("revisi\xf3n") diff --git a/test/test_change_stream.py b/test/test_change_stream.py index 9d29a80a44..5aa9ff6d97 100644 --- a/test/test_change_stream.py +++ b/test/test_change_stream.py @@ -111,8 +111,9 @@ def get_resume_token(self, invalidate=False): return (cs.next())["_id"] def get_start_at_operation_time(self): - """Get an operationTime. Advances the operation clock beyond the most - recently returned timestamp. + """Get an operationTime. + + Advances the operation clock beyond the most recently returned timestamp. """ optime = (self.client.admin.command("ping"))["operationTime"] return Timestamp(optime.time, optime.inc + 1) @@ -288,9 +289,7 @@ def _test_full_pipeline(self, expected_cs_stage): @no_type_check def test_full_pipeline(self): - """$changeStream must be the first stage in a change stream pipeline - sent to the server. - """ + """$changeStream must be the first stage in a change stream pipeline sent to the server.""" self._test_full_pipeline({}) @no_type_check @@ -329,7 +328,7 @@ def _test_next_blocks(self, change_stream): @no_type_check @client_context.require_sync def test_next_blocks(self): - """Test that next blocks until a change is readable""" + """Test that next blocks until a change is readable.""" # Use a short wait time to speed up the test. with self.change_stream(max_await_time_ms=250) as change_stream: self._test_next_blocks(change_stream) @@ -491,9 +490,10 @@ def _populate_and_exhaust_change_stream(self, change_stream, batch_size=3): return change def _get_expected_resume_token_legacy(self, stream, listener, previous_change=None): - """Predicts what the resume token should currently be for server - versions that don't support postBatchResumeToken. Assumes the stream - has never returned any changes if previous_change is None. + """Predicts what the resume token should currently be. + + For server versions that don't support postBatchResumeToken. Assumes + the stream has never returned any changes if previous_change is None. """ if previous_change is None: agg_cmd = listener.started_events[0] @@ -503,11 +503,12 @@ def _get_expected_resume_token_legacy(self, stream, listener, previous_change=No return previous_change["_id"] def _get_expected_resume_token(self, stream, listener, previous_change=None): - """Predicts what the resume token should currently be for server - versions that support postBatchResumeToken. Assumes the stream has - never returned any changes if previous_change is None. Assumes - listener is a AllowListEventListener that listens for aggregate and - getMore commands. + """Predicts what the resume token should currently be. + + For server versions that support postBatchResumeToken. Assumes the + stream has never returned any changes if previous_change is None. + Assumes listener is a AllowListEventListener that listens for + aggregate and getMore commands. """ if previous_change is None or stream._cursor._has_next(): token = self._get_expected_resume_token_legacy(stream, listener, previous_change) @@ -519,9 +520,7 @@ def _get_expected_resume_token(self, stream, listener, previous_change=None): @no_type_check def _test_raises_error_on_missing_id(self, expected_exception): - """ChangeStream will raise an exception if the server response is - missing the resume token. - """ + """ChangeStream will raise an exception if the response is missing the resume token.""" with self.change_stream([{"$project": {"_id": 0}}]) as change_stream: self.watched_collection().insert_one({}) with self.assertRaises(expected_exception): @@ -797,9 +796,7 @@ def test_aggregate_cursor_blocks(self): self._test_next_blocks(change_stream) def test_full_pipeline(self): - """$changeStream must be the first stage in a change stream pipeline - sent to the server. - """ + """$changeStream must be the first stage in a change stream pipeline sent to the server.""" self._test_full_pipeline({"allChangesForCluster": True}) @@ -1064,9 +1061,7 @@ def setFailPoint(self, scenario_dict): ) def assert_list_contents_are_subset(self, superlist, sublist): - """Check that each element in sublist is a subset of the corresponding - element in superlist. - """ + """Check that each sublist element is a subset of the corresponding superlist element.""" self.assertEqual(len(superlist), len(sublist)) for sup, sub in zip(superlist, sublist, strict=True): if isinstance(sub, dict): diff --git a/test/test_client.py b/test/test_client.py index c39618eadb..a724d0294b 100644 --- a/test/test_client.py +++ b/test/test_client.py @@ -1067,8 +1067,9 @@ def contribute_socket(self, conn, completed_handshake=True): self.assertIsNone(session._transaction.conn_mgr) def test_constants(self): - """This test uses MongoClient explicitly to make sure that host and - port are not overloaded. + """This test uses MongoClient explicitly. + + It makes sure that host and port are not overloaded. """ host, port = client_context.host, client_context.port kwargs: dict = client_context.default_client_options.copy() diff --git a/test/test_dns.py b/test/test_dns.py index 0889d44ab7..9b1bb6f5d6 100644 --- a/test/test_dns.py +++ b/test/test_dns.py @@ -210,8 +210,8 @@ def test_connect_case_insensitive(self): class TestInitialDnsSeedlistDiscovery(PyMongoTestCase): - """ - Initial DNS Seedlist Discovery prose tests + """Initial DNS Seedlist Discovery prose tests. + https://github.com/mongodb/specifications/blob/5036f26/source/initial-dns-seedlist-discovery/tests/README.md#prose-tests Numbered tests correspond to the numbered prose tests in the spec. The diff --git a/test/test_examples.py b/test/test_examples.py index ea7229fb70..68e163ef41 100644 --- a/test/test_examples.py +++ b/test/test_examples.py @@ -1421,7 +1421,8 @@ def predicate_three(): # End Snapshot Query Example 2 def check_for_snapshot(self, collection): - """Wait for snapshot reads to become available to prevent this error: + """Wait for snapshot reads to become available to prevent this error. + [246:SnapshotUnavailable]: Unable to read from a snapshot due to pending collection catalog changes; please retry the operation. Snapshot timestamp is Timestamp(1646666892, 4). Collection minimum is Timestamp(1646666892, 5) (on localhost:27017, modern retry, attempt 1) From https://github.com/mongodb/mongo-ruby-driver/commit/7c4117b58e3d12e237f7536f7521e18fc15f79ac """ diff --git a/test/test_hello_latched.py b/test/test_hello_latched.py index 8bc8e995a6..80818488fc 100644 --- a/test/test_hello_latched.py +++ b/test/test_hello_latched.py @@ -12,7 +12,7 @@ # See the License for the specific language governing permissions and # limitations under the License. -"""Test that connection continues to use hello after ismaster returns hello_ok""" +"""Test that connection continues to use hello after ismaster returns hello_ok.""" from __future__ import annotations @@ -30,7 +30,7 @@ def setUp(self): self._sent = [] def create_connection(self) -> Connection: - """Returns a minimal connection object for _hello""" + """Return a minimal connection object for _hello.""" conn = object.__new__(Connection) conn.hello_ok = False conn.performed_handshake = True @@ -39,14 +39,14 @@ def create_connection(self) -> Connection: return conn def test_hello_is_latched(self): - """ - Regression Test for PYTHON-5904 - Tests for connection hello_ok persistence when connection - Switches from ismaster to hello + """Regression test for PYTHON-5904. + + Tests for connection hello_ok persistence when the connection + switches from ismaster to hello. """ def mock_conn_command(db, cmd, **kwargs): - """Returns mocked hello and ismaster results for conn.command""" + """Return mocked hello and ismaster results for conn.command.""" self._sent.append(cmd.copy()) if cmd.get("ismaster") == 1: return {"ok": 1, "helloOk": True, "ismaster": True, "maxWireVersion": 25} diff --git a/test/test_kms_connect.py b/test/test_kms_connect.py index 91a48e944a..2f386b8701 100644 --- a/test/test_kms_connect.py +++ b/test/test_kms_connect.py @@ -87,7 +87,7 @@ async def offload(self, func: Callable[..., Any], *args: Any) -> Any: return func(*args) def encryption(self): - """The API's ``encryption`` module.""" + """Return the API's ``encryption`` module.""" if self.is_async: from pymongo.asynchronous import encryption else: @@ -95,7 +95,7 @@ def encryption(self): return encryption def kms_connect(self): - """The API's ``_kms_connect`` module.""" + """Return the API's ``_kms_connect`` module.""" if self.is_async: from pymongo.asynchronous import _kms_connect else: @@ -110,7 +110,7 @@ async def connect(self, address, pool_options, callback, timeout): return module._connect_kms(address, pool_options, callback, timeout) def proxy(self, proxy_url, tls_context=None, headers=None): - """The API's HTTP proxy KMS connect helper.""" + """Return the API's HTTP proxy KMS connect helper.""" if self.is_async: return AsyncHTTPProxyKMSConnect(proxy_url, tls_context, headers=headers) return HTTPProxyKMSConnect(proxy_url, tls_context, headers=headers) @@ -138,7 +138,7 @@ async def callback(context): return func def callback_returning(self, value): - """A kms_connect_callback that always produces ``value``.""" + """Return a kms_connect_callback that always produces ``value``.""" return self.callback(lambda context: value) def client_tls_context(self, verify=False): @@ -148,7 +148,7 @@ def client_tls_context(self, verify=False): return get_ssl_context(None, None, None, None, True, True, False, not self.is_async) def client_encryption(self, kms_providers, key_vault_namespace, client, kms_connect_callback): - """A ClientEncryption for this API using a local key provider.""" + """Return a ClientEncryption for this API using a local key provider.""" if self.is_async: from pymongo.asynchronous.encryption import AsyncClientEncryption @@ -170,7 +170,7 @@ def client_encryption(self, kms_providers, key_vault_namespace, client, kms_conn ) def simple_client(self): - """A lazily-connecting client for this API.""" + """Return a lazily-connecting client for this API.""" if self.is_async: from pymongo.asynchronous.mongo_client import AsyncMongoClient @@ -206,7 +206,7 @@ def _insecure_client_context(): def _kms_context(host="kms.example.com", port=443, timeout=10): - """A KMSConnectContext with the defaults used throughout these tests.""" + """Return a KMSConnectContext with the defaults used throughout these tests.""" return KMSConnectContext(host=host, port=port, timeout=timeout) @@ -266,7 +266,7 @@ def serve(): @contextmanager def _record_and_reply(accepted, reply): - """A proxy that records each CONNECT request, replies ``reply``, and closes.""" + """Create a proxy that records each CONNECT request, replies ``reply``, and closes.""" def handler(conn): request = _read_http_request(conn) @@ -281,7 +281,7 @@ def handler(conn): @contextmanager def _tls_echo_proxy(delay=0): - """A TLS CONNECT proxy that replies 200, then echoes one tunneled read.""" + """Create a TLS CONNECT proxy that replies 200, then echoes one tunneled read.""" server_ctx = _tls_server_context() def handler(conn): diff --git a/test/test_monitor.py b/test/test_monitor.py index b19b64715c..b302bd5003 100644 --- a/test/test_monitor.py +++ b/test/test_monitor.py @@ -105,8 +105,10 @@ def test_cleanup_executors_on_client_close(self): @client_context.require_sync def test_no_thread_start_runtime_err_on_shutdown(self): - """Test we silence noisy runtime errors fired when the MongoClient spawns a new thread - on process shutdown. + """Test we silence noisy runtime errors. + + The errors are fired when the MongoClient spawns a new thread on + process shutdown. """ command = [ sys.executable, diff --git a/test/test_pooling.py b/test/test_pooling.py index 16fcccb377..0cbb1f0a66 100644 --- a/test/test_pooling.py +++ b/test/test_pooling.py @@ -897,11 +897,12 @@ def test_max_pool_size_with_connection_failure(self): class TestPoolHandleConnectionError(unittest.TestCase): - """PYTHON-5919: PyOpenSSL raises OpenSSL.SSL.SysCallError/ZeroReturnError - (not ssl.SSLEOFError/ssl.SSLZeroReturnError) when the server closes the - socket during the TLS handshake, e.g. when an ingress rate limiter rejects - a connection. Pool._handle_connection_error must recognize these as - handshake-EOF errors and still add the SystemOverloadedError label. + """PYTHON-5919: PyOpenSSL raises OpenSSL.SSL.SysCallError/ZeroReturnError, not ssl.SSLEOFError/ssl.SSLZeroReturnError. + + These errors occur when the server closes the socket during the TLS + handshake, e.g. when an ingress rate limiter rejects a connection. + Pool._handle_connection_error must recognize these as handshake-EOF errors + and still add the SystemOverloadedError label. """ def _make_pool(self): diff --git a/test/test_raw_bson_shared.py b/test/test_raw_bson_shared.py index 0cbf560d09..d2006919f0 100644 --- a/test/test_raw_bson_shared.py +++ b/test/test_raw_bson_shared.py @@ -42,8 +42,9 @@ class _TaggedRawBSONDocument(RawBSONDocument): - """RawBSONDocument subclass with a different __init__ signature and - extra instance state, stored in __dict__. + """RawBSONDocument subclass with a different __init__ signature. + + The subclass stores extra instance state in ``__dict__``. """ def __init__(self, bson_bytes, tag, codec_options=None): diff --git a/test/test_read_preferences.py b/test/test_read_preferences.py index a9741e3301..0f0687d131 100644 --- a/test/test_read_preferences.py +++ b/test/test_read_preferences.py @@ -113,14 +113,15 @@ def setUp(self): self.addCleanup(self.db.coll.drop) def read_from_which_host(self, client): - """Do a find() on the client and return which host was used""" + """Do a find() on the client and return which host was used.""" cursor = client.pymongo_test.coll.find() next(cursor) return cursor.address def read_from_which_kind(self, client): - """Do a find() on the client and return 'primary' or 'secondary' - depending on which the client used. + """Do a find() on the client and return 'primary' or 'secondary'. + + Which one is returned depends on which the client used. """ address = self.read_from_which_host(client) if address == client.primary: diff --git a/test/test_retryable_writes.py b/test/test_retryable_writes.py index f523d9d03a..f48f4b2ad1 100644 --- a/test/test_retryable_writes.py +++ b/test/test_retryable_writes.py @@ -252,9 +252,7 @@ def test_server_selection_timeout_not_retried(self): @client_context.require_replica_set @client_context.require_test_commands def test_retry_timeout_raises_original_error(self): - """A ServerSelectionTimeoutError on the retry attempt raises the - original error. - """ + """A ServerSelectionTimeoutError on the retry attempt raises the original error.""" listener = OvertCommandListener() client = self.rs_or_single_client(retryWrites=True, event_listeners=[listener]) topology = client._topology @@ -588,8 +586,10 @@ def test_returns_original_error_code( class TestRetryableWritesTxnNumber(IgnoreDeprecationsTest): @client_context.require_replica_set def test_increment_transaction_id_without_sending_command(self): - """Test that the txnNumber field is properly incremented, even when - the first attempt fails before sending the command. + """Test that the txnNumber field is properly incremented. + + This holds even when the first attempt fails before sending the + command. """ listener = OvertCommandListener() client = self.rs_or_single_client(retryWrites=True, event_listeners=[listener]) diff --git a/test/test_son.py b/test/test_son.py index d5d5573031..d9f91035bd 100644 --- a/test/test_son.py +++ b/test/test_son.py @@ -139,7 +139,7 @@ def test_copying(self): self.assertEqual(id(reflexive_son1), id(reflexive_son1["reflexive"])) def test_iteration(self): - """Test __iter__""" + """Test __iter__.""" # test success case test_son = SON([(1, 100), (2, 200), (3, 300)]) for ele in test_son: @@ -153,7 +153,7 @@ def test_contains_has(self): self.assertNotIn(22, test_son, "in succeeded when it shouldn't") def test_clears(self): - """Test clear()""" + """Test clear().""" test_son = SON([(1, 100), (2, 200), (3, 300)]) test_son.clear() self.assertNotIn(1, test_son) @@ -162,7 +162,7 @@ def test_clears(self): self.assertEqual({}, test_son.to_dict()) def test_len(self): - """Test len""" + """Test len.""" test_son = SON() self.assertEqual(0, len(test_son)) test_son = SON([(1, 100), (2, 200), (3, 300)]) diff --git a/test/test_srv_polling.py b/test/test_srv_polling.py index 6b4e8983bc..78d377f7aa 100644 --- a/test/test_srv_polling.py +++ b/test/test_srv_polling.py @@ -137,9 +137,7 @@ def get_nodelist(self, client): return client._topology.description.server_descriptions().keys() def assert_nodelist_change(self, expected_nodelist, client, timeout=(100 * WAIT_TIME)): - """Check if the client._topology eventually sees all nodes in the - expected_nodelist. - """ + """Check if the client._topology eventually sees all nodes in the expected_nodelist.""" def predicate(): nodelist = self.get_nodelist(client) @@ -150,10 +148,11 @@ def predicate(): wait_until(predicate, "see expected nodelist", timeout=timeout) def assert_nodelist_nochange(self, expected_nodelist, client, timeout=(100 * WAIT_TIME)): - """Check if the client._topology ever deviates from seeing all nodes - in the expected_nodelist. Consistency is checked after sleeping for - (WAIT_TIME * 10) seconds. Also check that the resolver is called at - least once. + """Check if the client._topology ever deviates from the expected_nodelist. + + The topology must continue to see all nodes in the expected_nodelist. + Consistency is checked after sleeping for (WAIT_TIME * 10) seconds. + Also check that the resolver is called at least once. """ def predicate(): diff --git a/test/test_typing.py b/test/test_typing.py index 85b5d9bc1f..e57cc2c9d0 100644 --- a/test/test_typing.py +++ b/test/test_typing.py @@ -12,8 +12,9 @@ # See the License for the specific language governing permissions and # limitations under the License. -"""Test that each file in mypy_fails/ actually fails mypy, and test some -sample client code that uses PyMongo typings. +"""Test that each file in mypy_fails/ actually fails mypy. + +Also test some sample client code that uses PyMongo typings. """ from __future__ import annotations diff --git a/test/test_typing_strict.py b/test/test_typing_strict.py index 433adef841..fcf1f1a3f4 100644 --- a/test/test_typing_strict.py +++ b/test/test_typing_strict.py @@ -25,7 +25,7 @@ def test_generic_arguments() -> None: - """Ensure known usages of generic arguments pass strict typing""" + """Ensure known usages of generic arguments pass strict typing.""" if not TYPE_CHECKING: raise unittest.SkipTest("Used for Type Checking Only") mongo_client: pymongo.MongoClient[dict[str, Any]] = pymongo.MongoClient() diff --git a/test/test_uri_spec.py b/test/test_uri_spec.py index 7aa8803abb..3891fe69b8 100644 --- a/test/test_uri_spec.py +++ b/test/test_uri_spec.py @@ -12,8 +12,10 @@ # See the License for the specific language governing permissions and # limitations under the License. -"""Test that the pymongo.uri_parser module is compliant with the connection -string and uri options specifications. +"""Test the pymongo.uri_parser module. + +Covers the connection string specification and the uri options +specifications. """ from __future__ import annotations diff --git a/test/unified_format.py b/test/unified_format.py index 313b7eda20..0035850348 100644 --- a/test/unified_format.py +++ b/test/unified_format.py @@ -236,9 +236,7 @@ def close(self): class EntityMapUtil: - """Utility class that implements an entity map as per the unified - test format specification. - """ + """Utility class that implements an entity map as per the unified test format specification.""" def __init__(self, test_class): self._entities: dict[str, Any] = {} @@ -475,7 +473,7 @@ def get_lsid_for_session(self, session_name): return self._session_lsids[session_name] def advance_cluster_times(self, cluster_time) -> None: - """Manually synchronize entities when desired""" + """Manually synchronize entities when desired.""" for entity in self._entities.values(): if isinstance(entity, ClientSession) and cluster_time: entity.advance_cluster_time(cluster_time) @@ -1629,13 +1627,16 @@ def generate_test_classes( bypass_test_generation_errors=False, **kwargs, ): - """Method for generating test classes. Returns a dictionary where keys are - the names of test classes and values are the test class objects. + """Generate test classes. + + Returns a dictionary where keys are the names of test classes and values + are the test class objects. """ test_klasses = {} def test_base_class_factory(test_spec): - """Utility that creates the base class to use for test generation. + """Create the base class to use for test generation. + This is needed to ensure that cls.TEST_SPEC is appropriately set when the metaclass __init__ is invoked. """ diff --git a/test/unified_format_shared.py b/test/unified_format_shared.py index 803dfea05d..d860d345fc 100644 --- a/test/unified_format_shared.py +++ b/test/unified_format_shared.py @@ -387,8 +387,9 @@ def closed(self, event: ServerClosedEvent | TopologyClosedEvent) -> None: class MatchEvaluatorUtil: - """Utility class that implements methods for evaluating matches as per - the unified test format specification. + """Utility class that implements methods for evaluating matches. + + Matches are evaluated as per the unified test format specification. """ def __init__(self, test_class): @@ -470,9 +471,10 @@ def _evaluate_special_operation(self, opname, spec, actual, key_to_compare): method(spec, actual, key_to_compare) def _evaluate_if_special_operation(self, expectation, actual, key_to_compare=None): - """Returns True if a special operation is evaluated, False - otherwise. If the ``expectation`` map contains a single key, - value pair we check it for a special operation. + """Return True if a special operation is evaluated, False otherwise. + + If the ``expectation`` map contains a single key, value pair we + check it for a special operation. If given, ``key_to_compare`` is assumed to be the key in ``expectation`` whose corresponding value needs to be evaluated for a possible special operation. ``key_to_compare`` diff --git a/test/utils.py b/test/utils.py index 53d8e9dd95..a5a38d52d4 100644 --- a/test/utils.py +++ b/test/utils.py @@ -88,9 +88,10 @@ def wait_until(predicate, success_description, timeout=10): def ensure_all_connected(client: MongoClient) -> None: - """Ensure that the client's connection pool has socket connections to all - members of a replica set. Raises ConfigurationError when called with a - non-replica set client. + """Ensure that the client's connection pool is connected to all members. + + The pool must have socket connections to all members of a replica set. + Raises ConfigurationError when called with a non-replica set client. Depending on the use-case, the caller may need to clear any event listeners that are configured on the client. @@ -126,10 +127,12 @@ def predicate(): def assertRaisesExactly(cls, fn, *args, **kwargs): - """ - Unlike the standard assertRaises, this checks that a function raises a - specific class of exception, and not a subclass. E.g., check that - MongoClient() raises ConnectionFailure but not its subclass, AutoReconnect. + """Check the exact exception class a function raises. + + Unlike the standard assertRaises, this checks that a function raises a specific + class of exception, and not a subclass. E.g., check that + MongoClient() raises ConnectionFailure but not its subclass, + AutoReconnect. """ try: fn(*args, **kwargs) @@ -146,7 +149,7 @@ def set_fail_point(client, command_args): def joinall(tasks): - """Join threads with a 5-minute timeout, assert joins succeeded""" + """Join threads with a 5-minute timeout, assert joins succeeded.""" if _IS_SYNC: for t in tasks: t.join(300) diff --git a/test/utils_shared.py b/test/utils_shared.py index 9ad97aa1cf..eb39db8379 100644 --- a/test/utils_shared.py +++ b/test/utils_shared.py @@ -12,7 +12,7 @@ # See the License for the specific language governing permissions and # limitations under the License. -"""Shared utilities for testing pymongo""" +"""Shared utilities for testing pymongo.""" from __future__ import annotations @@ -379,7 +379,7 @@ def reset(self): self._call_list = [] def call_list(self): - """Returns a copy of the call list.""" + """Return a copy of the call list.""" return self._call_list[:] @property @@ -389,22 +389,23 @@ def call_count(self): def one(s): - """Get one element of a set""" + """Get one element of a set.""" return next(iter(s)) def oid_generated_on_process(oid): - """Makes a determination as to whether the given ObjectId was generated - by the current process, based on the 5-byte random number in the ObjectId. + """Determine if the ObjectId was generated by the current process. + + The determination is based on the 5-byte random number in the ObjectId. """ return ObjectId._random() == oid.binary[4:9] def delay(sec): - """Along with a ``$where`` operator, this triggers an arbitrarily long-running - operation on the server. + """Trigger an arbitrarily long-running operation on the server. - This can be useful in time-sensitive tests (e.g., timeouts, signals). + Use along with a ``$where`` operator. This can be useful in + time-sensitive tests (e.g., timeouts, signals). Note that you must have at least one document in the collection or the server may decide not to sleep at all. @@ -492,7 +493,7 @@ def _ignore_deprecations(): def ignore_deprecations(wrapped=None): - """A context manager or a decorator.""" + """Use as a context manager or a decorator.""" if wrapped: if iscoroutinefunction(wrapped): @@ -661,7 +662,7 @@ def cat_files(dest, *sources): @contextlib.contextmanager def assertion_context(msg): - """A context manager that adds info to an assertion failure.""" + """Act as a context manager that adds info to an assertion failure.""" try: yield except AssertionError as exc: @@ -800,8 +801,10 @@ def barrier_wait(barrier, timeout: float | None = None): def pack_msg_header(length: int, request_id: int, response_to: int, op_code: int) -> bytes: - """Pack a MongoDB wire-protocol message header (``