plain.dev 0.0.0__tar.gz

plain_dev-0.0.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2023, Dropseed, LLC
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

plain_dev-0.0.0/PKG-INFO

@@ -0,0 +1,178 @@
+Metadata-Version: 2.1
+Name: plain.dev
+Version: 0.0.0
+Summary: Work library for Plain
+Home-page: https://www.plainpackages.com/
+License: MIT
+Author: Dave Gaeddert
+Author-email: dave.gaeddert@dropseed.dev
+Requires-Python: >=3.8,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: click (>=8.0.0)
+Requires-Dist: debugpy (>=1.6.3,<2.0.0)
+Requires-Dist: gunicorn (>20)
+Requires-Dist: honcho (>=1.1.0,<2.0.0)
+Requires-Dist: psycopg2-binary (>=2.9.3,<3.0.0)
+Requires-Dist: requests (>=2.0.0)
+Requires-Dist: tomli (>=2.0.1,<3.0.0) ; python_version < "3.11"
+Project-URL: Documentation, https://www.plainpackages.com/docs/
+Project-URL: Repository, https://github.com/plainpackages/plain-dev
+Description-Content-Type: text/markdown
+
+<!-- This file is compiled from plain-dev/plain/dev/README.md. Do not edit this file directly. -->
+
+# 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-0.0.0/README.md

@@ -0,0 +1,150 @@
+<!-- This file is compiled from plain-dev/plain/dev/README.md. Do not edit this file directly. -->
+
+# 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-0.0.0/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-0.0.0/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-0.0.0/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-0.0.0/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-0.0.0/plain/dev/contribute/__init__.py

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