plain 0.69.0__py3-none-any.whl → 0.70.0__py3-none-any.whl

plain/AGENTS.md

@@ -10,7 +10,7 @@ The `plain` CLI is the main entrypoint for the framework. If `plain` is not avai
 - `plain run <filename>`: Run a Python script with Plain configured.
 - `plain agent docs <package>`: Show README.md and symbolicated source files for a specific package.
 - `plain agent docs --list`: List packages with docs available.
-- `plain agent request <path> --user <user_id>`: Make an authenticated request to the application and inspect the output.
+- `plain agent request <path> --user <user_id>`: Make an authenticated request to the running application and inspect the output.
 - `plain --help`: List all available commands (including those from installed packages).
 
 ## Code style

plain/CHANGELOG.md

@@ -1,5 +1,16 @@
 # plain changelog
 
+## [0.70.0](https://github.com/dropseed/plain/releases/plain@0.70.0) (2025-09-30)
+
+### What's changed
+
+- Added comprehensive type annotations throughout the codebase for improved IDE support and type checking ([365414c](https://github.com/dropseed/plain/commit/365414cc6f))
+- The `Asset` class in `plain.assets.finders` is now a module-level public class instead of being defined inside `iter_assets()` ([6321765](https://github.com/dropseed/plain/commit/6321765d30))
+
+### Upgrade instructions
+
+- No changes required
+
 ## [0.69.0](https://github.com/dropseed/plain/releases/plain@0.69.0) (2025-09-29)
 
 ### What's changed

plain/assets/compile.py

@@ -1,10 +1,14 @@
+from __future__ import annotations
+
 import gzip
 import os
 import shutil
+from collections.abc import Iterator
+from pathlib import Path
 
 from plain.runtime import PLAIN_TEMP_PATH
 
-from .finders import iter_assets
+from .finders import Asset, iter_assets
 from .fingerprints import AssetsFingerprintsManifest, get_file_fingerprint
 
 SKIP_COMPRESS_EXTENSIONS = (
@@ -40,7 +44,7 @@ SKIP_COMPRESS_EXTENSIONS = (
 )
 
 
-def get_compiled_path():
+def get_compiled_path() -> Path:
     """
     Get the path at runtime to the compiled assets directory.
 
@@ -49,7 +53,9 @@ def get_compiled_path():
     return PLAIN_TEMP_PATH / "assets" / "compiled"
 
 
-def compile_assets(*, target_dir, keep_original, fingerprint, compress):
+def compile_assets(
+    *, target_dir: str, keep_original: bool, fingerprint: bool, compress: bool
+) -> Iterator[tuple[str, str, list[str]]]:
     """
     Compile all assets to the target directory and save a JSON manifest
     mapping the original filenames to the compiled filenames.
@@ -73,17 +79,24 @@ def compile_assets(*, target_dir, keep_original, fingerprint, compress):
     manifest.save()
 
 
-def compile_asset(*, asset, target_dir, keep_original, fingerprint, compress):
+def compile_asset(
+    *,
+    asset: Asset,
+    target_dir: str,
+    keep_original: bool,
+    fingerprint: bool,
+    compress: bool,
+) -> tuple[str, list[str]]:
     """
     Compile an asset to multiple output paths.
     """
-    compiled_paths = []
+    compiled_paths: list[str] = []
 
     # The expected destination for the original asset
     target_path = os.path.join(target_dir, asset.url_path)
 
     # Keep track of where the final, resolved asset ends up
-    resolved_url_path = asset.url_path
+    resolved_url_path: str = asset.url_path
 
     # Make sure all the expected directories exist
     os.makedirs(os.path.dirname(target_path), exist_ok=True)
@@ -106,7 +119,7 @@ def compile_asset(*, asset, target_dir, keep_original, fingerprint, compress):
         shutil.copy(asset.absolute_path, fingerprinted_path)
         compiled_paths.append(fingerprinted_path)
 
-        resolved_url_path = os.path.relpath(fingerprinted_path, target_dir)
+        resolved_url_path = str(os.path.relpath(fingerprinted_path, target_dir))
 
     if compress and extension.lower() not in SKIP_COMPRESS_EXTENSIONS:
         for path in compiled_paths.copy():

plain/assets/finders.py

@@ -1,4 +1,7 @@
+from __future__ import annotations
+
 import os
+from collections.abc import Iterator
 
 from plain.packages import packages_registry
 from plain.runtime import APP_PATH
@@ -8,21 +11,22 @@ APP_ASSETS_DIR = APP_PATH / "assets"
 SKIP_ASSETS = (".DS_Store", ".gitignore")
 
 
-def iter_assets():
+class Asset:
+    def __init__(self, *, url_path: str, absolute_path: str):
+        self.url_path = url_path
+        self.absolute_path = absolute_path
+
+    def __str__(self) -> str:
+        return self.url_path
+
+
+def iter_assets() -> Iterator[Asset]:
     """
     Iterate all valid asset files found in the installed
     packages and the app itself.
     """
 
-    class Asset:
-        def __init__(self, *, url_path, absolute_path):
-            self.url_path = url_path
-            self.absolute_path = absolute_path
-
-        def __str__(self):
-            return self.url_path
-
-    def _iter_assets_dir(path):
+    def _iter_assets_dir(path: str) -> Iterator[tuple[str, str]]:
         for root, _, files in os.walk(path):
             for f in files:
                 if f in SKIP_ASSETS:
@@ -36,7 +40,7 @@ def iter_assets():
             yield Asset(url_path=url_path, absolute_path=abs_path)
 
 
-def iter_asset_dirs():
+def iter_asset_dirs() -> Iterator[str]:
     """
     Iterate all directories containing assets, from installed
     packages and from app/assets.

plain/assets/fingerprints.py

@@ -15,18 +15,18 @@ class AssetsFingerprintsManifest(dict):
     def __init__(self):
         self.path = PLAIN_TEMP_PATH / "assets" / "fingerprints.json"
 
-    def load(self):
+    def load(self) -> None:
         if self.path.exists():
             with open(self.path) as f:
                 self.update(json.load(f))
 
-    def save(self):
+    def save(self) -> None:
         with open(self.path, "w") as f:
             json.dump(self, f, indent=2)
 
 
 @cache
-def _get_manifest():
+def _get_manifest() -> AssetsFingerprintsManifest:
     """
     A cached function for loading the asset fingerprints manifest,
     so we don't have to keep loading it from disk over and over.
@@ -36,16 +36,17 @@ def _get_manifest():
     return manifest
 
 
-def get_fingerprinted_url_path(url_path):
+def get_fingerprinted_url_path(url_path: str) -> str | None:
     """
     Get the final fingerprinted path for an asset URL path.
     """
     manifest = _get_manifest()
     if url_path in manifest:
         return manifest[url_path]
+    return None
 
 
-def get_file_fingerprint(file_path):
+def get_file_fingerprint(file_path: str) -> str:
     """
     Get the fingerprint hash for a file.
     """

plain/assets/urls.py

@@ -18,7 +18,7 @@ class AssetsRouter(Router):
     ]
 
 
-def get_asset_url(url_path):
+def get_asset_url(url_path: str) -> str:
     """
     Get the full URL to a given asset path.
     """

plain/assets/views.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import functools
 import mimetypes
 import os
@@ -28,14 +30,14 @@ class AssetView(View):
     This class could be subclassed to further tweak the responses or behavior.
     """
 
-    def __init__(self, asset_path=None):
+    def __init__(self, asset_path: str | None = None):
         # Allow a path to be passed in AssetView.as_view(path="...")
         self.asset_path = asset_path
 
-    def get_url_path(self):
+    def get_url_path(self) -> str:
         return self.asset_path or self.url_kwargs["path"]
 
-    def get(self):
+    def get(self) -> Response | FileResponse:
         url_path = self.get_url_path()
 
         # Make a trailing slash work, but we don't expect it
@@ -71,7 +73,7 @@ class AssetView(View):
         response.headers = self.update_headers(response.headers, absolute_path)
         return response
 
-    def get_asset_path(self, path):
+    def get_asset_path(self, path: str) -> str:
         """Get the path to the compiled asset"""
         compiled_path = os.path.abspath(get_compiled_path())
         asset_path = os.path.join(compiled_path, path)
@@ -82,13 +84,14 @@ class AssetView(View):
 
         return asset_path
 
-    def get_debug_asset_path(self, path):
+    def get_debug_asset_path(self, path: str) -> str | None:
         """Make a "live" check to find the uncompiled asset in the filesystem"""
         for asset in iter_assets():
             if asset.url_path == path:
                 return asset.absolute_path
+        return None
 
-    def check_asset_path(self, path):
+    def check_asset_path(self, path: str | None) -> None:
         if not path:
             raise Http404("Asset not found")
 
@@ -99,7 +102,7 @@ class AssetView(View):
             raise Http404("Asset is a directory")
 
     @functools.cache
-    def get_last_modified(self, path):
+    def get_last_modified(self, path: str) -> str | None:
         try:
             mtime = os.path.getmtime(path)
         except OSError:
@@ -107,9 +110,10 @@ class AssetView(View):
 
         if mtime:
             return formatdate(mtime, usegmt=True)
+        return None
 
     @functools.cache
-    def get_etag(self, path):
+    def get_etag(self, path: str) -> str:
         try:
             mtime = os.path.getmtime(path)
         except OSError:
@@ -120,10 +124,10 @@ class AssetView(View):
         return f'"{timestamp:x}-{size:x}"'
 
     @functools.cache
-    def get_size(self, path):
+    def get_size(self, path: str) -> int:
         return os.path.getsize(path)
 
-    def update_headers(self, headers, path):
+    def update_headers(self, headers: dict, path: str) -> dict:
         headers.setdefault("Access-Control-Allow-Origin", "*")
 
         # Always vary on Accept-Encoding
@@ -165,7 +169,7 @@ class AssetView(View):
 
         return headers
 
-    def is_immutable(self, path):
+    def is_immutable(self, path: str) -> bool:
         """
         Determine whether an asset looks like it is immutable.
 
@@ -182,14 +186,14 @@ class AssetView(View):
 
         return False
 
-    def get_encoded_path(self, path):
+    def get_encoded_path(self, path: str) -> str | None:
         """
         If the client supports compression, return the path to the compressed file.
         Otherwise, return the original path.
         """
         accept_encoding = self.request.headers.get("Accept-Encoding")
         if not accept_encoding:
-            return
+            return None
 
         if "br" in accept_encoding:
             br_path = path + ".br"
@@ -200,15 +204,16 @@ class AssetView(View):
             gzip_path = path + ".gz"
             if os.path.exists(gzip_path):
                 return gzip_path
+        return None
 
-    def get_redirect_response(self, path):
+    def get_redirect_response(self, path: str) -> ResponseRedirect | None:
         """If the asset is not found, try to redirect to the fingerprinted path"""
         fingerprinted_url_path = get_fingerprinted_url_path(path)
 
         if not fingerprinted_url_path or fingerprinted_url_path == path:
             # Don't need to redirect if there is no fingerprinted path,
             # or we're already looking at it.
-            return
+            return None
 
         from .urls import AssetsRouter
 
@@ -221,7 +226,7 @@ class AssetView(View):
             },
         )
 
-    def get_conditional_response(self, path):
+    def get_conditional_response(self, path: str) -> ResponseNotModified | None:
         """
         Support conditional requests (HTTP 304 response) based on ETag and Last-Modified headers.
         """
@@ -241,8 +246,9 @@ class AssetView(View):
                 response = ResponseNotModified()
                 response.headers = self.update_headers(response.headers, path)
                 return response
+        return None
 
-    def get_range_response(self, path):
+    def get_range_response(self, path: str) -> Response | StreamingResponse | None:
         """
         Support range requests (HTTP 206 response).
         """

plain/chores/registry.py

@@ -1,17 +1,22 @@
+from __future__ import annotations
+
+from types import FunctionType
+from typing import Any
+
 from plain.packages import packages_registry
 
 
 class Chore:
-    def __init__(self, *, group, func):
+    def __init__(self, *, group: str, func: FunctionType):
         self.group = group
         self.func = func
         self.name = f"{group}.{func.__name__}"
         self.description = func.__doc__.strip() if func.__doc__ else ""
 
-    def __str__(self):
+    def __str__(self) -> str:
         return self.name
 
-    def run(self):
+    def run(self) -> Any:
         """
         Run the chore.
         """
@@ -20,21 +25,21 @@ class Chore:
 
 class ChoresRegistry:
     def __init__(self):
-        self._chores = {}
+        self._chores: dict[FunctionType, Chore] = {}
 
-    def register_chore(self, chore):
+    def register_chore(self, chore: Chore) -> None:
         """
         Register a chore with the specified name.
         """
         self._chores[chore.func] = chore
 
-    def import_modules(self):
+    def import_modules(self) -> None:
         """
         Import modules from installed packages and app to trigger registration.
         """
         packages_registry.autodiscover_modules("chores", include_app=True)
 
-    def get_chores(self):
+    def get_chores(self) -> list[Chore]:
         """
         Get all registered chores.
         """
@@ -44,7 +49,7 @@ class ChoresRegistry:
 chores_registry = ChoresRegistry()
 
 
-def register_chore(group):
+def register_chore(group: str) -> Any:
     """
     Register a chore with a given group.
 
@@ -54,7 +59,7 @@ def register_chore(group):
             pass
     """
 
-    def wrapper(func):
+    def wrapper(func: FunctionType) -> FunctionType:
         chore = Chore(group=group, func=func)
         chores_registry.register_chore(chore)
         return func

plain/cli/agent/__init__.py

@@ -7,7 +7,7 @@ from .request import request
 
 @click.group("agent", invoke_without_command=True)
 @click.pass_context
-def agent(ctx):
+def agent(ctx: click.Context) -> None:
     """Tools for coding agents."""
     if ctx.invoked_subcommand is None:
         # If no subcommand provided, show all AGENTS.md files

plain/cli/agent/docs.py

@@ -15,7 +15,7 @@ from .llmdocs import LLMDocs
     is_flag=True,
     help="List available packages",
 )
-def docs(package, show_list):
+def docs(package: str, show_list: bool) -> None:
     """Show LLM-friendly documentation and source for a package."""
 
     if show_list:
@@ -33,11 +33,12 @@ def docs(package, show_list):
                     available_packages.append("plain")
 
                 # Check other plain.* subpackages
-                for importer, modname, ispkg in pkgutil.iter_modules(
-                    plain.__path__, "plain."
-                ):
-                    if ispkg:
-                        available_packages.append(modname)
+                if hasattr(plain, "__path__"):
+                    for importer, modname, ispkg in pkgutil.iter_modules(
+                        plain.__path__, "plain."
+                    ):
+                        if ispkg:
+                            available_packages.append(modname)
             except Exception:
                 pass
 

plain/cli/agent/llmdocs.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import ast
 from pathlib import Path
 
@@ -7,10 +9,10 @@ import click
 class LLMDocs:
     """Generates LLM-friendly documentation."""
 
-    def __init__(self, paths):
+    def __init__(self, paths: list[Path]):
         self.paths = paths
 
-    def load(self):
+    def load(self) -> None:
         self.docs = set()
         self.sources = set()
 
@@ -47,7 +49,7 @@ class LLMDocs:
         self.docs = sorted(self.docs)
         self.sources = sorted(self.sources)
 
-    def display_path(self, path):
+    def display_path(self, path: Path) -> Path:
         if "plain" in path.parts:
             root_index = path.parts.index("plain")
         elif "plainx" in path.parts:
@@ -58,7 +60,7 @@ class LLMDocs:
         plain_root = Path(*path.parts[: root_index + 1])
         return path.relative_to(plain_root.parent)
 
-    def print(self, relative_to=None):
+    def print(self, relative_to: Path | None = None) -> None:
         for doc in self.docs:
             if relative_to:
                 display_path = doc.relative_to(relative_to)
@@ -81,7 +83,7 @@ class LLMDocs:
                 click.echo()
 
     @staticmethod
-    def symbolicate(file_path: Path):
+    def symbolicate(file_path: Path) -> str:
         if "internal" in str(file_path).split("/"):
             return ""
 
@@ -89,8 +91,16 @@ class LLMDocs:
 
         parsed = ast.parse(source)
 
-        def should_skip(node):
-            if isinstance(node, ast.ClassDef | ast.FunctionDef):
+        def should_skip(node: ast.AST) -> bool:
+            if isinstance(node, ast.ClassDef):
+                if any(
+                    isinstance(d, ast.Name) and d.id == "internalcode"
+                    for d in node.decorator_list
+                ):
+                    return True
+                if node.name.startswith("_"):
+                    return True
+            elif isinstance(node, ast.FunctionDef):
                 if any(
                     isinstance(d, ast.Name) and d.id == "internalcode"
                     for d in node.decorator_list
@@ -104,7 +114,7 @@ class LLMDocs:
                         return True
             return False
 
-        def process_node(node, indent=0):
+        def process_node(node: ast.AST, indent: int = 0) -> list[str]:
             lines = []
             prefix = "    " * indent
 

plain/cli/agent/md.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import importlib.util
 import pkgutil
 from pathlib import Path
@@ -7,7 +9,7 @@ import click
 from ..output import iterate_markdown
 
 
-def _get_packages_with_agents():
+def _get_packages_with_agents() -> dict[str, Path]:
     """Get dict mapping package names to AGENTS.md paths."""
     agents_files = {}
 
@@ -25,18 +27,21 @@ def _get_packages_with_agents():
                 agents_files["plain"] = agents_path
 
         # Check other plain.* subpackages
-        for importer, modname, ispkg in pkgutil.iter_modules(plain.__path__, "plain."):
-            if ispkg:
-                try:
-                    spec = importlib.util.find_spec(modname)
-                    if spec and spec.origin:
-                        package_path = Path(spec.origin).parent
-                        # Look for AGENTS.md at package root
-                        agents_path = package_path / "AGENTS.md"
-                        if agents_path.exists():
-                            agents_files[modname] = agents_path
-                except Exception:
-                    continue
+        if hasattr(plain, "__path__"):
+            for importer, modname, ispkg in pkgutil.iter_modules(
+                plain.__path__, "plain."
+            ):
+                if ispkg:
+                    try:
+                        spec = importlib.util.find_spec(modname)
+                        if spec and spec.origin:
+                            package_path = Path(spec.origin).parent
+                            # Look for AGENTS.md at package root
+                            agents_path = package_path / "AGENTS.md"
+                            if agents_path.exists():
+                                agents_files[modname] = agents_path
+                    except Exception:
+                        continue
     except Exception:
         pass
 
@@ -57,7 +62,7 @@ def _get_packages_with_agents():
     is_flag=True,
     help="List packages with AGENTS.md files",
 )
-def md(package, show_all, show_list):
+def md(package: str, show_all: bool, show_list: bool) -> None:
     """Show AGENTS.md for a package."""
 
     agents_files = _get_packages_with_agents()

plain/cli/agent/prompt.py

@@ -5,7 +5,7 @@ import subprocess
 import click
 
 
-def is_agent_environment():
+def is_agent_environment() -> bool:
     """Check if we're running inside a coding agent."""
     return bool(
         os.environ.get("CLAUDECODE")