plain 0.52.1__py3-none-any.whl → 0.53.0__py3-none-any.whl

plain/CHANGELOG.md

@@ -1,5 +1,28 @@
 # plain changelog
 
+## [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
+
+- Improved documentation for the assets subsystem: the `AssetsRouter` reference in the Assets README now links directly to the source code for quicker navigation ([65437e9](https://github.com/dropseed/plain/commit/65437e9bb1a522c7ababe0fc195f63bc5fd6c4d4))
+
+### Upgrade instructions
+
+- No changes required
+
 ## [0.52.1](https://github.com/dropseed/plain/releases/plain@0.52.1) (2025-06-27)
 
 ### What's changed

plain/assets/README.md

@@ -6,7 +6,7 @@
 
 To serve assets, put them in `app/assets` or `app/{package}/assets`.
 
-Then include the `AssetsRouter` in your own router, typically under the `assets/` path.
+Then include the [`AssetsRouter`](./urls.py#AssetsRouter) in your own router, typically under the `assets/` path.
 
 ```python
 # app/urls.py
@@ -40,7 +40,7 @@ In production, one of your deployment steps should be to compile the assets.
 plain build
 ```
 
-By default, this [generates "fingerprinted" and compressed versions of the assets](fingerprints.py#get_file_fingerprint), which are then served by your app. This means that a file like `main.css` will result in two new files, like `main.d0db67b.css` and `main.d0db67b.css.gz`.
+By default, this [generates "fingerprinted" and compressed versions of the assets](./fingerprints.py#get_file_fingerprint), which are then served by your app. This means that a file like `main.css` will result in two new files, like `main.d0db67b.css` and `main.d0db67b.css.gz`.
 
 The purpose of fingerprinting the assets is to allow the browser to cache them indefinitely. When the content of the file changes, the fingerprint will change, and the browser will use the newer file. This cuts down on the number of requests that your app has to handle related to assets.
 
@@ -64,6 +64,8 @@ class AppRouter(Router):
 
 ### How do you reference assets in Python code?
 
+There is a [`get_asset_url`](./urls.py#get_asset_url) function that you can use to get the URL of an asset in Python code. This is useful if you need to reference an asset in a non-template context, such as in a redirect or an API response.
+
 ```python
 from plain.assets.urls import get_asset_url
 
@@ -94,7 +96,7 @@ ls .plain/assets/compiled
 ./example-upload-to-cdn-script
 ```
 
-Use the `ASSETS_BASE_URL` setting to tell the `{{ asset() }}` template function where to point.
+Use the [`ASSETS_BASE_URL`](../runtime/global_settings.py#ASSETS_BASE_URL) setting to tell the `{{ asset() }}` template function where to point.
 
 ```python
 # app/settings.py
@@ -107,4 +109,4 @@ The default behavior is to fingerprint assets, which is an exact copy of the ori
 
 If you need the originals for any reason, you can use `plain build --keep-original`, though this will typically be combined with `--no-fingerprint` otherwise the fingerprinted files will still get priority in `{{ asset() }}` template calls.
 
-Note that by default, the `ASSETS_REDIRECT_ORIGINAL` setting is `True`, which will redirect requests for the original file to the fingerprinted file.
+Note that by default, the [`ASSETS_REDIRECT_ORIGINAL`](../runtime/global_settings.py#ASSETS_REDIRECT_ORIGINAL) setting is `True`, which will redirect requests for the original file to the fingerprinted file.

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/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/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/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/http/cookie.py

@@ -1,5 +1,9 @@
 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):
     """
@@ -18,3 +22,43 @@ def parse_cookie(cookie):
             # 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/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/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/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.1.dist-info → plain-0.53.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plain
-Version: 0.52.1
+Version: 0.53.0
 Summary: A web framework for building products with Python.
 Author-email: Dave Gaeddert <dave.gaeddert@dropseed.dev>
 License-File: LICENSE

{plain-0.52.1.dist-info → plain-0.53.0.dist-info}/RECORD

@@ -1,4 +1,4 @@
-plain/CHANGELOG.md,sha256=TdNwYCrcE4iKZQLbI89NSKnEz_eH_251d8E2eNpHXzI,3322
+plain/CHANGELOG.md,sha256=DHF0llr5trZE_8C0138MnuFQEAM9W2jM9nL0xfjjz8Y,4472
 plain/README.md,sha256=gik6DBZcJAITcm4WRq_L53AxkjY45eQLafyTCSf0CKE,3986
 plain/__main__.py,sha256=GK39854Lc_LO_JP8DzY9Y2MIQ4cQEl7SXFJy244-lC8,110
 plain/debug.py,sha256=XdjnXcbPGsi0J2SpHGaLthhYU5AjhBlkHdemaP4sbYY,758
@@ -8,7 +8,7 @@ plain/paginator.py,sha256=iXiOyt2r_YwNrkqCRlaU7V-M_BKaaQ8XZElUBVa6yeU,5844
 plain/signing.py,sha256=r2KvCOxkrSWCULFxYa9BHYx3L3a2oLq8RDnq_92inTw,8207
 plain/validators.py,sha256=TePzFHzwR4JXUAZ_Y2vC6mkKgVxHX3QBXI6Oex0rV8c,19236
 plain/wsgi.py,sha256=R6k5FiAElvGDApEbMPTT0MPqSD7n2e2Az5chQqJZU0I,236
-plain/assets/README.md,sha256=wgsmBK5vAHgFMZ010q7LTrgLq5BTfuPuuug5HLZ9GNw,3774
+plain/assets/README.md,sha256=8OW6y4rs0PqGvcbrndPJjOndcDUQUAgnO-Hj_PDHpWI,4151
 plain/assets/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 plain/assets/compile.py,sha256=DT85ygnNcY2_7VeozdsQlBvA-DzV7enUIMO_igJ1PjY,3296
 plain/assets/finders.py,sha256=2k8QZAbfUbc1LykxbzdazTSB6xNxJZnsZaGhWbSFZZs,1452
@@ -20,22 +20,22 @@ plain/chores/__init__.py,sha256=r9TXtQCH-VbvfnIJ5F8FxgQC35GRWFOfmMZN3q9niLg,67
 plain/chores/registry.py,sha256=V3WjuekRI22LFvJbqSkUXQtiOtuE2ZK8gKV1TRvxRUI,1866
 plain/cli/README.md,sha256=GzBry6mEilhM80SfVUg02ydGwAk0m-s6FAqQR1nRsMM,2022
 plain/cli/__init__.py,sha256=6w9T7K2WrPwh6DcaMb2oNt_CWU6Bc57nUTO2Bt1p38Y,63
-plain/cli/build.py,sha256=dKUYBNegvb6QNckR7XZ7CJJtINwZcmDvbUdv2dWwjf8,3226
+plain/cli/build.py,sha256=Lo6AYghJz0DM9fIVUSiBSOKa5vR0XCOxZWEjza6sc8Q,3172
 plain/cli/changelog.py,sha256=j-k1yZk9mpm-fLZgeWastiyIisxNSuAJfXTQ2B6WQmk,3457
 plain/cli/chores.py,sha256=xXSSFvr8T5jWfLWqe6E8YVMw1BkQxyOHHVuY0x9RH0A,2412
 plain/cli/core.py,sha256=D3t83ujjjHayblM-RuttrGoNf8hMV9-l3zQsbhVAjWU,2991
-plain/cli/docs.py,sha256=KCJCP_OVFb34zOkA6x7X6-iGFzx2tv4ZgXAM99TjWNg,7443
+plain/cli/docs.py,sha256=5-2_nQnInZAzHu3VnMW88gZyrhukhdjrkMKTMt0RRpI,7367
 plain/cli/formatting.py,sha256=1hZH13y1qwHcU2K2_Na388nw9uvoeQH8LrWL-O9h8Yc,2207
 plain/cli/help.py,sha256=NefZSEIixrX_WELVSnJDHRpLDWf7_4PXmkkMm3Q2mzo,787
 plain/cli/output.py,sha256=Fe3xS6Va4Bi1ZNrqi0nh09THTsdCyMW2b9SPY5I4n-o,1318
-plain/cli/preflight.py,sha256=FWFwMZ0W_t8ObTTRMnBmaiGN8PqdEAWgmSEPGDwZFpA,4148
+plain/cli/preflight.py,sha256=8tHBD4L4nPLUKThfaYx3SUZSJzC48oV2m_Hbn6W4ODc,4124
 plain/cli/print.py,sha256=XraUYrgODOJquIiEv78wSCYGRBplHXtXSS9QtFG5hqY,217
 plain/cli/registry.py,sha256=yKVMSDjW8g10nlV9sPXFGJQmhC_U-k4J4kM7N2OQVLA,1467
 plain/cli/scaffold.py,sha256=mcywA9DzfwoBSqWl5-Zpgcy1mTNUGEgdvoxXUrGcEVk,1351
 plain/cli/settings.py,sha256=9cx4bue664I2P7kUedlf4YhCPB0tSKSE4Q8mGyzEv2o,1995
 plain/cli/shell.py,sha256=iIwvlTdTBjLBBUdXMAmIRWSoynszOZI79-mrBg4RegU,1373
 plain/cli/startup.py,sha256=wLaFuyUb4ewWhtehBCGicrRCXIIGCRbeCT3ce9hUv-A,1022
-plain/cli/urls.py,sha256=7FOvLjfV1GsYKnb7SGlIgEfchQcrkWdYU1nY6aazGBI,3855
+plain/cli/urls.py,sha256=ghCW36aRszxmTo06A50FIvYopb6kQ07QekkDzM6_A1o,3824
 plain/cli/utils.py,sha256=VwlIh0z7XxzVV8I3qM2kZo07fkJFPoeeVZa1ODG616k,258
 plain/csrf/README.md,sha256=nxCpPk1HF5eAM-7paxg9D-9RVCU9jXsSPAVHkJvA_DU,717
 plain/csrf/middleware.py,sha256=U3B9R7ciO_UAf7O3jdNtVu6QZ_3Yrm8isRdnW6bVKX4,17401
@@ -48,10 +48,10 @@ plain/forms/fields.py,sha256=OyL4eZIgJ_XMLPHGar17hLepFmwHV-hSnb_n7s18yUU,34709
 plain/forms/forms.py,sha256=hF7Dl8rEaiBTZhFQyfbh1Zf54BSEka8RYpBiGqkTa8I,10441
 plain/http/README.md,sha256=F9wbahgSU3jIDEG14gJjdPJRem4weUNvwnwhb7o3cu0,722
 plain/http/__init__.py,sha256=DIsDRbBsCGa4qZgq-fUuQS0kkxfbTU_3KpIM9VvH04w,1067
-plain/http/cookie.py,sha256=11FnSG3Plo6T3jZDbPoCw7SKh9ExdBio3pTmIO03URg,597
+plain/http/cookie.py,sha256=THd7nOl-2ugeBPKgOhbD87aM2oxUbNH8HWrarUn0fpM,1955
 plain/http/multipartparser.py,sha256=Z1dFJNAd8N5RHUuF67jh1jBfZOFepORsre_3ee6CgOQ,27266
-plain/http/request.py,sha256=DbnC_E-PeiLM9pVJdcO869BtAU2gniLflMnPAOrrKU8,25618
-plain/http/response.py,sha256=WvVxQgQMq9X8YRBa9_neowfP3mx3TzN90SShSulfFQo,23970
+plain/http/request.py,sha256=93b2gqkfEsBczUyP_9vlueVoxyzzfbnJ423PDAk8aHc,26103
+plain/http/response.py,sha256=0xUhkTiT6JwohdwA7ymY2vpdCQVl4hnEExjk01LrJbg,23734
 plain/internal/__init__.py,sha256=fVBaYLCXEQc-7riHMSlw3vMTTuF7-0Bj2I8aGzv0o0w,171
 plain/internal/files/__init__.py,sha256=VctFgox4Q1AWF3klPaoCC5GIw5KeLafYjY5JmN8mAVw,63
 plain/internal/files/base.py,sha256=2z19tik2_xgXlI6nfVZ4woSF9WB0RSUzsvOfi1Bz8Wg,4113
@@ -100,7 +100,7 @@ plain/templates/core.py,sha256=iw58EAmyyv8N5HDA-Sq4-fLgz_qx8v8WJfurgR116jw,625
 plain/templates/jinja/__init__.py,sha256=xvYif0feMYR9pWjN0czthq2dk3qI4D5UQjgj9yp4dNA,2776
 plain/templates/jinja/environments.py,sha256=9plifzvQj--aTN1cCpJ2WdzQxZJpzB8S_4hghgQRQT0,2064
 plain/templates/jinja/extensions.py,sha256=AEmmmHDbdRW8fhjYDzq9eSSNbp9WHsXenD8tPthjc0s,1351
-plain/templates/jinja/filters.py,sha256=t_u8BkWtEpJFLbLywONxWKrenSzOvDJhfOLwlZiXHDU,968
+plain/templates/jinja/filters.py,sha256=ft5XUr4OLeQayn-MSxrycpFLyyN_yEo7j5WhWMwpTOs,1445
 plain/templates/jinja/globals.py,sha256=VMpuMZvwWOmb5MbzKK-ox-QEX_WSsXFxq0mm8biJgaU,558
 plain/test/README.md,sha256=fv4YzziU2QxgcNHSgv7aDUO45sDOofVuCNrV1NPbWzo,1106
 plain/test/__init__.py,sha256=MhNHtp7MYBl9kq-pMRGY11kJ6kU1I6vOkjNkit1TYRg,94
@@ -149,8 +149,8 @@ plain/views/forms.py,sha256=ESZOXuo6IeYixp1RZvPb94KplkowRiwO2eGJCM6zJI0,2400
 plain/views/objects.py,sha256=GGbcfg_9fPZ-PiaBwIHG2e__8GfWDR7JQtQ15wTyiHg,5970
 plain/views/redirect.py,sha256=daq2cQIkdDF78bt43sjuZxRAyJm_t_SKw6tyPmiXPIc,1985
 plain/views/templates.py,sha256=ivkI7LU7BXDQ0d4Geab96Is4-Cp03KbIntXRT1J8e6I,2139
-plain-0.52.1.dist-info/METADATA,sha256=iB2DW8m-StzH4FmWqnnbiiid1CpUVzr82YovQNFdD5Y,4297
-plain-0.52.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-plain-0.52.1.dist-info/entry_points.txt,sha256=nn4uKTRRZuEKOJv3810s3jtSMW0Gew7XDYiKIvBRR6M,93
-plain-0.52.1.dist-info/licenses/LICENSE,sha256=m0D5O7QoH9l5Vz_rrX_9r-C8d9UNr_ciK6Qwac7o6yo,3175
-plain-0.52.1.dist-info/RECORD,,
+plain-0.53.0.dist-info/METADATA,sha256=n3gNCFOwyioHwL_hKBiAmIGxSQG6CBM-XjM-x5EMq5I,4297
+plain-0.53.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+plain-0.53.0.dist-info/entry_points.txt,sha256=nn4uKTRRZuEKOJv3810s3jtSMW0Gew7XDYiKIvBRR6M,93
+plain-0.53.0.dist-info/licenses/LICENSE,sha256=m0D5O7QoH9l5Vz_rrX_9r-C8d9UNr_ciK6Qwac7o6yo,3175
+plain-0.53.0.dist-info/RECORD,,