Skip to content

feat: [Hackathron] Docstring linter #1037

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
yuriy-encord wants to merge 2 commits into
base: master
Choose a base branch
from
Open

feat: [Hackathron] Docstring linter #1037

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9155b0f
Implement docstring linter
yuriy-encord Nov 30, 2025
5edcc6e
Remove linter from pre-commit hooks
yuriy-encord Nov 30, 2025
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
7 changes: 7 additions & 0 deletions .pre-commit-config.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,3 +29,10 @@ repos:
entry: uv run mypy
language: system
files: ^encord/.*py$
- id: docstring-linter
name: Docstring Quality Check
entry: python tools/docstring_linter.py --check --config tools/docstring_linter_config.json --files
language: system
types: [python]
files: ^encord/.*py$
pass_filenames: true
24 changes: 13 additions & 11 deletions encord/client.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@
client.get_project()

Returns:
Project: A project record instance. See Project ORM for details.
Project: A project record instance. See Project ORM for details.

"""

Expand Down Expand Up @@ -192,9 +192,9 @@ def get_dataset(self) -> OrmDataset:
OrmDataset: A dataset record instance.

Raises:
AuthorisationError: If the dataset API key is invalid.
ResourceNotFoundError: If no dataset exists by the specified dataset EntityId.
UnknownError: If an error occurs while retrieving the dataset.
:class:`~encord.exceptions.AuthorisationError`: If the dataset API key is invalid.
:class:`~encord.exceptions.ResourceNotFoundError`: If no dataset exists by the specified dataset EntityId.
:class:`~encord.exceptions.UnknownError`: If an error occurs while retrieving the dataset.
"""
res = self._querier.basic_getter(
OrmDataset,
Expand Down Expand Up @@ -227,12 +227,12 @@ def list_data_rows(
data_hashes: optional list of individual data unit hashes to include

Returns:
List[DataRow]: A list of DataRows object that match the filter
List[:class:`~encord.orm.dataset.DataRow`]: A list of :class:`~encord.orm.dataset.DataRow`s object that match the filter

@gemini-code-assist gemini-code-assist Bot Nov 30, 2025

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The auto-generated docstring contains a grammatical error: '...a list of :class:~encord.orm.dataset.DataRows object...'. This should be '...a list of :class:~encord.orm.dataset.DataRow objects...'. This suggests a potential issue in the linter's pluralization logic.

Suggested change
List[:class:`~encord.orm.dataset.DataRow`]: A list of :class:`~encord.orm.dataset.DataRow`s object that match the filter
List[:class:`~encord.orm.dataset.DataRow`]: A list of :class:`~encord.orm.dataset.DataRow` objects that match the filter


Raises:
AuthorisationError: If the dataset API key is invalid.
ResourceNotFoundError: If no dataset exists by the specified dataset EntityId.
UnknownError: If an error occurs while retrieving the dataset.
:class:`~encord.exceptions.AuthorisationError`: If the dataset API key is invalid.
:class:`~encord.exceptions.ResourceNotFoundError`: If no dataset exists by the specified dataset EntityId.
:class:`~encord.exceptions.UnknownError`: If an error occurs while retrieving the dataset.
"""
created_before = optional_datetime_to_iso_str("created_before", created_before)
created_after = optional_datetime_to_iso_str("created_after", created_after)
Expand Down Expand Up @@ -803,9 +803,9 @@ def get_project(self, include_labels_metadata=True) -> OrmProject:
OrmProject: A project record instance.

Raises:
AuthorisationError: If the project API key is invalid.
ResourceNotFoundError: If no project exists by the specified project EntityId.
UnknownError: If an error occurs while retrieving the project.
:class:`~encord.exceptions.AuthorisationError`: If the project API key is invalid.
:class:`~encord.exceptions.ResourceNotFoundError`: If no project exists by the specified project EntityId.
:class:`~encord.exceptions.UnknownError`: If an error occurs while retrieving the project.
"""
return self._querier.basic_getter(
OrmProject, payload={"include_labels_metadata": include_labels_metadata}, retryable=True
Expand Down Expand Up @@ -1021,6 +1021,7 @@ def create_label_rows(
uids: list of data uids where label_status is NOT_LABELLED.
get_signed_url: bool whether to fetch the signed url for the internal label row
branch_name: Optional[str] which branch name against which to create the label row

Returns:
List[LabelRow]: A list of created label rows
"""
Expand Down Expand Up @@ -1157,6 +1158,7 @@ def get_label_logs(

def __set_project_ontology(self, ontology: LegacyOntology) -> bool:
"""Save updated project ontology

Args:
ontology: the updated project ontology

Expand Down
6 changes: 3 additions & 3 deletions encord/client_metadata_schema.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,8 +10,8 @@ def set_client_metadata_schema_from_dict(api_client: ApiClient, json_dict: Dict[
"""Set the client metadata schema from a dictionary.

Args:
api_client (ApiClient): The API client to use for the request.
json_dict (Dict[str, orm.ClientMetadataSchemaTypes]): A dictionary containing the client metadata schema types.
api_client: The API client to use for the request.
json_dict: A dictionary containing the client metadata schema types.

Raises:
NotImplementedError: If an unexpected data type is encountered in the schema.
Expand All @@ -32,7 +32,7 @@ def get_client_metadata_schema(api_client: ApiClient) -> Optional[Dict[str, orm.
"""Retrieve the client metadata schema.

Args:
api_client (ApiClient): The API client to use for the request.
api_client: The API client to use for the request.

Returns:
Optional[Dict[str, orm.ClientMetadataSchemaTypes]]: A dictionary containing the client metadata schema types
Expand Down
48 changes: 24 additions & 24 deletions encord/collection.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -163,8 +163,8 @@ def update_collection(self, name: Optional[str] = None, description: Optional[st
"""Update the collection's name and/or description.

Args:
name (Optional[str]): The new name for the collection.
description (Optional[str]): The new description for the collection.
name: The new name for the collection.
description: The new description for the collection.
"""
payload = UpdateCollectionPayload(name=name, description=description)
self._client.patch(
Expand All @@ -182,11 +182,11 @@ def list_items(
"""List storage items in the collection.

Args:
include_client_metadata (Optional[bool]): Whether to include client metadata for each item.
page_size (Optional[int]): The number of items to fetch per page.
include_client_metadata: Whether to include client metadata for each item.
page_size: The number of items to fetch per page.

Returns:
Iterator[StorageItem]: An iterator containing storage items in the collection.
Iterator[:class:`~encord.storage.StorageItem`]: An iterator containing storage items in the collection.
"""
params = GetCollectionItemsParams(includeClientMetadata=include_client_metadata, pageSize=page_size)
paged_items = self._client.get_paged_iterator(
Expand All @@ -203,11 +203,11 @@ def list_items_include_inaccessible(
"""List storage items in the collection, including those that are inaccessible.

Args:
include_client_metadata (Optional[bool]): Whether to include client metadata for each item.
page_size (Optional[int]): The number of items to fetch per page.
include_client_metadata: Whether to include client metadata for each item.
page_size: The number of items to fetch per page.

Returns:
Iterator[Union[StorageItem, StorageItemInaccessible]]: An iterator containing both accessible
Iterator[Union[:class:`~encord.storage.StorageItem`, :class:`~encord.storage.StorageItem`Inaccessible]]: An iterator containing both accessible
and inaccessible storage items in the collection.
Comment on lines +210 to 211

@gemini-code-assist gemini-code-assist Bot Nov 30, 2025

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The generated reference for StorageItemInaccessible appears to be broken. The linter seems to have incorrectly split the class name, resulting in :class:~encord.storage.StorageItemInaccessible. The correct syntax should be a single :class: role for the full class name, like :class:~encord.storage.StorageItemInaccessible``.

Suggested change
Iterator[Union[:class:`~encord.storage.StorageItem`, :class:`~encord.storage.StorageItem`Inaccessible]]: An iterator containing both accessible
and inaccessible storage items in the collection.
Iterator[Union[:class:`~encord.storage.StorageItem`, :class:`~encord.storage.StorageItemInaccessible`]]: An iterator containing both accessible
and inaccessible storage items in the collection.

"""
params = GetCollectionItemsParams(includeClientMetadata=include_client_metadata, pageSize=page_size)
Expand All @@ -228,8 +228,8 @@ def add_items(self, storage_item_uuids: Sequence[Union[UUID, str]]) -> Collectio
"""Add storage items to the collection.

Args:
storage_item_uuids (Sequence[Union[UUID, str]]): The list of storage item UUIDs to be added.
Either UUIDs or string representations of UUIDs are accepted.
storage_item_uuids: The list of storage item UUIDs to be added.
Either UUIDs or string representations of UUIDs are accepted.

Returns:
CollectionBulkItemResponse: The response after adding items to the collection.
Expand All @@ -247,8 +247,8 @@ def remove_items(self, storage_item_uuids: Sequence[Union[UUID, str]]) -> Collec
"""Remove storage items from the collection.

Args:
storage_item_uuids (Sequence[Union[UUID, str]]): The list of storage item UUIDs to be removed.
Either UUIDs or string representations of UUIDs are accepted.
storage_item_uuids: The list of storage item UUIDs to be removed.
Either UUIDs or string representations of UUIDs are accepted.

Returns:
CollectionBulkItemResponse: The response after removing items from the collection.
Expand All @@ -266,7 +266,7 @@ def add_preset_items(self, filter_preset: Union[FilterPreset, UUID, str]) -> Non
"""Async operation to add storage items matching a filter preset to the collection.

Args:
filter_preset (Union[FilterPreset, UUID, str]): The filter preset or its UUID/ID used to filter items.
filter_preset: The filter preset or its UUID/ID used to filter items.
"""
if isinstance(filter_preset, FilterPreset):
preset_uuid = filter_preset.uuid
Expand All @@ -289,7 +289,7 @@ def remove_preset_items(self, filter_preset: Union[FilterPreset, UUID, str]) ->
"""Async operation to remove storage items matching a filter preset from the collection.

Args:
filter_preset (Union[FilterPreset, UUID, str]): The filter preset or its UUID/ID used to filter items.
filter_preset: The filter preset or its UUID/ID used to filter items.
"""
if isinstance(filter_preset, FilterPreset):
preset_uuid = filter_preset.uuid
Expand Down Expand Up @@ -467,8 +467,8 @@ def update_collection(self, name: Optional[str] = None, description: Optional[st
"""Update the collection's name and/or description.

Args:
name (Optional[str]): The new name for the collection.
description (Optional[str]): The new description for the collection.
name: The new name for the collection.
description: The new description for the collection.
"""
payload = UpdateCollectionPayload(name=name, description=description)
self._client.patch(
Expand All @@ -485,10 +485,10 @@ def list_frames(
"""List frames in the collection.

Args:
page_size (Optional[int]): The number of items to fetch per page.
page_size: The number of items to fetch per page.

Returns:
Iterator[Tuple[LabelRowV2, List[ProjectDataCollectionInstance]]]: An list of tuples containing label
Iterator[Tuple[:class:`~encord.objects.LabelRowV2`, List[ProjectDataCollectionInstance]]]: An list of tuples containing label
row and corresponding frame instances in the collection.
"""
params = GetCollectionItemsParams(pageSize=page_size)
Expand All @@ -515,10 +515,10 @@ def list_annotations(
"""List annotations in the collection.

Args:
page_size (Optional[int]): The number of items to fetch per page.
page_size: The number of items to fetch per page.

Returns:
Iterator[Tuple[LabelRowV2, List[ProjectLabelCollectionInstance]]]: An list of tuples containing label
Iterator[Tuple[:class:`~encord.objects.LabelRowV2`, List[ProjectLabelCollectionInstance]]]: An list of tuples containing label
row and corresponding label instances in the collection.
"""
params = GetCollectionItemsParams(pageSize=page_size)
Expand All @@ -544,7 +544,7 @@ def add_items(
"""Add data items to the collection.

Args:
items (Sequence[ProjectDataCollectionItemRequest | ProjectLabelCollectionItemRequest]): The list of data items to be added.
items: The list of data items to be added.

Returns:
ProjectCollectionBulkItemResponse: The response after adding items to the collection.
Expand All @@ -563,7 +563,7 @@ def remove_items(
"""Remove data items from the collection.

Args:
items (Sequence[ProjectDataCollectionItemRequest | ProjectLabelCollectionItemRequest]): The list of data items to be removed.
items: The list of data items to be removed.

Returns:
ProjectCollectionBulkItemResponse: The response after removing items from the collection.
Expand All @@ -580,7 +580,7 @@ def add_preset_items(self, filter_preset: Union[FilterPreset, UUID, str]) -> Non
"""Async operation to add storage items matching a filter preset to the collection.

Args:
filter_preset (Union[FilterPreset, UUID, str]): The filter preset or its UUID/ID used to filter items.
filter_preset: The filter preset or its UUID/ID used to filter items.
"""
if isinstance(filter_preset, FilterPreset):
preset_uuid = filter_preset.uuid
Expand All @@ -603,7 +603,7 @@ def remove_preset_items(self, filter_preset: Union[FilterPreset, UUID, str]) ->
"""Async operation to remove storage items matching a filter preset from the collection.

Args:
filter_preset (Union[FilterPreset, UUID, str]): The filter preset or its UUID/ID used to filter items.
filter_preset: The filter preset or its UUID/ID used to filter items.
"""
if isinstance(filter_preset, FilterPreset):
preset_uuid = filter_preset.uuid
Expand Down
1 change: 1 addition & 0 deletions encord/common/utils.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,7 @@ def validate_user_agent_suffix(user_agent_suffix: str) -> str:
"""
Validate a User-Agent string according to RFC 9110, excluding comments.
Returns it whitespace trimmed

Args:
user_agent_suffix: The User-Agent string to validate

Expand Down
35 changes: 18 additions & 17 deletions encord/configs.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -77,9 +77,9 @@ def define_headers(self, resource_id: Optional[str], resource_type: Optional[str
"""Define headers for a request.

Args:
resource_id (Optional[str]): The resource ID.
resource_type (Optional[str]): The resource type.
data (str): The request data.
resource_id: The resource ID.
resource_type: The resource type.
data: The request data.

Returns:
Dict[str, Any]: A dictionary of headers.
Expand All @@ -91,7 +91,7 @@ def define_headers_v2(self, request: PreparedRequest) -> PreparedRequest:
"""Define headers for a request (v2).

Args:
request (PreparedRequest): The prepared request.
request: The prepared request.

Returns:
PreparedRequest: The prepared request with headers defined.
Expand Down Expand Up @@ -126,9 +126,9 @@ def define_headers(self, resource_id: Optional[str], resource_type: Optional[str
"""Define headers for a user-specific request.

Args:
resource_id (Optional[str]): The resource ID.
resource_type (Optional[str]): The resource type.
data (str): The request data.
resource_id: The resource ID.
resource_type: The resource type.
data: The request data.

Returns:
Dict[str, Any]: A dictionary of headers.
Expand All @@ -139,7 +139,7 @@ def define_headers_v2(self, request: PreparedRequest) -> PreparedRequest:
"""Define headers for a user-specific request (v2).

Args:
request (PreparedRequest): The prepared request.
request: The prepared request.

Returns:
PreparedRequest: The prepared request with headers defined.
Expand Down Expand Up @@ -193,7 +193,7 @@ def get_env_ssh_key() -> str:
str: The raw SSH key.

Raises:
ResourceNotFoundError: If the SSH key file or key is not found or is empty.
:class:`~encord.exceptions.ResourceNotFoundError`: If the SSH key file or key is not found or is empty.
"""
ssh_file = os.environ.get(_ENCORD_SSH_KEY_FILE)
if ssh_file:
Expand Down Expand Up @@ -265,9 +265,9 @@ def define_headers(self, resource_id: Optional[str], resource_type: Optional[str
"""Define headers for an SSH key-based request.

Args:
resource_id (Optional[str]): The resource ID.
resource_type (Optional[str]): The resource type.
data (str): The request data.
resource_id: The resource ID.
resource_type: The resource type.
data: The request data.

Returns:
Dict[str, Any]: A dictionary of headers.
Expand All @@ -288,7 +288,7 @@ def define_headers_v2(self, request: PreparedRequest) -> PreparedRequest:
"""Define headers for an SSH key-based request (v2).

Args:
request (PreparedRequest): The prepared request.
request: The prepared request.

Returns:
PreparedRequest: The prepared request with headers defined.
Expand Down Expand Up @@ -356,9 +356,9 @@ def define_headers(self, resource_id: Optional[str], resource_type: Optional[str
"""Define headers for a bearer token-based request.

Args:
resource_id (Optional[str]): The resource ID.
resource_type (Optional[str]): The resource type.
data (str): The request data.
resource_id: The resource ID.
resource_type: The resource type.
data: The request data.

Returns:
Dict[str, Any]: A dictionary of headers.
Expand All @@ -378,7 +378,7 @@ def define_headers_v2(self, request: PreparedRequest) -> PreparedRequest:
"""Define headers for a bearer token-based request (v2).

Args:
request (PreparedRequest): The prepared request.
request: The prepared request.

Returns:
PreparedRequest: The prepared request with headers defined.
Expand All @@ -402,6 +402,7 @@ def from_bearer_token(
token: The bearer token.
requests_settings: The requests settings for all outgoing network requests.
domain: Base domain for the endpoints

Returns:
BearerConfig: The bearer token configuration.
"""
Expand Down
Loading
Loading