shotgun-api3 3.9.0__py2.py3-none-any.whl → 3.9.2__py2.py3-none-any.whl

shotgun_api3/shotgun.py

@@ -29,6 +29,8 @@ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 """
 
+from __future__ import annotations  # Requried for 3.7
+
 import base64
 import copy
 import datetime
@@ -50,6 +52,17 @@ import urllib.parse
 import urllib.request
 import uuid  # used for attachment upload
 import xml.etree.ElementTree
+from typing import (
+    Any,
+    BinaryIO,
+    Dict,
+    Iterable,
+    List,
+    Optional,
+    Tuple,
+    TypeVar,
+    Union,
+)
 
 # Import Error and ResponseError (even though they're unused in this file) since they need
 # to be exposed as part of the API.
@@ -81,7 +94,35 @@ SHOTGUN_API_DISABLE_ENTITY_OPTIMIZATION = False
 
 # ----------------------------------------------------------------------------
 # Version
-__version__ = "3.9.0"
+__version__ = "3.9.2"
+
+
+# ----------------------------------------------------------------------------
+# Types
+
+
+T = TypeVar("T")
+
+if sys.version_info < (3, 9):
+    OrderItem = Dict
+    GroupingItem = Dict
+    BaseEntity = Dict
+else:
+    from typing import TypedDict
+
+    class OrderItem(TypedDict):
+        field_name: str
+        direction: str
+
+    class GroupingItem(TypedDict):
+        field: str
+        type: str
+        direction: str
+
+    class BaseEntity(TypedDict, total=False):
+        id: int
+        type: str
+
 
 # ----------------------------------------------------------------------------
 # Errors
@@ -168,7 +209,7 @@ class ServerCapabilities(object):
         the future. Therefore, usage of this class is discouraged.
     """
 
-    def __init__(self, host, meta):
+    def __init__(self, host: str, meta: Dict[str, Any]) -> None:
         """
         ServerCapabilities.__init__
 
@@ -181,7 +222,6 @@ class ServerCapabilities(object):
         :ivar bool is_dev: ``True`` if server is running a development version of the Shotgun
             codebase.
         """
-        self._ensure_python_version_supported()
         # Server host name
         self.host = host
         self.server_info = meta
@@ -208,14 +248,7 @@ class ServerCapabilities(object):
         self.version = tuple(self.version[:3])
         self._ensure_json_supported()
 
-    def _ensure_python_version_supported(self):
-        """
-        Checks the if current Python version is supported.
-        """
-        if sys.version_info < (3, 7):
-            raise ShotgunError("This module requires Python version 3.7 or higher.")
-
-    def _ensure_support(self, feature, raise_hell=True):
+    def _ensure_support(self, feature: Dict[str, Any], raise_hell: bool = True) -> bool:
         """
         Checks the server version supports a given feature, raises an exception if it does not.
 
@@ -243,13 +276,13 @@ class ServerCapabilities(object):
         else:
             return True
 
-    def _ensure_json_supported(self):
+    def _ensure_json_supported(self) -> None:
         """
         Ensures server has support for JSON API endpoint added in v2.4.0.
         """
         self._ensure_support({"version": (2, 4, 0), "label": "JSON API"})
 
-    def ensure_include_archived_projects(self):
+    def ensure_include_archived_projects(self) -> None:
         """
         Ensures server has support for archived Projects feature added in v5.3.14.
         """
@@ -257,7 +290,7 @@ class ServerCapabilities(object):
             {"version": (5, 3, 14), "label": "include_archived_projects parameter"}
         )
 
-    def ensure_per_project_customization(self):
+    def ensure_per_project_customization(self) -> bool:
         """
         Ensures server has support for per-project customization feature added in v5.4.4.
         """
@@ -265,7 +298,7 @@ class ServerCapabilities(object):
             {"version": (5, 4, 4), "label": "project parameter"}, True
         )
 
-    def ensure_support_for_additional_filter_presets(self):
+    def ensure_support_for_additional_filter_presets(self) -> bool:
         """
         Ensures server has support for additional filter presets feature added in v7.0.0.
         """
@@ -273,7 +306,7 @@ class ServerCapabilities(object):
             {"version": (7, 0, 0), "label": "additional_filter_presets parameter"}, True
         )
 
-    def ensure_user_following_support(self):
+    def ensure_user_following_support(self) -> bool:
         """
         Ensures server has support for listing items a user is following, added in v7.0.12.
         """
@@ -281,7 +314,7 @@ class ServerCapabilities(object):
             {"version": (7, 0, 12), "label": "user_following parameter"}, True
         )
 
-    def ensure_paging_info_without_counts_support(self):
+    def ensure_paging_info_without_counts_support(self) -> bool:
         """
         Ensures server has support for optimized pagination, added in v7.4.0.
         """
@@ -289,7 +322,7 @@ class ServerCapabilities(object):
             {"version": (7, 4, 0), "label": "optimized pagination"}, False
         )
 
-    def ensure_return_image_urls_support(self):
+    def ensure_return_image_urls_support(self) -> bool:
         """
         Ensures server has support for returning thumbnail URLs without additional round-trips, added in v3.3.0.
         """
@@ -297,7 +330,7 @@ class ServerCapabilities(object):
             {"version": (3, 3, 0), "label": "return thumbnail URLs"}, False
         )
 
-    def __str__(self):
+    def __str__(self) -> str:
         return "ServerCapabilities: host %s, version %s, is_dev %s" % (
             self.host,
             self.version,
@@ -355,7 +388,7 @@ class _Config(object):
     Container for the client configuration.
     """
 
-    def __init__(self, sg):
+    def __init__(self, sg: "Shotgun"):
         """
         :param sg: Shotgun connection.
         """
@@ -376,41 +409,41 @@ class _Config(object):
         # If the optional timeout parameter is given, blocking operations
         # (like connection attempts) will timeout after that many seconds
         # (if it is not given, the global default timeout setting is used)
-        self.timeout_secs = None
+        self.timeout_secs: Optional[float] = None
         self.api_ver = "api3"
         self.convert_datetimes_to_utc = True
-        self._records_per_page = None
-        self.api_key = None
-        self.script_name = None
-        self.user_login = None
-        self.user_password = None
-        self.auth_token = None
-        self.sudo_as_login = None
+        self._records_per_page: Optional[int] = None
+        self.api_key: Optional[str] = None
+        self.script_name: Optional[str] = None
+        self.user_login: Optional[str] = None
+        self.user_password: Optional[str] = None
+        self.auth_token: Optional[str] = None
+        self.sudo_as_login: Optional[str] = None
         # Authentication parameters to be folded into final auth_params dict
