Entities: Advanced filtering

ayon_api/_api.py

@@ -84,6 +84,7 @@
         ActionModeType,
         StreamType,
         EntityListAttributeDefinitionDict,
+        AdvancedFilterDict,
     )
     from ._api_helpers.links import CreateLinkData
 
@@ -4218,6 +4219,7 @@ def get_folders(
     tags: Optional[Iterable[str]] = None,
     active: Optional[bool] = True,
     has_links: Optional[bool] = None,
+    filters: Optional[AdvancedFilterDict] = None,
     fields: Optional[Iterable[str]] = None,
     own_attributes: bool = False,
 ) -> Generator[FolderDict, None, None]:
@@ -4259,6 +4261,7 @@ def get_folders(
             Both are returned if is set to None.
         has_links (Optional[Literal[IN, OUT, ANY]]): Filter
             representations with IN/OUT/ANY links.
+        filters (Optional[AdvancedFilterDict]): Advanced filtering options.
         fields (Optional[Iterable[str]]): Fields to be queried for
             folder. All possible folder fields are returned
             if 'None' is passed.
@@ -4286,6 +4289,7 @@ def get_folders(
         tags=tags,
         active=active,
         has_links=has_links,
+        filters=filters,
         fields=fields,
         own_attributes=own_attributes,
     )
@@ -4571,6 +4575,7 @@ def get_tasks(
     statuses: Optional[Iterable[str]] = None,
     tags: Optional[Iterable[str]] = None,
     active: Optional[bool] = True,
+    filters: Optional[AdvancedFilterDict] = None,
     fields: Optional[Iterable[str]] = None,
     own_attributes: bool = False,
 ) -> Generator[TaskDict, None, None]:
@@ -4595,6 +4600,7 @@ def get_tasks(
             filtering.
         active (Optional[bool]): Filter active/inactive tasks.
             Both are returned if is set to None.
+        filters (Optional[AdvancedFilterDict]): Advanced filtering options.
         fields (Optional[Iterable[str]]): Fields to be queried for
             folder. All possible folder fields are returned
             if 'None' is passed.
@@ -4617,6 +4623,7 @@ def get_tasks(
         statuses=statuses,
         tags=tags,
         active=active,
+        filters=filters,
         fields=fields,
         own_attributes=own_attributes,
     )
@@ -4695,6 +4702,7 @@ def get_tasks_by_folder_paths(
     statuses: Optional[Iterable[str]] = None,
     tags: Optional[Iterable[str]] = None,
     active: Optional[bool] = True,
+    filters: Optional[AdvancedFilterDict] = None,
     fields: Optional[Iterable[str]] = None,
     own_attributes: bool = False,
 ) -> dict[str, list[TaskDict]]:
@@ -4717,6 +4725,7 @@ def get_tasks_by_folder_paths(
             filtering.
         active (Optional[bool]): Filter active/inactive tasks.
             Both are returned if is set to None.
+        filters (Optional[AdvancedFilterDict]): Advanced filtering options.
         fields (Optional[Iterable[str]]): Fields to be queried for
             folder. All possible folder fields are returned
             if 'None' is passed.
@@ -4739,6 +4748,7 @@ def get_tasks_by_folder_paths(
         statuses=statuses,
         tags=tags,
         active=active,
+        filters=filters,
         fields=fields,
         own_attributes=own_attributes,
     )
@@ -4988,6 +4998,7 @@ def get_products(
     statuses: Optional[Iterable[str]] = None,
     tags: Optional[Iterable[str]] = None,
     active: Optional[bool] = True,
+    filters: Optional[AdvancedFilterDict] = None,
     fields: Optional[Iterable[str]] = None,
     own_attributes=_PLACEHOLDER,
 ) -> Generator[ProductDict, None, None]:
@@ -5019,6 +5030,7 @@ def get_products(
             for filtering.
         active (Optional[bool]): Filter active/inactive products.
             Both are returned if is set to None.
+        filters (Optional[AdvancedFilterDict]): Advanced filtering options.
         fields (Optional[Iterable[str]]): Fields to be queried for
             folder. All possible folder fields are returned
             if 'None' is passed.
@@ -5043,6 +5055,7 @@ def get_products(
         statuses=statuses,
         tags=tags,
         active=active,
+        filters=filters,
         fields=fields,
         own_attributes=own_attributes,
     )
@@ -5325,6 +5338,7 @@ def get_versions(
     statuses: Optional[Iterable[str]] = None,
     tags: Optional[Iterable[str]] = None,
     active: Optional[bool] = True,
+    filters: Optional[AdvancedFilterDict] = None,
     fields: Optional[Iterable[str]] = None,
     own_attributes=_PLACEHOLDER,
 ) -> Generator[VersionDict, None, None]:
@@ -5351,6 +5365,7 @@ def get_versions(
             for filtering.
         active (Optional[bool]): Receive active/inactive entities.
             Both are returned when 'None' is passed.
+        filters (Optional[AdvancedFilterDict]): Advanced filtering options.
         fields (Optional[Iterable[str]]): Fields to be queried
             for version. All possible folder fields are returned
             if 'None' is passed.
@@ -5374,6 +5389,7 @@ def get_versions(
         statuses=statuses,
         tags=tags,
         active=active,
+        filters=filters,
         fields=fields,
         own_attributes=own_attributes,
     )
@@ -5819,6 +5835,7 @@ def get_representations(
     tags: Optional[Iterable[str]] = None,
     active: Optional[bool] = True,
     has_links: Optional[str] = None,
+    filters: Optional[AdvancedFilterDict] = None,
     fields: Optional[Iterable[str]] = None,
     own_attributes=_PLACEHOLDER,
 ) -> Generator[RepresentationDict, None, None]:
@@ -5849,6 +5866,7 @@ def get_representations(
             Both are returned when 'None' is passed.
         has_links (Optional[Literal[IN, OUT, ANY]]): Filter
             representations with IN/OUT/ANY links.
+        filters (Optional[AdvancedFilterDict]): Advanced filtering options.
         fields (Optional[Iterable[str]]): Fields to be queried for
             representation. All possible fields are returned if 'None' is
             passed.
@@ -5871,6 +5889,7 @@ def get_representations(
         tags=tags,
         active=active,
         has_links=has_links,
+        filters=filters,
         fields=fields,
         own_attributes=own_attributes,
     )
@@ -7282,7 +7301,15 @@ def get_entity_lists(
     active: Optional[bool] = None,
     fields: Optional[Iterable[str]] = None,
 ) -> Generator[dict[str, Any], None, None]:
-    """Fetch entity lists from server.
+    """Fetch entity lists from AYON server.
+
+    Warnings:
+        You can't get list items for lists with different 'entityType' in
+            one call.
+
+    Notes:
+        To get list items, you have to pass 'items' field or
+            'items.{sub-fields you want}' to 'fields' argument.
 
     Args:
         project_name (str): Project name where entity lists are.

ayon_api/_api_helpers/base.py

@@ -2,7 +2,7 @@
 
 import logging
 import typing
-from typing import Optional, Any, Iterable
+from typing import Optional, Any, Iterable, Union
 
 import requests
 
@@ -142,6 +142,11 @@ def _prepare_fields(
     ):
         raise NotImplementedError()
 
+    def _prepare_advanced_filters(
+        self, filters: Union[str, dict[str, Any], None]
+    ) -> Optional[str]:
+        raise NotImplementedError()
+
     def _convert_entity_data(self, entity: AnyEntityDict):
         raise NotImplementedError()
 

ayon_api/_api_helpers/folders.py

@@ -21,6 +21,7 @@
         FolderDict,
         FlatFolderDict,
         ProjectHierarchyDict,
+        AdvancedFilterDict,
     )
 
 
@@ -216,6 +217,7 @@ def get_folders(
         tags: Optional[Iterable[str]] = None,
         active: Optional[bool] = True,
         has_links: Optional[bool] = None,
+        filters: Optional[AdvancedFilterDict] = None,
         fields: Optional[Iterable[str]] = None,
         own_attributes: bool = False
     ) -> Generator[FolderDict, None, None]:
@@ -257,6 +259,7 @@ def get_folders(
                 Both are returned if is set to None.
             has_links (Optional[Literal[IN, OUT, ANY]]): Filter
                 representations with IN/OUT/ANY links.
+            filters (Optional[AdvancedFilterDict]): Advanced filtering options.
             fields (Optional[Iterable[str]]): Fields to be queried for
                 folder. All possible folder fields are returned
                 if 'None' is passed.
@@ -270,11 +273,11 @@ def get_folders(
         if not project_name:
             return
 
-        filters = {
+        graphql_filters = {
             "projectName": project_name
         }
         if not prepare_list_filters(
-            filters,
+            graphql_filters,
             ("folderIds", folder_ids),
             ("folderPaths", folder_paths),
             ("folderNames", folder_names),
@@ -291,9 +294,10 @@ def get_folders(
             ("folderHasTasks", has_tasks),
             ("folderHasLinks", has_links),
             ("folderHasChildren", has_children),
+            ("filter", self._prepare_advanced_filters(filters)),
         ):
             if filter_value is not None:
-                filters[filter_key] = filter_value
+                graphql_filters[filter_key] = filter_value
 
         if parent_ids is not None:
             parent_ids = set(parent_ids)
@@ -313,7 +317,7 @@ def get_folders(
                 parent_ids.remove(project_name)
                 parent_ids.add("root")
 
-            filters["parentFolderIds"] = list(parent_ids)
+            graphql_filters["parentFolderIds"] = list(parent_ids)
 
         if not fields:
             fields = self.get_default_fields_for_type("folder")
@@ -328,7 +332,7 @@ def get_folders(
             fields.add("ownAttrib")
 
         query = folders_graphql_query(fields)
-        for attr, filter_value in filters.items():
+        for attr, filter_value in graphql_filters.items():
             query.set_variable_value(attr, filter_value)
 
         for parsed_data in query.continuous_query(self):

ayon_api/_api_helpers/products.py

@@ -18,7 +18,11 @@
 from .base import BaseServerAPI, _PLACEHOLDER
 
 if typing.TYPE_CHECKING:
-    from ayon_api.typing import ProductDict, ProductTypeDict
+    from ayon_api.typing import (
+        ProductDict,
+        ProductTypeDict,
+        AdvancedFilterDict,
+    )
 
 
 class ProductsAPI(BaseServerAPI):
@@ -43,6 +47,7 @@ def get_products(
         statuses: Optional[Iterable[str]] = None,
         tags: Optional[Iterable[str]] = None,
         active: Optional[bool] = True,
+        filters: Optional[AdvancedFilterDict] = None,
         fields: Optional[Iterable[str]] = None,
         own_attributes=_PLACEHOLDER
     ) -> Generator[ProductDict, None, None]:
@@ -74,6 +79,7 @@ def get_products(
                 for filtering.
             active (Optional[bool]): Filter active/inactive products.
                 Both are returned if is set to None.
+            filters (Optional[AdvancedFilterDict]): Advanced filtering options.
             fields (Optional[Iterable[str]]): Fields to be queried for
                 folder. All possible folder fields are returned
                 if 'None' is passed.
@@ -145,18 +151,18 @@ def get_products(
             fields.add("folderId")
 
         # Prepare filters for query
-        filters = {
+        graphql_filters = {
             "projectName": project_name
         }
 
         if filter_folder_ids:
-            filters["folderIds"] = list(filter_folder_ids)
+            graphql_filters["folderIds"] = list(filter_folder_ids)
 
         if filter_product_names:
-            filters["productNames"] = list(filter_product_names)
+            graphql_filters["productNames"] = list(filter_product_names)
 
         if not prepare_list_filters(
-            filters,
+            graphql_filters,
             ("productIds", product_ids),
             ("productTypes", product_types),
             ("productBaseTypes", product_base_types),
@@ -168,12 +174,13 @@ def get_products(
         for filter_key, filter_value in (
             ("productNameRegex", product_name_regex),
             ("productPathRegex", product_path_regex),
+            ("filter", self._prepare_advanced_filters(filters)),
         ):
             if filter_value:
-                filters[filter_key] = filter_value
+                graphql_filters[filter_key] = filter_value
 
         query = products_graphql_query(fields)
-        for attr, filter_value in filters.items():
+        for attr, filter_value in graphql_filters.items():
             query.set_variable_value(attr, filter_value)
 
         parsed_data = query.query(self)