plain 0.1.0__py3-none-any.whl

plain/cli/README.md

@@ -0,0 +1,123 @@
+# CLI
+
+The `plain` CLI loads commands from Plain itself, and any `INSTALLED_PACKAGES`.
+
+Commands are written using [Click]((https://click.palletsprojects.com/en/8.1.x/))
+(one of Plain's few dependencies),
+which has been one of those most popular CLI frameworks in Python for a long time now.
+
+## Built-in commands
+
+### `plain shell`
+
+Open a Python shell with the Plain loaded.
+
+To auto-load models or run other code at shell launch,
+create an `app/shell.py` and it will be imported automatically.
+
+```python
+# app/shell.py
+from organizations.models import Organization
+
+__all__ = [
+    "Organization",
+]
+```
+
+### `plain compile`
+
+Compile static assets (used in the deploy/production process).
+
+Automatically runs `plain tailwind compile` if [plain-tailwind](https://plainframework.com/docs/plain-tailwind/) is installed.
+
+Automatically runs `npm run compile` if you have a `package.json` with `scripts.compile`.
+
+### `plain run`
+
+Run a Python script in the context of your app.
+
+### `plain legacy`
+
+A temporary holdover for running the old `manage.py` commands that haven't been converted yet.
+
+### `plain preflight`
+
+Run preflight checks to ensure your app is ready to run.
+
+### `plain create`
+
+Create a new local package.
+
+### `plain setting`
+
+View the runtime value of a named setting.
+
+## Adding commands
+
+### Add an `app/cli.py`
+
+You can add "root" commands to your app by defining a `cli` function in `app/cli.py`.
+
+```python
+import click
+
+
+@click.group()
+def cli():
+    pass
+
+
+@cli.command()
+def custom_command():
+    click.echo("An app command!")
+```
+
+Then you can run the command with `plain`.
+
+```bash
+$ plain custom-command
+An app command!
+```
+
+### Add CLI commands to your local packages
+
+Any package in `INSTALLED_PACKAGES` can define CLI commands by creating a `cli.py` in the root of the package.
+In `cli.py`, create a command or group of commands named `cli`.
+
+```python
+import click
+
+
+@click.group()
+def cli():
+    pass
+
+
+@cli.command()
+def hello():
+    click.echo("Hello, world!")
+```
+
+Plain will use the name of the package in the CLI,
+then any commands you defined.
+
+```bash
+$ plain <pkg> hello
+Hello, world!
+```
+
+### Add CLI commands to published packages
+
+Some packages, like [plain-dev](https://plainframework.com/docs/plain-dev/),
+never show up in `INSTALLED_PACKAGES` but still have CLI commands.
+These are detected via Python entry points.
+
+An example with `pyproject.toml` and Poetry:
+
+```toml
+# pyproject.toml
+[tool.poetry.plugins."plain.cli"]
+"dev" = "plain.dev:cli"
+"pre-commit" = "plain.dev.precommit:cli"
+"contrib" = "plain.dev.contribute:cli"
+```

plain/cli/__init__.py

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

plain/cli/cli.py

@@ -0,0 +1,439 @@
+import importlib
+import json
+import os
+import subprocess
+import sys
+from importlib.util import find_spec
+from pathlib import Path
+
+import click
+from click.core import Command, Context
+
+import plain.runtime
+from plain import preflight
+from plain.packages import packages
+
+from .formatting import PlainContext
+from .packages import EntryPointGroup, InstalledPackagesGroup
+
+
+@click.group()
+def plain_cli():
+    pass
+
+
+@plain_cli.command(
+    "legacy",
+    context_settings={
+        "ignore_unknown_options": True,
+    },
+)
+@click.argument("legacy_args", nargs=-1, type=click.UNPROCESSED)
+def legacy_alias(legacy_args):
+    result = subprocess.run(
+        [
+            "python",
+            "-m",
+            "plain.internal.legacy",
+            *legacy_args,
+        ],
+    )
+    if result.returncode:
+        sys.exit(result.returncode)
+
+
+# @plain_cli.command
+# def docs():
+#     """Open the Forge documentation in your browser"""
+#     subprocess.run(["open", "https://www.forgepackages.com/docs/?ref=cli"])
+
+
+@plain_cli.command()
+@click.option(
+    "-i",
+    "--interface",
+    type=click.Choice(["ipython", "bpython", "python"]),
+    help="Specify an interactive interpreter interface.",
+)
+def shell(interface):
+    """
+    Runs a Python interactive interpreter. Tries to use IPython or
+    bpython, if one of them is available.
+    """
+
+    if interface:
+        interface = [interface]
+    else:
+
+        def get_default_interface():
+            try:
+                import IPython  # noqa
+
+                return ["python", "-m", "IPython"]
+            except ImportError:
+                pass
+
+            return ["python"]
+
+        interface = get_default_interface()
+
+    result = subprocess.run(
+        interface,
+        env={
+            "PYTHONSTARTUP": os.path.join(os.path.dirname(__file__), "startup.py"),
+            **os.environ,
+        },
+    )
+    if result.returncode:
+        sys.exit(result.returncode)
+
+
+@plain_cli.command()
+@click.argument("script", nargs=1, type=click.Path(exists=True))
+def run(script):
+    """Run a Python script in the context of your app"""
+    before_script = "import plain.runtime; plain.runtime.setup()"
+    command = f"{before_script}; exec(open('{script}').read())"
+    result = subprocess.run(["python", "-c", command])
+    if result.returncode:
+        sys.exit(result.returncode)
+
+
+# @plain_cli.command()
+# @click.option("--filter", "-f", "name_filter", help="Filter settings by name")
+# @click.option("--overridden", is_flag=True, help="Only show overridden settings")
+# def settings(name_filter, overridden):
+#     """Print Plain settings"""
+#     table = Table(box=box.MINIMAL)
+#     table.add_column("Setting")
+#     table.add_column("Default value")
+#     table.add_column("App value")
+#     table.add_column("Type")
+#     table.add_column("Module")
+
+#     for setting in dir(settings):
+#         if setting.isupper():
+#             if name_filter and name_filter.upper() not in setting:
+#                 continue
+
+#             is_overridden = settings.is_overridden(setting)
+
+#             if overridden and not is_overridden:
+#                 continue
+
+#             default_setting = settings._default_settings.get(setting)
+#             if default_setting:
+#                 default_value = default_setting.value
+#                 annotation = default_setting.annotation
+#                 module = default_setting.module
+#             else:
+#                 default_value = ""
+#                 annotation = ""
+#                 module = ""
+
+#             table.add_row(
+#                 setting,
+#                 Pretty(default_value) if default_value else "",
+#                 Pretty(getattr(settings, setting))
+#                 if is_overridden
+#                 else Text("<Default>", style="italic dim"),
+#                 Pretty(annotation) if annotation else "",
+#                 str(module.__name__) if module else "",
+#             )
+
+#     console = Console()
+#     console.print(table)
+
+
+@plain_cli.command("preflight")
+@click.argument("package_label", nargs=-1)
+@click.option(
+    "--deploy",
+    is_flag=True,
+    help="Check deployment settings.",
+)
+@click.option(
+    "--fail-level",
+    default="ERROR",
+    type=click.Choice(["CRITICAL", "ERROR", "WARNING", "INFO", "DEBUG"]),
+    help="Message level that will cause the command to exit with a non-zero status. Default is ERROR.",
+)
+@click.option(
+    "--database",
+    "databases",
+    multiple=True,
+    help="Run database related checks against these aliases.",
+)
+def preflight_checks(package_label, deploy, fail_level, databases):
+    """
+    Use the system check framework to validate entire Plain project.
+    Raise CommandError for any serious message (error or critical errors).
+    If there are only light messages (like warnings), print them to stderr
+    and don't raise an exception.
+    """
+    include_deployment_checks = deploy
+
+    if package_label:
+        package_configs = [
+            packages.get_package_config(label) for label in package_label
+        ]
+    else:
+        package_configs = None
+
+    all_issues = preflight.run_checks(
+        package_configs=package_configs,
+        include_deployment_checks=include_deployment_checks,
+        databases=databases,
+    )
+
+    header, body, footer = "", "", ""
+    visible_issue_count = 0  # excludes silenced warnings
+
+    if all_issues:
+        debugs = [
+            e for e in all_issues if e.level < preflight.INFO and not e.is_silenced()
+        ]
+        infos = [
+            e
+            for e in all_issues
+            if preflight.INFO <= e.level < preflight.WARNING and not e.is_silenced()
+        ]
+        warnings = [
+            e
+            for e in all_issues
+            if preflight.WARNING <= e.level < preflight.ERROR and not e.is_silenced()
+        ]
+        errors = [
+            e
+            for e in all_issues
+            if preflight.ERROR <= e.level < preflight.CRITICAL and not e.is_silenced()
+        ]
+        criticals = [
+            e
+            for e in all_issues
+            if preflight.CRITICAL <= e.level and not e.is_silenced()
+        ]
+        sorted_issues = [
+            (criticals, "CRITICALS"),
+            (errors, "ERRORS"),
+            (warnings, "WARNINGS"),
+            (infos, "INFOS"),
+            (debugs, "DEBUGS"),
+        ]
+
+        for issues, group_name in sorted_issues:
+            if issues:
+                visible_issue_count += len(issues)
+                formatted = (
+                    click.style(str(e), fg="red")
+                    if e.is_serious()
+                    else click.style(str(e), fg="yellow")
+                    for e in issues
+                )
+                formatted = "\n".join(sorted(formatted))
+                body += f"\n{group_name}:\n{formatted}\n"
+
+    if visible_issue_count:
+        header = "Preflight check identified some issues:\n"
+
+    if any(
+        e.is_serious(getattr(preflight, fail_level)) and not e.is_silenced()
+        for e in all_issues
+    ):
+        footer += "\n"
+        footer += "Preflight check identified {} ({} silenced).".format(
+            "no issues"
+            if visible_issue_count == 0
+            else "1 issue"
+            if visible_issue_count == 1
+            else "%s issues" % visible_issue_count,
+            len(all_issues) - visible_issue_count,
+        )
+        msg = click.style("SystemCheckError: %s" % header, fg="red") + body + footer
+        raise click.ClickException(msg)
+    else:
+        if visible_issue_count:
+            footer += "\n"
+            footer += "Preflight check identified {} ({} silenced).".format(
+                "no issues"
+                if visible_issue_count == 0
+                else "1 issue"
+                if visible_issue_count == 1
+                else "%s issues" % visible_issue_count,
+                len(all_issues) - visible_issue_count,
+            )
+            msg = header + body + footer
+            click.echo(msg, err=True)
+        else:
+            click.echo("Preflight check identified no issues.", err=True)
+
+
+@plain_cli.command()
+@click.pass_context
+def compile(ctx):
+    """Compile static assets"""
+
+    # TODO preflight for assets only?
+
+    # TODO make this an entrypoint instead
+    # Compile our Tailwind CSS (including templates in plain itself)
+    if find_spec("plain.tailwind") is not None:
+        result = subprocess.run(["plain", "tailwind", "compile", "--minify"])
+        if result.returncode:
+            click.secho(
+                f"Error compiling Tailwind CSS (exit {result.returncode})", fg="red"
+            )
+            sys.exit(result.returncode)
+
+    # TODO also look in [tool.plain.compile.run]
+
+    # Run a "compile" script from package.json automatically
+    package_json = Path("package.json")
+    if package_json.exists():
+        with package_json.open() as f:
+            package = json.load(f)
+
+        if package.get("scripts", {}).get("compile"):
+            result = subprocess.run(["npm", "run", "compile"])
+            if result.returncode:
+                click.secho(
+                    f"Error in `npm run compile` (exit {result.returncode})", fg="red"
+                )
+                sys.exit(result.returncode)
+
+    # Run the regular collectstatic
+    ctx.invoke(legacy_alias, legacy_args=["collectstatic", "--noinput"])
+
+
+@plain_cli.command()
+@click.argument("package_name")
+def create(package_name):
+    """Create a new local package"""
+    package_dir = plain.runtime.APP_PATH / package_name
+    package_dir.mkdir(exist_ok=True)
+
+    empty_dirs = (
+        f"templates/{package_name}",
+        "migrations",
+    )
+    for d in empty_dirs:
+        (package_dir / d).mkdir(parents=True, exist_ok=True)
+
+    empty_files = (
+        "__init__.py",
+        "migrations/__init__.py",
+        "models.py",
+        "views.py",
+    )
+    for f in empty_files:
+        (package_dir / f).touch(exist_ok=True)
+
+    # Create a urls.py file with a default namespace
+    if not (package_dir / "urls.py").exists():
+        (package_dir / "urls.py").write_text(
+            f"""from plain.urls import path
+
+default_namespace = f"{package_name}"
+
+urlpatterns = [
+    # path("", views.IndexView, name="index"),
+]
+"""
+        )
+
+    click.secho(
+        f'Created {package_dir.relative_to(Path.cwd())}. Make sure to add "{package_name}" to INSTALLED_PACKAGES!',
+        fg="green",
+    )
+
+
+@plain_cli.command()
+@click.argument("setting_name")
+def setting(setting_name):
+    """Print the value of a setting at runtime"""
+    try:
+        setting = getattr(plain.runtime.settings, setting_name)
+        click.echo(setting)
+    except AttributeError:
+        click.secho(f'Setting "{setting_name}" not found', fg="red")
+
+
+class AppCLIGroup(click.Group):
+    """
+    Loads app.cli if it exists as `plain app`
+    """
+
+    MODULE_NAME = "app.cli"
+
+    def list_commands(self, ctx):
+        try:
+            find_spec(self.MODULE_NAME)
+            return ["app"]
+        except ModuleNotFoundError:
+            return []
+
+    def get_command(self, ctx, name):
+        if name != "app":
+            return
+
+        try:
+            cli = importlib.import_module(self.MODULE_NAME)
+            return cli.cli
+        except ModuleNotFoundError:
+            return
+
+
+class PlainCommandCollection(click.CommandCollection):
+    context_class = PlainContext
+
+    def __init__(self, *args, **kwargs):
+        sources = []
+
+        try:
+            # Setup has to run before the installed packages CLI work
+            # and it also does the .env file loading right now...
+            plain.runtime.setup()
+
+            sources = [
+                InstalledPackagesGroup(),
+                EntryPointGroup(),
+                AppCLIGroup(),
+                plain_cli,
+            ]
+        except plain.runtime.AppPathNotFound:
+            click.secho(
+                "Plain `app` directory not found. Some commands may be missing.",
+                fg="yellow",
+                err=True,
+            )
+
+            sources = [
+                EntryPointGroup(),
+                plain_cli,
+            ]
+        except Exception as e:
+            click.secho(
+                f"Error setting up Plain CLI\n{e}",
+                fg="red",
+                err=True,
+            )
+
+            sources = [
+                EntryPointGroup(),
+                AppCLIGroup(),
+                plain_cli,
+            ]
+
+        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/cli/formatting.py

@@ -0,0 +1,61 @@
+import click
+from click.formatting import iter_rows, measure_table, term_len, wrap_text
+
+
+class PlainHelpFormatter(click.HelpFormatter):
+    def write_heading(self, heading):
+        styled_heading = click.style(heading, underline=True)
+        self.write(f"{'':>{self.current_indent}}{styled_heading}\n")
+
+    def write_usage(self, prog, args, prefix="Usage: "):
+        prefix_styled = click.style(prefix, italic=True)
+        super().write_usage(prog, args, prefix=prefix_styled)
+
+    def write_dl(
+        self,
+        rows,
+        col_max=30,
+        col_spacing=2,
+    ):
+        """Writes a definition list into the buffer.  This is how options
+        and commands are usually formatted.
+
+        :param rows: a list of two item tuples for the terms and values.
+        :param col_max: the maximum width of the first column.
+        :param col_spacing: the number of spaces between the first and
+                            second column.
+        """
+        rows = list(rows)
+        widths = measure_table(rows)
+        if len(widths) != 2:
+            raise TypeError("Expected two columns for definition list")
+
+        first_col = min(widths[0], col_max) + col_spacing
+
+        for first, second in iter_rows(rows, len(widths)):
+            first_styled = click.style(first, bold=True)
+            self.write(f"{'':>{self.current_indent}}{first_styled}")
+            if not second:
+                self.write("\n")
+                continue
+            if term_len(first) <= first_col - col_spacing:
+                self.write(" " * (first_col - term_len(first)))
+            else:
+                self.write("\n")
+                self.write(" " * (first_col + self.current_indent))
+
+            text_width = max(self.width - first_col - 2, 10)
+            wrapped_text = wrap_text(second, text_width, preserve_paragraphs=True)
+            lines = wrapped_text.splitlines()
+
+            if lines:
+                self.write(f"{lines[0]}\n")
+
+                for line in lines[1:]:
+                    self.write(f"{'':>{first_col + self.current_indent}}{line}\n")
+            else:
+                self.write("\n")
+
+
+class PlainContext(click.Context):
+    formatter_class = PlainHelpFormatter

plain/cli/packages.py

@@ -0,0 +1,73 @@
+import importlib
+from importlib.metadata import entry_points
+from importlib.util import find_spec
+
+import click
+
+from plain.packages import packages
+
+
+class InstalledPackagesGroup(click.Group):
+    """
+    Packages in INSTALLED_PACKAGES with a cli.py module
+    will be discovered automatically.
+    """
+
+    PLAIN_APPS_PREFIX = "plain."
+    MODULE_NAME = "cli"
+
+    def list_commands(self, ctx):
+        packages_with_commands = []
+
+        # Get installed packages with a cli.py module
+        for app in packages.get_package_configs():
+            if not find_spec(f"{app.name}.{self.MODULE_NAME}"):
+                continue
+
+            cli_name = app.name
+
+            if cli_name.startswith(self.PLAIN_APPS_PREFIX):
+                cli_name = cli_name[len(self.PLAIN_APPS_PREFIX) :]
+
+            packages_with_commands.append(cli_name)
+
+        return packages_with_commands
+
+    def get_command(self, ctx, name):
+        # Try it as plain.x and just x (we don't know ahead of time which it is, but prefer plain.x)
+        for n in [self.PLAIN_APPS_PREFIX + name, name]:
+            try:
+                cli = importlib.import_module(f"{n}.{self.MODULE_NAME}")
+            except ModuleNotFoundError:
+                continue
+
+            # Get the app's cli.py group
+            try:
+                return cli.cli
+            except AttributeError:
+                continue
+
+
+class EntryPointGroup(click.Group):
+    """
+    Python packages can be added to the Plain CLI
+    via the plain_cli entrypoint in their setup.py.
+
+    This is intended for packages that don't go in INSTALLED_PACKAGES.
+    """
+
+    ENTRYPOINT_NAME = "plain.cli"
+
+    def list_commands(self, ctx):
+        rv = []
+
+        for entry_point in entry_points().select(group=self.ENTRYPOINT_NAME):
+            rv.append(entry_point.name)
+
+        rv.sort()
+        return rv
+
+    def get_command(self, ctx, name):
+        for entry_point in entry_points().select(group=self.ENTRYPOINT_NAME):
+            if entry_point.name == name:
+                return entry_point.load()

plain/cli/print.py

@@ -0,0 +1,9 @@
+import click
+
+
+def print_event(msg, newline=True):
+    arrow = click.style("-->", fg=214, bold=True)
+    message = str(msg)
+    if not newline:
+        message += " "
+    click.secho(f"{arrow} {message}", nl=newline)