-        self.extra_auth_params = None
+        self.extra_auth_params: Optional[Dict[str, Any]] = None
         # uuid as a string
-        self.session_uuid = None
-        self.scheme = None
-        self.server = None
-        self.api_path = None
+        self.session_uuid: Optional[str] = None
+        self.scheme: Optional[str] = None
+        self.server: Optional[str] = None
+        self.api_path: Optional[str] = None
         # The raw_http_proxy reflects the exact string passed in
         # to the Shotgun constructor. This can be useful if you
         # need to construct a Shotgun API instance based on
         # another Shotgun API instance.
-        self.raw_http_proxy = None
+        self.raw_http_proxy: Optional[str] = None
         # if a proxy server is being used, the proxy_handler
         # below will contain a urllib2.ProxyHandler instance
         # which can be used whenever a request needs to be made.
-        self.proxy_handler = None
-        self.proxy_server = None
+        self.proxy_handler: Optional["urllib.request.ProxyHandler"] = None
+        self.proxy_server: Optional[str] = None
         self.proxy_port = 8080
-        self.proxy_user = None
-        self.proxy_pass = None
-        self.session_token = None
-        self.authorization = None
+        self.proxy_user: Optional[str] = None
+        self.proxy_pass: Optional[str] = None
+        self.session_token: Optional[str] = None
+        self.authorization: Optional[str] = None
         self.localized = False
 
-    def set_server_params(self, base_url):
+    def set_server_params(self, base_url: str) -> None:
         """
         Set the different server related fields based on the passed in URL.
 
@@ -432,7 +465,7 @@ class _Config(object):
         )
 
     @property
-    def records_per_page(self):
+    def records_per_page(self) -> int:
         """
         The records per page value from the server.
         """
@@ -465,19 +498,19 @@ class Shotgun(object):
 
     def __init__(
         self,
-        base_url,
-        script_name=None,
-        api_key=None,
-        convert_datetimes_to_utc=True,
-        http_proxy=None,
-        connect=True,
-        ca_certs=None,
-        login=None,
-        password=None,
-        sudo_as_login=None,
-        session_token=None,
-        auth_token=None,
-    ):
+        base_url: str,
+        script_name: Optional[str] = None,
+        api_key: Optional[str] = None,
+        convert_datetimes_to_utc: bool = True,
+        http_proxy: Optional[str] = None,
+        connect: bool = True,
+        ca_certs: Optional[str] = None,
+        login: Optional[str] = None,
+        password: Optional[str] = None,
+        sudo_as_login: Optional[str] = None,
+        session_token: Optional[str] = None,
+        auth_token: Optional[str] = None,
+    ) -> None:
         """
         Initializes a new instance of the Shotgun client.
 
@@ -589,7 +622,7 @@ class Shotgun(object):
                     "must provide login/password, session_token or script_name/api_key"
                 )
 
-        self.config = _Config(self)
+        self.config: _Config = _Config(self)
         self.config.api_key = api_key
         self.config.script_name = script_name
         self.config.user_login = login
@@ -625,7 +658,7 @@ class Shotgun(object):
         ):
             SHOTGUN_API_DISABLE_ENTITY_OPTIMIZATION = True
 
-        self._connection = None
+        self._connection: Optional[Http] = None
 
         self.__ca_certs = self._get_certs_file(ca_certs)
 
@@ -690,7 +723,7 @@ class Shotgun(object):
         # this relies on self.client_caps being set first
         self.reset_user_agent()
 
-        self._server_caps = None
+        self._server_caps: Optional[ServerCapabilities] = None
         # test to ensure the the server supports the json API
         # call to server will only be made once and will raise error
         if connect:
@@ -704,7 +737,7 @@ class Shotgun(object):
             self.config.user_password = None
             self.config.auth_token = None
 
-    def _split_url(self, base_url):
+    def _split_url(self, base_url: str) -> Tuple[Optional[str], Optional[str]]:
         """
         Extract the hostname:port and username/password/token from base_url
         sent when connect to the API.
@@ -736,7 +769,7 @@ class Shotgun(object):
     # API Functions
 
     @property
-    def server_info(self):
+    def server_info(self) -> Dict[str, Any]:
         """
         Property containing server information.
 
@@ -754,7 +787,7 @@ class Shotgun(object):
         return self.server_caps.server_info
 
     @property
-    def server_caps(self):
+    def server_caps(self) -> ServerCapabilities:
         """
         Property containing :class:`ServerCapabilities` object.
 
@@ -769,7 +802,7 @@ class Shotgun(object):
             self._server_caps = ServerCapabilities(self.config.server, self.info())
         return self._server_caps
 
-    def connect(self):
+    def connect(self) -> None:
         """
         Connect client to the server if it is not already connected.
 
@@ -780,7 +813,7 @@ class Shotgun(object):
         self.info()
         return
 
-    def close(self):
+    def close(self) -> None:
         """
         Close the current connection to the server.
 
@@ -789,7 +822,7 @@ class Shotgun(object):
         self._close_connection()
         return
 
-    def info(self):
+    def info(self) -> Dict[str, Any]:
         """
         Get API-related metadata from the Shotgun server.
 
@@ -822,15 +855,15 @@ class Shotgun(object):
 
     def find_one(
         self,
-        entity_type,
-        filters,
-        fields=None,
-        order=None,
-        filter_operator=None,
-        retired_only=False,
-        include_archived_projects=True,
-        additional_filter_presets=None,
-    ):
+        entity_type: str,
+        filters: Union[List, Tuple, Dict[str, Any]],
+        fields: Optional[List[str]] = None,
+        order: Optional[List[OrderItem]] = None,
+        filter_operator: Optional[str] = None,
+        retired_only: bool = False,
+        include_archived_projects: bool = True,
+        additional_filter_presets: Optional[List[Dict[str, Any]]] = None,
+    ) -> Optional[BaseEntity]:
         """
         Shortcut for :meth:`~shotgun_api3.Shotgun.find` with ``limit=1`` so it returns a single
         result.
@@ -845,7 +878,7 @@ class Shotgun(object):
 
         :param list fields: Optional list of fields to include in each entity record returned.
             Defaults to ``["id"]``.
-        :param int order: Optional list of fields to order the results by. List has the format::
+        :param list order: Optional list of fields to order the results by. List has the format::
 
                 [
                     {'field_name':'foo', 'direction':'asc'},
@@ -862,7 +895,7 @@ class Shotgun(object):
             same query.
         :param bool include_archived_projects: Optional boolean flag to include entities whose projects
             have been archived. Defaults to ``True``.
-        :param additional_filter_presets: Optional list of presets to further filter the result
+        :param list additional_filter_presets: Optional list of presets to further filter the result
             set, list has the form::
 
                 [{
@@ -902,17 +935,17 @@ class Shotgun(object):
 
     def find(
         self,
-        entity_type,
-        filters,
-        fields=None,
-        order=None,
-        filter_operator=None,
-        limit=0,
-        retired_only=False,
-        page=0,
-        include_archived_projects=True,
-        additional_filter_presets=None,
-    ):
+        entity_type: str,
+        filters: Union[List, Tuple, Dict[str, Any]],
+        fields: Optional[List[str]] = None,
+        order: Optional[List[OrderItem]] = None,
+        filter_operator: Optional[str] = None,
+        limit: int = 0,
+        retired_only: bool = False,
+        page: int = 0,
+        include_archived_projects: bool = True,
+        additional_filter_presets: Optional[List[Dict[str, Any]]] = None,
+    ) -> List[BaseEntity]:
         """
         Find entities matching the given filters.
 
