plain.dev 0.0.0__py3-none-any.whl

plain/dev/README.md

@@ -0,0 +1,148 @@
+# plain-dev
+
+A single command to run everything you need for local Plain development.
+
+![Plain work command example](https://user-images.githubusercontent.com/649496/176533533-cfd44dc5-afe5-42af-8b5d-33a9fa23f8d9.gif)
+
+The `plain dev` command runs a combination of local commands + a Docker container for your database.
+
+The following processes will run simultaneously (some will only run if they are detected as available):
+
+<!-- - [`manage.py runserver` (and migrations)](#runserver)
+- [`plain-models start --logs`](#plain-models)
+- [`plain-tailwind compile --watch`](#plain-tailwind)
+- [`npm run watch`](#package-json)
+- [`stripe listen --forward-to`](#stripe)
+- [`ngrok http --subdomain`](#ngrok)
+
+It also comes with [debugging](#debugging) tools to make local debugging easier with VS Code. -->
+
+## Installation
+
+```sh
+pip install plain-dev
+```
+
+If you have `plain-models` installed (i.e. you're using a database),
+then add `DATABASE_URL` to your `.env` file.
+
+```sh
+DATABASE_URL=postgres://postgres:postgres@localhost:54321/postgres
+```
+
+```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"}
+```
+
+```sh
+plain dev
+```
+
+## `plain dev`
+
+### Default processes
+
+- plain preflight
+- gunicorn
+- migrations
+- tailwind
+
+### Custom processes
+
+- package.json "dev" script
+- pyproject.toml `tool.plain.dev.run = {command = "..."}`
+
+### GitHub Codespaces
+
+The `BASE_URL` setting is automatically set to the Codespace URL.
+
+TODO
+
+## `plain dev db`
+
+Only supports Postgres currently.
+
+- snapshot
+- import
+- export
+
+
+## Development processes
+
+### Gunicorn
+
+The key process here is still `manage.py runserver`.
+But, before that runs, it will also wait for the database to be available and run `manage.py migrate`.
+
+### plain-models
+
+If [`plain-models`](https://github.com/plainpackages/plain-models) is installed, it will automatically start and show the logs of the running database container.
+
+### plain-tailwind
+
+If [`plain-tailwind`](https://github.com/plainpackages/plain-tailwind) is installed, it will automatically run the Tailwind `compile --watch` process.
+
+## Debugging
+
+[View on YouTube →](https://www.youtube.com/watch?v=pG0KaJSVyBw)
+
+Since `plain work` runs multiple processes at once, the regular [pdb](https://docs.python.org/3/library/pdb.html) debuggers can be hard to use.
+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_context(self, **kwargs):
+        context = super().get_context(**kwargs)
+
+        # Make sure the debugger is attached (will need to be if runserver reloads)
+        from plain.work import debug; debug.attach()
+
+        # Add a breakpoint (or use the gutter in VSCode to add one)
+        breakpoint()
+
+        return context
+```
+
+When you load the page, you'll see "Waiting for debugger to attach...".
+
+Add a new VS Code debug configuration (using localhost and port 5768) by saving this to `.vscode/launch.json` or using the GUI:
+
+```json
+// .vscode/launch.json
+{
+    // Use IntelliSense to learn about possible attributes.
+    // Hover to view descriptions of existing attributes.
+    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "Plain: Attach to Django",
+            "type": "python",
+            "request": "attach",
+            "connect": {
+                "host": "localhost",
+                "port": 5678
+            },
+            "pathMappings": [
+                {
+                    "localRoot": "${workspaceFolder}",
+                    "remoteRoot": "."
+                }
+            ],
+            "justMyCode": true,
+            "django": true
+        }
+    ]
+}
+```
+
+Then in the "Run and Debug" tab, you can click the green arrow next to "Plain: Attach to Django" to start the debugger.
+
+In your terminal is should tell you it was attached, and when you hit a breakpoint you'll see the debugger information in VS Code.
+If Django's runserver reloads, you'll be prompted to reattach by clicking the green arrow again.

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()