Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .evergreen/scripts/generate_config.py
Original file line number Diff line number Diff line change
Expand Up @@ -850,7 +850,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
Expand Down
6 changes: 3 additions & 3 deletions .evergreen/scripts/resync_all_specs.py
Original file line number Diff line number Diff line change
Expand Up @@ -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():
Expand Down Expand Up @@ -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("-", "_")
Expand Down Expand Up @@ -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(
Expand Down
2 changes: 1 addition & 1 deletion .evergreen/scripts/setup_uv.py
Original file line number Diff line number Diff line change
Expand Up @@ -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"


Expand Down
82 changes: 49 additions & 33 deletions .evergreen/scripts/test_generate_config.py
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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"))
Expand All @@ -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 = []
Expand All @@ -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()
Expand All @@ -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 (
(
Expand All @@ -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"]
Expand Down Expand Up @@ -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]}"
Expand All @@ -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
Expand All @@ -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 = []
Expand Down Expand Up @@ -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 [])}
Expand Down Expand Up @@ -324,7 +338,8 @@ def test_fuzz_task_wiring():


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).
Expand All @@ -342,10 +357,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
Expand Down
4 changes: 2 additions & 2 deletions .evergreen/scripts/test_setup_uv.py
Original file line number Diff line number Diff line change
Expand Up @@ -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)}
Expand Down Expand Up @@ -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)
Expand Down
13 changes: 7 additions & 6 deletions bson/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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


Expand Down
5 changes: 3 additions & 2 deletions bson/_helpers.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 3 additions & 1 deletion bson/binary.py
Original file line number Diff line number Diff line change
Expand Up @@ -233,6 +233,7 @@ class BinaryVectorDtype(Enum):

class BinaryVector:
"""Vector of numbers along with metadata for binary interoperability.

.. versionadded:: 4.10
"""

Expand All @@ -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
Expand Down
32 changes: 20 additions & 12 deletions bson/codec_options.py
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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.
Expand All @@ -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
Expand All @@ -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::
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion bson/datetime_ms.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading
Loading