@@ -990,7 +1023,7 @@ class Shotgun(object):
             same query.
         :param bool include_archived_projects: Optional boolean flag to include entities whose projects
             have been archived. Defaults to ``True``.
-        :param additional_filter_presets: Optional list of presets to further filter the result
+        :param list additional_filter_presets: Optional list of presets to further filter the result
             set, list has the form::
 
                 [{
@@ -1101,15 +1134,15 @@ class Shotgun(object):
 
     def _construct_read_parameters(
         self,
-        entity_type,
-        fields,
-        filters,
-        retired_only,
-        order,
-        include_archived_projects,
-        additional_filter_presets,
-    ):
-        params = {}
+        entity_type: str,
+        fields: Optional[List[str]],
+        filters: Dict[str, Any],
+        retired_only: bool,
+        order: Optional[List[Dict[str, Any]]],
+        include_archived_projects: bool,
+        additional_filter_presets: Optional[List[Dict[str, Any]]],
+    ) -> Dict[str, Any]:
+        params: Dict[str, Any] = {}
         params["type"] = entity_type
         params["return_fields"] = fields or ["id"]
         params["filters"] = filters
@@ -1139,7 +1172,9 @@ class Shotgun(object):
             params["sorts"] = sort_list
         return params
 
-    def _add_project_param(self, params, project_entity):
+    def _add_project_param(
+        self, params: Dict[str, Any], project_entity
+    ) -> Dict[str, Any]:
 
         if project_entity and self.server_caps.ensure_per_project_customization():
             params["project"] = project_entity
@@ -1147,14 +1182,18 @@ class Shotgun(object):
         return params
 
     def _translate_update_params(
-        self, entity_type, entity_id, data, multi_entity_update_modes
-    ):
+        self,
+        entity_type: str,
+        entity_id: int,
+        data: Dict,
+        multi_entity_update_modes: Optional[Dict],
+    ) -> Dict[str, Any]:
         global SHOTGUN_API_DISABLE_ENTITY_OPTIMIZATION
 
         def optimize_field(field_dict):
             if SHOTGUN_API_DISABLE_ENTITY_OPTIMIZATION:
                 return field_dict
-            return {k: _get_type_and_id_from_value(v) for k, v in field_dict.items()}
+            return {k: _optimize_filter_field(v) for k, v in field_dict.items()}
 
         full_fields = self._dict_to_list(
             data,
@@ -1170,13 +1209,13 @@ class Shotgun(object):
 
     def summarize(
         self,
-        entity_type,
-        filters,
-        summary_fields,
-        filter_operator=None,
-        grouping=None,
-        include_archived_projects=True,
-    ):
+        entity_type: str,
+        filters: Union[List, Dict[str, Any]],
+        summary_fields: List[Dict[str, str]],
+        filter_operator: Optional[str] = None,
+        grouping: Optional[List[GroupingItem]] = None,
+        include_archived_projects: bool = True,
+    ) -> Dict[str, Any]:
         """
         Summarize field data returned by a query.
 
@@ -1376,7 +1415,12 @@ class Shotgun(object):
         records = self._call_rpc("summarize", params)
         return records
 
-    def create(self, entity_type, data, return_fields=None):
+    def create(
+        self,
+        entity_type: str,
+        data: Dict[str, Any],
+        return_fields: Optional[List[str]] = None,
+    ) -> Dict[str, Any]:
         """
         Create a new entity of the specified ``entity_type``.
 
@@ -1459,7 +1503,13 @@ class Shotgun(object):
 
         return result
 
-    def update(self, entity_type, entity_id, data, multi_entity_update_modes=None):
+    def update(
+        self,
+        entity_type: str,
+        entity_id: int,
+        data: Dict[str, Any],
+        multi_entity_update_modes: Optional[Dict[str, Any]] = None,
+    ) -> BaseEntity:
         """
         Update the specified entity with the supplied data.
 
@@ -1538,7 +1588,7 @@ class Shotgun(object):
 
         return result
 
-    def delete(self, entity_type, entity_id):
+    def delete(self, entity_type: str, entity_id: int) -> bool:
         """
         Retire the specified entity.
 
@@ -1562,7 +1612,7 @@ class Shotgun(object):
 
         return self._call_rpc("delete", params)
 
-    def revive(self, entity_type, entity_id):
+    def revive(self, entity_type: str, entity_id: int) -> bool:
         """
         Revive an entity that has previously been deleted.
 
@@ -1580,7 +1630,7 @@ class Shotgun(object):
 
         return self._call_rpc("revive", params)
 
-    def batch(self, requests):
+    def batch(self, requests: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
         """
         Make a batch request of several :meth:`~shotgun_api3.Shotgun.create`,
         :meth:`~shotgun_api3.Shotgun.update`, and :meth:`~shotgun_api3.Shotgun.delete` calls.
@@ -1695,7 +1745,13 @@ class Shotgun(object):
         records = self._call_rpc("batch", calls)
         return self._parse_records(records)
 
-    def work_schedule_read(self, start_date, end_date, project=None, user=None):
+    def work_schedule_read(
+        self,
+        start_date: str,
+        end_date: str,
+        project: Optional[Dict[str, Any]] = None,
+        user: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
         """
         Return the work day rules for a given date range.
 
@@ -1766,13 +1822,13 @@ class Shotgun(object):
 
     def work_schedule_update(
         self,
-        date,
-        working,
-        description=None,
-        project=None,
-        user=None,
-        recalculate_field=None,
-    ):
+        date: str,
+        working: bool,
+        description: Optional[str] = None,
+        project: Optional[Dict[str, Any]] = None,
+        user: Optional[Dict[str, Any]] = None,
+        recalculate_field: Optional[str] = None,
+    ) -> Dict[str, Any]:
         """
         Update the work schedule for a given date.
 
@@ -1826,7 +1882,30 @@ class Shotgun(object):
 
         return self._call_rpc("work_schedule_update", params)
 
-    def follow(self, user, entity):
+    def export_page(self, page_id, format, layout_name=None):
+        """
+        Export the specified page to the given format.
+        This method allows you to export a page to CSV.
+        Respective layout or page should be marked as API Exportable in the Flow Production Tracking UI.
+        For more information, see documentation_.
+        .. _documentation: https://help.autodesk.com/view/SGSUB/ENU/?guid=SG_Tutorials_tu_export_csv_html#enable-api-export-for-a-page
+        If ``layout_name`` is not passed in, the default layout name will be used.
+            >>> sg.export_page(12345, "csv", layout_name="My Layout")
+            "ID,Name,Status\\n1,Shot 001,ip\\n2,    Shot 002,rev\\n"
+            >>> sg.export_page(12345, "csv")
+            "ID,Name,Status\\n1,Shot 001,ip\\n2,Shot 002,rev\\n"
+        :param int page_id: The ID of the page to export.
+        :param str format: The format to export the page to. Supported format is ``"csv"``.
+        :param str layout_name: Optional layout name. This should be the name of the layout seen in the Flow Production Tracking UI.
+        :returns: string containing data of the given page.
+        :rtype: string
+        """
+
+        params = dict(format=format, page_id=page_id, layout_name=layout_name)
+
+        return self._call_rpc("export_page", params)
+
+    def follow(self, user: Dict[str, Any], entity: Dict[str, Any]) -> Dict[str, Any]:
         """
         Add the entity to the user's followed entities.
 
@@ -1854,7 +1933,7 @@ class Shotgun(object):
 
         return self._call_rpc("follow", params)
 
-    def unfollow(self, user, entity):
+    def unfollow(self, user: Dict[str, Any], entity: Dict[str, Any]) -> Dict[str, Any]:
         """
         Remove entity from the user's followed entities.
 
@@ -1881,7 +1960,7 @@ class Shotgun(object):
 
         return self._call_rpc("unfollow", params)
 
-    def followers(self, entity):
+    def followers(self, entity: Dict[str, Any]) -> List[Dict[str, Any]]:
         """
         Return all followers for an entity.
 
@@ -1909,7 +1988,12 @@ class Shotgun(object):
 
         return self._call_rpc("followers", params)
 
-    def following(self, user, project=None, entity_type=None):
+    def following(
+        self,
+        user: Dict[str, Any],
+        project: Optional[Dict[str, Any]] = None,
+        entity_type: Optional[str] = None,
+    ) -> List[BaseEntity]:
         """
         Return all entity instances a user is following.
 
@@ -1940,7 +2024,9 @@ class Shotgun(object):
 
         return self._call_rpc("following", params)
 
-    def schema_entity_read(self, project_entity=None):
+    def schema_entity_read(
+        self, project_entity: Optional[BaseEntity] = None
+    ) -> Dict[str, Dict[str, Any]]:
         """
         Return all active entity types, their display names, and their visibility.
 
@@ -1975,7 +2061,7 @@ class Shotgun(object):
             The returned display names for this method will be localized when the ``localize`` Shotgun config property is set to ``True``. See :ref:`localization` for more information.
         """
 
-        params = {}
+        params: Dict[str, Any] = {}
 
         params = self._add_project_param(params, project_entity)
 
@@ -1984,7 +2070,9 @@ class Shotgun(object):
         else:
             return self._call_rpc("schema_entity_read", None)
 
-    def schema_read(self, project_entity=None):
+    def schema_read(
+        self, project_entity: Optional[BaseEntity] = None
+    ) -> Dict[str, Dict[str, Any]]:
         """
         Get the schema for all fields on all entities.
 
@@ -2047,7 +2135,7 @@ class Shotgun(object):
             The returned display names for this method will be localized when the ``localize`` Shotgun config property is set to ``True``. See :ref:`localization` for more information.
         """
 
-        params = {}
+        params: Dict[str, Any] = {}
 
         params = self._add_project_param(params, project_entity)
 
@@ -2056,7 +2144,12 @@ class Shotgun(object):
         else:
             return self._call_rpc("schema_read", None)
 
-    def schema_field_read(self, entity_type, field_name=None, project_entity=None):
+    def schema_field_read(
+        self,
+        entity_type: str,
+        field_name: Optional[str] = None,
+        project_entity: Optional[BaseEntity] = None,
+    ) -> Dict[str, Dict[str, Any]]:
         """
         Get schema for all fields on the specified entity type or just the field name specified
         if provided.
@@ -2121,8 +2214,12 @@ class Shotgun(object):
         return self._call_rpc("schema_field_read", params)
 
     def schema_field_create(
-        self, entity_type, data_type, display_name, properties=None
-    ):
+        self,
+        entity_type: str,
+        data_type: str,
+        display_name: str,
+        properties: Optional[Dict[str, Any]] = None,
+    ) -> str:
         """
         Create a field for the specified entity type.
 
@@ -2160,8 +2257,12 @@ class Shotgun(object):
         return self._call_rpc("schema_field_create", params)
 
     def schema_field_update(
-        self, entity_type, field_name, properties, project_entity=None
-    ):
+        self,
+        entity_type: str,
+        field_name: str,
+        properties: Dict[str, Any],
+        project_entity: Optional[BaseEntity] = None,
+    ) -> bool:
         """
         Update the properties for the specified field on an entity.
 
@@ -2175,9 +2276,9 @@ class Shotgun(object):
         >>> sg.schema_field_update("Asset", "sg_test_number", properties)
         True
 
-        :param entity_type: Entity type of field to update.
-        :param field_name: Internal Shotgun name of the field to update.
-        :param properties: Dictionary with key/value pairs where the key is the property to be
+        :param str entity_type: Entity type of field to update.
+        :param str field_name: Internal Shotgun name of the field to update.
+        :param dict properties: Dictionary with key/value pairs where the key is the property to be
             updated and the value is the new value.
         :param dict project_entity: Optional Project entity specifying which project to modify the
             ``visible`` property for. If ``visible`` is present in ``properties`` and
@@ -2202,7 +2303,7 @@ class Shotgun(object):
         params = self._add_project_param(params, project_entity)
         return self._call_rpc("schema_field_update", params)
 
-    def schema_field_delete(self, entity_type, field_name):
+    def schema_field_delete(self, entity_type: str, field_name: str) -> bool:
         """
         Delete the specified field from the entity type.
 
@@ -2219,7 +2320,7 @@ class Shotgun(object):
 
         return self._call_rpc("schema_field_delete", params)
 
-    def add_user_agent(self, agent):
+    def add_user_agent(self, agent: str) -> None:
         """
         Add agent to the user-agent header.
 
@@ -2231,7 +2332,7 @@ class Shotgun(object):
         """
         self._user_agents.append(agent)
 
-    def reset_user_agent(self):
+    def reset_user_agent(self) -> None:
         """
         Reset user agent to the default value.
 
@@ -2251,7 +2352,7 @@ class Shotgun(object):
             "ssl %s" % (self.client_caps.ssl_version),
         ]
 
-    def set_session_uuid(self, session_uuid):
+    def set_session_uuid(self, session_uuid: str) -> None:
         """
         Set the browser session_uuid in the current Shotgun API instance.
 
@@ -2269,12 +2370,12 @@ class Shotgun(object):
 
     def share_thumbnail(
         self,
-        entities,
-        thumbnail_path=None,
-        source_entity=None,
-        filmstrip_thumbnail=False,
-        **kwargs,
-    ):
+        entities: List[Dict[str, Any]],
+        thumbnail_path: Optional[str] = None,
+        source_entity: Optional[BaseEntity] = None,
+        filmstrip_thumbnail: bool = False,
+        **kwargs: Any,
+    ) -> int:
         """
         Associate a thumbnail with more than one Shotgun entity.
 
@@ -2413,7 +2514,9 @@ class Shotgun(object):
 
         return attachment_id
 
-    def upload_thumbnail(self, entity_type, entity_id, path, **kwargs):
+    def upload_thumbnail(
+        self, entity_type: str, entity_id: int, path: str, **kwargs: Any
+    ) -> int:
         """
         Upload a file from a local path and assign it as the thumbnail for the specified entity.
 
@@ -2438,12 +2541,15 @@ class Shotgun(object):
         :param int entity_id: Id of the entity to set the thumbnail for.
         :param str path: Full path to the thumbnail file on disk.
         :returns: Id of the new attachment
+        :rtype: int
         """
         return self.upload(
             entity_type, entity_id, path, field_name="thumb_image", **kwargs
         )
 
-    def upload_filmstrip_thumbnail(self, entity_type, entity_id, path, **kwargs):
+    def upload_filmstrip_thumbnail(
+        self, entity_type: str, entity_id: int, path: str, **kwargs: Any
+    ) -> int:
         """
         Upload filmstrip thumbnail to specified entity.
 
@@ -2494,13 +2600,13 @@ class Shotgun(object):
 
     def upload(
         self,
-        entity_type,
-        entity_id,
-        path,
-        field_name=None,
-        display_name=None,
-        tag_list=None,
-    ):
+        entity_type: str,
+        entity_id: int,
+        path: str,
+        field_name: Optional[str] = None,
+        display_name: Optional[str] = None,
+        tag_list: Optional[str] = None,
+    ) -> int:
         """
         Upload a file to the specified entity.
 
@@ -2583,14 +2689,14 @@ class Shotgun(object):
 
     def _upload_to_storage(
         self,
-        entity_type,
-        entity_id,
-        path,
-        field_name,
-        display_name,
-        tag_list,
-        is_thumbnail,
-    ):
+        entity_type: str,
+        entity_id: int,
+        path: str,
+        field_name: Optional[str],
+        display_name: Optional[str],
+        tag_list: Optional[str],
+        is_thumbnail: bool,
+    ) -> int:
         """
         Internal function to upload a file to the Cloud storage and link it to the specified entity.
 
@@ -2673,14 +2779,14 @@ class Shotgun(object):
 
     def _upload_to_sg(
         self,
-        entity_type,
-        entity_id,
-        path,
-        field_name,
-        display_name,
-        tag_list,
-        is_thumbnail,
-    ):
+        entity_type: str,
+        entity_id: int,
+        path: str,
+        field_name: Optional[str],
+        display_name: Optional[str],
+        tag_list: Optional[str],
+        is_thumbnail: bool,
+    ) -> int:
         """
         Internal function to upload a file to Shotgun and link it to the specified entity.
 
@@ -2752,7 +2858,9 @@ class Shotgun(object):
         attachment_id = int(result.split(":", 2)[1].split("\n", 1)[0])
         return attachment_id
 
-    def _get_attachment_upload_info(self, is_thumbnail, filename, is_multipart_upload):
+    def _get_attachment_upload_info(
+        self, is_thumbnail: bool, filename: str, is_multipart_upload: bool
+    ) -> Dict[str, Any]:
         """
         Internal function to get the information needed to upload a file to Cloud storage.
 
@@ -2799,7 +2907,12 @@ class Shotgun(object):
             "upload_info": upload_info,
         }
 
-    def download_attachment(self, attachment=False, file_path=None, attachment_id=None):
+    def download_attachment(
+        self,
+        attachment: Union[Dict[str, Any], bool] = False,
+        file_path: Optional[str] = None,
+        attachment_id: Optional[int] = None,
+    ) -> Union[str, bytes, None]:
         """
         Download the file associated with a Shotgun Attachment.
 
@@ -2915,7 +3028,7 @@ class Shotgun(object):
             else:
                 return attachment
 
-    def get_auth_cookie_handler(self):
+    def get_auth_cookie_handler(self) -> urllib.request.HTTPCookieProcessor:
         """
         Return an urllib cookie handler containing a cookie for FPTR
         authentication.
@@ -2947,7 +3060,9 @@ class Shotgun(object):
         cj.set_cookie(c)
         return urllib.request.HTTPCookieProcessor(cj)
 
-    def get_attachment_download_url(self, attachment):
+    def get_attachment_download_url(
+        self, attachment: Optional[Union[int, dict[str, Any]]]
+    ) -> str:
         """
         Return the URL for downloading provided Attachment.
 
@@ -3005,7 +3120,9 @@ class Shotgun(object):
             )
         return url
 
-    def authenticate_human_user(self, user_login, user_password, auth_token=None):
+    def authenticate_human_user(
+        self, user_login: str, user_password: str, auth_token: Optional[str] = None
+    ) -> Union[Dict[str, Any], None]:
         """
         Authenticate Shotgun HumanUser.
 
