Add type hints

Author: Daverball

HISTORY.rst

@@ -10,7 +10,10 @@ unreleased
 - Use GitHub Actions for CI.
   [jugmac00]
 
-- Switch to PEP-420 namespace package
+- Switch to PEP-420 namespace package.
+  [Daverball]
+
+- Add type hints.
   [Daverball]
 
 0.2.0 (2018-02-02)

more/content_security/core.py

@@ -1,21 +1,43 @@
+from __future__ import annotations
+
 import base64
 import os
+from typing import TYPE_CHECKING, Literal
 
 from morepath import App
 from morepath.request import Request
 from more.content_security.policy import ContentSecurityPolicy
 
+if TYPE_CHECKING:
+    from collections.abc import Callable
+    from typing_extensions import TypeVar
+
+    from webob import Response as BaseResponse
+
+    from morepath.types import Tween
+
+    _AppT = TypeVar(
+        "_AppT",
+        bound="ContentSecurityApp",
+        default="ContentSecurityApp",
+        covariant=True,
+    )
+else:
+    from typing import TypeVar
+
+    _AppT = TypeVar("_AppT", bound="ContentSecurityApp", covariant=True)
+
 # see https://csp.withgoogle.com/docs/faq.html#generating-nonces
 NONCE_LENGTH = 16
 
 
-def random_nonce():
+def random_nonce() -> str:
     return base64.b64encode(os.urandom(NONCE_LENGTH)).decode("utf-8")
 
 
-class ContentSecurityRequest(Request):
+class ContentSecurityRequest(Request[_AppT]):
     @property
-    def content_security_policy(self):
+    def content_security_policy(self) -> ContentSecurityPolicy:
         """Provides access to a request-local version of the content
         security policy.
 
@@ -32,10 +54,10 @@ def content_security_policy(self):
         return self._content_security_policy
 
     @content_security_policy.setter
-    def content_security_policy(self, policy):
+    def content_security_policy(self, policy: ContentSecurityPolicy) -> None:
         self._content_security_policy = policy
 
-    def content_security_policy_nonce(self, target):
+    def content_security_policy_nonce(self, target: Literal["script", "style"]) -> str:
         """Generates a nonce that's random once per request, adds it to
         either 'style-src' or 'script-src' and returns its value.
 
@@ -57,7 +79,7 @@ def content_security_policy_nonce(self, target):
         return nonce
 
     @property
-    def content_security_policy_nonce_value(self):
+    def content_security_policy_nonce_value(self) -> str:
         """Returns the request-bound content security nonce. It is secure
         to keep this once per request. It is only dangerous to use nonces
         over more than one request.
@@ -78,23 +100,29 @@ class ContentSecurityApp(App):
 
 
 @ContentSecurityApp.setting("content_security_policy", "default")
-def default_policy():
+def default_policy() -> ContentSecurityPolicy:
     return ContentSecurityPolicy()
 
 
 @ContentSecurityApp.setting("content_security_policy", "apply_policy")
-def default_policy_apply_factory():
-    def apply_policy(policy, request, response):
+def default_policy_apply_factory() -> (
+    Callable[[ContentSecurityPolicy, Request, BaseResponse], None]
+):
+    def apply_policy(
+        policy: ContentSecurityPolicy, request: Request, response: BaseResponse
+    ) -> None:
         policy.apply(response)
 
     return apply_policy
 
 
 @ContentSecurityApp.tween_factory()
-def content_security_policy_tween_factory(app, handler):
+def content_security_policy_tween_factory(
+    app: ContentSecurityApp, handler: Tween
+) -> Tween:
     policy_settings = app.settings.content_security_policy
 
-    def content_security_policy_tween(request):
+    def content_security_policy_tween(request: ContentSecurityRequest) -> BaseResponse:
         response = handler(request)
 
         if hasattr(request, "_content_security_policy"):

more/content_security/policy.py

@@ -1,6 +1,17 @@
+from __future__ import annotations
+
 import inspect
 
 from copy import deepcopy
+from typing import TYPE_CHECKING, Any, Generic, TypeGuard, TypeVar
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Generator
+    from typing_extensions import Self
+
+    from webob.response import Response as BaseResponse
+
+_T = TypeVar("_T")
 
 SELF = "'self'"
 UNSAFE_INLINE = "'unsafe-inline'"
@@ -9,7 +20,7 @@
 STRICT_DYNAMIC = "'strict-dynamic'"
 
 
-class Directive:
+class Directive(Generic[_T]):
     """Descriptor for the management and rendering of CSP directives.
 
     Uses types to do some basic sanity checking. This does not ensure
