Add typing annotations

Initial draft courtesy of `monkeytype`:

```shell
.venv/bin/uv pip install -e plone.api[test] monkeytype zope.testrunner
monkeytype run .venv/bin/zope-testrunner --path plone.api/src/
for module in `monkeytype list-modules`; do monkeytype apply $module || true > /dev/null;done
```

Author: ale-rt

.meta.toml

@@ -9,6 +9,15 @@ commit-id = "2.5.1"
 codespell_extra_lines = """
         exclude: docs/locale/.*.pot
 """
+extra_lines = """
+-   repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.18.2
+    hooks:
+    -   id: mypy
+        additional_dependencies:
+            - types-decorator
+        exclude: docs
+"""
 
 [pyproject]
 check_manifest_ignores = """

.pre-commit-config.yaml

@@ -76,6 +76,13 @@ repos:
     hooks:
     -   id: i18ndude
 
+-   repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.18.2
+    hooks:
+    -   id: mypy
+        additional_dependencies:
+            - types-decorator
+        exclude: docs
 
 ##
 # Add extra configuration options in .meta.toml:

news/+a04874c0.internal.md

@@ -0,0 +1 @@
+Add typing annotations [@ale-rt]

news/+ec620103.internal.md

@@ -0,0 +1 @@
+More typing annotations for the typing module

setup.py

@@ -36,6 +36,7 @@
         "plone.dexterity",
         "plone.i18n",
         "plone.registry",
+        "plone.supermodel",
         "plone.uuid",
         "zope.globalrequest",
         "Products.CMFCore",

src/plone/api/_types.py

@@ -0,0 +1,20 @@
+"""Shared internal typing aliases used across plone.api modules."""
+
+from Acquisition import ImplicitAcquisitionWrapper
+from typing import TypeAlias
+from ZPublisher.HTTPRequest import HTTPRequest
+
+try:
+    from plone.dexterity.content import DexterityContent as _DexterityContext
+except ImportError:  # pragma: no cover
+    _DexterityContext = ImplicitAcquisitionWrapper
+
+
+# Public-facing context type for content APIs.
+Context: TypeAlias = _DexterityContext
+
+# Broader acquisition-wrapped context for APIs that can accept portal/tool roots.
+ContainerContext: TypeAlias = ImplicitAcquisitionWrapper
+
+# Shared request type for browser/request-aware APIs.
+Request: TypeAlias = HTTPRequest

src/plone/api/addon.py

@@ -11,6 +11,8 @@
 from plone.base.utils import get_installer
 from Products.CMFPlone.controlpanel.browser.quickinstaller import InstallerView
 from Products.GenericSetup import EXTENSION
+from typing import Any
+from typing import cast
 from zope.component import getAllUtilitiesRegisteredFor
 from zope.globalrequest import getRequest
 
@@ -94,7 +96,7 @@ def _get_non_installable_addons() -> NonInstallableAddons:
 
 
 @lru_cache(maxsize=1)
-def _cached_addons() -> tuple[tuple[str, AddonInformation]]:
+def _cached_addons() -> tuple[tuple[str, AddonInformation], ...]:
     """Return information about add-ons in this installation.
 
     :returns: Tuple of tuples with add-on id and AddonInformation.
@@ -130,7 +132,7 @@ def _cached_addons() -> tuple[tuple[str, AddonInformation]]:
         profile_type = pid_parts[-1]
         if product_id not in addons:
             # get some basic information on the product
-            product = {
+            product: dict[str, Any] = {
                 "id": product_id,
                 "version": get_version(product_id),
                 "title": product_id,
@@ -274,7 +276,9 @@ def get(addon: str) -> AddonInformation:
     addons = dict(_cached_addons())
     if addon not in addons:
         raise InvalidParameterError(f"No add-on {addon} found.")
-    return _update_addon_info(addons.get(addon), _get_installer())
+    return _update_addon_info(
+        cast(AddonInformation, addons.get(addon)), _get_installer()
+    )
 
 
 @required_parameters("addon")