@@ -3064,7 +3181,9 @@ class Shotgun(object):
             self.config.auth_token = original_auth_token
             raise
 
-    def update_project_last_accessed(self, project, user=None):
+    def update_project_last_accessed(
+        self, project: Dict[str, Any], user: Optional[Dict[str, Any]] = None
+    ) -> None:
         """
         Update a Project's ``last_accessed_by_current_user`` field to the current timestamp.
 
@@ -3110,7 +3229,9 @@ class Shotgun(object):
         record = self._call_rpc("update_project_last_accessed_by_current_user", params)
         self._parse_records(record)[0]
 
-    def note_thread_read(self, note_id, entity_fields=None):
+    def note_thread_read(
+        self, note_id: int, entity_fields: Optional[Dict[str, Any]] = None
+    ) -> List[Dict[str, Any]]:
         """
         Return the full conversation for a given note, including Replies and Attachments.
 
@@ -3185,7 +3306,13 @@ class Shotgun(object):
         result = self._parse_records(record)
         return result
 
-    def text_search(self, text, entity_types, project_ids=None, limit=None):
+    def text_search(
+        self,
+        text: str,
+        entity_types: Dict[str, Any],
+        project_ids: Optional[List] = None,
+        limit: Optional[int] = None,
+    ) -> Dict[str, Any]:
         """
         Search across the specified entity types for the given text.
 
@@ -3279,13 +3406,13 @@ class Shotgun(object):
 
     def activity_stream_read(
         self,
-        entity_type,
-        entity_id,
-        entity_fields=None,
-        min_id=None,
-        max_id=None,
-        limit=None,
-    ):
+        entity_type: str,
+        entity_id: int,
+        entity_fields: Optional[Dict[str, Any]] = None,
+        min_id: Optional[int] = None,
+        max_id: Optional[int] = None,
+        limit: Optional[int] = None,
+    ) -> Dict[str, Any]:
         """
         Retrieve activity stream data from Shotgun.
 
@@ -3375,7 +3502,7 @@ class Shotgun(object):
         result = self._parse_records(record)[0]
         return result
 
-    def nav_expand(self, path, seed_entity_field=None, entity_fields=None):
+    def nav_expand(self, path: str, seed_entity_field=None, entity_fields=None):
         """
         Expand the navigation hierarchy for the supplied path.
 
@@ -3395,7 +3522,9 @@ class Shotgun(object):
             },
         )
 
-    def nav_search_string(self, root_path, search_string, seed_entity_field=None):
+    def nav_search_string(
+        self, root_path: str, search_string: str, seed_entity_field=None
+    ):
         """
         Search function adapted to work with the navigation hierarchy.
 
@@ -3414,7 +3543,12 @@ class Shotgun(object):
             },
         )
 
-    def nav_search_entity(self, root_path, entity, seed_entity_field=None):
+    def nav_search_entity(
+        self,
+        root_path: str,
+        entity: Dict[str, Any],
+        seed_entity_field: Optional[Dict[str, Any]] = None,
+    ):
         """
         Search function adapted to work with the navigation hierarchy.
 
@@ -3434,7 +3568,7 @@ class Shotgun(object):
             },
         )
 
-    def get_session_token(self):
+    def get_session_token(self) -> str:
         """
         Get the session token associated with the current session.
 
@@ -3458,7 +3592,7 @@ class Shotgun(object):
 
         return session_token
 
-    def preferences_read(self, prefs=None):
+    def preferences_read(self, prefs: Optional[List] = None) -> Dict[str, Any]:
         """
         Get a subset of the site preferences.
 
@@ -3481,7 +3615,7 @@ class Shotgun(object):
 
         return self._call_rpc("preferences_read", {"prefs": prefs})
 
-    def user_subscriptions_read(self):
+    def user_subscriptions_read(self) -> List:
         """
         Get the list of user subscriptions.
 
@@ -3493,8 +3627,9 @@ class Shotgun(object):
 
         return self._call_rpc("user_subscriptions_read", None)
 
-    def user_subscriptions_create(self, users):
-        # type: (list[dict[str, Union[str, list[str], None]) -> bool
+    def user_subscriptions_create(
+        self, users: List[Dict[str, Union[str, List[str], None]]]
+    ) -> bool:
         """
         Assign subscriptions to users.
 
@@ -3515,7 +3650,7 @@ class Shotgun(object):
 
         return response.get("status") == "success"
 
-    def _build_opener(self, handler):
+    def _build_opener(self, handler) -> urllib.request.OpenerDirector:
         """
         Build urllib2 opener with appropriate proxy handler.
         """
@@ -3616,7 +3751,13 @@ class Shotgun(object):
     # ========================================================================
     # RPC Functions
 
-    def _call_rpc(self, method, params, include_auth_params=True, first=False):
+    def _call_rpc(
+        self,
+        method: str,
+        params: Any,
+        include_auth_params: bool = True,
+        first: bool = False,
+    ) -> Any:
         """
         Call the specified method on the Shotgun Server sending the supplied payload.
         """
@@ -3680,7 +3821,7 @@ class Shotgun(object):
             return results[0]
         return results
 
-    def _auth_params(self):
+    def _auth_params(self) -> Dict[str, Any]:
         """
         Return a dictionary of the authentication parameters being used.
         """
@@ -3735,7 +3876,7 @@ class Shotgun(object):
 
         return auth_params
 
-    def _sanitize_auth_params(self, params):
+    def _sanitize_auth_params(self, params: Dict[str, Any]) -> Dict[str, Any]:
         """
         Given an authentication parameter dictionary, sanitize any sensitive
         information and return the sanitized dict copy.
@@ -3746,7 +3887,9 @@ class Shotgun(object):
                 sanitized_params[k] = "********"
         return sanitized_params
 
-    def _build_payload(self, method, params, include_auth_params=True):
+    def _build_payload(
+        self, method: str, params, include_auth_params: bool = True
+    ) -> Dict[str, Any]:
         """
         Build the payload to be send to the rpc endpoint.
         """
@@ -3764,7 +3907,7 @@ class Shotgun(object):
 
         return {"method_name": method, "params": call_params}
 