@@ -20,13 +31,19 @@ class Directive:
 
     """
 
-    def __init__(self, name, type, default, render):
+    def __init__(
+        self,
+        name: str,
+        type: type[_T],
+        default: Callable[[], _T],
+        render: Callable[[_T], str | None],
+    ) -> None:
         self.name = name
         self.type = type
         self.default = default
         self.renderer = render
 
-    def render(self, instance):
+    def render(self, instance: ContentSecurityPolicy) -> str | None:
         if self.name not in instance.__dict__:
             return None
 
@@ -35,7 +52,9 @@ def render(self, instance):
 
         return self.renderer(instance.__dict__[self.name])
 
-    def __get__(self, instance, cls):
+    def __get__(
+        self, instance: ContentSecurityPolicy, cls: type[ContentSecurityPolicy]
+    ) -> _T:
         if instance is None:
             return self
 
@@ -44,40 +63,37 @@ def __get__(self, instance, cls):
 
         return instance.__dict__[self.name]
 
-    def __set__(self, instance, value):
+    def __set__(self, instance: ContentSecurityPolicy, value: _T) -> None:
         if not isinstance(value, self.type):
             raise TypeError(f"Expected type {self.type}")
 
         instance.__dict__[self.name] = value
 
 
-class SetDirective(Directive):
-    def __init__(self, name):
-        parent = super()
-        parent.__init__(name, type=set, default=set, render=render_set)
+class SetDirective(Directive[set[str]]):
+    def __init__(self, name: str) -> None:
+        super().__init__(name, type=set, default=set, render=render_set)
 
 
-class SingleValueDirective(Directive):
-    def __init__(self, name):
-        parent = super()
-        parent.__init__(name, type=str, default=str, render=str)
+class SingleValueDirective(Directive[str]):
+    def __init__(self, name: str) -> None:
+        super().__init__(name, type=str, default=str, render=str)
 
 
-class BooleanDirective(Directive):
-    def __init__(self, name):
-        parent = super()
-        parent.__init__(name, type=bool, default=bool, render=render_bool)
+class BooleanDirective(Directive[bool]):
+    def __init__(self, name: str) -> None:
+        super().__init__(name, type=bool, default=bool, render=render_bool)
 
 
-def is_directive(obj):
+def is_directive(obj: object) -> TypeGuard[Directive[Any]]:
     return isinstance(obj, Directive)
 
 
-def render_set(value):
+def render_set(value: set[str]) -> str:
     return " ".join(sorted(value))
 
 
-def render_bool(value):
+def render_bool(value: bool) -> str | None:
     return "" if value else None
 
 
@@ -103,39 +119,52 @@ class ContentSecurityPolicy:
     """
 
     # Fetch directives
