Some updates to docs (#1534)

cognite/client/data_classes/filters.py

@@ -251,16 +251,56 @@ def _filter_body(self, camel_case_property: bool) -> dict[str, Any]:
 
 @final
 class And(CompoundFilter):
+    """A filter that combines multiple filters with a logical AND.
+
+    Args:
+        *filters (Filter): The filters to combine.
+
+
+    Example:
+
+        Combine an In and an Equals filter::
+
+            >>> from cognite.client.data_classes.filters import And, Equals, In
+            >>> filter = And(Equals(("some", "property"), 42), In(("another", "property"), ["a", "b", "c"]))
+    """
+
     _filter_name = "and"
 
 
 @final
 class Or(CompoundFilter):
+    """A filter that combines multiple filters with a logical OR.
+
+    Args:
+        *filters (Filter): The filters to combine.
+
+    Example:
+
+        Combine an In and an Equals filter::
+
+            >>> from cognite.client.data_classes.filters import Or, Equals, In
+            >>> filter = Or(Equals(("some", "property"), 42), In(("another", "property"), ["a", "b", "c"]))
+    """
+
     _filter_name = "or"
 
 
 @final
 class Not(CompoundFilter):
+    """A filter that negates another filter.
+
+    Args:
+        filter (Filter): The filter to negate.
+
+    Example:
+
+        Negate an Equals filter:
+
+            >>> from cognite.client.data_classes.filters import Or, Equals
+            >>> filter = Not(Equals(("some", "property"), 42))
+    """
+
     _filter_name = "not"
 
     def __init__(self, filter: Filter) -> None:
@@ -272,6 +312,23 @@ def _filter_body(self, camel_case_property: bool) -> dict:
 
 @final
 class Nested(Filter):
+    """A filter to apply to the node at the other side of a direct relation.
+
+    Args:
+        scope (PropertyReference): The direct relation property to traverse.
+        filter (Filter): The filter to apply.
+
+    Example:
+
+        Filter on a related node's property:
+
+            >>> from cognite.client.data_classes.filters import Nested, Equals
+            >>> filter = Nested(
+            ...     ("somespace", "somecontainer", "related"),
+            ...     Equals(("somespace", "somecontainer", "someProperty"), 42)
+            ... )
+    """
+
     _filter_name = "nested"
 
     def __init__(self, scope: PropertyReference, filter: Filter) -> None:
@@ -284,6 +341,16 @@ def _filter_body(self, camel_case_property: bool) -> dict[str, Any]:
 
 @final
 class MatchAll(Filter):
+    """A filter that matches all instances.
+
+    Example:
+
+        Match everything:
+
+            >>> from cognite.client.data_classes.filters import MatchAll
+            >>> filter = MatchAll()
+    """
+
     _filter_name = "matchAll"
 
     def _filter_body(self, camel_case_property: bool) -> dict[str, Any]:
@@ -292,6 +359,20 @@ def _filter_body(self, camel_case_property: bool) -> dict[str, Any]:
 
 @final
 class HasData(Filter):
+    """Return only instances that have data in the provided containers/views.
+
+    Args:
+        containers (Sequence[tuple[str, str] | ContainerId] | None): Containers to check for data.
+        views (Sequence[tuple[str, str, str] | ViewId] | None): Views to check for data.
+
+    Example:
+
+        Filter on having data in a specific container:
+
+            >>> from cognite.client.data_classes.filters import HasData
+            >>> filter = HasData(containers=[("somespace", "somecontainer")])
+    """
+
     _filter_name = "hasData"
 
     def __init__(
@@ -319,6 +400,23 @@ def _filter_body(self, camel_case_property: bool) -> list:
 
 @final
 class Range(FilterWithProperty):
+    """Filters results based on a range of values.
+
+    Args:
+        property (PropertyReference): The property to filter on.
+        gt (FilterValue | None): Greater than.
+        gte (FilterValue | None): Greater than or equal to.
+        lt (FilterValue | None): Less than.
+        lte (FilterValue | None): Less than or equal to.
+
+    Example:
+
+        Retrieve all instances with a property value greater than 42:
+
+            >>> from cognite.client.data_classes.filters import Range
+            >>> filter = Range(("some", "property"), gt=42)
+    """
+
     _filter_name = "range"
 
     def __init__(
@@ -350,6 +448,26 @@ def _filter_body(self, camel_case_property: bool) -> dict[str, Any]:
 
 @final
 class Overlaps(Filter):
+    """Filters results based whether or not the provided range overlaps with the range given by the start and end
+    properties.
+
+    Args:
+        start_property (PropertyReference): The property to filter on.
+        end_property (PropertyReference): The property to filter on.
+        gt (FilterValue | None): Greater than.
+        gte (FilterValue | None): Greater than or equal to.
+        lt (FilterValue | None): Less than.
+        lte (FilterValue | None): Less than or equal to.
+
+
+    Example:
+
+        Retrieve all instances with a range overlapping with the range (42, 100):
+
+            >>> from cognite.client.data_classes.filters import Overlaps
+            >>> filter = Overlaps(("some", "startProperty"), ("some", "endProperty"), gt=42, lt=100)
+    """
+
     _filter_name = "overlaps"
 
     def __init__(
@@ -387,31 +505,114 @@ def _filter_body(self, camel_case_property: bool) -> dict[str, Any]:
 
 @final
 class Equals(FilterWithPropertyAndValue):
+    """Filters results based on whether the property equals the provided value.
+
+    Args:
+        property (PropertyReference): The property to filter on.
+        value (FilterValue): The value to filter on.
+
+    Example:
+
+        Filter than can be used to retrieve items where the property value equals 42:
+
+            >>> from cognite.client.data_classes.filters import Equals
+            >>> filter = Equals(("some", "property"), 42)
+    """
+
     _filter_name = "equals"
 
 
 @final
 class In(FilterWithPropertyAndValueList):
+    """Filters results based on whether the property equals one of the provided values.
+
+    Args:
+        property (PropertyReference): The property to filter on.
+        values (FilterValueList): The values to filter on.
+
+    Example:
+
+        Filter than can be used to retrieve items where the property value equals 42 or 43 (or both):
+
+            >>> from cognite.client.data_classes.filters import In
+            >>> filter = In(("some", "property"), [42, 43])
+    """
+
     _filter_name = "in"
 
 
 @final
 class Exists(FilterWithProperty):
+    """Filters results based on whether the property is set or not.
+
+    Args:
+        property (PropertyReference): The property to filter on.
+
+    Example:
+
+        Filter than can be used to retrieve items where the property value is set:
+
+            >>> from cognite.client.data_classes.filters import Exists
+            >>> filter = Exists(("some", "property"))
+    """
+
     _filter_name = "exists"
 
 
 @final
 class Prefix(FilterWithPropertyAndValue):
+    """Prefix filter results based on whether the (text) property starts with the provided value.
+
+    Args:
+        property (PropertyReference): The property to filter on.
+        value (FilterValue): The value to filter on.
+
+    Example:
+
+        Filter than can be used to retrieve items where the property value starts with "somePrefix":
+
+            >>> from cognite.client.data_classes.filters import Prefix
+            >>> filter = Prefix(("some", "property"), "somePrefix")
+    """
+
     _filter_name = "prefix"
 
 
 @final
 class ContainsAny(FilterWithPropertyAndValueList):
+    """Returns results where the referenced property contains _any_ of the provided values.
+
+    Args:
+        property (PropertyReference): The property to filter on.
+        values (FilterValueList): The value to filter on.
+
+    Example:
+
+        Filter than can be used to retrieve items where the property value contains either 42 or 43:
+
+            >>> from cognite.client.data_classes.filters import ContainsAny
+            >>> filter = ContainsAny(("some", "property"), [42, 43])
+    """
+
     _filter_name = "containsAny"
 
 
 @final
 class ContainsAll(FilterWithPropertyAndValueList):
+    """Returns results where the referenced property contains _all_ of the provided values.
+
+    Args:
+        property (PropertyReference): The property to filter on.
+        values (FilterValueList): The value to filter on.
+
+    Example:
+
+        Filter than can be used to retrieve items where the property value contains both 42 and 43:
+
+            >>> from cognite.client.data_classes.filters import ContainsAll
+            >>> filter = ContainsAll(("some", "property"), [42, 43])
+    """
+
     _filter_name = "containsAll"
 
 

docs/source/assets.rst

@@ -0,0 +1,75 @@
+Assets
+======
+Retrieve an asset by id
+^^^^^^^^^^^^^^^^^^^^^^^
+.. automethod:: cognite.client._api.assets.AssetsAPI.retrieve
+
+Retrieve multiple assets by id
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. automethod:: cognite.client._api.assets.AssetsAPI.retrieve_multiple
+
+Retrieve an asset subtree
+^^^^^^^^^^^^^^^^^^^^^^^^^
+.. automethod:: cognite.client._api.assets.AssetsAPI.retrieve_subtree
+
+List assets
+^^^^^^^^^^^
+.. automethod:: cognite.client._api.assets.AssetsAPI.list
+
+Aggregate assets
+^^^^^^^^^^^^^^^^
+.. automethod:: cognite.client._api.assets.AssetsAPI.aggregate
+
+Aggregate Asset Count
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. automethod:: cognite.client._api.assets.AssetsAPI.aggregate_count
+
+Aggregate Asset Value Cardinality
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. automethod:: cognite.client._api.assets.AssetsAPI.aggregate_cardinality_values
+
+Aggregate Asset Property Cardinality
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. automethod:: cognite.client._api.assets.AssetsAPI.aggregate_cardinality_properties
+
+Aggregate Asset Unique Values
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. automethod:: cognite.client._api.assets.AssetsAPI.aggregate_unique_values
+
+Aggregate Asset Unique Properties
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. automethod:: cognite.client._api.assets.AssetsAPI.aggregate_unique_properties
+
+Search for assets
+^^^^^^^^^^^^^^^^^
+.. automethod:: cognite.client._api.assets.AssetsAPI.search
+
+Create assets
+^^^^^^^^^^^^^
+.. automethod:: cognite.client._api.assets.AssetsAPI.create
+
+Create asset hierarchy
+^^^^^^^^^^^^^^^^^^^^^^
+.. automethod:: cognite.client._api.assets.AssetsAPI.create_hierarchy
+
+Delete assets
+^^^^^^^^^^^^^
+.. automethod:: cognite.client._api.assets.AssetsAPI.delete
+
+Filter assets
+^^^^^^^^^^^^^
+.. automethod:: cognite.client._api.assets.AssetsAPI.filter
+
+Update assets
+^^^^^^^^^^^^^
+.. automethod:: cognite.client._api.assets.AssetsAPI.update
+
+Upsert assets
+^^^^^^^^^^^^^
+.. automethod:: cognite.client._api.assets.AssetsAPI.upsert
+
+Asset Data classes
+^^^^^^^^^^^^^^^^^^
+.. automodule:: cognite.client.data_classes.assets
+    :members:
+    :show-inheritance: