Oleg Yurchik
b8388fa4a2
- Add python-development-database skill: metaorm patterns for tables, repositories, filters, settings, transactions, pagination, and exceptions - Add python-development-telegram-bot skill: aiogram bot service with polling/webhook, router structure, middlewares, inline keyboards, and pagination - Add python-development-tests skill: test organization guidelines with pytest, fixtures, and dependency injection rules - Update python-development-stack: replace SQLModel/SQLAlchemy with metaorm; add pytest, pytest-asyncio, pytest-cov, faker - Update python-development-fastapi: add sections for dependencies and list endpoints with ListResponse schema - Update python-development-code-style: allow ctx as exception for typer.Context parameter - Update python-development index with links to all three new skills Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
58 lines
3.5 KiB
Markdown
58 lines
3.5 KiB
Markdown
---
|
|
name: python-development-code-style
|
|
description: Code conventions, typing, testing habits, and engineering principles. Use when writing, reviewing, or refactoring Python code.
|
|
---
|
|
|
|
## Rules
|
|
- Follow PEP 8 for all Python code. Use `ruff` for automatic formatting and linting.
|
|
- Every package `__init__.py` must declare the public API explicitly with `__all__`. `__all__` is always a tuple, even when it contains a single element. Use inline comment group headers to separate imports by source module.
|
|
- Inside `__init__.py` import only from sibling modules. Do not place executable code.
|
|
- Group related names together in `__all__` and mirror the grouping with comment headers. Example:
|
|
```python
|
|
from .base import BaseService, ServiceMixin
|
|
from .dto import ServiceInput, ServiceOutput
|
|
from .exceptions import ServiceError, ValidationError
|
|
from .fabric import get_service
|
|
from .settings import ServiceSettings
|
|
|
|
__all__ = (
|
|
# base
|
|
"BaseService",
|
|
"ServiceMixin",
|
|
# dto
|
|
"ServiceInput",
|
|
"ServiceOutput",
|
|
# exceptions
|
|
"ServiceError",
|
|
"ValidationError",
|
|
# fabric
|
|
"get_service",
|
|
# settings
|
|
"ServiceSettings",
|
|
)
|
|
```
|
|
- Wildcard imports (`from module import *`) are forbidden in every module, including `__init__.py`. Always import explicit names.
|
|
- Within a package, import sibling modules using relative imports (`from .module import Name`). When importing from a different top-level package or from a parent package that is not a direct sibling, use an absolute import (`from project_name.module import Name`).
|
|
- Group imports in every module into three blocks separated by a blank line:
|
|
1. Standard library (`import pathlib`, `from typing import Self`, etc.).
|
|
2. Third-party packages (`import yaml`, `from pydantic import Field`, etc.).
|
|
3. Project-local imports (`from .services import MyService`, `from microclaw.settings import Settings`, etc.).
|
|
- Within each block, place `from ... import ...` lines first, then `import ...` lines. Sort all lines alphabetically. Example:
|
|
```python
|
|
import json
|
|
import pathlib
|
|
from typing import Self
|
|
|
|
import yaml
|
|
from pydantic import Field
|
|
from pydantic_settings import BaseSettings
|
|
|
|
from .services import MyService
|
|
from microclaw.settings import Settings
|
|
```
|
|
- Functions and methods must not return tuples of multiple values. Returning a tuple is allowed only in exceptional cases (e.g. unpacking a well-known pair such as `(key, value)`). When a function needs to return more than one piece of data, define a Pydantic `BaseModel` for the result or reuse an existing model. This makes the return type self-documenting, enables IDE autocomplete, and keeps field names stable during refactoring.
|
|
- Do not use `from __future__ import annotations`. Use explicit forward-reference strings (e.g. `"MyClass"`) when necessary.
|
|
- Do not use `if TYPE_CHECKING:` blocks. Import the types you need at the top level. Deferred imports inside `TYPE_CHECKING` hide dependencies and break runtime introspection.
|
|
- Do not abbreviate variable or parameter names. Write them out in full so the intent is obvious without context. Examples of forbidden abbreviations: `idx` (use `index`), `dep` (use `dependency`), `cfg` (use `config` or `configuration`), `msg` (use `message`), `err` (use `error`), `resp` (use `response`). The same rule applies to class attributes, function parameters, and local variables.
|
|
- Exception: when implementing Typer commands, the parameter name `ctx` is allowed for the `typer.Context` object because it is the idiomatic name required by the framework.
|