Skip to content

chore: make ruff also format code examples in docstrings #2318

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
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

chore: make ruff also format code examples in docstrings #2318

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f1c4429
add setting to pyproject to make ruff fix docstrings
haakonvt Sep 5, 2025
b57a65f
format all the files!!
haakonvt Sep 5, 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
42 changes: 22 additions & 20 deletions cognite/client/_api/agents/agents.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,10 +49,9 @@ def upsert(self, agents: AgentUpsert | Sequence[AgentUpsert]) -> Agent | AgentLi
... AgentUpsert,
... QueryKnowledgeGraphAgentToolUpsert,
... QueryKnowledgeGraphAgentToolConfiguration,
... DataModelInfo
... DataModelInfo,
... )
>>> client = CogniteClient()
...
>>> find_assets_tool = QueryKnowledgeGraphAgentToolUpsert(
... name="find assets",
... description="Use this tool to find assets",
Expand All @@ -65,12 +64,10 @@ def upsert(self, agents: AgentUpsert | Sequence[AgentUpsert]) -> Agent | AgentLi
... view_external_ids=["CogniteAsset"],
... )
... ]
... )
... ),
... )
>>> agent = AgentUpsert(
... external_id="my_agent",
... name="My Agent",
... tools=[find_assets_tool]
... external_id="my_agent", name="My Agent", tools=[find_assets_tool]
... )
>>> client.agents.upsert(agents=[agent])

Expand All @@ -83,9 +80,8 @@ def upsert(self, agents: AgentUpsert | Sequence[AgentUpsert]) -> Agent | AgentLi
... DataModelInfo,
... SummarizeDocumentAgentToolUpsert,
... AskDocumentAgentToolUpsert,
... QueryTimeSeriesDatapointsAgentToolUpsert
... QueryTimeSeriesDatapointsAgentToolUpsert,
... )
...
>>> find_assets_tool = QueryKnowledgeGraphAgentToolUpsert(
... name="find assets",
... description="Use this tool to query the knowledge graph for assets",
Expand All @@ -98,7 +94,7 @@ def upsert(self, agents: AgentUpsert | Sequence[AgentUpsert]) -> Agent | AgentLi
... view_external_ids=["CogniteAsset"],
... )
... ]
... )
... ),
... )
>>> find_files_tool = QueryKnowledgeGraphAgentToolUpsert(
... name="find files",
Expand All @@ -112,7 +108,7 @@ def upsert(self, agents: AgentUpsert | Sequence[AgentUpsert]) -> Agent | AgentLi
... view_external_ids=["CogniteFile"],
... )
... ]
... )
... ),
... )
>>> find_time_series_tool = QueryKnowledgeGraphAgentToolUpsert(
... name="find time series",
Expand All @@ -126,26 +122,33 @@ def upsert(self, agents: AgentUpsert | Sequence[AgentUpsert]) -> Agent | AgentLi
... view_external_ids=["CogniteTimeSeries"],
... )
... ]
... )
... ),
... )
>>> summarize_tool = SummarizeDocumentAgentToolUpsert(
... name="summarize document",
... description="Use this tool to get a summary of a document"
... description="Use this tool to get a summary of a document",
... )
>>> ask_doc_tool = AskDocumentAgentToolUpsert(
... name="ask document",
... description="Use this tool to ask questions about specific documents"
... description="Use this tool to ask questions about specific documents",
... )
>>> ts_tool = QueryTimeSeriesDatapointsAgentToolUpsert(
... name="query time series",
... description="Use this tool to query time series data points"
... description="Use this tool to query time series data points",
... )
>>> agent = AgentUpsert(
... external_id="my_agent",
... name="My agent",
... description="An agent with many tools",
... instructions="You are a helpful assistant that can query knowledge graphs, summarize documents, answer questions about documents, and query time series data points.",
... tools=[find_assets_tool, find_files_tool, find_time_series_tool, summarize_tool, ask_doc_tool, ts_tool]
... tools=[
... find_assets_tool,
... find_files_tool,
... find_time_series_tool,
... summarize_tool,
... ask_doc_tool,
... ts_tool,
... ],
... )
>>> client.agents.upsert(agents=[agent])

