plain 0.52.2__tar.gz → 0.54.0__tar.gz

{plain-0.52.2 → plain-0.54.0}/.gitignore

@@ -4,7 +4,6 @@
 *.py[co]
 __pycache__
 *.DS_Store
-.coverage
 
 # Test apps
 plain*/tests/.plain
@@ -16,3 +15,5 @@ plain*/tests/.plain
 
 # Plain temp dirs
 .plain
+
+.vscode

{plain-0.52.2 → plain-0.54.0}/PKG-INFO

@@ -1,12 +1,14 @@
 Metadata-Version: 2.4
 Name: plain
-Version: 0.52.2
+Version: 0.54.0
 Summary: A web framework for building products with Python.
 Author-email: Dave Gaeddert <dave.gaeddert@dropseed.dev>
 License-File: LICENSE
 Requires-Python: >=3.11
 Requires-Dist: click>=8.0.0
 Requires-Dist: jinja2>=3.1.2
+Requires-Dist: opentelemetry-api>=1.34.1
+Requires-Dist: opentelemetry-semantic-conventions>=0.55b1
 Description-Content-Type: text/markdown
 
 # Plain
@@ -59,6 +61,7 @@ The `plain` package includes everything you need to start handling web requests
 - [plain.support](/plain-support/plain/support/README.md) - Customer support forms.
 - [plain.redirection](/plain-redirection/plain/redirection/README.md) - Redirects managed in the database.
 - [plain.pageviews](/plain-pageviews/plain/pageviews/README.md) - Basic self-hosted page view tracking and reporting.
+- [plain.observer](/plain-observer/plain/observer/README.md) - On-page telemetry reporting.
 
 ## Dev Packages
 

{plain-0.52.2 → plain-0.54.0}/plain/CHANGELOG.md

@@ -1,5 +1,29 @@
 # plain changelog
 
