plain.dev 0.1.0__py3-none-any.whl

plain/dev/README.md

@@ -0,0 +1,96 @@
+# plain.dev
+
+A single command that runs everything you need for local development.
+
+![Plain dev command example](https://github.com/dropseed/plain/assets/649496/3643bb64-a99b-4a8e-adab-8c6b81791ea9)
+
+The `plain.dev` package can be [installed from PyPI](https://pypi.org/project/plain.dev/), and does *not* need to be added to `INSTALLED_PACKAGES`.
+
+- [`plain dev`](#plain-dev)
+- [`plain dev services`](#plain-dev-services)
+- [`plain pre-commit`](#plain-pre-commit)
+- [`plain contrib`](#plain-contrib)
+- [VS Code debugging](#vscode-debugging)
+
+## `plain dev`
+
+The `plain dev` command does several things:
+
+- Sets `PLAIN_CSRF_TRUSTED_ORIGINS` to localhost by default
+- Runs `plain preflight` to check for any issues
+- Executes any pending model migrations
+- Starts `gunicorn` with `--reload`
+- Runs `plain tailwind compile --watch`, if `plain.tailwind` is installed
+- Any custom process defined in `pyproject.toml` at `tool.plain.dev.run`
+- Necessary services (ex. Postgres) defined in `pyproject.toml` at `tool.plain.dev.services`
+
+### Services
+
+Use services to define databases or other processes that your app *needs* to be functional. The services will be started automatically in `plain dev`, but also in `plain pre-commit` (so preflight and tests have a database).
+
+Ultimately, how you run your development database is up to you. But a recommended starting point is to use Docker:
+
+```toml
+# pyproject.toml
+[tool.plain.dev.services]
+postgres = {cmd = "docker run --name app-postgres --rm -p 54321:5432 -v $(pwd)/.plain/dev/pgdata:/var/lib/postgresql/data -e POSTGRES_PASSWORD=postgres postgres:15 postgres"}
+```
+
+### Custom processes
+
+Unlike [services](#services), custom processes are *only* run during `plain dev`. This is a good place to run something like [ngrok](https://ngrok.com/) or a [Plain worker](../../../plain-worker), which you might need to use your local site, but don't need running for executing tests, for example.
+
+```toml
+# pyproject.toml
+[tool.plain.dev.run]
+ngrok = {command = "ngrok http $PORT"}
+```
+
+## `plain dev services`
+
+Starts your [services](#services) by themselves.
+
+## `plain pre-commit`
+
+A built-in pre-commit hook that can be installed with `plain pre-commit --install`.
+
+Runs:
+
+- Custom commands defined in `pyproject.toml` at `tool.plain.pre-commit.run`
+- `plain code check`, if [`plain.code`](https://plainframework.com/docs/plain-code/plain/code/) is installed
+- `poetry lock --check`, if using [Poetry](https://python-poetry.org/)
+- `plain preflight --database default`
+- `plain legacy migrate --check`
+- `plain legacy makemigrations --dry-run --check`
+- `plain compile`
+- `plain test`
+
+## VS Code debugging
+
+![Debug Plain with VS Code](https://github.com/dropseed/plain-public/assets/649496/250138b6-7702-4ab6-bf38-e0c8e3c56d06)
+
+Since `plain dev` runs multiple processes at once, the regular [pdb](https://docs.python.org/3/library/pdb.html) debuggers don't quite work.
+
+Instead, we include [microsoft/debugpy](https://github.com/microsoft/debugpy) and an `attach` function to make it even easier to use VS Code's debugger.
+
+First, import and run the `debug.attach()` function:
+
+```python
+class HomeView(TemplateView):
+    template_name = "home.html"
+
+    def get_template_context(self):
+        context = super().get_template_context()
+
+        # Make sure the debugger is attached (will need to be if runserver reloads)
+        from plain.dev import debug; debug.attach()
+
+        # Add a breakpoint (or use the gutter in VS Code to add one)
+        breakpoint()
+
+        return context
+```
+
+When you load the page, you'll see "Waiting for debugger to attach...".
+
+You can then run the VS Code debugger and attach to an existing Python process, at localhost:5678.

plain/dev/__init__.py

@@ -0,0 +1,5 @@
+from .cli import cli
+from .debug import attach
+from .requests import RequestsMiddleware
+
+__all__ = ["cli", "RequestsMiddleware", "attach"]

plain/dev/cli.py

@@ -0,0 +1,166 @@
+import json
+import os
+import subprocess
+import sys
+from importlib.util import find_spec
+from pathlib import Path
+
+import click
+from honcho.manager import Manager as HonchoManager
+
+from plain.runtime import APP_PATH
+
+from .db import cli as db_cli
+from .pid import Pid
+from .services import Services
+from .utils import has_pyproject_toml, plainpackage_installed
+
+try:
+    import tomllib
+except ModuleNotFoundError:
+    import tomli as tomllib
+
+
+@click.group(invoke_without_command=True)
+@click.pass_context
+@click.option(
+    "--port",
+    "-p",
+    default=8000,
+    type=int,
+    help="Port to run the web server on",
+    envvar="PORT",
+)
+def cli(ctx, port):
+    """Start local development"""
+
+    if ctx.invoked_subcommand:
+        return
+
+    returncode = Dev(port=port).run()
+    if returncode:
+        sys.exit(returncode)
+
+
+@cli.command()
+def services():
+    """Start additional services defined in pyproject.toml"""
+    Services().run()
+
+
+class Dev:
+    def __init__(self, *, port):
+        self.manager = HonchoManager()
+        self.port = port
+        self.plain_env = {
+            **os.environ,
+            "PYTHONUNBUFFERED": "true",
+        }
+        self.custom_process_env = {
+            **self.plain_env,
+            "PORT": str(self.port),
+            "PYTHONPATH": os.path.join(APP_PATH.parent, "app"),
+        }
+
+    def run(self):
+        pid = Pid()
+        pid.write()
+
+        try:
+            self.add_csrf_trusted_origins()
+            self.run_preflight()
+            self.add_gunicorn()
+            self.add_tailwind()
+            self.add_pyproject_run()
+            self.add_services()
+
+            self.manager.loop()
+
+            return self.manager.returncode
+        finally:
+            pid.rm()
+
+    def add_csrf_trusted_origins(self):
+        if "PLAIN_CSRF_TRUSTED_ORIGINS" in os.environ:
+            return
+
+        csrf_trusted_origins = json.dumps(
+            [f"http://localhost:{self.port}", f"http://127.0.0.1:{self.port}"]
+        )
+
+        click.secho(
+            f"Automatically set PLAIN_CSRF_TRUSTED_ORIGINS={click.style(csrf_trusted_origins, underline=True)}",
+            bold=True,
+        )
+
+        # Set BASE_URL for plain and custom processes
+        self.plain_env["PLAIN_CSRF_TRUSTED_ORIGINS"] = csrf_trusted_origins
+        self.custom_process_env["PLAIN_CSRF_TRUSTED_ORIGINS"] = csrf_trusted_origins
+
+    def run_preflight(self):
+        if subprocess.run(["plain", "preflight"], env=self.plain_env).returncode:
+            click.secho("Preflight check failed!", fg="red")
+            sys.exit(1)
+
+    def add_gunicorn(self):
+        plain_db_installed = find_spec("plain.models") is not None
+
+        # TODO not necessarily watching the right .env...
+        # could return path from env.load?
+        extra_watch_files = []
+        for f in os.listdir(APP_PATH.parent):
+            if f.startswith(".env"):
+                # Will include some extra, but good enough for now
+                extra_watch_files.append(f)
+
+        reload_extra = " ".join(f"--reload-extra-file {f}" for f in extra_watch_files)
+        gunicorn = f"gunicorn --bind 127.0.0.1:{self.port} --reload plain.wsgi:app --timeout 60 --access-logfile - --error-logfile - {reload_extra} --access-logformat '\"%(r)s\" status=%(s)s length=%(b)s dur=%(M)sms'"
+
+        if plain_db_installed:
+            runserver_cmd = (
+                f"plain models db-wait && plain legacy migrate && {gunicorn}"
+            )
+        else:
+            runserver_cmd = gunicorn
+
+        if "WEB_CONCURRENCY" not in self.plain_env:
+            # Default to two workers so request log etc are less
+            # likely to get locked up
+            self.plain_env["WEB_CONCURRENCY"] = "2"
+
+        self.manager.add_process("plain", runserver_cmd, env=self.plain_env)
+
+    def add_tailwind(self):
+        if not plainpackage_installed("tailwind"):
+            return
+
+        self.manager.add_process("tailwind", "plain tailwind compile --watch")
+
+    def add_pyproject_run(self):
+        if not has_pyproject_toml(APP_PATH.parent):
+            return
+
+        with open(Path(APP_PATH.parent, "pyproject.toml"), "rb") as f:
+            pyproject = tomllib.load(f)
+
+        for name, data in (
+            pyproject.get("tool", {}).get("plain", {}).get("dev", {}).get("run", {})
+        ).items():
+            env = {
+                **self.custom_process_env,
+                **data.get("env", {}),
+            }
+            self.manager.add_process(name, data["cmd"], env=env)
+
+    def add_services(self):
+        services = Services.get_services(APP_PATH.parent)
+        for name, data in services.items():
+            env = {
+                **os.environ,
+                "PYTHONUNBUFFERED": "true",
+                **data.get("env", {}),
+            }
+            self.manager.add_process(name, data["cmd"], env=env)
+
+
+cli.add_command(db_cli)

plain/dev/config.py

@@ -0,0 +1,20 @@
+import importlib
+from pathlib import Path
+
+from plain.packages import PackageConfig
+from plain.runtime import settings
+
+
+class Config(PackageConfig):
+    name = "plain.dev"
+
+    def ready(self):
+        # Symlink the plain package into .plain so we can look at it easily
+        plain_path = Path(
+            importlib.util.find_spec("plain.runtime").origin
+        ).parent.parent
+        if not settings.PLAIN_TEMP_PATH.exists():
+            settings.PLAIN_TEMP_PATH.mkdir()
+        src_path = settings.PLAIN_TEMP_PATH / "src"
+        if plain_path.exists() and not src_path.exists():
+            src_path.symlink_to(plain_path)

plain/dev/contribute/__init__.py

@@ -0,0 +1,3 @@
+from .cli import cli
+
+__all__ = ["cli"]

plain/dev/contribute/cli.py

@@ -0,0 +1,114 @@
+import subprocess
+import sys
+from pathlib import Path
+
+import click
+import tomllib
+
+
+@click.command("contribute")
+@click.option("--repo", default="../plain", help="Path to the plain repo")
+@click.argument("package")
+def cli(package, repo):
+    """Contribute to plain by linking a package locally."""
+
+    if package == "reset":
+        click.secho("Undoing any changes to pyproject.toml and poetry.lock", bold=True)
+        result = subprocess.run(["git", "checkout", "pyproject.toml", "poetry.lock"])
+        if result.returncode:
+            click.secho("Failed to checkout pyproject.toml and poetry.lock", fg="red")
+            sys.exit(result.returncode)
+
+        click.secho("Removing current .venv", bold=True)
+        result = subprocess.run(["rm", "-rf", ".venv"])
+        if result.returncode:
+            click.secho("Failed to remove .venv", fg="red")
+            sys.exit(result.returncode)
+
+        click.secho("Running poetry install", bold=True)
+        result = subprocess.run(["poetry", "install"])
+        if result.returncode:
+            click.secho("Failed to install", fg="red")
+            sys.exit(result.returncode)
+
+        return
+
+    repo = Path(repo)
+    if not repo.exists():
+        click.secho(f"Repo not found at {repo}", fg="red")
+        return
+
+    repo_branch = (
+        subprocess.check_output(
+            [
+                "git",
+                "rev-parse",
+                "--abbrev-ref",
+                "HEAD",
+            ],
+            cwd=repo,
+        )
+        .decode()
+        .strip()
+    )
+    click.secho(f"Using repo at {repo} ({repo_branch} branch)", bold=True)
+
+    pyproject = Path("pyproject.toml")
+    if not pyproject.exists():
+        click.secho("pyproject.toml not found", fg="red")
+        return
+
+    poetry_group = "main"
+
+    with pyproject.open("rb") as f:
+        pyproject_data = tomllib.load(f)
+        poetry_dependencies = (
+            pyproject_data.get("tool", {}).get("poetry", {}).get("dependencies", {})
+        )
+
+        for group_name, group_data in (
+            pyproject_data.get("tool", {}).get("poetry", {}).get("group", {}).items()
+        ):
+            if package in group_data.get("dependencies", {}).keys():
+                poetry_group = group_name
+                break
+
+        if not poetry_group and package not in poetry_dependencies.keys():
+            click.secho(
+                f"{package} not found in pyproject.toml (only poetry is supported)",
+                fg="red",
+            )
+            return
+
+    click.secho(f"Linking {package} to {repo}", bold=True)
+    if package == "plain" or package.startswith("plain-"):
+        result = subprocess.run(
+            [
+                "poetry",
+                "add",
+                "--editable",
+                "--group",
+                poetry_group,
+                str(repo / package),  # Link a subdirectory
+            ]
+        )
+        if result.returncode:
+            click.secho("Failed to link the package", fg="red")
+            sys.exit(result.returncode)
+    elif package.startswith("plainx-"):
+        result = subprocess.run(
+            [
+                "poetry",
+                "add",
+                "--editable",
+                "--group",
+                poetry_group,
+                str(repo),
+            ]
+        )
+        if result.returncode:
+            click.secho("Failed to link the package", fg="red")
+            sys.exit(result.returncode)
+    else:
+        click.secho(f"Unknown package {package}", fg="red")
+        sys.exit(2)

plain/dev/db/__init__.py

@@ -0,0 +1,3 @@
+from .cli import cli
+
+__all__ = ["cli"]

plain/dev/db/cli.py

@@ -0,0 +1,113 @@
+import os
+import sys
+
+import click
+
+from ..services import Services
+from .container import DBContainer
+
+
+@click.group("db")
+def cli():
+    """Start, stop, and manage the local Postgres database"""
+    pass
+
+
+# @cli.command()
+# def reset():
+#     DBContainer().reset(create=True)
+#     click.secho("Local development database reset", fg="green")
+
+
+@cli.command()
+@click.argument("export_path", default="")
+def export(export_path):
+    """Export the local database to a file"""
+    if not export_path:
+        current_dir_name = os.path.basename(os.getcwd())
+        export_path = f"{current_dir_name}-dev-db.sql"
+    with Services():
+        export_successful = DBContainer().export(export_path)
+
+    if export_successful:
+        click.secho(f"Local development database exported to {export_path}", fg="green")
+    else:
+        click.secho("Export failed", fg="red")
+        sys.exit(1)
+
+
+@cli.command("import")
+@click.argument("sql_file")
+def import_db(sql_file):
+    """Import a database file into the local database"""
+
+    print(f"Importing {sql_file} ({os.path.getsize(sql_file) / 1024 / 1024:.2f} MB)")
+
+    with Services():
+        successful = DBContainer().import_sql(sql_file)
+
+    if successful:
+        click.secho(f"Local development database imported from {sql_file}", fg="green")
+    else:
+        click.secho("Import failed", fg="red")
+        sys.exit(1)
+
+
+@cli.group()
+def snapshot():
+    """Manage local database snapshots"""
+    pass
+
+
+@snapshot.command("create")
+@click.argument("name")
+@click.pass_context
+def snapshot_create(ctx, name):
+    """Create a snapshot of the main database"""
+    created = DBContainer().create_snapshot(name)
+    if not created:
+        click.secho(f'Snapshot "{name}" already exists', fg="red")
+        sys.exit(1)
+
+    click.secho(f'Snapshot "{name}" created', fg="green")
+    print()
+    ctx.invoke(snapshot_list)
+
+
+@snapshot.command("list")
+def snapshot_list():
+    """List all snapshots"""
+    DBContainer().list_snapshots()
+
+
+@snapshot.command("restore")
+@click.argument("name")
+@click.option("--yes", "-y", is_flag=True)
+def snapshot_restore(name, yes):
+    """Restore a snapshot to the main database"""
+    if not yes:
+        click.confirm(
+            f'Are you sure you want to restore snapshot "{name}" to the main database?',
+            abort=True,
+        )
+
+    DBContainer().restore_snapshot(name)
+    click.secho(f'Snapshot "{name}" restored', fg="green")
+
+
+@snapshot.command("delete")
+@click.argument("name")
+@click.pass_context
+def snapshot_delete(ctx, name):
+    """Delete a snapshot"""
+    deleted = DBContainer().delete_snapshot(name)
+    if not deleted:
+        click.secho(f'Snapshot "{name}" does not exist', fg="red")
+        sys.exit(1)
+    click.secho(f'Snapshot "{name}" deleted', fg="green")
+    print()
+    ctx.invoke(snapshot_list)
+
+
+if __name__ == "__main__":
+    cli()

plain/dev/db/container.py

@@ -0,0 +1,151 @@
+import os
+import shlex
+import subprocess
+
+from plain.runtime import APP_PATH, settings
+
+SNAPSHOT_DB_PREFIX = "plaindb_snapshot_"
+
+
+class DBContainer:
+    def __init__(self):
+        project_root = APP_PATH.parent
+        tmp_dir = settings.PLAIN_TEMP_PATH
+
+        name = os.path.basename(project_root) + "-postgres-1"
+
+        if "DATABASE_URL" in os.environ:
+            from plain.models import database_url
+
+            postgres_version = os.environ.get("POSTGRES_VERSION")
+            parsed_db_url = database_url.parse(os.environ.get("DATABASE_URL"))
+
+        self.name = name
+        self.tmp_dir = os.path.abspath(tmp_dir)
+        self.postgres_version = postgres_version or "13"
+        self.postgres_port = parsed_db_url.get("PORT", "5432")
+        self.postgres_db = parsed_db_url.get("NAME", "postgres")
+        self.postgres_user = parsed_db_url.get("USER", "postgres")
+        self.postgres_password = parsed_db_url.get("PASSWORD", "postgres")
+
+    def execute(self, command, *args, **kwargs):
+        docker_flags = kwargs.pop("docker_flags", "-it")
+        return subprocess.run(
+            [
+                "docker",
+                "exec",
+                docker_flags,
+                self.name,
+                *shlex.split(command),
+            ]
+            + list(args),
+            check=True,
+            **kwargs,
+        )
+
+    def reset(self, create=False):
+        try:
+            self.execute(
+                f"dropdb {self.postgres_db} --force -U {self.postgres_user}",
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+            )
+        except subprocess.CalledProcessError as e:
+            if "does not exist" not in e.stdout.decode():
+                print(e.stderr.decode())
+                raise
+
+        if create:
+            self.execute(
+                f"createdb {self.postgres_db} -U {self.postgres_user}",
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+            )
+
+    def terminate_connections(self):
+        self.execute(
+            f"psql -U {self.postgres_user} {self.postgres_db} -c",
+            f"SELECT pg_terminate_backend(pg_stat_activity.pid) FROM pg_stat_activity WHERE pg_stat_activity.datname = '{self.postgres_db}' AND pid <> pg_backend_pid();",
+            stdout=subprocess.DEVNULL,
+        )
+
+    def create_snapshot(self, name):
+        snapshot_name = f"{SNAPSHOT_DB_PREFIX}{name}"
+        current_git_branch = (
+            subprocess.check_output(["git", "rev-parse", "--abbrev-ref", "HEAD"])
+            .decode()
+            .strip()
+        )
+        description = f"branch={current_git_branch}"
+
+        self.terminate_connections()
+        try:
+            self.execute(
+                f"createdb {snapshot_name} '{description}' -U {self.postgres_user} -T {self.postgres_db}",
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+            )
+        except subprocess.CalledProcessError as e:
+            if "already exists" in e.stdout.decode():
+                return False
+            else:
+                raise
+
+        return True
+
+    def list_snapshots(self):
+        self.execute(
+            f"psql -U {self.postgres_user} {self.postgres_db} -c",
+            f"SELECT REPLACE(datname, '{SNAPSHOT_DB_PREFIX}', '') as name, pg_size_pretty(pg_database_size(datname)) as size, pg_catalog.shobj_description(oid, 'pg_database') AS description, (pg_stat_file('base/'||oid ||'/PG_VERSION')).modification as created FROM pg_catalog.pg_database WHERE datname LIKE '{SNAPSHOT_DB_PREFIX}%' ORDER BY created;",
+        )
+
+    def delete_snapshot(self, name):
+        snapshot_name = f"{SNAPSHOT_DB_PREFIX}{name}"
+        try:
+            self.execute(
+                f"dropdb {snapshot_name} -U {self.postgres_user}",
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+            )
+        except subprocess.CalledProcessError as e:
+            if "does not exist" in e.stdout.decode():
+                return False
+            else:
+                raise
+
+        return True
+
+    def restore_snapshot(self, name):
+        snapshot_name = f"{SNAPSHOT_DB_PREFIX}{name}"
+        self.reset(create=False)
+        self.execute(
+            f"createdb {self.postgres_db} -U {self.postgres_user} -T {snapshot_name}",
+        )
+
+    def export(self, export_path):
+        successful = (
+            subprocess.run(
+                [
+                    "docker",
+                    "exec",
+                    self.name,
+                    "/bin/bash",
+                    "-c",
+                    f"pg_dump -U {self.postgres_user} {self.postgres_db}",
+                ],
+                stdout=open(export_path, "w+"),
+            ).returncode
+            == 0
+        )
+        return successful
+
+    def import_sql(self, sql_file):
+        self.reset(create=True)
+        successful = (
+            subprocess.run(
+                f"docker exec -i {self.name} psql -U {self.postgres_user} {self.postgres_db} < {shlex.quote(sql_file)}",
+                shell=True,
+            ).returncode
+            == 0
+        )
+        return successful

plain/dev/debug.py

@@ -0,0 +1,12 @@
+import debugpy
+
+
+def attach(endpoint=("localhost", 5678)):
+    if debugpy.is_client_connected():
+        print("Debugger already attached")
+        return
+
+    debugpy.listen(endpoint)
+    print("Waiting for debugger to attach...")
+    debugpy.wait_for_client()
+    print("Debugger attached!")

plain/dev/default_settings.py

@@ -0,0 +1,5 @@
+DEV_REQUESTS_IGNORE_PATHS = [
+    "/favicon.ico",
+]
+
+DEV_REQUESTS_MAX = 50