From 322e1d1ef6d531ceaf1886f95dcc2021d870211c Mon Sep 17 00:00:00 2001 From: Alex Stephen Date: Thu, 24 Sep 2026 20:40:51 +0000 Subject: [PATCH] Infra: Replace archived pydocstyle hook with ruff D rules pycqa/pydocstyle is archived, which zizmor 1.30.0 flags as archived-uses in .pre-commit-config.yaml. Enable ruff's pydocstyle rules with the same ignore list and fix the docstrings it reports. Co-authored-by: Fokko Driesprong Co-Authored-By: Claude Opus 5.5 (1M context) --- .pre-commit-config.yaml | 10 ----- pyiceberg/expressions/__init__.py | 1 + pyiceberg/expressions/visitors.py | 1 + pyiceberg/table/__init__.py | 64 ++++++++++++++---------------- pyiceberg/table/update/snapshot.py | 5 ++- pyiceberg/table/update/validate.py | 2 +- pyiceberg/transforms.py | 1 + pyiceberg/utils/decimal.py | 2 + pyproject.toml | 10 ++++- 9 files changed, 48 insertions(+), 48 deletions(-) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index f57bcd0d8d..f0dedd0804 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -52,16 +52,6 @@ repos: hooks: - id: markdownlint args: ["--fix"] - - repo: https://github.com/pycqa/pydocstyle - rev: 6.3.0 - hooks: - - id: pydocstyle - args: - [ - "--ignore=D100,D102,D101,D103,D104,D107,D203,D212,D213,D404,D405,D406,D407,D411,D413,D415,D417", - ] - additional_dependencies: - - tomli==2.0.1 - repo: https://github.com/codespell-project/codespell rev: v2.4.1 hooks: diff --git a/pyiceberg/expressions/__init__.py b/pyiceberg/expressions/__init__.py index ece0db82db..1fb9810fff 100644 --- a/pyiceberg/expressions/__init__.py +++ b/pyiceberg/expressions/__init__.py @@ -221,6 +221,7 @@ def eval(self, struct: StructProtocol) -> Any: Args: struct (StructProtocol): A row object that abides by the StructProtocol and returns values given a position. + Returns: Any: The value at the referenced field's position in `struct`. """ diff --git a/pyiceberg/expressions/visitors.py b/pyiceberg/expressions/visitors.py index 5072d3de11..c8ef8d4c4a 100644 --- a/pyiceberg/expressions/visitors.py +++ b/pyiceberg/expressions/visitors.py @@ -331,6 +331,7 @@ def visit_unbound_predicate(self, predicate: UnboundPredicate) -> T: Args: predicate (UnboundPredicate): An unbound predicate. + Raises: TypeError: This always raises since an unbound predicate is not expected in a bound boolean expression. """ diff --git a/pyiceberg/table/__init__.py b/pyiceberg/table/__init__.py index 2c5c26800c..c535a6d319 100644 --- a/pyiceberg/table/__init__.py +++ b/pyiceberg/table/__init__.py @@ -855,7 +855,6 @@ def upsert( """Shorthand API for performing an upsert to an iceberg table. Args: - df: The input dataframe to upsert with the table's data. join_cols: Columns to join on, if not provided, it will use the identifier-field-ids. when_matched_update_all: Bool indicating to update rows that are matched but require an update @@ -866,26 +865,25 @@ def upsert( branch: Branch Reference to run the upsert operation snapshot_properties: Custom properties to be added to the snapshot summary - To learn more about the identifier-field-ids: https://iceberg.apache.org/spec/#identifier-field-ids - - Example Use Cases: - Case 1: Both Parameters = True (Full Upsert) - Existing row found → Update it - New row found → Insert it + To learn more about the identifier-field-ids: https://iceberg.apache.org/spec/#identifier-field-ids - Case 2: when_matched_update_all = False, when_not_matched_insert_all = True - Existing row found → Do nothing (no updates) - New row found → Insert it + Example Use Cases: + Case 1: Both Parameters = True (Full Upsert) + Existing row found → Update it + New row found → Insert it - Case 3: when_matched_update_all = True, when_not_matched_insert_all = False - Existing row found → Update it - New row found → Do nothing (no inserts) + Case 2: when_matched_update_all = False, when_not_matched_insert_all = True + Existing row found → Do nothing (no updates) + New row found → Insert it - Case 4: Both Parameters = False (No Merge Effect) - Existing row found → Do nothing - New row found → Do nothing - (Function effectively does nothing) + Case 3: when_matched_update_all = True, when_not_matched_insert_all = False + Existing row found → Update it + New row found → Do nothing (no inserts) + Case 4: Both Parameters = False (No Merge Effect) + Existing row found → Do nothing + New row found → Do nothing + (Function effectively does nothing) Returns: An UpsertResult class (contains details of rows updated and inserted) @@ -1660,7 +1658,6 @@ def upsert( """Shorthand API for performing an upsert to an iceberg table. Args: - df: The input dataframe to upsert with the table's data. join_cols: Columns to join on, if not provided, it will use the identifier-field-ids. when_matched_update_all: Bool indicating to update rows that are matched but require an update @@ -1671,26 +1668,25 @@ def upsert( branch: Branch Reference to run the upsert operation snapshot_properties: Custom properties to be added to the snapshot summary - To learn more about the identifier-field-ids: https://iceberg.apache.org/spec/#identifier-field-ids - - Example Use Cases: - Case 1: Both Parameters = True (Full Upsert) - Existing row found → Update it - New row found → Insert it + To learn more about the identifier-field-ids: https://iceberg.apache.org/spec/#identifier-field-ids - Case 2: when_matched_update_all = False, when_not_matched_insert_all = True - Existing row found → Do nothing (no updates) - New row found → Insert it + Example Use Cases: + Case 1: Both Parameters = True (Full Upsert) + Existing row found → Update it + New row found → Insert it - Case 3: when_matched_update_all = True, when_not_matched_insert_all = False - Existing row found → Update it - New row found → Do nothing (no inserts) + Case 2: when_matched_update_all = False, when_not_matched_insert_all = True + Existing row found → Do nothing (no updates) + New row found → Insert it - Case 4: Both Parameters = False (No Merge Effect) - Existing row found → Do nothing - New row found → Do nothing - (Function effectively does nothing) + Case 3: when_matched_update_all = True, when_not_matched_insert_all = False + Existing row found → Update it + New row found → Do nothing (no inserts) + Case 4: Both Parameters = False (No Merge Effect) + Existing row found → Do nothing + New row found → Do nothing + (Function effectively does nothing) Returns: An UpsertResult class (contains details of rows updated and inserted) diff --git a/pyiceberg/table/update/snapshot.py b/pyiceberg/table/update/snapshot.py index 8024e808b2..8feebb9901 100644 --- a/pyiceberg/table/update/snapshot.py +++ b/pyiceberg/table/update/snapshot.py @@ -1084,7 +1084,8 @@ def _remove_ref_snapshot(self, ref_name: str) -> ManageSnapshots: Args: ref_name: branch / tag name to remove Stages the updates and requirements for the remove-snapshot-ref. - Returns + + Returns: This method for chaining """ updates = (RemoveSnapshotRefUpdate(ref_name=ref_name),) @@ -1381,6 +1382,7 @@ def by_id(self, snapshot_id: int) -> ExpireSnapshots: Args: snapshot_id (int): The ID of the snapshot to expire. + Returns: This for method chaining. """ @@ -1402,6 +1404,7 @@ def by_ids(self, snapshot_ids: list[int]) -> ExpireSnapshots: Args: snapshot_ids (List[int]): List of snapshot IDs to expire. + Returns: This for method chaining. """ diff --git a/pyiceberg/table/update/validate.py b/pyiceberg/table/update/validate.py index 0545182bf0..66e3f111ea 100644 --- a/pyiceberg/table/update/validate.py +++ b/pyiceberg/table/update/validate.py @@ -301,7 +301,7 @@ def _starting_sequence_number(table: Table, starting_snapshot: Snapshot) -> int: table: Table to find snapshot from starting_snapshot: Snapshot from where to start looking - Returns + Returns: Sequence number as int """ if starting_snapshot is not None: diff --git a/pyiceberg/transforms.py b/pyiceberg/transforms.py index 54c01d9bed..74925c695f 100644 --- a/pyiceberg/transforms.py +++ b/pyiceberg/transforms.py @@ -761,6 +761,7 @@ class TruncateTransform(Transform[S, S]): Args: width (int): The truncate width, should be positive. + Raises: ValueError: If a type is provided that is incompatible with a Truncate transform. """ diff --git a/pyiceberg/utils/decimal.py b/pyiceberg/utils/decimal.py index 0ed2de1d5b..6d1f73a73c 100644 --- a/pyiceberg/utils/decimal.py +++ b/pyiceberg/utils/decimal.py @@ -76,6 +76,7 @@ def decimal_to_bytes(value: Decimal, byte_length: int | None = None) -> bytes: Args: value (Decimal): a decimal value. byte_length (int): The number of bytes. + Returns: bytes: the unscaled value of the Decimal as bytes. """ @@ -105,6 +106,7 @@ def truncate_decimal(value: Decimal, width: int) -> Decimal: Args: value (Decimal): a decimal value. width (int): A width for the returned Decimal instance. + Returns: Decimal: A truncated Decimal instance. """ diff --git a/pyproject.toml b/pyproject.toml index bd9d1091b4..d1e3cb0550 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -202,14 +202,20 @@ select = [ "I", # isort "UP", # pyupgrade "T100", # flake8-debugger + "D", # pydocstyle +] +ignore = [ + "D100", "D101", "D102", "D103", "D104", "D107", + "D203", "D212", "D213", + "D404", "D405", "D406", "D407", "D411", "D413", "D415", "D417", ] -ignore = [] # Allow autofix for all enabled rules (when `--fix`) is provided. fixable = ["ALL"] unfixable = [] -per-file-ignores = {} +# pydocstyle skips test files by default (match = (?!test_).*\.py); mirror that for the D rules. +per-file-ignores = { "tests/**/test_*.py" = ["D"] } # Allow unused variables when underscore-prefixed. dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"