pyramid_traversal_api 0.1.0__tar.gz

pyramid_traversal_api-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ARTEFACTS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pyramid_traversal_api-0.1.0/PKG-INFO

@@ -0,0 +1,51 @@
+Metadata-Version: 2.4
+Name: pyramid_traversal_api
+Version: 0.1.0
+Summary: Tools for writing REST APIs in Pyramid using the traversal API
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Pyramid
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Dist: marshmallow
+Requires-Dist: pyramid
+Requires-Dist: ruff ; extra == 'dev'
+Requires-Dist: sphinx ; extra == 'dev'
+Requires-Dist: pytest ; extra == 'dev'
+Requires-Dist: pytest-cov ; extra == 'dev'
+Requires-Dist: pytest-mock ; extra == 'dev'
+Requires-Dist: webtest>=3.0.7 ; extra == 'dev'
+Requires-Dist: sqlalchemy ; extra == 'sqla'
+Requires-Python: >=3.10
+Provides-Extra: dev
+Provides-Extra: sqla
+Description-Content-Type: text/markdown
+
+# pyramid-traversal-api
+
+**NOTE** This library is currently WIP. Expect breakages, even between minor versions, while on major version 0.
+
+A set of helpers that makes it easier to write traversal-based REST APIs for [pyramid](https://trypyramid.com/) with modern QoL features like
+
+ * Request/response validation
+ * Automatic OpenAPI
+ * Automatic SQLAlchemy requests
+   - But possible to write your own support for any backend
+ * Built around writing REST APIs
+
+## Design goals
+
+ * Build tools FOR pyramid, not REPLACING pyramid
+   - No new abstraction layers on top of Pyramid, just new building blocks
+ * Easy to slap on top of an existing project, allowing gradual migration
+   - Start small finish big, like Pyramid
+
+## Standing on the shoulder of giants
+
+Thank you to the pylons project for Pyramid. Greetings also go to `Theron Luhn` for [pyramid-marshmallow](https://pypi.org/project/pyramid-marshmallow/), which the OpenAPI functionality of this package is based on.
+
+## Requirements
+
+Python 3.9 or later

pyramid_traversal_api-0.1.0/README.md

@@ -0,0 +1,26 @@
+# pyramid-traversal-api
+
+**NOTE** This library is currently WIP. Expect breakages, even between minor versions, while on major version 0.
+
+A set of helpers that makes it easier to write traversal-based REST APIs for [pyramid](https://trypyramid.com/) with modern QoL features like
+
+ * Request/response validation
+ * Automatic OpenAPI
+ * Automatic SQLAlchemy requests
+   - But possible to write your own support for any backend
+ * Built around writing REST APIs
+
+## Design goals
+
+ * Build tools FOR pyramid, not REPLACING pyramid
+   - No new abstraction layers on top of Pyramid, just new building blocks
+ * Easy to slap on top of an existing project, allowing gradual migration
+   - Start small finish big, like Pyramid
+
+## Standing on the shoulder of giants
+
+Thank you to the pylons project for Pyramid. Greetings also go to `Theron Luhn` for [pyramid-marshmallow](https://pypi.org/project/pyramid-marshmallow/), which the OpenAPI functionality of this package is based on.
+
+## Requirements
+
+Python 3.9 or later

pyramid_traversal_api-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[project]
+name = "pyramid_traversal_api"
+version = "0.1.0"
+description = "Tools for writing REST APIs in Pyramid using the traversal API"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICEN[CS]E*"]
+requires-python = ">=3.10"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+	"Framework :: Pyramid",
+	"Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "marshmallow",
+    "pyramid",
+]
+
+[project.optional-dependencies]
+sqla = [
+    "sqlalchemy"
+]
+
+dev = [
+    "ruff",
+    "sphinx",
+    "pytest",
+    "pytest-cov",
+    "pytest-mock",
+    "webtest>=3.0.7",
+]
+
+[build-system]
+requires = ["uv_build>=0.9.18,<0.10.0"]
+build-backend = "uv_build"

pyramid_traversal_api-0.1.0/src/pyramid_traversal_api/__init__.py

@@ -0,0 +1,104 @@
+from marshmallow import Schema
+from pyramid.response import Response
+from pyramid.viewderivers import VIEW
+import pyramid.httpexceptions as exc
+
+import logging
+
+log = logging.getLogger(__name__)
+
+
+def includeme(config):
+    # Forward some work to pyramid_marshmallow for now
+    config.add_view_deriver(view_validator)
+    config.add_view_deriver(view_marshaller, under="rendered_view", over=VIEW)
+    config.add_view_deriver(view_api_spec)
+
+
+def process_schema(schema: dict):
+    """Normalizes a schema. If it is a dict, convert it to Schema. If not, return as-is."""
+    if isinstance(schema, Schema):
+        return schema
+    elif isinstance(schema, dict):
+        return Schema.from_dict(schema)()
+    else:
+        raise TypeError(f"Schema {schema} is invalid type")
+
+
+def process_schemas(schemas):
+    """Handle a schemas passed in as a view deriver, creating a nonce schema if a
+    dictionary.
+    """
+    if schemas is None:
+        return {}
+    new_schemas = {}
+    for response, schema in schemas.items():
+        new_schemas[response] = process_schema(schema)
+    return new_schemas
+
+
+def view_validator(view, info):
+    # https://github.com/luhn/pyramid-marshmallow/blob/main/pyramid_marshmallow/__init__.py
+    schema = info.options.get("validate")
+    if schema is None:
+        return view
+    schema = process_schema(schema)
+
+    def wrapped(context, request):
+        if request.method == "GET":
+            data = dict()
+            for k, v in request.GET.items():
+                field = schema.fields.get(k)
+                if isinstance(field, fields.List):
+                    data.setdefault(k, []).append(v)
+                else:
+                    data[k] = v
+        else:
+            data = request.json_body
+        request.data = schema.load(data)
+        return view(context, request)
+
+    return wrapped
+
+
+view_validator.options = ("validate",)
+
+
+def view_marshaller(view, info):
+    """If there is a schema for the response code being returned, we marshal it
+    TODO: Maybe ignore the marshalling altogether and only use it for schema?"""
+    schemas = process_schemas(info.options.get("marshal_responses"))
+    if not any([schema is not None for schema in schemas.values()]):
+        return view
+
+    def wrapped(context, request):
+        output = view(context, request)
+
+        status = str(request.response.status_int)
+
+        if isinstance(output, Response) or status not in schemas:
+            return output
+        else:
+            dumped = schemas[status].dump(output)
+
+            errors = schemas[status].validate(dumped)
+            if len(errors) != 0:
+                log.info(f"Validation errors: {errors}")
+                raise exc.HTTPInternalServerError(
+                    "Unable to generate correct response. This is on us. Sorry"
+                )
+            return dumped
+
+    return wrapped
+
+
+# Ignore type as we are doing some Python dark magic here
+view_marshaller.options = ("marshal_responses",)  # type: ignore[attr-defined]
+
+
+# TODO: consolidate view options
+def view_api_spec(view, info):
+    return view
+
+
+view_api_spec.options = "api_spec"  # type: ignore[attr-defined]

pyramid_traversal_api-0.1.0/src/pyramid_traversal_api/crud.py

@@ -0,0 +1,56 @@
+# Helper for automagically generating CRUD views for a resource
+import marshmallow
+import typing
+import functools
+import logging
+
+log = logging.getLogger(__name__)
+
+
+def crud(
+    create: typing.Optional[marshmallow.Schema],
+    read: typing.Optional[bool],
+    update: typing.Optional[marshmallow.Schema],
+    delete: typing.Optional[bool],
+):
+    """Decorator to attach to a resource class. For each kwarg in create, read, update, delete, creates a corresponding view using the schema if a value is provided.
+    For `read` and `delete`, you can only enable or disable creation of the view.
+
+    :param create:
+        Not yet implemented
+    :param read:
+        Not yet implemented
+    :param update:
+        Not yet implemented
+    :param delete:
+        Not yet implemented
+    """
+
+    def inner(f):
+        @functools.wraps(f)
+        def wrapper(*args, **kwds):
+            cls = f(*args, **kwds)
+
+            log.debug(f"Creating crud for {cls}")
+
+            if create is not None:
+                log.debug("Creating create")
+                raise NotImplementedError("Not yet implemented")
+
+            if read is not None:
+                log.debug("Creating read")
+                raise NotImplementedError("Not yet implemented")
+
+            if update is not None:
+                log.debug("Creating update")
+                raise NotImplementedError("Not yet implemented")
+
+            if delete is not None:
+                log.debug("Creating delete")
+                raise NotImplementedError("Not yet implemented")
+
+            return cls
+
+        return wrapper
+
+    return inner

pyramid_traversal_api-0.1.0/src/pyramid_traversal_api/deprecation.py

@@ -0,0 +1,41 @@
+"""Implements a decorator that allows you to warn API users of deprecation using RFC9745"""
+
+import functools
+import typing
+import pyramid.httpexceptions as exc
+from email.utils import formatdate
+
+from datetime import datetime
+from time import mktime
+
+
+def deprecation(deprecation_datetime: str, link: typing.Optional[str]):
+    """Implements the deprecation HTTP header (RFC9745) for a view. The view will continue to work after the deprecation datetime, but should be considered not wanted. The deprecation header will be injected both before and after deprecation time.
+
+    ::param date:
+        The date (and time) of the endpoint being deprecated in ISO 8601 format.
+    ::param link:
+        An optional link to information about the deprecation, provided to the user in the Link header
+    """
+    parsed_deprecation_datetime = datetime.fromisoformat(deprecation_datetime)
+    headers = {
+        "Deprecation": formatdate(
+            timeval=mktime(parsed_deprecation_datetime.timetuple()),
+            localtime=False,
+            usegmt=True,
+        )
+    }
+    if link is not None:
+        headers["Link"] = f'<{link}>;rel="deprecation";type="text/html"'
+
+    def inner(f):
+        @functools.wraps(f)
+        def wrapper(context, request):
+            for header in headers.keys():
+                request.response.headers[header] = headers[header]
+
+            return f(context, request)
+
+        return wrapper
+
+    return inner

pyramid_traversal_api-0.1.0/src/pyramid_traversal_api/openapi/generator.py

@@ -0,0 +1,232 @@
+"""Took for traversing a Pyramid Traversal node graph and generating an OpenAPI spec to describe it."""
+
+import inspect
+
+from pathlib import Path
+
+from pyramid.path import DottedNameResolver
+
+from .helpers import (
+    set_request_body,
+    set_query_params,
+    set_response_body,
+    get_operation_id,
+    split_docstring,
+    set_tag,
+    schema_name_resolver,
+)
+
+from apispec import APISpec, utils
+
+import logging
+
+log = logging.getLogger(__name__)
+
+
+def ops_from_view(
+    spec, introspectable, url_params, response_types, gen_external_docs_callback=None
+):
+    """Generates a dictionary of operations for a given introspectable(view).
+
+    `url_params` are url params that apply to the URL we are currently at.
+    `traverse_resource` deduces any url params for the current URL,
+    and also passes them recursively to child resources.
+    """
+    # Do openapi magic here
+    # Taken from pyramid-marshmallow
+    operations = {}
+    methods = introspectable["request_methods"] or ["GET"]
+    if isinstance(methods, str):
+        methods = [methods]
+    for method in methods:
+        method = method.lower()
+        operations[method] = introspectable
+
+    final_ops = dict()
+    for method, view in operations.items():
+        summary, descr, user_op = split_docstring(view["callable"].__doc__)
+        op = {
+            "responses": dict(),
+            "parameters": url_params.copy(),
+            "operationId": get_operation_id(view)
+            if len(operations) == 1
+            else f"{method}_{get_operation_id(view)}",
+        }
+        if gen_external_docs_callback is not None:
+            op["externalDocs"] = gen_external_docs_callback(view["callable"])
+        if summary:
+            op["summary"] = summary
+        if descr:
+            op["description"] = descr
+
+        if "validate" in view:
+            if method == "get":
+                set_query_params(spec, op, view)
+            else:
+                set_request_body(spec, op, view)
+        if "marshal_responses" in view:
+            set_response_body(spec, op, view)
+        set_tag(spec, op, view)
+        final_op = utils.deepupdate(op, user_op)
+        final_op = utils.deepupdate(final_op, view.get("api_spec", dict()))
+
+        # We are required to have some response, so make one up.
+        if "200" not in final_op["responses"]:
+            final_op["responses"]["200"] = {
+                "description": "",
+            }
+
+        # Naive auto-detection of resources that represent an SQL table
+        if "404" not in final_op["responses"] and len(url_params) > 0:
+            final_op["responses"]["404"] = {
+                "description": "An object was not found for "
+                + " or ".join(map(lambda param: f"`{param['name']}`", url_params))
+            }
+        if "400" not in final_op["responses"] and "validate" in view:
+            final_op["responses"]["400"] = {"description": "Request validation failed"}
+
+        # Any response types generated by framework are also added
+        for key, value in response_types.items():
+            log.debug(f"Checking if {key} in responses")
+            if key not in final_op["responses"]:
+                log.debug(f"Adding response {key}")
+                final_op["responses"][key] = value
+
+        log.debug(f"FINAL OP: {final_op}")
+        final_ops[method] = final_op
+
+    return final_ops
+
+
+def populate_url_params(param):
+    """Takes a param definition as defined on a resource,
+    and adds necessary fields to make it an OpenAPI URL parameter
+    """
+    return {**param, "in": "path", "required": True}
+
+
+def traverse_resource(
+    spec,
+    introspector,
+    context,
+    path="",
+    url_params=[],
+    response_types={},
+    gen_external_docs_callback=None,
+):
+    log.info(
+        f"Traversing {context} at path {path} inherited response types {response_types}"
+    )
+    # Iterate all views of this resource
+    for item in introspector.get_category("views", context):
+        introspectable = item["introspectable"]
+        if introspectable["context"] == context:
+            view_path = f"{path}/{introspectable['name']}"
+
+            ops = ops_from_view(
+                spec,
+                introspectable,
+                url_params,
+                response_types,
+                gen_external_docs_callback,
+            )
+            spec.path(view_path, operations=ops)
+        else:
+            # log.info(item["introspectable"]["context"])
+            pass
+
+    # Then, check child resources
+    new_children = getattr(context, "static_children", None)
+
+    dynamic_child = context.get_dynamic_openapi_info()
+    if dynamic_child:
+        log.info("Path has dynamic children")
+        new_url_params = url_params + list(
+            map(populate_url_params, dynamic_child["params"])
+        )
+        # We need to determine some sane name for the url param
+        # So we pick table name + primary key name
+        traverse_resource(
+            spec,
+            introspector,
+            dynamic_child["resource"],
+            f"{path}/"
+            + "/".join(
+                map(lambda param: "{" + param["name"] + "}", dynamic_child["params"])
+            ),
+            new_url_params,
+            response_types,
+            gen_external_docs_callback,
+        )
+
+    if new_children:
+        log.info("Path has children")
+
+        # Supports both dynamic and static children at the same time
+        for k, v in new_children.items():
+            traverse_resource(
+                spec,
+                introspector,
+                v,
+                f"{path}/{k}",
+                url_params,
+                response_types,
+                gen_external_docs_callback,
+            )
+
+    log.info("Path has no children")
+
+
+def generate_apispec(
+    name,
+    version,
+    registry,
+    resource,
+    path="",
+    global_response_types={},
+    gen_external_docs_callback=None,
+) -> dict:
+    """Returns an APISpec object from traversing the tree with a given resource as root.
+    `path` specifies an optional URL prefix for every endpoint
+
+    :param name:
+        The name of the API that is documented
+    :param version:
+        The version of the API that is documented
+    :param registry:
+        An instance of a pyramid registry
+    :param resource:
+        The traversal context to use as root
+    :param path:
+        An optional path prefix
+    :param global_response_types:
+        Any HTTP response codes that may be returned due to how the server is configured (f.ex extra validation or security)
+    :param gen_external_docs_callback:
+        An optional callback that takes a view and returns a dict containing an external documentation object. See https://swagger.io/specification/#external-documentation-object
+    """
+
+    name_resolver = DottedNameResolver()
+    MarshmallowPlugin = name_resolver.maybe_resolve(
+        registry.settings.get(
+            "openapi.plugin", "apispec.ext.marshmallow.MarshmallowPlugin"
+        )
+    )
+
+    marshmallow_plugin = MarshmallowPlugin(schema_name_resolver=schema_name_resolver)
+
+    spec = APISpec(
+        name,
+        version,
+        openapi_version="3.0.0",
+        plugins=[marshmallow_plugin],
+    )
+
+    traverse_resource(
+        spec,
+        registry.introspector,
+        resource,
+        path,
+        response_types=global_response_types,
+        gen_external_docs_callback=gen_external_docs_callback,
+    )
+    return spec.to_dict()

pyramid_traversal_api-0.1.0/src/pyramid_traversal_api/openapi/helpers.py

@@ -0,0 +1,111 @@
+"""Helpers for OpenAPI generation
+Mostly copied verbatim or slightly modified from https://github.com/luhn/pyramid-marshmallow/blob/main/pyramid_marshmallow
+"""
+
+from marshmallow import Schema
+from apispec import utils as apispec_utils
+from apispec.ext.marshmallow.common import (
+    resolve_schema_cls,
+    resolve_schema_instance,
+)
+
+
+def _schema(schema):
+    if isinstance(schema, dict):
+        return Schema.from_dict(schema)
+    else:
+        return schema
+
+
+def schema_name_resolver(schema):
+    cls = resolve_schema_cls(schema)
+    instance = resolve_schema_instance(schema)
+    name = cls.__name__
+    if not cls.opts.register:
+        # Unregistered schemas are put inline.
+        return False
+    if instance.only or instance.exclude:
+        # If schema includes only select fields, treat it as nonce
+        return False
+    if name.endswith("Schema"):
+        name = name[:-6] or name
+    if instance.partial:
+        name = "Partial" + name
+    return name
+
+
+def set_request_body(spec, op, view):
+    op["requestBody"] = {
+        "content": {
+            "application/json": {
+                "schema": _schema(view["validate"]),
+            },
+        },
+    }
+
+
+def set_query_params(spec, op, view):
+    op["parameters"].append(
+        {
+            "in": "query",
+            "schema": _schema(view["validate"]),
+        }
+    )
+
+
+def set_tag(spec, op, view):
+    context = view["context"]
+    if not context:
+        return
+    tag = getattr(context, "__tag__", None)
+    if not tag:
+        return
+    if isinstance(tag, dict):
+        # Cheating and using the private variable spec._tags
+        if not any(x["name"] == tag["name"] for x in spec._tags):
+            spec.tag(tag)
+        tag_name = tag["name"]
+    else:
+        tag_name = tag
+    op.setdefault("tags", []).append(tag_name)
+
+
+def split_docstring(docstring):
+    """
+    Split a docstring in half, delineated with a "---".  The first half is
+    returned verbatim, the second half is parsed as YAML.
+
+    """
+    split_lines = apispec_utils.trim_docstring(docstring).split("\n")
+
+    # Cut YAML from rest of docstring
+    for index, line in enumerate(split_lines):
+        line = line.strip()
+        if line.startswith("---"):
+            cut_from = index
+            break
+    else:
+        cut_from = len(split_lines)
+
+    summary = split_lines[0].strip() or None
+    docs = "\n".join(split_lines[1:cut_from]).strip() or None
+    yaml_string = "\n".join(split_lines[cut_from:])
+    if yaml_string:
+        parsed = yaml.safe_load(yaml_string)
+    else:
+        parsed = dict()
+    return summary, docs, parsed
+
+
+def set_response_body(spec, op, view):
+    for response_code, schema in view["marshal_responses"].items():
+        op["responses"][response_code] = {
+            "description": "",
+            "content": {
+                "application/json": {"schema": schema},
+            },
+        }
+
+
+def get_operation_id(view):
+    return view["callable"].__name__

pyramid_traversal_api-0.1.0/src/pyramid_traversal_api/resource/__init__.py

@@ -0,0 +1,89 @@
+import time
+import logging
+
+from typing import Type
+
+log = logging.getLogger(__name__)
+
+
+class Resource:
+    # Static children are child nodes that can be reached by a static name without needing any backend lookup.
+    static_children: dict[str, Type["Resource"]] = {}
+
+    # Store known views (in class namespace, or "class static", so it is remembered)
+    # Key is the view name, and the value is a list of request methods
+    _known_views: dict[str, list[str]] = {}
+
+    def __init__(self, request, *args, **kwargs):
+        self.request = request
+        self.variables = kwargs or {}
+
+    def __getitem__(self, key: str) -> "Resource":
+        if self._determine_is_reserved_keyname(key):
+            raise KeyError("A view exists by this name, so stopping traversal")
+
+        if key not in self.static_children:
+            raise KeyError("no item")
+        item = self.static_children[key]
+
+        return self._mkchild(key, item)
+
+    def __getattr__(self, key):
+        if key in self.variables:
+            return self.variables[key]
+
+        # Attribute doesn't exist, provide some debug info for the developer
+        available_keys = ", ".join(self.variables.keys())
+        raise AttributeError(
+            f'Attribute "{key}" not found in {type(self).__name__} (class {self.__class__.__name__}). Available: {available_keys}'
+        )
+
+    def _mkchild(self, key: str, resource, *args, **kwargs):
+        """Helper that sets necessary fields for Pyramid traversal"""
+        child = resource(self.request, **{**self.variables, **kwargs})
+        child.__parent__ = self
+        child.__name__ = key
+
+        return child
+
+    @classmethod
+    def get_dynamic_openapi_info(cls):
+        """Returns information about a child resoure and the url parameters required for it.
+        Implement it if your resource does some kind of lookup for its children"""
+        return None
+
+    def _determine_is_reserved_keyname(self, key):
+        """Uses pyramid introspection (https://docs.pylonsproject.org/projects/pyramid/en/latest/narr/introspector.html)
+        to determine if there is a view registered to this resource with the given key name. If so, we probably don't want to look it up in SQL,
+        so this function is a helper for used in __getitem__ implementations.
+        """
+        log.debug(f"Checking if {key} is reserved")
+        if key in self._known_views.keys() and (
+            self._known_views[key] is None
+            or self.request.method in self._known_views[key]
+        ):
+            # Note that we cannot store if a key is NOT a view as it would lead to a DOS vulnerability
+            log.debug(f"{self.request.method} {key} is known to be a view")
+            return True
+        # Performance tests on my local machine shows this function costs ~0.04ms. Debug logging is orders of magnitude more expensive.
+        # In the future we could try wrapping all the resource classes in factories that can perform the introspection at config-time?
+        t = time.perf_counter_ns()
+
+        introspector = self.request.registry.introspector
+        view_intr = introspector.get_category("views")
+        for view in view_intr:
+            context = view["introspectable"]["context"]
+            if context == self.__class__:
+                name = view["introspectable"]["name"]
+                request_methods = view["introspectable"]["request_methods"]
+                if name == key and (
+                    request_methods is None or self.request.method in request_methods
+                ):
+                    t_e = time.perf_counter_ns()
+                    # We want to be aware of traversal time for now.
+                    log.debug(
+                        f"Stopping traversal, done in {(t_e - t) / 1000 / 1000}ms"
+                    )
+                    self._known_views[key] = request_methods
+                    return True
+        return False

pyramid_traversal_api-0.1.0/src/pyramid_traversal_api/resource/collection.py

@@ -0,0 +1,43 @@
+from pyramid_traversal_api.resource import Resource
+
+
+class ResourceCollectionValidatorMeta(type):
+    def __new__(cls, clsname, bases, attrs):
+        if clsname != "ResourceCollection":
+            if "child_resource_class" not in attrs:
+                raise ValueError(
+                    f"child_resource_class must be set for ResourceClass when creating {clsname}"
+                )
+
+        return super().__new__(cls, clsname, bases, attrs)
+
+
+class ResourceCollection(Resource, metaclass=ResourceCollectionValidatorMeta):
+    """A node that wraps a collection of a resource, usually fetched from a database or similar.
+    Override the query_collection function with your own query logic"""
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+
+    def __getitem__(self, key):
+        if self._determine_is_reserved_keyname(key):
+            raise KeyError("A view exists by this name, so stopping traversal")
+
+        instance = self.query_item(key)
+
+        if not instance:
+            raise KeyError("No object found")
+
+        resource = self._mkchild(
+            key, self.child_resource_class, **{self.__name__: instance}
+        )
+
+        return resource
+
+    def query_item(self, key):
+        """Function intended to be overloaded with your own query logic"""
+        raise NotImplementedError("Remember to implement query_item")
+
+    @classmethod
+    def get_dynamic_openapi_info(cls):
+        raise NotImplementedError("get_dynamic_openapi_info needs to be implemented")

pyramid_traversal_api-0.1.0/src/pyramid_traversal_api/resource/sqla_collection.py

@@ -0,0 +1,119 @@
+from sqlalchemy.sql.schema import Column
+from sqlalchemy.orm.decl_api import DeclarativeBase
+from pyramid_traversal_api.resource.collection import (
+    ResourceCollection,
+    ResourceCollectionValidatorMeta,
+)
+from pyramid_traversal_api.resource import Resource
+from sqlalchemy import select
+import sqlalchemy
+import pyramid.httpexceptions as exc
+
+from collections.abc import Callable
+from typing import Optional, Type, Any
+
+from uuid import UUID
+
+
+# Key normalizers automatically translate the key (which is a string) to whatever type is required for the column type
+def uuid_normalizer(self, key):
+    # Due to SQLite, if the colum type is UUID, we have to convert the key to uuid first
+    try:
+        return UUID(key)
+    except ValueError:
+        raise exc.HTTPBadRequest("Bad UUID")
+
+
+def noop_normalizer(self, key):
+    return key
+
+
+class SqlaCollectionValidatorMeta(ResourceCollectionValidatorMeta):
+    """Validates a ResourceSqlaCollection and performs other setup tasks at class creation time, so no runtime validation is necessary"""
+
+    def __new__(cls, clsname, bases, attrs):
+        if clsname != "ResourceSqlaCollection":
+            if "sql_class" not in attrs:
+                raise ValueError(
+                    f"sql_class must be set for a ResourceSqlaCollection when creating {clsname}"
+                )
+            if "child_resource_class" not in attrs:
+                raise ValueError(
+                    f"child_resource_class must be set for a ResourceSqlaCollection when creating {clsname}"
+                )
+
+            # Optional
+            if "query_field" not in attrs:
+                attrs["query_field"] = cls._determine_sql_field(
+                    clsname, attrs["sql_class"]
+                )
+
+            # Some key types may need to be normalized before querying, determine that now
+            match type(attrs["query_field"].type):
+                case sqlalchemy.sql.sqltypes.Uuid:
+                    attrs["key_normalizer"] = uuid_normalizer
+                case _:
+                    attrs["key_normalizer"] = noop_normalizer
+
+        return super().__new__(cls, clsname, bases, attrs)
+
+    @staticmethod
+    def _determine_sql_field(clsname, sql_class):
+        """This function introspects the SQLAlchemy entity and finds the primary key."""
+        if len(sql_class.__table__.primary_key.columns) != 1:
+            raise NotImplementedError(
+                f"Error validating {clsname} - SqlChildResource does not support sql models with multiple primary keys - sorry!"
+            )
+        return sql_class.__table__.primary_key.columns[0]
+
+
+class ResourceSqlaCollection(ResourceCollection, metaclass=SqlaCollectionValidatorMeta):
+    """Helper resource class for cases where the child node is an instance of an SQLAlchemy enity.
+    By default it will auto-detect the column to query by looking for the primary key. You can also explicitly specify the query column using `query_field` if needed.
+    """
+
+    # By ignoring typing here, we force any downstream class to implement these
+    # These need to be set for any inheriting class to work properly
+    sql_class: Type[DeclarativeBase] = None  # type: ignore
+    child_resource_class: Type[Resource] = None  # type: ignore
+    # Optional, overrides the field to be queried
+    query_field: Optional[Type[Column]] = None
+
+    # Auto-populated by the metaclass
+    key_normalizer: Callable[[str], Any]
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+
+    @classmethod
+    def get_dynamic_openapi_info(cls):
+        return {
+            "resource": cls.child_resource_class,
+            "params": [
+                {
+                    "name": cls.sql_class.__table__.name + "_" + cls.query_field.name,
+                    "description": f"Primary key of {cls.sql_class.__table__.name}",
+                    "schema": {
+                        # TODO: autodetect a better type based on the primary key field type?
+                        "type": "string",
+                    },
+                }
+            ],
+        }
+
+    def _query_object(self, key):
+        """Performs the SQLAlchemy query to fetch the object. By default uses the provided query field, or the one autodetected by the constructor.
+        Override this if you have special requirements for how the query is made
+
+        The database session is assumed to be reachable on request and be named dbsession.
+        TODO: make this configurable"""
+
+        normalized_key = self.key_normalizer(key)
+
+        return self.request.dbsession.scalars(
+            select(self.sql_class).where(self.query_field == normalized_key)
+        ).first()
+
+    def query_item(self, key):
+        """Queries SQLAlchemy for the specified key"""
+        return self._query_object(key)

pyramid_traversal_api-0.1.0/src/pyramid_traversal_api/sunset.py

@@ -0,0 +1,47 @@
+"""Implements a decorator that allows you to warn of and enforce using RFC8594"""
+
+import functools
+import typing
+import pyramid.httpexceptions as exc
+from email.utils import formatdate
+
+from datetime import datetime
+from time import mktime
+
+
+def sunset(sunset_datetime: str, link: typing.Optional[str]):
+    """Implements the sunset HTTP header (RFC8594) for a view. The view will automatically stop working entirely once the date is passed.
+    This decorator can be used for automatically enforcing grade periods for deprecated views.
+
+    ::param date:
+        The date (and time) of the endpoint being sunset in ISO 8601 format. The endpoint will automatically stop working after this date.
+    ::param link:
+        An optional link to information about the sunsetting, provided to the suer in the Link header.
+    """
+    parsed_sunset_datetime = datetime.fromisoformat(sunset_datetime)
+    headers = {
+        "Sunset": formatdate(
+            timeval=mktime(parsed_sunset_datetime.timetuple()),
+            localtime=False,
+            usegmt=True,
+        )
+    }
+    if link is not None:
+        headers["Link"] = f'<{link}>;rel="sunset";type="text/html"'
+
+    def inner(f):
+        @functools.wraps(f)
+        def wrapper(context, request):
+            if datetime.now() > parsed_sunset_datetime:
+                raise exc.HTTPBadRequest(
+                    "This endpoint has been sunset", headers=headers
+                )
+            else:
+                for header in headers.keys():
+                    request.response.headers[header] = headers[header]
+
+            return f(context, request)
+
+        return wrapper
+
+    return inner