|
| 1 | +## [[app_name]] |
| 2 | + |
| 3 | +This is a Proper-based web application. Proper is an opinionated, batteries-included Python web framework. It uses ASGI with sync Python controllers, Peewee ORM, Huey task queue, Jx components, and Formidable forms. |
| 4 | + |
| 5 | +Deep reference docs are bundled in the `proper` skill. |
| 6 | + |
| 7 | +## Key Conventions |
| 8 | + |
| 9 | +- **Everything is CRUD** - controllers map to RESTful resource actions (index, new, create, show, edit, update, delete) |
| 10 | +- **Singular names** - resource/model/controller names are always singular (e.g., `Post`, not `Posts`) |
| 11 | +- **Boot order matters** - `__init__.py` imports: main → router → controllers → models → tasks. New controllers/models must be imported in their respective `__init__.py` |
| 12 | +- **`form.save()` returns unsaved** - it returns a model instance that hasn't been persisted yet; call `instance.save()` to write to DB |
| 13 | +- **Controllers are sync** - despite ASGI, controller methods are regular sync Python |
| 14 | +- **`current` context** - `current.request`, `current.user`, `current.auth_session` available in controllers and templates |
| 15 | + |
| 16 | +## Common Commands |
| 17 | + |
| 18 | +```bash |
| 19 | +proper g resource Post title:str body:text # Generate full CRUD resource |
| 20 | +proper g model Photo title:str published:bool # Generate model only |
| 21 | +proper install auth|storage|i18n|channels # Install addons |
| 22 | +proper db migrate # Run migrations |
| 23 | +uv run proper run # Start dev server |
| 24 | +``` |
| 25 | + |
| 26 | +## File Organization |
| 27 | + |
| 28 | +What | Where | Also modify |
| 29 | +-------------------- | ---------------------------------- | ------------------------- |
| 30 | +Controller | `controllers/{name}_controller.py` | `controllers/__init__.py` |
| 31 | +Model | `models/{name}.py` | `models/__init__.py` |
| 32 | +Form | `forms/{name}.py` | - |
| 33 | +Views | `views/{name}/*.jx` | - |
| 34 | +Concern (controller) | `controllers/concerns/{name}.py` | controller that uses it |
| 35 | +Concern (model) | `models/concerns/{name}.py` | model that uses it |
| 36 | +Task | `tasks/{name}.py` | - |
| 37 | +Email | `emails/{name}.py`/`views/emails/{name}.jx` | - |
| 38 | +Config | `config/{name}.py` | `config/__init__.py` |
| 39 | + |
| 40 | +## General Guidelines |
| 41 | + |
| 42 | +- Before suggesting removal or simplification of existing configuration (editable installs, specific build steps, etc.), ask the user first. Do not proactively remove things that look unnecessary. |
| 43 | + |
| 44 | +## Writing / Editing |
| 45 | + |
| 46 | +- Unless done to avoid recursive imports, place all the imports at the beginning of the file. |
| 47 | +- After creating or updating a python file, run `uv run ruff check --fix ${file} 2>/dev/null || true` to fix any linting errors. |
| 48 | +- Never disable any linter errors without user confirmation. |
| 49 | + |
| 50 | +## Testing |
| 51 | + |
| 52 | +- Always run `uv run pytest` as the test runner command. Do not use `pytest` directly or any other test runner unless explicitly told otherwise. |
| 53 | +- Never remove or disable any tests without user confirmation. |
| 54 | +- When writing tests, use real filesystem and real objects instead of mocks unless it requires running separated service or asked to mock. Avoid unittest.mock patterns for integration-style tests. |
| 55 | +- When debugging test failures, check for framework-specific behaviors |
| 56 | + |
| 57 | +## Dependencies |
| 58 | + |
| 59 | +- Use `uv add <package>` to add dependencies. Do not manually edit pyproject.toml for adding requirements. |
0 commit comments