Expand Down Expand Up @@ -268,8 +271,7 @@ def chat(
>>> from cognite.client.data_classes.agents import Message
>>> client = CogniteClient()
>>> response = client.agents.chat(
... agent_id="my_agent",
... messages=Message("What can you help me with?")
... agent_id="my_agent", messages=Message("What can you help me with?")
... )
>>> print(response.text)

Expand All @@ -278,7 +280,7 @@ def chat(
>>> follow_up = client.agents.chat(
... agent_id="my_agent",
... messages=Message("Tell me more about that"),
... cursor=response.cursor
... cursor=response.cursor,
... )

Send multiple messages at once:
Expand All @@ -287,8 +289,8 @@ def chat(
... agent_id="my_agent",
... messages=[
... Message("Help me find the 1st stage compressor."),
... Message("Once you have found it, find related time series.")
... ]
... Message("Once you have found it, find related time series."),
... ],
... )
"""
self._warnings.warn()
Expand Down
4 changes: 1 addition & 3 deletions cognite/client/_api/ai/tools/documents.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,9 +43,7 @@ def summarize(
You can also use external ID or instance ID:

>>> from cognite.client.data_classes.data_modeling import NodeId
>>> client.ai.tools.documents.summarize(
... instance_id=NodeId("my-space", "my-xid")
... )
>>> client.ai.tools.documents.summarize(instance_id=NodeId("my-space", "my-xid"))
"""
ident = IdentifierSequenceWithInstanceId.load(id, external_id, instance_id).as_singleton()
res = self._post(self._RESOURCE_PATH + "/summarize", json={"items": ident.as_dicts()})
Expand Down
4 changes: 3 additions & 1 deletion cognite/client/_api/annotations.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -233,7 +233,9 @@ def list(self, filter: AnnotationFilter | dict, limit: int | None = DEFAULT_LIMI
>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes import AnnotationFilter
>>> client = CogniteClient()
>>> flt = AnnotationFilter(annotated_resource_type="file", annotated_resource_ids=[{"id": 123}])
>>> flt = AnnotationFilter(
... annotated_resource_type="file", annotated_resource_ids=[{"id": 123}]
... )
>>> res = client.annotations.list(flt, limit=None)
"""
assert_type(filter, "filter", [AnnotationFilter, dict], allow_none=False)
Expand Down
71 changes: 48 additions & 23 deletions cognite/client/_api/assets.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -281,7 +281,9 @@ def retrieve_multiple(

Get assets by external id:

>>> res = client.assets.retrieve_multiple(external_ids=["abc", "def"], ignore_unknown_ids=True)
>>> res = client.assets.retrieve_multiple(
... external_ids=["abc", "def"], ignore_unknown_ids=True
... )
"""
identifiers = IdentifierSequence.load(ids=ids, external_ids=external_ids)
return self._retrieve_multiple(
Expand All @@ -303,7 +305,9 @@ def aggregate(self, filter: AssetFilter | dict[str, Any] | None = None) -> list[

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> aggregate_by_prefix = client.assets.aggregate(filter={"external_id_prefix": "prefix"})
>>> aggregate_by_prefix = client.assets.aggregate(
... filter={"external_id_prefix": "prefix"}
... )
"""
warnings.warn(
f"This method is deprecated. Use {self.__class__.__name__}.aggregate_count instead.", DeprecationWarning
Expand Down Expand Up @@ -382,8 +386,8 @@ def aggregate_cardinality_values(
>>> from cognite.client.data_classes.assets import AssetProperty
>>> is_critical = Search(AssetProperty.description, "critical")
>>> critical_assets = client.assets.aggregate_cardinality_values(
... AssetProperty.metadata_key("timezone"),
... advanced_filter=is_critical)
... AssetProperty.metadata_key("timezone"), advanced_filter=is_critical
... )
"""
self._validate_filter(advanced_filter)
return self._advanced_aggregate(
Expand Down Expand Up @@ -458,7 +462,9 @@ def aggregate_unique_values(
>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes.assets import AssetProperty
>>> client = CogniteClient()
>>> result = client.assets.aggregate_unique_values(AssetProperty.metadata_key("timezone"))
>>> result = client.assets.aggregate_unique_values(
... AssetProperty.metadata_key("timezone")
... )
>>> print(result.unique)

Get the different labels with count used for assets created after 2020-01-01 in your CDF project:
Expand All @@ -467,8 +473,12 @@ def aggregate_unique_values(
>>> from cognite.client.data_classes.assets import AssetProperty
>>> from cognite.client.utils import timestamp_to_ms
>>> from datetime import datetime
>>> created_after_2020 = filters.Range(AssetProperty.created_time, gte=timestamp_to_ms(datetime(2020, 1, 1)))
>>> result = client.assets.aggregate_unique_values(AssetProperty.labels, advanced_filter=created_after_2020)
>>> created_after_2020 = filters.Range(
... AssetProperty.created_time, gte=timestamp_to_ms(datetime(2020, 1, 1))
... )
>>> result = client.assets.aggregate_unique_values(
... AssetProperty.labels, advanced_filter=created_after_2020
... )
>>> print(result.unique)

Get the different labels with count for assets updated after 2020-01-01 in your CDF project, but exclude all labels that
Expand All @@ -478,8 +488,14 @@ def aggregate_unique_values(
>>> from cognite.client.data_classes import aggregations
>>> from cognite.client.data_classes import filters
>>> not_test = aggregations.Not(aggregations.Prefix("test"))
>>> created_after_2020 = filters.Range(AssetProperty.last_updated_time, gte=timestamp_to_ms(datetime(2020, 1, 1)))
>>> result = client.assets.aggregate_unique_values(AssetProperty.labels, advanced_filter=created_after_2020, aggregate_filter=not_test)
>>> created_after_2020 = filters.Range(
... AssetProperty.last_updated_time, gte=timestamp_to_ms(datetime(2020, 1, 1))
... )
>>> result = client.assets.aggregate_unique_values(
... AssetProperty.labels,
... advanced_filter=created_after_2020,
... aggregate_filter=not_test,
... )
>>> print(result.unique)

"""
Expand Down Expand Up @@ -632,7 +648,8 @@ def create_hierarchy(
>>> assets = [
... Asset(external_id="root", name="root"),
... Asset(external_id="child1", parent_external_id="root", name="child1"),
... Asset(external_id="child2", parent_external_id="root", name="child2")]
... Asset(external_id="child2", parent_external_id="root", name="child2"),
... ]
>>> res = client.assets.create_hierarchy(assets)

Create an asset hierarchy, but run update for existing assets:
Expand Down Expand Up @@ -723,7 +740,7 @@ def delete(

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> client.assets.delete(id=[1,2,3], external_id="3")
>>> client.assets.delete(id=[1, 2, 3], external_id="3")
"""
self._delete_multiple(
identifiers=IdentifierSequence.load(ids=id, external_ids=external_id),
Expand Down Expand Up @@ -765,7 +782,11 @@ def update(
>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes import AssetUpdate
>>> client = CogniteClient()
>>> my_update = AssetUpdate(id=1).description.set("New description").metadata.add({"key": "value"})
>>> my_update = (
... AssetUpdate(id=1)
... .description.set("New description")
... .metadata.add({"key": "value"})
... )
>>> res1 = client.assets.update(my_update)
>>> # Remove an already set field like so
>>> another_update = AssetUpdate(id=1).description.set(None)
Expand Down Expand Up @@ -889,8 +910,8 @@ def filter(
>>> from cognite.client.data_classes.assets import AssetProperty, SortableAssetProperty
>>> in_timezone = filters.Prefix(AssetProperty.metadata_key("timezone"), "Europe")
>>> res = client.assets.filter(
... filter=in_timezone,
... sort=(SortableAssetProperty.external_id, "asc"))
... filter=in_timezone, sort=(SortableAssetProperty.external_id, "asc")
... )

"""
warnings.warn(
Expand Down Expand Up @@ -951,12 +972,14 @@ def search(

Search for assets using multiple filters, finding all assets with name similar to `xyz` with parent asset `123` or `456` with source `some source`:

>>> res = client.assets.search(name="xyz",filter={"parent_ids": [123,456],"source": "some source"})
>>> res = client.assets.search(
... name="xyz", filter={"parent_ids": [123, 456], "source": "some source"}
... )

Search for an asset with an attached label:

>>> my_label_filter = LabelFilter(contains_all=["PUMP"])
>>> res = client.assets.search(name="xyz",filter=AssetFilter(labels=my_label_filter))
>>> res = client.assets.search(name="xyz", filter=AssetFilter(labels=my_label_filter))
"""
return self._search(
list_cls=AssetList,
Expand Down Expand Up @@ -1075,12 +1098,12 @@ def list(
Iterate over assets:

>>> for asset in client.assets:
... asset # do something with the asset
... asset # do something with the asset

Iterate over chunks of assets to reduce memory load:

>>> for asset_list in client.assets(chunk_size=2500):
... asset_list # do something with the assets
... asset_list # do something with the assets

Filter assets based on labels:

Expand All @@ -1105,17 +1128,19 @@ def list(
>>> from cognite.client.data_classes.assets import AssetProperty, SortableAssetProperty
>>> in_timezone = filters.Prefix(AssetProperty.metadata_key("timezone"), "Europe")
>>> res = client.assets.list(
... advanced_filter=in_timezone,
... sort=(SortableAssetProperty.external_id, "asc"))
... advanced_filter=in_timezone, sort=(SortableAssetProperty.external_id, "asc")
... )

Combine filter and advanced filter:

>>> from cognite.client.data_classes import filters
>>> not_instrument_lvl5 = filters.And(
... filters.ContainsAny("labels", ["Level5"]),
... filters.Not(filters.ContainsAny("labels", ["Instrument"]))
... filters.ContainsAny("labels", ["Level5"]),
... filters.Not(filters.ContainsAny("labels", ["Instrument"])),
... )
>>> res = client.assets.list(
... asset_subtree_ids=[123456], advanced_filter=not_instrument_lvl5
... )
>>> res = client.assets.list(asset_subtree_ids=[123456], advanced_filter=not_instrument_lvl5)

"""
agg_props = self._process_aggregated_props(aggregated_properties)
Expand Down
Loading
Loading