+## [0.54.0](https://github.com/dropseed/plain/releases/plain@0.54.0) (2025-07-18)
+
+### What's changed
+
+- Added OpenTelemetry instrumentation for HTTP requests, views, and template rendering ([b0224d0418](https://github.com/dropseed/plain/commit/b0224d0418))
+- Added `plain-observer` package reference to plain README ([f29ff4dafe](https://github.com/dropseed/plain/commit/f29ff4dafe))
+
+### Upgrade instructions
+
+- No changes required
+
+## [0.53.0](https://github.com/dropseed/plain/releases/plain@0.53.0) (2025-07-18)
+
+### What's changed
+
+- Added a `pluralize` filter for Jinja templates to handle singular/plural forms ([4cef9829ed](https://github.com/dropseed/plain/commit/4cef9829ed))
+- Added `get_signed_cookie()` method to `HttpRequest` for retrieving and verifying signed cookies ([f8796c8786](https://github.com/dropseed/plain/commit/f8796c8786))
+- Improved CLI error handling by using `click.UsageError` instead of manual error printing ([88f06c5184](https://github.com/dropseed/plain/commit/88f06c5184))
+- Simplified preflight check success message ([adffc06152](https://github.com/dropseed/plain/commit/adffc06152))
+
+### Upgrade instructions
+
+- No changes required
+
 ## [0.52.2](https://github.com/dropseed/plain/releases/plain@0.52.2) (2025-06-27)
 
 ### What's changed

{plain-0.52.2 → plain-0.54.0}/plain/README.md

@@ -48,6 +48,7 @@ The `plain` package includes everything you need to start handling web requests
 - [plain.support](/plain-support/plain/support/README.md) - Customer support forms.
 - [plain.redirection](/plain-redirection/plain/redirection/README.md) - Redirects managed in the database.
 - [plain.pageviews](/plain-pageviews/plain/pageviews/README.md) - Basic self-hosted page view tracking and reporting.
+- [plain.observer](/plain-observer/plain/observer/README.md) - On-page telemetry reporting.
 
 ## Dev Packages
 

{plain-0.52.2 → plain-0.54.0}/plain/cli/build.py

@@ -37,12 +37,9 @@ def build(keep_original, fingerprint, compress):
     """Pre-deployment build step (compile assets, css, js, etc.)"""
 
     if not keep_original and not fingerprint:
-        click.secho(
-            "You must either keep the original assets or fingerprint them.",
-            fg="red",
-            err=True,
+        raise click.UsageError(
+            "You must either keep the original assets or fingerprint them."
         )
-        sys.exit(1)
 
     # Run user-defined build commands first
     pyproject_path = plain.runtime.APP_PATH.parent / "pyproject.toml"

{plain-0.52.2 → plain-0.54.0}/plain/cli/docs.py

@@ -1,6 +1,5 @@
 import ast
 import importlib.util
-import sys
 from pathlib import Path
 
 import click
@@ -16,8 +15,7 @@ from .output import iterate_markdown
 @click.argument("module", default="")
 def docs(module, llm, open):
     if not module and not llm:
-        click.secho("You must specify a module or use --llm", fg="red")
-        sys.exit(1)
+        raise click.UsageError("You must specify a module or use --llm")
 
     if llm:
         paths = [Path(__file__).parent.parent]
@@ -49,14 +47,12 @@ def docs(module, llm, open):
         # Get the README.md file for the module
         spec = importlib.util.find_spec(module)
         if not spec:
-            click.secho(f"Module {module} not found", fg="red")
-            sys.exit(1)
+            raise click.UsageError(f"Module {module} not found")
 
         module_path = Path(spec.origin).parent
         readme_path = module_path / "README.md"
         if not readme_path.exists():
-            click.secho(f"README.md not found for {module}", fg="red")
-            sys.exit(1)
+            raise click.UsageError(f"README.md not found for {module}")
 
         if open:
             click.launch(str(readme_path))

{plain-0.52.2 → plain-0.54.0}/plain/cli/preflight.py

@@ -123,4 +123,4 @@ def preflight_checks(package_label, deploy, fail_level, database):
             msg = header + body + footer
             click.echo(msg, err=True)
         else:
-            click.secho("✔ Preflight check identified no issues.", err=True, fg="green")
+            click.secho("✔ Checks passed", err=True, fg="green")

{plain-0.52.2 → plain-0.54.0}/plain/cli/urls.py

@@ -1,5 +1,3 @@
-import sys
-
 import click
 
 
@@ -17,8 +15,7 @@ def list_urls(flat):
     from plain.urls import URLResolver, get_resolver
 
     if not settings.URLS_ROUTER:
-        click.secho("URLS_ROUTER is not set", fg="red")
-        sys.exit(1)
+        raise click.UsageError("URLS_ROUTER is not set")
 
     resolver = get_resolver(settings.URLS_ROUTER)
     if flat:

plain-0.54.0/plain/http/cookie.py

@@ -0,0 +1,64 @@
+from http import cookies
+
+from plain.runtime import settings
+from plain.signing import BadSignature, TimestampSigner
+from plain.utils.encoding import force_bytes
+
+
+def parse_cookie(cookie):
+    """
+    Return a dictionary parsed from a `Cookie:` header string.
+    """
+    cookiedict = {}
+    for chunk in cookie.split(";"):
+        if "=" in chunk:
+            key, val = chunk.split("=", 1)
+        else:
+            # Assume an empty name per
+            # https://bugzilla.mozilla.org/show_bug.cgi?id=169091
+            key, val = "", chunk
+        key, val = key.strip(), val.strip()
+        if key or val:
+            # unquote using Python's algorithm.
+            cookiedict[key] = cookies._unquote(val)
+    return cookiedict
+
+
+def _cookie_key(key):
+    """
+    Generate a key for cookie signing that matches the pattern used by
+    set_signed_cookie and get_signed_cookie.
+    """
+    return b"plain.http.cookies" + force_bytes(key)
+
+
+def get_signed_cookie_signer(key, salt=""):
+    """
+    Create a TimestampSigner for signed cookies with the same configuration
+    used by both set_signed_cookie and get_signed_cookie.
+    """
+    return TimestampSigner(
+        key=_cookie_key(settings.SECRET_KEY),
+        fallback_keys=map(_cookie_key, settings.SECRET_KEY_FALLBACKS),
+        salt=key + salt,
+    )
+
+
+def sign_cookie_value(key, value, salt=""):
+    """
+    Sign a cookie value using the standard Plain cookie signing approach.
+    """
+    signer = get_signed_cookie_signer(key, salt)
+    return signer.sign(value)
+
+
+def unsign_cookie_value(key, signed_value, salt="", max_age=None, default=None):
+    """
+    Unsign a cookie value using the standard Plain cookie signing approach.
+    Returns the default value if the signature is invalid or the cookie has expired.
+    """
+    signer = get_signed_cookie_signer(key, salt)
+    try:
+        return signer.unsign(signed_value, max_age=max_age)
+    except BadSignature:
+        return default

{plain-0.52.2 → plain-0.54.0}/plain/http/request.py

@@ -13,6 +13,7 @@ from plain.exceptions import (
     RequestDataTooBig,
     TooManyFieldsSent,
 )
+from plain.http.cookie import unsign_cookie_value
 from plain.http.multipartparser import (
     MultiPartParser,
     MultiPartParserError,
@@ -427,6 +428,20 @@ class HttpRequest:
     def readlines(self):
         return list(self)
 
+    def get_signed_cookie(self, key, default=None, salt="", max_age=None):
+        """
+        Retrieve a cookie value signed with the SECRET_KEY.
+
+        Return default if the cookie doesn't exist or signature verification fails.
+        """
+
+        try:
+            cookie_value = self.cookies[key]
+        except KeyError:
+            return default
+
+        return unsign_cookie_value(key, cookie_value, salt, max_age, default)
+
 
 class HttpHeaders(CaseInsensitiveMapping):
     HTTP_PREFIX = "HTTP_"

{plain-0.52.2 → plain-0.54.0}/plain/http/response.py

@@ -12,13 +12,14 @@ from http.client import responses
 from http.cookies import SimpleCookie
 from urllib.parse import urlparse
 
-from plain import signals, signing
+from plain import signals
 from plain.exceptions import DisallowedRedirect
+from plain.http.cookie import sign_cookie_value
 from plain.json import PlainJSONEncoder
 from plain.runtime import settings
 from plain.utils import timezone
 from plain.utils.datastructures import CaseInsensitiveMapping
-from plain.utils.encoding import force_bytes, iri_to_uri
+from plain.utils.encoding import iri_to_uri
 from plain.utils.http import content_disposition_header, http_date
 from plain.utils.regex_helper import _lazy_re_compile
 
@@ -260,16 +261,8 @@ class ResponseBase:
     def set_signed_cookie(self, key, value, salt="", **kwargs):
         """Set a cookie signed with the SECRET_KEY."""
 
-        def _cookie_key(k):
-            return b"plain.http.cookies" + force_bytes(k)
-
-        signer = signing.TimestampSigner(
-            key=_cookie_key(settings.SECRET_KEY),
-            fallback_keys=map(_cookie_key, settings.SECRET_KEY_FALLBACKS),
-            salt=key + salt,
-        )
-        value = signer.sign(value)
-        return self.set_cookie(key, value, **kwargs)
+        signed_value = sign_cookie_value(key, value, salt)
+        return self.set_cookie(key, signed_value, **kwargs)
 
     def delete_cookie(self, key, path="/", domain=None, samesite=None):
         # Browsers can ignore the Set-Cookie header if the cookie doesn't use

{plain-0.52.2 → plain-0.54.0}/plain/internal/handlers/base.py

@@ -1,6 +1,9 @@
 import logging
 import types
 
+from opentelemetry import baggage, trace
+from opentelemetry.semconv.attributes import http_attributes, url_attributes
+
 from plain.exceptions import ImproperlyConfigured
 from plain.logs import log_response
 from plain.runtime import settings
@@ -26,6 +29,9 @@ BUILTIN_AFTER_MIDDLEWARE = [
 ]
 
 
+tracer = trace.get_tracer("plain")
+
+
 class BaseHandler:
     _middleware_chain = None
 
@@ -35,8 +41,7 @@ class BaseHandler:
 
         Must be called after the environment is fixed (see __call__ in subclasses).
         """
-        get_response = self._get_response
-        handler = convert_exception_to_response(get_response)
+        handler = convert_exception_to_response(self._get_response)
 
         middlewares = reversed(
             BUILTIN_BEFORE_MIDDLEWARE + settings.MIDDLEWARE + BUILTIN_AFTER_MIDDLEWARE
@@ -59,18 +64,55 @@ class BaseHandler:
 
     def get_response(self, request):
         """Return a Response object for the given HttpRequest."""
-        # Setup default url resolver for this thread
-        response = self._middleware_chain(request)
-        response._resource_closers.append(request.close)
-        if response.status_code >= 400:
-            log_response(
-                "%s: %s",
-                response.reason_phrase,
-                request.path,
-                response=response,
-                request=request,
+
+        span_attributes = {
+            "plain.request.id": request.unique_id,
+            http_attributes.HTTP_REQUEST_METHOD: request.method,
+            url_attributes.URL_PATH: request.path_info,
+            url_attributes.URL_SCHEME: request.scheme,
+        }
+
+        # Add full URL if we can build it (requires proper WSGI environment)
+        try:
+            span_attributes[url_attributes.URL_FULL] = request.build_absolute_uri()
+        except KeyError:
+            # Missing required WSGI environment variables (e.g. in tests)
+            pass
+
+        # Add query string if present
+        if query_string := request.meta.get("QUERY_STRING"):
+            span_attributes[url_attributes.URL_QUERY] = query_string
+
+        span_context = baggage.set_baggage("http.request.cookies", request.cookies)
+
+        with tracer.start_as_current_span(
+            f"{request.method} {request.path_info}",
+            context=span_context,
+            attributes=span_attributes,
+            kind=trace.SpanKind.SERVER,
+        ) as span:
+            response = self._middleware_chain(request)
+            response._resource_closers.append(request.close)
+
+            span.set_attribute(
+                http_attributes.HTTP_RESPONSE_STATUS_CODE, response.status_code
+            )
+
+            span.set_status(
+                trace.StatusCode.OK
+                if response.status_code < 400
+                else trace.StatusCode.ERROR
             )
-        return response
+
+            if response.status_code >= 400:
+                log_response(
+                    "%s: %s",
+                    response.reason_phrase,
+                    request.path,
+                    response=response,
+                    request=request,
+                )
+            return response
 
     def _get_response(self, request):
         """
@@ -94,9 +136,18 @@ class BaseHandler:
         Retrieve/set the urlrouter for the request. Return the view resolved,
         with its args and kwargs.
         """
+
         resolver = get_resolver()
         # Resolve the view, and assign the match object back to the request.
         resolver_match = resolver.resolve(request.path_info)
+
+        span = trace.get_current_span()
+        span.set_attribute(http_attributes.HTTP_ROUTE, resolver_match.route)
+
+        # Route makes a better name
+        if resolver_match.route:
+            span.update_name(f"{request.method} {resolver_match.route}")
+
         request.resolver_match = resolver_match
         return resolver_match
 

plain-0.54.0/plain/templates/core.py

@@ -0,0 +1,42 @@
+import jinja2
+from opentelemetry import trace
+from opentelemetry.semconv._incubating.attributes.code_attributes import (
+    CODE_FUNCTION_NAME,
+    CODE_NAMESPACE,
+)
+
+from .jinja import environment
+
+tracer = trace.get_tracer("plain")
+
+
+class TemplateFileMissing(Exception):
+    def __str__(self) -> str:
+        if self.args:
+            return f"Template file {self.args[0]} not found"
+        else:
+            return "Template file not found"
+
+
+class Template:
+    def __init__(self, filename: str) -> None:
+        self.filename = filename
+
+        try:
+            self._jinja_template = environment.get_template(filename)
+        except jinja2.TemplateNotFound:
+            raise TemplateFileMissing(filename)
+
+    def render(self, context: dict) -> str:
+        with tracer.start_as_current_span(
+            f"render {self.filename}",
+            kind=trace.SpanKind.INTERNAL,
+            attributes={
+                CODE_FUNCTION_NAME: "render",
+                CODE_NAMESPACE: f"{self.__class__.__module__}.{self.__class__.__qualname__}",
+                "template.filename": self.filename,
+                "template.engine": "jinja2",
+            },
+        ):
+            result = self._jinja_template.render(context)
+            return result

{plain-0.52.2 → plain-0.54.0}/plain/templates/jinja/filters.py

@@ -15,6 +15,25 @@ def localtime_filter(value, timezone=None):
     return localtime(value, timezone)
 
 
+def pluralize_filter(value, singular="", plural="s"):
+    """Returns plural suffix based on the value count.
+
+    Usage:
+        {{ count }} item{{ count|pluralize }}
+        {{ count }} ox{{ count|pluralize("en") }}
+        {{ count }} cact{{ count|pluralize("us","i") }}
+    """
+    try:
+        count = int(value)
+    except (ValueError, TypeError):
+        return singular
+
+    if count == 1:
+        return singular
+
+    return plural
+
+
 default_filters = {
     # The standard Python ones
     "strftime": datetime.datetime.strftime,
@@ -27,4 +46,5 @@ default_filters = {
     "timesince": timesince,
     "json_script": json_script,
     "islice": islice,  # slice for dict.items()
+    "pluralize": pluralize_filter,
 }

{plain-0.52.2 → plain-0.54.0}/plain/views/base.py

@@ -1,6 +1,12 @@
 import logging
 from http import HTTPMethod
 
+from opentelemetry import trace
+from opentelemetry.semconv._incubating.attributes.code_attributes import (
+    CODE_FUNCTION_NAME,
+    CODE_NAMESPACE,
+)
+
 from plain.http import (
     HttpRequest,
     JsonResponse,
@@ -16,6 +22,9 @@ from .exceptions import ResponseException
 logger = logging.getLogger("plain.request")
 
 
+tracer = trace.get_tracer("plain")
+
+
 class View:
     request: HttpRequest
     url_args: tuple
@@ -35,9 +44,23 @@ class View:
     @classonlymethod
     def as_view(cls, *init_args, **init_kwargs):
         def view(request, *url_args, **url_kwargs):
-            v = cls(*init_args, **init_kwargs)
-            v.setup(request, *url_args, **url_kwargs)
-            return v.get_response()
+            with tracer.start_as_current_span(
+                f"{cls.__name__}",
+                kind=trace.SpanKind.INTERNAL,
+                attributes={
+                    CODE_FUNCTION_NAME: "as_view",
+                    CODE_NAMESPACE: f"{cls.__module__}.{cls.__qualname__}",
+                },
+            ) as span:
+                v = cls(*init_args, **init_kwargs)
+                v.setup(request, *url_args, **url_kwargs)
+                response = v.get_response()
+                span.set_status(
+                    trace.StatusCode.OK
+                    if response.status_code < 400
+                    else trace.StatusCode.ERROR
+                )
+                return response
 
         view.view_class = cls
 

{plain-0.52.2 → plain-0.54.0}/pyproject.toml

@@ -1,12 +1,14 @@
 [project]
 name = "plain"
-version = "0.52.2"
+version = "0.54.0"
 description = "A web framework for building products with Python."
 authors = [{name = "Dave Gaeddert", email = "dave.gaeddert@dropseed.dev"}]
 readme = "README.md"
 dependencies = [
     "jinja2>=3.1.2",
     "click>=8.0.0",
+    "opentelemetry-api>=1.34.1",
+    "opentelemetry-semantic-conventions>=0.55b1",
 ]
 requires-python = ">=3.11"
 

plain-0.54.0/tests/.gitignore

@@ -0,0 +1 @@
+.plain

plain-0.52.2/plain/http/cookie.py

@@ -1,20 +0,0 @@
-from http import cookies
-
-
-def parse_cookie(cookie):
-    """
-    Return a dictionary parsed from a `Cookie:` header string.
-    """
-    cookiedict = {}
-    for chunk in cookie.split(";"):
-        if "=" in chunk:
-            key, val = chunk.split("=", 1)
-        else:
-            # Assume an empty name per
-            # https://bugzilla.mozilla.org/show_bug.cgi?id=169091
-            key, val = "", chunk
-        key, val = key.strip(), val.strip()
-        if key or val:
-            # unquote using Python's algorithm.
-            cookiedict[key] = cookies._unquote(val)
-    return cookiedict

plain-0.52.2/plain/templates/core.py

@@ -1,24 +0,0 @@
-import jinja2
-
-from .jinja import environment
-
-
-class TemplateFileMissing(Exception):
-    def __str__(self) -> str:
-        if self.args:
-            return f"Template file {self.args[0]} not found"
-        else:
-            return "Template file not found"
-
-
-class Template:
-    def __init__(self, filename: str) -> None:
-        self.filename = filename
-
-        try:
-            self._jinja_template = environment.get_template(filename)
-        except jinja2.TemplateNotFound:
-            raise TemplateFileMissing(filename)
-
-    def render(self, context: dict) -> str:
-        return self._jinja_template.render(context)

plain-0.52.2/tests/.gitignore

@@ -1,3 +0,0 @@
-/.coverage
-/htmlcov
-.plain