-    child_src = SetDirective("child-src")
-    connect_src = SetDirective("connect-src")
-    default_src = SetDirective("default-src")
-    font_src = SetDirective("font-src")
-    frame_src = SetDirective("frame-src")
-    img_src = SetDirective("img-src")
-    manifest_src = SetDirective("manifest-src")
-    media_src = SetDirective("media-src")
-    object_src = SetDirective("object-src")
-    script_src = SetDirective("script-src")
-    style_src = SetDirective("style-src")
-    worker_src = SetDirective("worker-src")
+    child_src: SetDirective = SetDirective("child-src")
+    connect_src: SetDirective = SetDirective("connect-src")
+    default_src: SetDirective = SetDirective("default-src")
+    font_src: SetDirective = SetDirective("font-src")
+    frame_src: SetDirective = SetDirective("frame-src")
+    img_src: SetDirective = SetDirective("img-src")
+    manifest_src: SetDirective = SetDirective("manifest-src")
+    media_src: SetDirective = SetDirective("media-src")
+    object_src: SetDirective = SetDirective("object-src")
+    script_src: SetDirective = SetDirective("script-src")
+    style_src: SetDirective = SetDirective("style-src")
+    worker_src: SetDirective = SetDirective("worker-src")
 
     # Document directives
-    base_uri = SetDirective("base-uri")
-    plugin_types = SetDirective("plugin-types")
-    sandbox = SingleValueDirective("sandbox")
-    disown_opener = BooleanDirective("disown-opener")
+    base_uri: SetDirective = SetDirective("base-uri")
+    plugin_types: SetDirective = SetDirective("plugin-types")
+    sandbox: SingleValueDirective = SingleValueDirective("sandbox")
+    disown_opener: BooleanDirective = BooleanDirective("disown-opener")
 
     # Navigation directives
-    form_action = SetDirective("form-action")
-    frame_ancestors = SetDirective("frame-ancestors")
+    form_action: SetDirective = SetDirective("form-action")
+    frame_ancestors: SetDirective = SetDirective("frame-ancestors")
 
     # Reporting directives
-    report_uri = SingleValueDirective("report-uri")
-    report_to = SingleValueDirective("report-to")
+    report_uri: SingleValueDirective = SingleValueDirective("report-uri")
+    report_to: SingleValueDirective = SingleValueDirective("report-to")
 
     # Other directives
-    block_all_mixed_content = BooleanDirective("block-all-mixed-content")
-    require_sri_for = SingleValueDirective("require-sri-for")
-    upgrade_insecure_requeists = BooleanDirective("upgrade-insecure-requests")
-
-    def __init__(self, report_only=False, **directives):
+    block_all_mixed_content: BooleanDirective = BooleanDirective(
+        "block-all-mixed-content"
+    )
+    require_sri_for: SingleValueDirective = SingleValueDirective("require-sri-for")
+    upgrade_insecure_requeists: BooleanDirective = BooleanDirective(
+        "upgrade-insecure-requests"
+    )
+
+    def __init__(
+        self,
+        report_only: bool = False,
+        # NOTE: This is both a little too lax and a little too strict, but
+        #       it doesn't seem worth defining a TypedDict, to get better
+        #       type checking on this, this will work for most cases and
+        #       is not the recommended style of defining the directives
+        #       anyways.
+        **directives: set[str] | str | bool,
+    ) -> None:
         self.report_only = report_only
 
         for directive in directives:
@@ -144,32 +173,35 @@ def __init__(self, report_only=False, **directives):
             assert hasattr(self, name)
             setattr(self, name, directives[directive])
 
-    def copy(self):
+    def copy(self) -> Self:
         policy = self.__class__()
         policy.__dict__ = deepcopy(self.__dict__)
 
         return policy
 
     @property
-    def directives(self):
+    def directives(self) -> Generator[Directive[Any]]:
         for name, value in inspect.getmembers(self.__class__, is_directive):
             yield value
 
     @property
-    def text(self):
-        values = ((d.name, d.render(self)) for d in self.directives)
-        values = ((name, text) for name, text in values if text is not None)
+    def text(self) -> str:
+        values = (
+            (d.name, text)
+            for d in self.directives
+            if (text := d.render(self)) is not None
+        )
 
         return ";".join(" ".join(v).strip() for v in values)
 
     @property
-    def header_name(self):
+    def header_name(self) -> str:
         if self.report_only:
             return "Content-Security-Policy-Report-Only"
         else:
             return "Content-Security-Policy"
 
-    def apply(self, response):
+    def apply(self, response: BaseResponse) -> None:
         text = self.text
 
         if text: