plain 0.35.0__tar.gz → 0.37.0__tar.gz

plain-0.37.0/PKG-INFO

@@ -0,0 +1,77 @@
+Metadata-Version: 2.4
+Name: plain
+Version: 0.37.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
+Description-Content-Type: text/markdown
+
+# Plain
+
+**Plain is a web framework for building products with Python.**
+
+The core `plain` package provides the backbone of a Python web application (similar to [Flask](https://flask.palletsprojects.com/en/stable/)), while the additional first-party packages can power a more fully-featured database-backed app (similar to [Django](https://www.djangoproject.com/)).
+
+All Plain packages are designed to work together and use [PEP 420](https://peps.python.org/pep-0420/) to share the `plain` namespace.
+
+To quickly get started with Plain, visit [plainframework.com/start/](https://plainframework.com/start/).
+
+## Core Modules
+
+The `plain` package includes everything you need to start handling web requests with Python:
+
+- [assets](./assets/README.md) - Serve static files and assets.
+- [cli](./cli/README.md) - The `plain` CLI, powered by Click.
+- [csrf](./csrf/README.md) - Cross-Site Request Forgery protection.
+- [forms](./forms/README.md) - HTML forms and form validation.
+- [http](./http/README.md) - HTTP request and response handling.
+- [logs](./logs/README.md) - Logging configuration and utilities.
+- [preflight](./preflight/README.md) - Preflight checks for your app.
+- [runtime](./runtime/README.md) - Runtime settings and configuration.
+- [templates](./templates/README.md) - Jinja2 templates and rendering.
+- [test](./test/README.md) - Test utilities and fixtures.
+- [urls](./urls/README.md) - URL routing and request dispatching.
+- [views](./views/README.md) - Class-based views and request handlers.
+
+## Foundational Packages
+
+- [plain.models](/plain-models/plain/models/README.md) - Define and interact with your database models.
+- [plain.cache](/plain-cache/plain/cache/README.md) - A database-driven general purpose cache.
+- [plain.email](/plain-email/plain/email/README.md) - Send emails with SMTP or custom backends.
+- [plain.sessions](/plain-sessions/plain/sessions/README.md) - User sessions and cookies.
+- [plain.worker](/plain-worker/plain/worker/README.md) - Backgrounb jobs stored in the database.
+- [plain.api](/plain-api/plain/api/README.md) - Build APIs with Plain views.
+
+## Auth Packages
+
+- [plain.auth](/plain-auth/plain/auth/README.md) - User authentication and authorization.
+- [plain.oauth](/plain-oauth/plain/oauth/README.md) - OAuth authentication and API access.
+- [plain.passwords](/plain-passwords/plain/passwords/README.md) - Password-based login and registration.
+- [plain.loginlink](/plain-loginlink/plain/loginlink/README.md) - Login links for passwordless authentication.
+
+## Admin Packages
+
+- [plain.admin](/plain-admin/plain/admin/README.md) - An admin interface for back-office tasks.
+- [plain.flags](/plain-flags/plain/flags/README.md) - Feature flags.
+- [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.
+
+## Dev Packages
+
+- [plain.dev](/plain-dev/plain/dev/README.md) - A single command for local development.
+- [plain.pytest](/plain-pytest/plain/pytest/README.md) - Pytest fixtures and helpers.
+- [plain.code](/plain-code/plain/code/README.md) - Code formatting and linting.
+- [plain.tunnel](/plain-tunnel/plain/tunnel/README.md) - Expose your local server to the internet.
+
+## Frontend Packages
+
+- [plain.tailwind](/plain-tailwind/plain/tailwind/README.md) - Tailwind CSS integration without Node.js.
+- [plain.htmx](/plain-htmx/plain/htmx/README.md) - HTMX integrated into views and templates.
+- [plain.elements](/plain-elements/plain/elements/README.md) - Server-side HTML components.
+- [plain.pages](/plain-pages/plain/pages/README.md) - Static pages with Markdown and Jinja2.
+- [plain.esbuild](/plain-esbuild/plain/esbuild/README.md) - Simple JavaScript bundling and minification.
+- [plain.vendor](/plain-vendor/plain/vendor/README.md) - Vendor JavaScript and CSS libraries.

plain-0.37.0/plain/README.md

@@ -0,0 +1,66 @@
+# Plain
+
+**Plain is a web framework for building products with Python.**
+
+The core `plain` package provides the backbone of a Python web application (similar to [Flask](https://flask.palletsprojects.com/en/stable/)), while the additional first-party packages can power a more fully-featured database-backed app (similar to [Django](https://www.djangoproject.com/)).
+
+All Plain packages are designed to work together and use [PEP 420](https://peps.python.org/pep-0420/) to share the `plain` namespace.
+
+To quickly get started with Plain, visit [plainframework.com/start/](https://plainframework.com/start/).
+
+## Core Modules
+
+The `plain` package includes everything you need to start handling web requests with Python:
+
+- [assets](./assets/README.md) - Serve static files and assets.
+- [cli](./cli/README.md) - The `plain` CLI, powered by Click.
+- [csrf](./csrf/README.md) - Cross-Site Request Forgery protection.
+- [forms](./forms/README.md) - HTML forms and form validation.
+- [http](./http/README.md) - HTTP request and response handling.
+- [logs](./logs/README.md) - Logging configuration and utilities.
+- [preflight](./preflight/README.md) - Preflight checks for your app.
+- [runtime](./runtime/README.md) - Runtime settings and configuration.
+- [templates](./templates/README.md) - Jinja2 templates and rendering.
+- [test](./test/README.md) - Test utilities and fixtures.
+- [urls](./urls/README.md) - URL routing and request dispatching.
+- [views](./views/README.md) - Class-based views and request handlers.
+
+## Foundational Packages
+
+- [plain.models](/plain-models/plain/models/README.md) - Define and interact with your database models.
+- [plain.cache](/plain-cache/plain/cache/README.md) - A database-driven general purpose cache.
+- [plain.email](/plain-email/plain/email/README.md) - Send emails with SMTP or custom backends.
+- [plain.sessions](/plain-sessions/plain/sessions/README.md) - User sessions and cookies.
+- [plain.worker](/plain-worker/plain/worker/README.md) - Backgrounb jobs stored in the database.
+- [plain.api](/plain-api/plain/api/README.md) - Build APIs with Plain views.
+
+## Auth Packages
+
+- [plain.auth](/plain-auth/plain/auth/README.md) - User authentication and authorization.
+- [plain.oauth](/plain-oauth/plain/oauth/README.md) - OAuth authentication and API access.
+- [plain.passwords](/plain-passwords/plain/passwords/README.md) - Password-based login and registration.
+- [plain.loginlink](/plain-loginlink/plain/loginlink/README.md) - Login links for passwordless authentication.
+
+## Admin Packages
+
+- [plain.admin](/plain-admin/plain/admin/README.md) - An admin interface for back-office tasks.
+- [plain.flags](/plain-flags/plain/flags/README.md) - Feature flags.
+- [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.
+
+## Dev Packages
+
+- [plain.dev](/plain-dev/plain/dev/README.md) - A single command for local development.
+- [plain.pytest](/plain-pytest/plain/pytest/README.md) - Pytest fixtures and helpers.
+- [plain.code](/plain-code/plain/code/README.md) - Code formatting and linting.
+- [plain.tunnel](/plain-tunnel/plain/tunnel/README.md) - Expose your local server to the internet.
+
+## Frontend Packages
+
+- [plain.tailwind](/plain-tailwind/plain/tailwind/README.md) - Tailwind CSS integration without Node.js.
+- [plain.htmx](/plain-htmx/plain/htmx/README.md) - HTMX integrated into views and templates.
+- [plain.elements](/plain-elements/plain/elements/README.md) - Server-side HTML components.
+- [plain.pages](/plain-pages/plain/pages/README.md) - Static pages with Markdown and Jinja2.
+- [plain.esbuild](/plain-esbuild/plain/esbuild/README.md) - Simple JavaScript bundling and minification.
+- [plain.vendor](/plain-vendor/plain/vendor/README.md) - Vendor JavaScript and CSS libraries.

{plain-0.35.0 → plain-0.37.0}/plain/assets/views.py

@@ -254,7 +254,7 @@ class AssetView(View):
 
         if not range_header.startswith("bytes="):
             return Response(
-                status=416, headers=[("Content-Range", f"bytes */{file_size}")]
+                status_code=416, headers=[("Content-Range", f"bytes */{file_size}")]
             )
 
         range_values = range_header.split("=")[1].split("-")
@@ -263,7 +263,7 @@ class AssetView(View):
 
         if start >= file_size:
             return Response(
-                status=416, headers=[("Content-Range", f"bytes */{file_size}")]
+                status_code=416, headers=[("Content-Range", f"bytes */{file_size}")]
             )
 
         end = min(end, file_size - 1)
@@ -272,7 +272,7 @@ class AssetView(View):
             f.seek(start)
             content = f.read(end - start + 1)
 
-        response = StreamingResponse(BytesIO(content), status=206)
+        response = StreamingResponse(BytesIO(content), status_code=206)
         response.headers = self.update_headers(response.headers, path)
         response.headers["Content-Range"] = f"bytes {start}-{end}/{file_size}"
         response.headers["Content-Length"] = str(end - start + 1)

plain-0.37.0/plain/cli/build.py

@@ -0,0 +1,107 @@
+import shutil
+import subprocess
+import sys
+import tomllib
+from importlib.metadata import entry_points
+from pathlib import Path
+
+import click
+
+import plain.runtime
+from plain.assets.compile import compile_assets, get_compiled_path
+
+
+@click.command()
+@click.option(
+    "--keep-original/--no-keep-original",
+    "keep_original",
+    is_flag=True,
+    default=False,
+    help="Keep the original assets",
+)
+@click.option(
+    "--fingerprint/--no-fingerprint",
+    "fingerprint",
+    is_flag=True,
+    default=True,
+    help="Fingerprint the assets",
+)
+@click.option(
+    "--compress/--no-compress",
+    "compress",
+    is_flag=True,
+    default=True,
+    help="Compress the assets",
+)
+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,
+        )
+        sys.exit(1)
+
+    # Run user-defined build commands first
+    pyproject_path = plain.runtime.APP_PATH.parent / "pyproject.toml"
+    if pyproject_path.exists():
+        with pyproject_path.open("rb") as f:
+            pyproject = tomllib.load(f)
+
+        for name, data in (
+            pyproject.get("tool", {})
+            .get("plain", {})
+            .get("build", {})
+            .get("run", {})
+            .items()
+        ):
+            click.secho(f"Running {name} from pyproject.toml", bold=True)
+            result = subprocess.run(data["cmd"], shell=True)
+            print()
+            if result.returncode:
+                click.secho(f"Error in {name} (exit {result.returncode})", fg="red")
+                sys.exit(result.returncode)
+
+    # Then run installed package build steps (like tailwind, typically should run last...)
+    for entry_point in entry_points(group="plain.build"):
+        click.secho(f"Running {entry_point.name}", bold=True)
+        result = entry_point.load()()
+        print()
+
+    # Compile our assets
+    target_dir = get_compiled_path()
+    click.secho(f"Compiling assets to {target_dir}", bold=True)
+    if target_dir.exists():
+        click.secho("(clearing previously compiled assets)")
+        shutil.rmtree(target_dir)
+    target_dir.mkdir(parents=True, exist_ok=True)
+
+    total_files = 0
+    total_compiled = 0
+
+    for url_path, resolved_url_path, compiled_paths in compile_assets(
+        target_dir=target_dir,
+        keep_original=keep_original,
+        fingerprint=fingerprint,
+        compress=compress,
+    ):
+        if url_path == resolved_url_path:
+            click.secho(url_path, bold=True)
+        else:
+            click.secho(url_path, bold=True, nl=False)
+            click.secho(" → ", fg="yellow", nl=False)
+            click.echo(resolved_url_path)
+
+        print("\n".join(f"  {Path(p).relative_to(Path.cwd())}" for p in compiled_paths))
+
+        total_files += 1
+        total_compiled += len(compiled_paths)
+
+    click.secho(
+        f"\nCompiled {total_files} assets into {total_compiled} files", fg="green"
+    )
+
+    # TODO could do a jinja pre-compile here too?
+    # environment.compile_templates() but it needs a target, ignore_errors=False

plain-0.37.0/plain/cli/core.py

@@ -0,0 +1,113 @@
+import traceback
+
+import click
+from click.core import Command, Context
+
+import plain.runtime
+from plain.exceptions import ImproperlyConfigured
+
+from .build import build
+from .docs import docs
+from .formatting import PlainContext
+from .preflight import preflight_checks
+from .registry import cli_registry
+from .scaffold import create
+from .settings import setting
+from .shell import run, shell
+from .urls import urls
+from .utils import utils
+
+
+@click.group()
+def plain_cli():
+    pass
+
+
+plain_cli.add_command(docs)
+plain_cli.add_command(preflight_checks)
+plain_cli.add_command(create)
+plain_cli.add_command(build)
+plain_cli.add_command(utils)
+plain_cli.add_command(urls)
+plain_cli.add_command(setting)
+plain_cli.add_command(shell)
+plain_cli.add_command(run)
+
+
+class CLIRegistryGroup(click.Group):
+    """
+    Click Group that exposes commands from the CLI registry.
+    """
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        cli_registry.import_modules()
+
+    def list_commands(self, ctx):
+        return sorted(cli_registry.get_commands().keys())
+
+    def get_command(self, ctx, name):
+        commands = cli_registry.get_commands()
+        return commands.get(name)
+
+
+class PlainCommandCollection(click.CommandCollection):
+    context_class = PlainContext
+
+    def __init__(self, *args, **kwargs):
+        sources = []
+
+        try:
+            plain.runtime.setup()
+
+            sources = [
+                CLIRegistryGroup(),
+                plain_cli,
+            ]
+        except plain.runtime.AppPathNotFound:
+            # Allow some commands to work regardless of being in a valid app
+            click.secho(
+                "Plain `app` directory not found. Some commands may be missing.",
+                fg="yellow",
+                err=True,
+            )
+
+            sources = [
+                plain_cli,
+            ]
+        except ImproperlyConfigured as e:
+            # Show what was configured incorrectly and exit
+            click.secho(
+                str(e),
+                fg="red",
+                err=True,
+            )
+
+            exit(1)
+        except Exception as e:
+            # Show the exception and exit
+            print("---")
+            print(traceback.format_exc())
+            print("---")
+
+            click.secho(
+                f"Error: {e}",
+                fg="red",
+                err=True,
+            )
+
+            exit(1)
+
+        super().__init__(*args, **kwargs)
+
+        self.sources = sources
+
+    def get_command(self, ctx: Context, cmd_name: str) -> Command | None:
+        cmd = super().get_command(ctx, cmd_name)
+        if cmd:
+            # Pass the formatting down to subcommands automatically
+            cmd.context_class = self.context_class
+        return cmd
+
+
+cli = PlainCommandCollection()

plain-0.37.0/plain/cli/docs.py

@@ -0,0 +1,211 @@
+import ast
+import importlib.util
+import sys
+from pathlib import Path
+
+import click
+
+from plain.packages import packages_registry
+
+
+def symbolicate(file_path: Path):
+    if "internal" in str(file_path).split("/"):
+        return ""
+
+    source = file_path.read_text()
+
+    parsed = ast.parse(source)
+
+    def should_skip(node):
+        if isinstance(node, ast.ClassDef | ast.FunctionDef):
+            if any(
+                isinstance(d, ast.Name) and d.id == "internalcode"
+                for d in node.decorator_list
+            ):
+                return True
+            if node.name.startswith("_"):  # and not node.name.endswith("__"):
+                return True
+        elif isinstance(node, ast.Assign):
+            for target in node.targets:
+                if (
+                    isinstance(target, ast.Name) and target.id.startswith("_")
+                    # and not target.id.endswith("__")
+                ):
+                    return True
+        return False
+
+    def process_node(node, indent=0):
+        lines = []
+        prefix = "    " * indent
+
+        if should_skip(node):
+            return []
+
+        if isinstance(node, ast.ClassDef):
+            decorators = [
+                f"{prefix}@{ast.unparse(d)}"
+                for d in node.decorator_list
+                if not (isinstance(d, ast.Name) and d.id == "internal")
+            ]
+            lines.extend(decorators)
+            bases = [ast.unparse(base) for base in node.bases]
+            lines.append(f"{prefix}class {node.name}({', '.join(bases)})")
+            # if ast.get_docstring(node):
+            #     lines.append(f'{prefix}    """{ast.get_docstring(node)}"""')
+            for child in node.body:
+                child_lines = process_node(child, indent + 1)
+                if child_lines:
+                    lines.extend(child_lines)
+            # if not has_body:
+            #     lines.append(f"{prefix}    pass")
+
+        elif isinstance(node, ast.FunctionDef):
+            decorators = [f"{prefix}@{ast.unparse(d)}" for d in node.decorator_list]
+            lines.extend(decorators)
+            args = ast.unparse(node.args)
+            lines.append(f"{prefix}def {node.name}({args})")
+            # if ast.get_docstring(node):
+            #     lines.append(f'{prefix}    """{ast.get_docstring(node)}"""')
+            # lines.append(f"{prefix}    pass")
+
+        elif isinstance(node, ast.Assign):
+            for target in node.targets:
+                if isinstance(target, ast.Name):
+                    lines.append(f"{prefix}{target.id} = {ast.unparse(node.value)}")
+
+        return lines
+
+    symbolicated_lines = []
+    for node in parsed.body:
+        symbolicated_lines.extend(process_node(node))
+
+    return "\n".join(symbolicated_lines)
+
+
+@click.command()
+@click.option("--llm", "llm", is_flag=True)
+@click.option("--open")
+@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)
+
+    if llm:
+        click.echo(
+            "Below is all of the documentation and abbreviated source code for the Plain web framework. "
+            "Your job is to read and understand it, and then act as the Plain Framework Assistant and "
+            "help the developer accomplish whatever they want to do next."
+            "\n\n---\n\n"
+        )
+
+        docs = set()
+        sources = set()
+
+        # Get everything for Plain core
+        for path in Path(__file__).parent.parent.glob("**/*.md"):
+            docs.add(path)
+        for source in Path(__file__).parent.parent.glob("**/*.py"):
+            sources.add(source)
+
+        # Find every *.md file in the other plain packages and installed apps
+        for package_config in packages_registry.get_package_configs():
+            if package_config.name.startswith("app."):
+                # Ignore app packages for now
+                continue
+
+            for path in Path(package_config.path).glob("**/*.md"):
+                docs.add(path)
+
+            for source in Path(package_config.path).glob("**/*.py"):
+                sources.add(source)
+
+        docs = sorted(docs)
+        sources = sorted(sources)
+
+        for doc in docs:
+            try:
+                display_path = doc.relative_to(Path.cwd())
+            except ValueError:
+                display_path = doc.absolute()
+            click.secho(f"<Docs: {display_path}>", fg="yellow")
+            click.echo(doc.read_text())
+            click.secho(f"</Docs: {display_path}>", fg="yellow")
+            click.echo()
+
+        for source in sources:
+            if symbolicated := symbolicate(source):
+                try:
+                    display_path = source.relative_to(Path.cwd())
+                except ValueError:
+                    display_path = source.absolute()
+                click.secho(f"<Source: {display_path}>", fg="yellow")
+                click.echo(symbolicated)
+                click.secho(f"</Source: {display_path}>", fg="yellow")
+                click.echo()
+
+        click.secho(
+            "That's everything! Copy this into your AI tool of choice.",
+            err=True,
+            fg="green",
+        )
+
+        return
+
+    if module:
+        # Automatically prefix if we need to
+        if not module.startswith("plain"):
+            module = f"plain.{module}"
+
+        # 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)
+
+        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)
+
+        if open:
+            click.launch(str(readme_path))
+        else:
+
+            def _iterate_markdown(content):
+                """
+                Iterator that does basic markdown for a Click pager.
+
+                Headings are yellow and bright, code blocks are indented.
+                """
+
+                in_code_block = False
+                for line in content.splitlines():
+                    if line.startswith("```"):
+                        in_code_block = not in_code_block
+
+                    if in_code_block:
+                        yield click.style(line, dim=True)
+                    elif line.startswith("# "):
+                        yield click.style(line, fg="yellow", bold=True)
+                    elif line.startswith("## "):
+                        yield click.style(line, fg="yellow", bold=True)
+                    elif line.startswith("### "):
+                        yield click.style(line, fg="yellow", bold=True)
+                    elif line.startswith("#### "):
+                        yield click.style(line, fg="yellow", bold=True)
+                    elif line.startswith("##### "):
+                        yield click.style(line, fg="yellow", bold=True)
+                    elif line.startswith("###### "):
+                        yield click.style(line, fg="yellow", bold=True)
+                    elif line.startswith("**") and line.endswith("**"):
+                        yield click.style(line, bold=True)
+                    elif line.startswith("> "):
+                        yield click.style(line, italic=True)
+                    else:
+                        yield line
+
+                    yield "\n"
+
+            click.echo_via_pager(_iterate_markdown(readme_path.read_text()))