-    def _encode_payload(self, payload):
+    def _encode_payload(self, payload) -> bytes:
         """
         Encode the payload to a string to be passed to the rpc endpoint.
 
@@ -3775,7 +3918,9 @@ class Shotgun(object):
 
         return json.dumps(payload, ensure_ascii=False).encode("utf-8")
 
-    def _make_call(self, verb, path, body, headers):
+    def _make_call(
+        self, verb: str, path: str, body, headers: Optional[Dict[str, Any]]
+    ) -> Tuple[Tuple[int, str], Dict[str, Any], str]:
         """
         Make an HTTP call to the server.
 
@@ -3825,7 +3970,9 @@ class Shotgun(object):
             )
             time.sleep(rpc_attempt_interval)
 
-    def _http_request(self, verb, path, body, headers):
+    def _http_request(
+        self, verb: str, path: str, body, headers: Dict[str, Any]
+    ) -> Tuple[Tuple[int, str], Dict[str, Any], str]:
         """
         Make the actual HTTP request.
         """
@@ -3849,7 +3996,9 @@ class Shotgun(object):
 
         return (http_status, resp_headers, resp_body)
 
-    def _make_upload_request(self, request, opener):
+    def _make_upload_request(
+        self, request, opener: "urllib.request.OpenerDirector"
+    ) -> "urllib.request._UrlopenRet":
         """
         Open the given request object, return the
         response, raises URLError on protocol errors.
@@ -3861,7 +4010,7 @@ class Shotgun(object):
             raise
         return result
 
-    def _parse_http_status(self, status):
+    def _parse_http_status(self, status: Tuple) -> None:
         """
         Parse the status returned from the http request.
 
@@ -3879,7 +4028,9 @@ class Shotgun(object):
 
         return
 
-    def _decode_response(self, headers, body):
+    def _decode_response(
+        self, headers: Dict[str, Any], body: str
+    ) -> Union[str, Dict[str, Any]]:
         """
         Decode the response from the server from the wire format to
         a python data structure.
@@ -3900,7 +4051,7 @@ class Shotgun(object):
             return self._json_loads(body)
         return body
 
-    def _json_loads(self, body):
+    def _json_loads(self, body: str) -> Any:
         return json.loads(body)
 
     def _response_errors(self, sg_response):
@@ -3949,7 +4100,7 @@ class Shotgun(object):
                 raise Fault(sg_response.get("message", "Unknown Error"))
         return
 
-    def _visit_data(self, data, visitor):
+    def _visit_data(self, data: T, visitor) -> T:
         """
         Walk the data (simple python types) and call the visitor.
         """
@@ -3959,17 +4110,17 @@ class Shotgun(object):
 
         recursive = self._visit_data
         if isinstance(data, list):
-            return [recursive(i, visitor) for i in data]
+            return [recursive(i, visitor) for i in data]  # type: ignore[return-value]
 
         if isinstance(data, tuple):
-            return tuple(recursive(i, visitor) for i in data)
+            return tuple(recursive(i, visitor) for i in data)  # type: ignore[return-value]
 
         if isinstance(data, dict):
-            return dict((k, recursive(v, visitor)) for k, v in data.items())
+            return dict((k, recursive(v, visitor)) for k, v in data.items())  # type: ignore[return-value]
 
         return visitor(data)
 
-    def _transform_outbound(self, data):
+    def _transform_outbound(self, data: T) -> T:
         """
         Transform data types or values before they are sent by the client.
 
@@ -4016,7 +4167,7 @@ class Shotgun(object):
 
         return self._visit_data(data, _outbound_visitor)
 
-    def _transform_inbound(self, data):
+    def _transform_inbound(self, data: T) -> T:
         """
         Transforms data types or values after they are received from the server.
         """
@@ -4052,7 +4203,7 @@ class Shotgun(object):
     # ========================================================================
     # Connection Functions
 
-    def _get_connection(self):
+    def _get_connection(self) -> Http:
         """
         Return the current connection or creates a new connection to the current server.
         """
@@ -4081,7 +4232,7 @@ class Shotgun(object):
 
         return self._connection
 
-    def _close_connection(self):
+    def _close_connection(self) -> None:
         """
         Close the current connection.
         """
@@ -4100,7 +4251,7 @@ class Shotgun(object):
     # ========================================================================
     # Utility
 
-    def _parse_records(self, records):
+    def _parse_records(self, records: List) -> List:
         """
         Parse 'records' returned from the api to do local modifications:
 
@@ -4156,7 +4307,7 @@ class Shotgun(object):
 
         return records
 
-    def _build_thumb_url(self, entity_type, entity_id):
+    def _build_thumb_url(self, entity_type: str, entity_id: int) -> str:
         """
         Return the URL for the thumbnail of an entity given the entity type and the entity id.
 
@@ -4204,8 +4355,12 @@ class Shotgun(object):
         raise RuntimeError("Unknown code %s %s" % (code, thumb_url))
 
     def _dict_to_list(
-        self, d, key_name="field_name", value_name="value", extra_data=None
-    ):
+        self,
+        d: Optional[Dict[str, Any]],
+        key_name: str = "field_name",
+        value_name: str = "value",
+        extra_data=None,
+    ) -> List[Dict[str, Any]]:
         """
         Utility function to convert a dict into a list dicts using the key_name and value_name keys.
 
@@ -4222,7 +4377,9 @@ class Shotgun(object):
             ret.append(d)
         return ret
 
-    def _dict_to_extra_data(self, d, key_name="value"):
+    def _dict_to_extra_data(
+        self, d: Optional[Dict[str, Any]], key_name="value"
+    ) -> Dict[str, Any]:
         """
         Utility function to convert a dict into a dict compatible with the extra_data arg
         of _dict_to_list.
@@ -4231,7 +4388,7 @@ class Shotgun(object):
         """
         return dict([(k, {key_name: v}) for (k, v) in (d or {}).items()])
 
-    def _upload_file_to_storage(self, path, storage_url):
+    def _upload_file_to_storage(self, path: str, storage_url: str) -> None:
         """
         Internal function to upload an entire file to the Cloud storage.
 
@@ -4251,7 +4408,9 @@ class Shotgun(object):
 
         LOG.debug("File uploaded to Cloud storage: %s", filename)
 
-    def _multipart_upload_file_to_storage(self, path, upload_info):
+    def _multipart_upload_file_to_storage(
+        self, path: str, upload_info: Dict[str, Any]
+    ) -> None:
         """
         Internal function to upload a file to the Cloud storage in multiple parts.
 
@@ -4293,7 +4452,9 @@ class Shotgun(object):
 
         LOG.debug("File uploaded in multiple parts to Cloud storage: %s", path)
 
-    def _get_upload_part_link(self, upload_info, filename, part_number):
+    def _get_upload_part_link(
+        self, upload_info: Dict[str, Any], filename: str, part_number: int
+    ) -> str:
         """
         Internal function to get the url to upload the next part of a file to the
         Cloud storage, in a multi-part upload process.
@@ -4333,7 +4494,9 @@ class Shotgun(object):
         LOG.debug("Got next upload link from server for multipart upload.")
         return result.split("\n", 2)[1]
 
-    def _upload_data_to_storage(self, data, content_type, size, storage_url):
+    def _upload_data_to_storage(
+        self, data: BinaryIO, content_type: str, size: int, storage_url: str
+    ) -> str:
         """
         Internal function to upload data to Cloud storage.
 
@@ -4382,19 +4545,21 @@ class Shotgun(object):
             else:
                 break
         else:
-            raise ShotgunError("Max attemps limit reached.")
+            raise ShotgunError("Max attempts limit reached.")
 
         etag = result.info()["Etag"]
         LOG.debug("Part upload completed successfully.")
         return etag
 
-    def _complete_multipart_upload(self, upload_info, filename, etags):
+    def _complete_multipart_upload(
+        self, upload_info: Dict[str, Any], filename: str, etags: Iterable[str]
+    ) -> None:
         """
         Internal function to complete a multi-part upload to the Cloud storage.
 
         :param dict upload_info: Contains details received from the server, about the upload.
         :param str filename: Name of the file for which we want to complete the upload.
-        :param tupple etags: Contains the etag of each uploaded file part.
+        :param tuple etags: Contains the etag of each uploaded file part.
         """
 
         params = {
@@ -4421,7 +4586,9 @@ class Shotgun(object):
         if not result.startswith("1"):
             raise ShotgunError("Unable get upload part link: %s" % result)
 
-    def _requires_direct_s3_upload(self, entity_type, field_name):
+    def _requires_direct_s3_upload(
+        self, entity_type: str, field_name: Optional[str]
+    ) -> bool:
         """
         Internal function that determines if an entity_type + field_name combination
         should be uploaded to cloud storage.
@@ -4462,7 +4629,7 @@ class Shotgun(object):
         else:
             return False
 
-    def _send_form(self, url, params):
+    def _send_form(self, url: str, params: Dict[str, Any]) -> str:
         """
         Utility function to send a Form to Shotgun and process any HTTP errors that
         could occur.
@@ -4502,42 +4669,7 @@ class Shotgun(object):
 
             return result
         else:
-            raise ShotgunError("Max attemps limit reached.")
-
-
-class CACertsHTTPSConnection(http.client.HTTPConnection):
-    """ "
-    This class allows to create an HTTPS connection that uses the custom certificates
-    passed in.
-    """
-
-    default_port = http.client.HTTPS_PORT
-
-    def __init__(self, *args, **kwargs):
-        """
-        :param args: Positional arguments passed down to the base class.
-        :param ca_certs: Path to the custom CA certs file.
-        :param kwargs: Keyword arguments passed down to the bas class
-        """
-        # Pop that argument,
-        self.__ca_certs = kwargs.pop("ca_certs")
-        super().__init__(self, *args, **kwargs)
-
-    def connect(self):
-        "Connect to a host on a given (SSL) port."
-        super().connect(self)
-        # Now that the regular HTTP socket has been created, wrap it with our SSL certs.
-        if (sys.version_info.major, sys.version_info.minor) >= (3, 8):
-            context = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
-            context.verify_mode = ssl.CERT_REQUIRED
-            context.check_hostname = False
-            if self.__ca_certs:
-                context.load_verify_locations(self.__ca_certs)
-            self.sock = context.wrap_socket(self.sock)
-        else:
-            self.sock = ssl.wrap_socket(
-                self.sock, ca_certs=self.__ca_certs, cert_reqs=ssl.CERT_REQUIRED
-            )
+            raise ShotgunError("Max attempts limit reached.")
 
 
 # Helpers from the previous API, left as is.
@@ -4629,7 +4761,7 @@ class FormPostHandler(urllib.request.BaseHandler):
         return self.http_request(request)
 
 
-def _translate_filters(filters, filter_operator):
+def _translate_filters(filters: Union[List, Tuple], filter_operator) -> Dict[str, Any]:
     """
     Translate filters params into data structure expected by rpc call.
     """
@@ -4638,7 +4770,7 @@ def _translate_filters(filters, filter_operator):
     return _translate_filters_dict(wrapped_filters)
 
 
-def _translate_filters_dict(sg_filter):
+def _translate_filters_dict(sg_filter: Dict[str, Any]) -> Dict[str, Any]:
     new_filters = {}
     filter_operator = sg_filter.get("filter_operator")
 
@@ -4691,31 +4823,44 @@ def _translate_filters_simple(sg_filter):
         and condition["relation"] in ["is", "is_not", "in", "not_in"]
         and isinstance(values[0], dict)
     ):
-        values = [_get_type_and_id_from_value(v) for v in values]
+        values = [_optimize_filter_field(v) for v in values]
 
     condition["values"] = values
 
     return condition
 
 
-def _version_str(version):
+def _version_str(version) -> str:
     """
     Convert a tuple of int's to a '.' separated str.
     """
     return ".".join(map(str, version))
 
 
-def _get_type_and_id_from_value(value):
+def _optimize_filter_field(
+    field_value: Union[Dict[str, Any], List], recursive: bool = True
+) -> Union[Dict, List]:
     """
-    For an entity dictionary, returns a new dictionary with only the type and id keys.
-    If any of these keys are not present, the original dictionary is returned.
+    For an FPT entity, returns a new dictionary with only the type,
+    id, and other allowed keys.
+    If case of any processing error, the original dictionary is returned.
+
+    At least `type` and `id` keys are required to do the optimization
     """
-    try:
-        if isinstance(value, dict):
-            return {"type": value["type"], "id": value["id"]}
-        elif isinstance(value, list):
-            return [{"type": v["type"], "id": v["id"]} for v in value]
-    except (KeyError, TypeError):
-        LOG.debug(f"Could not optimize entity value {value}")
-
-    return value
+    allowed_keys = {
+        "id",
+        "type",
+        "url",
+        "name",
+        "content_type",
+        "local_path",
+        "storage",
+        "relative_path",
+    }
+    if isinstance(field_value, dict) and "id" in field_value and "type" in field_value:
+        return {key: field_value[key] for key in allowed_keys if key in field_value}
+
+    elif recursive and isinstance(field_value, list):
+        return [_optimize_filter_field(fv, recursive=False) for fv in field_value]
+
+    return field_value