plain 0.75.0__py3-none-any.whl → 0.77.0__py3-none-any.whl

plain/CHANGELOG.md

@@ -1,5 +1,37 @@
 # plain changelog
 
+## [0.77.0](https://github.com/dropseed/plain/releases/plain@0.77.0) (2025-10-13)
+
+### What's changed
+
+- The `plain server --reload` now uses `watchfiles` for improved cross-platform file watching ([92e95c5032](https://github.com/dropseed/plain/commit/92e95c5032))
+- Server reloader now watches `.env*` files for changes and triggers automatic reload ([92e95c5032](https://github.com/dropseed/plain/commit/92e95c5032))
+- HTML template additions and deletions now trigger automatic server reload when using `--reload` ([f2f31c288b](https://github.com/dropseed/plain/commit/f2f31c288b))
+- Internal server worker type renamed from "gthread" to "thread" for clarity ([6470748e91](https://github.com/dropseed/plain/commit/6470748e91))
+
+### Upgrade instructions
+
+- No changes required
+
+## [0.76.0](https://github.com/dropseed/plain/releases/plain@0.76.0) (2025-10-12)
+
+### What's changed
+
+- Added new `plain server` command with built-in WSGI server (vendored gunicorn) ([f9dc2867c7](https://github.com/dropseed/plain/commit/f9dc2867c7))
+- The `plain server` command supports `WEB_CONCURRENCY` environment variable for worker processes ([0c3e8c6f32](https://github.com/dropseed/plain/commit/0c3e8c6f32))
+- Simplified server startup logging to use a single consolidated log line ([b1405b71f0](https://github.com/dropseed/plain/commit/b1405b71f0))
+- Removed `gunicorn` as an external dependency - server functionality is now built into plain core ([cb6c2f484d](https://github.com/dropseed/plain/commit/cb6c2f484d))
+- Internal server environment variables renamed from `GUNICORN_*` to `PLAIN_SERVER_*` ([745c073123](https://github.com/dropseed/plain/commit/745c073123))
+- Removed unused server features including hooks, syslog, proxy protocol, user/group dropping, and config file loading ([be0f82d92b](https://github.com/dropseed/plain/commit/be0f82d92b), [10c206875b](https://github.com/dropseed/plain/commit/10c206875b), [ecf327014c](https://github.com/dropseed/plain/commit/ecf327014c), [fb5a10f50b](https://github.com/dropseed/plain/commit/fb5a10f50b))
+
+### Upgrade instructions
+
+- Replace any direct usage of `gunicorn` with the new `plain server` command (ex. `gunicorn plain.wsgi:app --workers 4` becomes `plain server --workers 4`)
+- Update any deployment scripts or Procfiles that use `gunicorn` to use `plain server` instead
+- Remove `gunicorn` from your project dependencies if you added it separately (it's now built into plain)
+- For Heroku deployments, the `$PORT` is not automatically detected - update your Procfile to `web: plain server --bind 0.0.0.0:$PORT`
+- If you were using gunicorn configuration files, migrate the settings to `plain server` command-line options (run `plain server --help` to see available options)
+
 ## [0.75.0](https://github.com/dropseed/plain/releases/plain@0.75.0) (2025-10-10)
 
 ### What's changed

plain/cli/core.py

@@ -19,6 +19,7 @@ from .install import install
 from .preflight import preflight_cli
 from .registry import cli_registry
 from .scaffold import create
+from .server import server
 from .settings import setting
 from .shell import run, shell
 from .upgrade import upgrade
@@ -45,6 +46,7 @@ plain_cli.add_command(shell)
 plain_cli.add_command(run)
 plain_cli.add_command(install)
 plain_cli.add_command(upgrade)
+plain_cli.add_command(server)
 
 
 class CLIRegistryGroup(click.Group):
@@ -68,26 +70,33 @@ class PlainCommandCollection(click.CommandCollection):
     context_class = PlainContext
 
     def __init__(self, *args: Any, **kwargs: Any):
-        sources = []
+        # Start with only built-in commands (no setup needed)
+        sources = [plain_cli]
+
+        super().__init__(*args, **kwargs)
+        self.sources = sources
+        self._registry_group = None
+        self._setup_attempted = False
+
+    def _ensure_registry_loaded(self) -> None:
+        """Lazy load the registry group (requires setup)."""
+        if self._registry_group is not None or self._setup_attempted:
+            return
+
+        self._setup_attempted = True
 
         try:
             plain.runtime.setup()
-
-            sources = [
-                CLIRegistryGroup(),
-                plain_cli,
-            ]
+            self._registry_group = CLIRegistryGroup()
+            # Add registry group to sources
+            self.sources.insert(0, self._registry_group)
         except plain.runtime.AppPathNotFound:
-            # Allow some commands to work regardless of being in a valid app
+            # Allow built-in 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(
@@ -95,7 +104,6 @@ class PlainCommandCollection(click.CommandCollection):
                 fg="red",
                 err=True,
             )
-
             exit(1)
         except Exception as e:
             # Show the exception and exit
@@ -108,19 +116,29 @@ class PlainCommandCollection(click.CommandCollection):
                 fg="red",
                 err=True,
             )
-
             exit(1)
 
-        super().__init__(*args, **kwargs)
-
-        self.sources = sources
-
     def get_command(self, ctx: Context, cmd_name: str) -> Command | None:
+        # Try built-in commands first
         cmd = super().get_command(ctx, cmd_name)
+
+        if cmd is None:
+            # Command not found in built-ins, try registry (requires setup)
+            self._ensure_registry_loaded()
+            cmd = super().get_command(ctx, cmd_name)
+        elif not getattr(cmd, "without_runtime_setup", False):
+            # Command found but needs setup - ensure registry is loaded
+            self._ensure_registry_loaded()
+
         if cmd:
             # Pass the formatting down to subcommands automatically
             cmd.context_class = self.context_class
         return cmd
 
+    def list_commands(self, ctx: Context) -> list[str]:
+        # For help listing, we need to show registry commands too
+        self._ensure_registry_loaded()
+        return super().list_commands(ctx)
+
 
 cli = PlainCommandCollection()

plain/cli/runtime.py

@@ -0,0 +1,28 @@
+"""
+CLI runtime utilities.
+
+This module provides decorators and utilities for CLI commands.
+"""
+
+from collections.abc import Callable
+from typing import TypeVar
+
+F = TypeVar("F", bound=Callable)
+
+
+def without_runtime_setup(f: F) -> F:
+    """
+    Decorator to mark commands that don't need plain.runtime.setup().
+
+    Use this for commands that don't access settings or app code,
+    particularly for commands that fork (like server) where setup()
+    should happen in the worker process, not the parent.
+
+    Example:
+        @without_runtime_setup
+        @click.command()
+        def server(**options):
+            ...
+    """
+    f.without_runtime_setup = True  # type: ignore[attr-defined]  # dynamic attribute for decorator
+    return f

plain/cli/server.py

@@ -0,0 +1,135 @@
+import click
+
+from plain.cli.runtime import without_runtime_setup
+
+
+@without_runtime_setup
+@click.command()
+@click.option(
+    "--bind",
+    "-b",
+    multiple=True,
+    default=["127.0.0.1:8000"],
+    help="Address to bind to (HOST:PORT, can be used multiple times)",
+)
+@click.option(
+    "--threads",
+    type=int,
+    default=1,
+    help="Number of threads per worker",
+    show_default=True,
+)
+@click.option(
+    "--workers",
+    "-w",
+    type=int,
+    default=1,
+    envvar="WEB_CONCURRENCY",
+    help="Number of worker processes",
+    show_default=True,
+)
+@click.option(
+    "--timeout",
+    "-t",
+    type=int,
+    default=30,
+    help="Worker timeout in seconds",
+    show_default=True,
+)
+@click.option(
+    "--certfile",
+    type=click.Path(exists=True),
+    help="SSL certificate file",
+)
+@click.option(
+    "--keyfile",
+    type=click.Path(exists=True),
+    help="SSL key file",
+)
+@click.option(
+    "--log-level",
+    default="info",
+    type=click.Choice(["debug", "info", "warning", "error", "critical"]),
+    help="Logging level",
+    show_default=True,
+)
+@click.option(
+    "--reload",
+    is_flag=True,
+    help="Restart workers when code changes (dev only)",
+)
+@click.option(
+    "--access-log",
+    default="-",
+    help="Access log file (use '-' for stdout)",
+    show_default=True,
+)
+@click.option(
+    "--error-log",
+    default="-",
+    help="Error log file (use '-' for stderr)",
+    show_default=True,
+)
+@click.option(
+    "--log-format",
+    default="%(asctime)s [%(process)d] [%(levelname)s] %(message)s",
+    help="Log format string (applies to both error and access logs)",
+    show_default=True,
+)
+@click.option(
+    "--access-log-format",
+    help="Access log format string (HTTP request details)",
+    default='%(h)s %(l)s %(u)s %(t)s "%(r)s" %(s)s %(b)s "%(f)s" "%(a)s"',
+    show_default=True,
+)
+@click.option(
+    "--max-requests",
+    type=int,
+    default=0,
+    help="Max requests before worker restart (0=disabled)",
+    show_default=True,
+)
+@click.option(
+    "--pidfile",
+    type=click.Path(),
+    help="PID file path",
+)
+def server(
+    bind: tuple[str, ...],
+    threads: int,
+    workers: int,
+    timeout: int,
+    certfile: str | None,
+    keyfile: str | None,
+    log_level: str,
+    reload: bool,
+    access_log: str,
+    error_log: str,
+    log_format: str,
+    access_log_format: str,
+    max_requests: int,
+    pidfile: str | None,
+) -> None:
+    """
+    Run a production-ready WSGI server.
+    """
+    from plain.server import ServerApplication
+    from plain.server.config import Config
+
+    cfg = Config(
+        bind=list(bind),
+        threads=threads,
+        workers=workers,
+        timeout=timeout,
+        max_requests=max_requests,
+        reload=reload,
+        pidfile=pidfile,
+        certfile=certfile,
+        keyfile=keyfile,
+        loglevel=log_level,
+        accesslog=access_log,
+        errorlog=error_log,
+        log_format=log_format,
+        access_log_format=access_log_format,
+    )
+    ServerApplication(cfg=cfg).run()

plain/internal/reloader.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+import os
+import os.path
+import re
+import sys
+import threading
+from collections.abc import Callable
+
+import watchfiles
+
+COMPILED_EXT_RE = re.compile(r"py[co]$")
+
+
+class Reloader(threading.Thread):
+    """File change reloader using watchfiles for cross-platform native file watching."""
+
+    def __init__(self, callback: Callable[[str], None], watch_html: bool) -> None:
+        super().__init__()
+        self.daemon = True
+        self._callback = callback
+        self._watch_html = watch_html
+
+    def get_watch_paths(self) -> set[str]:
+        """Get all directories to watch for changes."""
+        paths = set()
+
+        # Get directories from loaded Python modules
+        for module in tuple(sys.modules.values()):
+            if not hasattr(module, "__file__") or not module.__file__:
+                continue
+            # Convert .pyc/.pyo to .py and get directory
+            file_path = COMPILED_EXT_RE.sub("py", module.__file__)
+            dir_path = os.path.dirname(os.path.abspath(file_path))
+            if os.path.isdir(dir_path):
+                paths.add(dir_path)
+
+        # Add current working directory for .env files
+        cwd = os.getcwd()
+        if os.path.isdir(cwd):
+            paths.add(cwd)
+
+        return paths
+
+    def run(self) -> None:
+        """Watch for file changes and trigger callback."""
+        watch_paths = self.get_watch_paths()
+
+        for changes in watchfiles.watch(*watch_paths, rust_timeout=1000):
+            for change_type, file_path in changes:
+                should_reload = False
+                filename = os.path.basename(file_path)
+
+                # Python files: reload on modify/add
+                if change_type in (watchfiles.Change.modified, watchfiles.Change.added):
+                    if file_path.endswith(".py"):
+                        should_reload = True
+
+                # .env files: reload on modify/add/delete
+                if change_type in (
+                    watchfiles.Change.modified,
+                    watchfiles.Change.added,
+                    watchfiles.Change.deleted,
+                ):
+                    if filename.startswith(".env"):
+                        should_reload = True
+
+                # HTML files: only reload on add/delete (Jinja auto-reloads modifications)
+                if self._watch_html and change_type in (
+                    watchfiles.Change.added,
+                    watchfiles.Change.deleted,
+                ):
+                    if file_path.endswith(".html"):
+                        should_reload = True
+
+                if should_reload:
+                    self._callback(file_path)

plain/server/LICENSE

@@ -0,0 +1,35 @@
+Plain HTTP Server - License and Attribution
+============================================
+
+This module is based on gunicorn (https://gunicorn.org), integrated from
+commit 1dc4ce9d59c3458305d701c4c6d63aa6b1d1b309 (gunicorn 23.0.0, October 2024).
+
+The gunicorn code has been integrated into Plain and modified for Plain's
+specific use case. All files should be considered modified from the original.
+
+Original repository: https://github.com/benoitc/gunicorn
+
+--------------------------------------------------------------------------------
+
+MIT License
+
+Copyright (c) 2009-2024 Benoît Chesneau <benoitc@gunicorn.org>
+Copyright (c) 2009-2015 Paul J. Davis <paul.joseph.davis@gmail.com>
+
+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.

plain/server/README.md

@@ -0,0 +1,74 @@
+# plain.server
+
+**Plain's internal HTTP server based on vendored gunicorn.**
+
+## Overview
+
+This module provides a WSGI HTTP server for Plain applications. It is based on [gunicorn](https://gunicorn.org), which has been vendored into Plain's core to provide better integration and control over the HTTP server layer.
+
+The server is designed to work seamlessly with Plain's development workflow while still maintaining WSGI compatibility, allowing you to eject to any alternative WSGI server if needed.
+
+## Usage
+
+### Command Line
+
+The simplest way to run the server is using the `plain server` command:
+
+```bash
+# Run with defaults (127.0.0.1:8000)
+plain server
+
+# Specify host and port
+plain server --bind 0.0.0.0:8080
+
+# Run with SSL
+plain server --certfile cert.pem --keyfile key.pem
+
+# Enable auto-reload for development
+plain server --reload
+
+# Use multiple threads
+plain server --threads 8
+```
+
+## Configuration Options
+
+Common options:
+
+- `--bind` / `-b` - Address to bind to (default: `127.0.0.1:8000`)
+- `--workers` / `-w` - Number of worker processes (default: 1, or `$WEB_CONCURRENCY` env var)
+- `--threads` - Number of threads per worker (default: 1)
+- `--timeout` / `-t` - Worker timeout in seconds (default: 30)
+- `--reload` - Enable auto-reload on code changes, including `.env*` files (default: False)
+- `--certfile` - Path to SSL certificate file
+- `--keyfile` - Path to SSL key file
+- `--log-level` - Logging level: debug, info, warning, error, critical (default: info)
+- `--access-log` - Access log file path (default: `-` for stdout)
+- `--error-log` - Error log file path (default: `-` for stderr)
+- `--log-format` - Log format string for error logs
+- `--access-log-format` - Access log format string for HTTP request details
+- `--max-requests` - Max requests before worker restart (default: 0, disabled)
+- `--pidfile` - PID file path
+
+### Environment Variables
+
+- `WEB_CONCURRENCY` - Sets the number of worker processes (commonly used by Heroku and other PaaS providers)
+- `SENDFILE` - Enable/disable use of sendfile() syscall (set to `1`, `yes`, `true`, or `y` to enable)
+- `FORWARDED_ALLOW_IPS` - Comma-separated list of trusted proxy IPs for secure headers (default: `127.0.0.1,::1`)
+
+For a complete list of options, run `plain server --help`.
+
+## WSGI Ejection Point
+
+While Plain includes this built-in server, you can still use any WSGI-compatible server you prefer. Plain's `wsgi.py` module provides a standard WSGI application interface:
+
+```bash
+# Using uvicorn
+uvicorn plain.wsgi:app --port 8000
+
+# Using waitress
+waitress-serve --port=8000 plain.wsgi:app
+
+# Using gunicorn as an alternative
+gunicorn plain.wsgi:app --workers 4
+```

plain/server/__init__.py

@@ -0,0 +1,9 @@
+#
+# This file is part of gunicorn released under the MIT license.
+# See the LICENSE for more information.
+#
+# Vendored and modified for Plain.
+
+from .app import ServerApplication
+
+__all__ = ["ServerApplication"]

plain/server/app.py

@@ -0,0 +1,52 @@
+#
+#
+# This file is part of gunicorn released under the MIT license.
+# See the LICENSE for more information.
+#
+# Vendored and modified for Plain.
+
+from __future__ import annotations
+
+import sys
+from typing import TYPE_CHECKING, Any
+
+from .arbiter import Arbiter
+
+if TYPE_CHECKING:
+    from .config import Config
+
+
+class ServerApplication:
+    """
+    Plain's server application.
+
+    This class provides the interface for running the WSGI server.
+    """
+
+    def __init__(self, cfg: Config) -> None:
+        self.cfg: Config = cfg
+        self.callable: Any = None
+
+    def load(self) -> Any:
+        """Load the WSGI application."""
+        # Import locally to avoid circular dependencies and allow
+        # the WSGI module to handle Plain runtime setup
+        from plain.wsgi import app
+
+        return app
+
+    def wsgi(self) -> Any:
+        """Get the WSGI application."""
+        if self.callable is None:
+            self.callable = self.load()
+        return self.callable
+
+    def run(self) -> None:
+        """Run the server."""
+
+        try:
+            Arbiter(self).run()
+        except RuntimeError as e:
+            print(f"\nError: {e}\n", file=sys.stderr)
+            sys.stderr.flush()
+            sys.exit(1)