Add Type hints to common API methods

[austinwitherspoon]

Now that shotgun is supposed to by py3.7 only, it would be great to add type hints for a better experience in IDE. currently in VS code with Pylance for instance, the inferred types for find() aren't great:

def find(
    self: Self@Shotgun,
    entity_type: Unknown,
    filters: Unknown,
    fields: Unknown | None = None,
    order: Unknown | None = None,
    filter_operator: Unknown | None = None,
    limit: int = 0,
    retired_only: bool = False,
    page: int = 0,
    include_archived_projects: bool = True,
    additional_filter_presets: Unknown | None = None
) -> (list[Unknown] | tuple[Unknown])

If we explicitly type hint it like so:

    def find(
        self,
        entity_type: str,
        filters: Iterable[Union[Iterable, Dict[str, Any]]],
        fields: Optional[Iterable[str]] = None,
        order: Optional[Iterable[Dict[str, str]]] = None,
        filter_operator: Union[Literal['all'], Literal['any']] = None,
        limit: int = 0,
        retired_only: bool = False,
        page: int = 0,
        include_archived_projects: bool = True,
        additional_filter_presets: Optional[Iterable[str]]= None,
    ) -> List[Dict[str, Any]]:

We would have a better experience with static type checkers, and a better experience interacting with the shotgun API from our IDEs.

If for some reason we still want to support python 2 despite officially being 3.7+, we can do the same thing with python 2 compatible comment-style type hints.

Either way, adding hints to the most common methods (find, find_one, create, update, delete, revive, batch, schema_read, ...) would make development smoother!

[carlos-villavicencio-adsk]

This is a really good suggestion. We're waiting until the end of April 2024 to end supporting Python 2. After that, new features like this can be included.