plain 0.68.0__py3-none-any.whl → 0.103.0__py3-none-any.whl

plain/chores/README.md

@@ -8,7 +8,7 @@
 
 ## Overview
 
-Chores are registered functions that can be run at any time to keep an app in a desirable state.
+Chores are registered classes that can be run at any time to keep an app in a desirable state.
 
 ![](https://assets.plainframework.com/docs/plain-chores-run.png)
 
@@ -16,19 +16,19 @@ A good example is the clearing of expired sessions in [`plain.sessions`](/plain-
 
 ```python
 # plain/sessions/chores.py
-from plain.chores import register_chore
+from plain.chores import Chore, register_chore
 from plain.utils import timezone
 
 from .models import Session
 
 
-@register_chore("sessions")
-def clear_expired():
-    """
-    Delete sessions that have expired.
-    """
-    result = Session.query.filter(expires_at__lt=timezone.now()).delete()
-    return f"{result[0]} expired sessions deleted"
+@register_chore
+class ClearExpired(Chore):
+    """Delete sessions that have expired."""
+
+    def run(self):
+        result = Session.query.filter(expires_at__lt=timezone.now()).delete()
+        return f"{result[0]} expired sessions deleted"
 ```
 
 ## Running chores
@@ -38,33 +38,35 @@ The `plain chores run` command will execute all registered chores. When and how
 There are several ways you can run chores depending on your needs:
 
 - on deploy
-- as a [`plain.worker` scheduled job](/plain-worker/plain/worker/README.md#scheduled-jobs)
+- as a [`plain.jobs` scheduled job](/plain-jobs/plain/jobs/README.md#scheduled-jobs)
 - as a cron job (using any cron-like system where your app is hosted)
 - manually as needed
 
 ## Writing chores
 
-A chore is a function decorated with `@register_chore(chore_group_name)`. It can write a description as a docstring, and it can return a value that will be printed when the chore is run.
+A chore is a class that inherits from [`Chore`](./core.py#Chore) and implements the `run()` method. Register the chore using the [`@register_chore`](./registry.py#register_chore) decorator. The chore name is the class's qualified name (`__qualname__`), and the description comes from the class docstring.
 
 ```python
 # app/chores.py
-from plain.chores import register_chore
+from plain.chores import Chore, register_chore
+
 
+@register_chore
+class ChoreName(Chore):
+    """A chore description can go here."""
 
-@register_chore("app")
-def chore_name():
-    """
-    A chore description can go here
-    """
-    # Do a thing!
-    return "We did it!"
+    def run(self):
+        # Do a thing!
+        return "We did it!"
 ```
 
+### Best practices
+
 A good chore is:
 
-- Fast
-- Idempotent
-- Recurring
-- Stateless
+- **Fast** - Should complete quickly, not block for long periods
+- **Idempotent** - Safe to run multiple times without side effects
+- **Recurring** - Designed to run regularly, not just once
+- **Stateless** - Doesn't rely on external state between runs
 
 If chores are written in `app/chores.py` or `{pkg}/chores.py`, then they will be imported automatically and registered.

plain/chores/__init__.py

@@ -1,3 +1,4 @@
+from .core import Chore
 from .registry import register_chore
 
-__all__ = ["register_chore"]
+__all__ = ["Chore", "register_chore"]

plain/chores/core.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+
+class Chore(ABC):
+    """
+    Abstract base class for chores.
+
+    Subclasses must implement:
+    - run() method
+
+    Example:
+        @register_chore
+        class ClearExpired(Chore):
+            '''Delete sessions that have expired.'''
+
+            def run(self):
+                # ... implementation
+                return "10 sessions deleted"
+    """
+
+    @abstractmethod
+    def run(self) -> Any:
+        """Run the chore. Must be implemented by subclasses."""
+        pass

plain/chores/registry.py

@@ -1,42 +1,33 @@
-from plain.packages import packages_registry
-
+from __future__ import annotations
 
-class Chore:
-    def __init__(self, *, group, func):
-        self.group = group
-        self.func = func
-        self.name = f"{group}.{func.__name__}"
-        self.description = func.__doc__.strip() if func.__doc__ else ""
+from plain.packages import packages_registry
 
-    def __str__(self):
-        return self.name
-
-    def run(self):
-        """
-        Run the chore.
-        """
-        return self.func()
+from .core import Chore
 
 
 class ChoresRegistry:
-    def __init__(self):
-        self._chores = {}
+    def __init__(self) -> None:
+        self._chores: dict[str, type[Chore]] = {}
 
-    def register_chore(self, chore):
+    def register_chore(self, chore_class: type[Chore]) -> None:
         """
-        Register a chore with the specified name.
+        Register a chore class.
+
+        Args:
+            chore_class: A Chore subclass to register
         """
-        self._chores[chore.func] = chore
+        name = f"{chore_class.__module__}.{chore_class.__qualname__}"
+        self._chores[name] = chore_class
 
-    def import_modules(self):
+    def import_modules(self) -> None:
         """
         Import modules from installed packages and app to trigger registration.
         """
         packages_registry.autodiscover_modules("chores", include_app=True)
 
-    def get_chores(self):
+    def get_chores(self) -> list[type[Chore]]:
         """
-        Get all registered chores.
+        Get all registered chore classes.
         """
         return list(self._chores.values())
 
@@ -44,19 +35,15 @@ class ChoresRegistry:
 chores_registry = ChoresRegistry()
 
 
-def register_chore(group):
+def register_chore(cls: type[Chore]) -> type[Chore]:
     """
-    Register a chore with a given group.
+    Decorator to register a chore class.
 
     Usage:
-        @register_chore("clear_expired")
-        def clear_expired():
-            pass
+        @register_chore
+        class ClearExpired(Chore):
+            def run(self):
+                return "Done!"
     """
-
-    def wrapper(func):
-        chore = Chore(group=group, func=func)
-        chores_registry.register_chore(chore)
-        return func
-
-    return wrapper
+    chores_registry.register_chore(cls)
+    return cls

plain/cli/README.md

@@ -1,41 +1,210 @@
-# CLI
+# plain.cli
 
-**The `plain` CLI and how to add your own commands to it.**
+**The `plain` command-line interface and tools for adding custom commands.**
 
 - [Overview](#overview)
 - [Adding commands](#adding-commands)
+    - [Register a command group](#register-a-command-group)
+    - [Register a shortcut command](#register-a-shortcut-command)
+    - [Mark commands as common](#mark-commands-as-common)
+- [Shell](#shell)
+    - [Run a script with app context](#run-a-script-with-app-context)
+    - [SHELL_IMPORT](#shell_import)
+- [Built-in commands](#built-in-commands)
+- [FAQs](#faqs)
+- [Installation](#installation)
 
 ## Overview
 
-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.
+The `plain` CLI provides commands for running your app, managing databases, starting shells, and more. You can also add your own commands using the [`register_cli`](./registry.py#register_cli) decorator.
 
-## Adding commands
-
-The [`register_cli`](./registry.py#register_cli) decorator can be used to add your own commands to the `plain` CLI.
+Commands are written using [Click](https://click.palletsprojects.com/), a popular Python CLI framework that is one of Plain's few dependencies.
 
 ```python
 import click
 from plain.cli import register_cli
 
 
-@register_cli("example-subgroup-name")
+@register_cli("hello")
+@click.command()
+def cli():
+    """Say hello"""
+    click.echo("Hello from my custom command!")
+```
+
+After defining this command, you can run it with `plain hello`:
+
+```bash
+$ plain hello
+Hello from my custom command!
+```
+
+## Adding commands
+
+You can register commands from anywhere, but Plain will automatically import `cli.py` modules from your app and installed packages. The most common locations are:
+
+- `app/cli.py` for app-specific commands
+- `<package>/cli.py` for package-specific commands
+
+### Register a command group
+
+Use [`@register_cli`](./registry.py#register_cli) with a Click group to create subcommands:
+
+```python
+@register_cli("users")
 @click.group()
 def cli():
-    """Custom example commands"""
+    """User management commands"""
     pass
 
+
+@cli.command()
+@click.argument("email")
+def create(email):
+    """Create a new user"""
+    click.echo(f"Creating user: {email}")
+
+
 @cli.command()
-def example_command():
-    click.echo("An example command!")
+def list():
+    """List all users"""
+    click.echo("Listing users...")
 ```
 
-Then you can run the command with `plain`.
+This creates `plain users create` and `plain users list` commands.
+
+### Register a shortcut command
+
+Some commands are used frequently enough to warrant a top-level shortcut. You can indicate that a command is a shortcut for a subcommand by passing `shortcut_for`:
+
+```python
+@register_cli("migrate", shortcut_for="models")
+@click.command()
+def migrate():
+    """Run database migrations"""
+    # ...
+```
+
+This makes `plain migrate` available as a shortcut for `plain models migrate`. The shortcut relationship is shown in help output.
+
+### Mark commands as common
+
+Use the [`common_command`](./runtime.py#common_command) decorator to highlight frequently used commands in help output:
+
+```python
+from plain.cli import register_cli
+from plain.cli.runtime import common_command
+
+
+@register_cli("dev")
+@common_command
+@click.command()
+def dev():
+    """Start development server"""
+    # ...
+```
+
+Common commands appear in a separate "Common Commands" section when running `plain --help`.
+
+## Shell
+
+The `plain shell` command starts an interactive Python shell with your Plain app already loaded.
 
 ```bash
-$ plain example-subgroup-name example-command
-An example command!
+$ plain shell
 ```
 
-Technically you can register a CLI from anywhere, but typically you will do it in either `app/cli.py` or a package's `<pkg>/cli.py`, as those modules will be autoloaded by Plain.
+If you have IPython installed, it will be used automatically. You can also specify an interface explicitly:
+
+```bash
+$ plain shell --interface ipython
+$ plain shell --interface bpython
+$ plain shell --interface python
+```
+
+For one-off commands, use the `-c` flag:
+
+```bash
+$ plain shell -c "from app.users.models import User; print(User.query.count())"
+```
+
+### Run a script with app context
+
+The `plain run` command executes a Python script with your app context already set up:
+
+```bash
+$ plain run scripts/import_data.py
+```
+
+This is useful for one-off scripts that need access to your models and settings.
+
+### SHELL_IMPORT
+
+Customize what gets imported automatically when the shell starts by setting `SHELL_IMPORT` in your settings:
+
+```python
+# app/settings.py
+SHELL_IMPORT = "app.shell"
+```
+
+Then create that module with the objects you want available:
+
+```python
+# app/shell.py
+from app.projects.models import Project
+from app.users.models import User
+
+__all__ = ["Project", "User"]
+```
+
+Now when you run `plain shell`, those objects will be automatically imported and available.
+
+## Built-in commands
+
+Plain includes several built-in commands:
+
+| Command               | Description                              |
+| --------------------- | ---------------------------------------- |
+| `plain shell`         | Interactive Python shell                 |
+| `plain run <script>`  | Execute a Python script with app context |
+| `plain server`        | Production-ready WSGI server             |
+| `plain preflight`     | Validation checks before deployment      |
+| `plain create <name>` | Create a new local package               |
+| `plain settings`      | View current settings                    |
+| `plain urls`          | List all URL patterns                    |
+| `plain docs`          | View package documentation               |
+| `plain build`         | Run build commands                       |
+| `plain install`       | Install package dependencies             |
+| `plain upgrade`       | Upgrade Plain packages                   |
+
+Additional commands are added by installed packages (like `plain models migrate` from plain.models).
+
+## FAQs
+
+#### How do I run commands that don't need the app to be set up?
+
+Use the [`without_runtime_setup`](./runtime.py#without_runtime_setup) decorator for commands that don't need access to settings or app code. This is useful for commands that fork processes (like `server`) where setup should happen in the worker process:
+
+```python
+from plain.cli.runtime import without_runtime_setup
+
+
+@without_runtime_setup
+@click.command()
+def server():
+    """Start the server"""
+    # Setup happens in the worker process, not here
+    # ...
+```
+
+#### Where should I put my custom commands?
+
+Put app-specific commands in `app/cli.py`. Plain will automatically import this module. If you're building a reusable package, put commands in `<package>/cli.py`.
+
+#### Can I use argparse instead of Click?
+
+No, Plain's CLI is built on Click and the registration system expects Click commands. However, Click is well-documented and provides a better developer experience than argparse for most use cases.
+
+## Installation
+
+The CLI is included with Plain. No additional installation is required.

plain/cli/__init__.py

@@ -1,3 +1,4 @@
 from .registry import register_cli
+from .runtime import common_command
 
-__all__ = ["register_cli"]
+__all__ = ["register_cli", "common_command"]

plain/cli/agent.py

@@ -0,0 +1,234 @@
+from __future__ import annotations
+
+import importlib.util
+import json
+import pkgutil
+import shutil
+from pathlib import Path
+
+import click
+
+
+def _get_agent_dirs() -> list[Path]:
+    """Get list of agents/.claude/ directories from installed plain.* packages."""
+    agent_dirs: list[Path] = []
+
+    try:
+        import plain
+
+        # Check core plain package (namespace package)
+        plain_spec = importlib.util.find_spec("plain")
+        if plain_spec and plain_spec.submodule_search_locations:
+            for location in plain_spec.submodule_search_locations:
+                agent_dir = Path(location) / "agents" / ".claude"
+                if agent_dir.exists() and agent_dir.is_dir():
+                    agent_dirs.append(agent_dir)
+                    break
+
+        # Check other plain.* subpackages
+        if hasattr(plain, "__path__"):
+            for importer, modname, ispkg in pkgutil.iter_modules(
+                plain.__path__, "plain."
+            ):
+                if ispkg:
+                    try:
+                        spec = importlib.util.find_spec(modname)
+                        if spec and spec.origin:
+                            agent_dir = Path(spec.origin).parent / "agents" / ".claude"
+                            if agent_dir.exists() and agent_dir.is_dir():
+                                agent_dirs.append(agent_dir)
+                    except Exception:
+                        continue
+    except Exception:
+        pass
+
+    return agent_dirs
+
+
+def _install_agent_dir(source_dir: Path, dest_dir: Path) -> tuple[int, int]:
+    """Copy contents of a source agents/.claude/ dir to the project's .claude/ dir.
+
+    Handles skills/ subdirectories and rules/ files.
+    Returns (installed_count, removed_count) for reporting.
+    """
+    installed_count = 0
+
+    # Copy skills (directories containing SKILL.md)
+    source_skills = source_dir / "skills"
+    if source_skills.exists():
+        dest_skills = dest_dir / "skills"
+        dest_skills.mkdir(parents=True, exist_ok=True)
+        for skill_dir in source_skills.iterdir():
+            if skill_dir.is_dir() and (skill_dir / "SKILL.md").exists():
+                dest_skill = dest_skills / skill_dir.name
+                # Check mtime to skip unchanged
+                if dest_skill.exists():
+                    source_mtime = (skill_dir / "SKILL.md").stat().st_mtime
+                    dest_mtime = (
+                        (dest_skill / "SKILL.md").stat().st_mtime
+                        if (dest_skill / "SKILL.md").exists()
+                        else 0
+                    )
+                    if source_mtime <= dest_mtime:
+                        continue
+                    shutil.rmtree(dest_skill)
+                shutil.copytree(skill_dir, dest_skill)
+                installed_count += 1
+
+    # Copy rules (individual .md files)
+    source_rules = source_dir / "rules"
+    if source_rules.exists():
+        dest_rules = dest_dir / "rules"
+        dest_rules.mkdir(parents=True, exist_ok=True)
+        for rule_file in source_rules.iterdir():
+            if rule_file.is_file() and rule_file.suffix == ".md":
+                dest_rule = dest_rules / rule_file.name
+                # Check mtime to skip unchanged
+                if dest_rule.exists():
+                    if rule_file.stat().st_mtime <= dest_rule.stat().st_mtime:
+                        continue
+                shutil.copy2(rule_file, dest_rule)
+                installed_count += 1
+
+    return installed_count, 0
+
+
+def _cleanup_orphans(dest_dir: Path, agent_dirs: list[Path]) -> int:
+    """Remove plain* items from .claude/ that no longer exist in any source package."""
+    removed_count = 0
+
+    # Collect all source skill and rule names
+    source_skills: set[str] = set()
+    source_rules: set[str] = set()
+    for agent_dir in agent_dirs:
+        skills_dir = agent_dir / "skills"
+        if skills_dir.exists():
+            for d in skills_dir.iterdir():
+                if d.is_dir() and (d / "SKILL.md").exists():
+                    source_skills.add(d.name)
+        rules_dir = agent_dir / "rules"
+        if rules_dir.exists():
+            for f in rules_dir.iterdir():
+                if f.is_file() and f.suffix == ".md":
+                    source_rules.add(f.name)
+
+    # Remove orphaned skills
+    dest_skills = dest_dir / "skills"
+    if dest_skills.exists():
+        for dest in dest_skills.iterdir():
+            if (
+                dest.is_dir()
+                and dest.name.startswith("plain")
+                and dest.name not in source_skills
+            ):
+                shutil.rmtree(dest)
+                removed_count += 1
+
+    # Remove orphaned rules
+    dest_rules = dest_dir / "rules"
+    if dest_rules.exists():
+        for dest in dest_rules.iterdir():
+            if (
+                dest.is_file()
+                and dest.name.startswith("plain")
+                and dest.suffix == ".md"
+                and dest.name not in source_rules
+            ):
+                dest.unlink()
+                removed_count += 1
+
+    return removed_count
+
+
+def _cleanup_session_hook(dest_dir: Path) -> None:
+    """Remove the old plain agent context SessionStart hook from settings.json."""
+    settings_file = dest_dir / "settings.json"
+
+    if not settings_file.exists():
+        return
+
+    settings = json.loads(settings_file.read_text())
+
+    hooks = settings.get("hooks", {})
+    session_hooks = hooks.get("SessionStart", [])
+
+    # Remove any plain agent or plain-context.md hooks
+    session_hooks = [h for h in session_hooks if "plain agent" not in str(h)]
+    session_hooks = [h for h in session_hooks if "plain-context.md" not in str(h)]
+
+    if session_hooks:
+        hooks["SessionStart"] = session_hooks
+    else:
+        hooks.pop("SessionStart", None)
+
+    if hooks:
+        settings["hooks"] = hooks
+    else:
+        settings.pop("hooks", None)
+
+    if settings:
+        settings_file.write_text(json.dumps(settings, indent=2) + "\n")
+    else:
+        settings_file.unlink()
+
+
+@click.group()
+def agent() -> None:
+    """AI agent integration for Plain projects"""
+    pass
+
+
+@agent.command()
+def install() -> None:
+    """Install skills and rules to agent directories"""
+    cwd = Path.cwd()
+    claude_dir = cwd / ".claude"
+
+    if not claude_dir.exists():
+        click.secho("No .claude/ directory found.", fg="yellow")
+        return
+
+    agent_dirs = _get_agent_dirs()
+
+    # Clean up orphaned plain-* items
+    removed_count = _cleanup_orphans(claude_dir, agent_dirs)
+
+    # Install from each package
+    total_installed = 0
+    for source_dir in agent_dirs:
+        installed, _ = _install_agent_dir(source_dir, claude_dir)
+        total_installed += installed
+
+    # Clean up old session hook
+    _cleanup_session_hook(claude_dir)
+
+    parts = []
+    if total_installed > 0:
+        parts.append(f"installed {total_installed}")
+    if removed_count > 0:
+        parts.append(f"removed {removed_count}")
+    click.echo(f"Agent: {', '.join(parts)} in .claude/") if parts else click.echo(
+        "Agent: up to date"
+    )
+
+
+@agent.command()
+def skills() -> None:
+    """List available skills from installed packages"""
+    agent_dirs = _get_agent_dirs()
+
+    skill_names = []
+    for agent_dir in agent_dirs:
+        skills_dir = agent_dir / "skills"
+        if skills_dir.exists():
+            for d in skills_dir.iterdir():
+                if d.is_dir() and (d / "SKILL.md").exists():
+                    skill_names.append(d.name)
+
+    if not skill_names:
+        click.echo("No skills found in installed packages.")
+        return
+
+    click.echo("Available skills:")
+    for name in sorted(skill_names):
+        click.echo(f"  - {name}")