tempest-fastapi-sdk 0.41.0__tar.gz → 0.43.0__tar.gz

{tempest_fastapi_sdk-0.41.0 → tempest_fastapi_sdk-0.43.0}/CHANGELOG.md

@@ -5,6 +5,72 @@ All notable changes to **tempest-fastapi-sdk** are listed below.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.43.0] — 2026-06-11
+
+### Added
+
+- **Distributed tracing with OpenTelemetry.** `setup_tracing(app,
+  service_name=..., otlp_endpoint=...)` installs an OTLP/gRPC span
+  exporter and auto-instruments FastAPI (incoming requests),
+  SQLAlchemy (queries, via `sqlalchemy_engine=db.engine`) and httpx
+  (outbound calls) so one trace follows a request across services.
+  `otlp_endpoint=None` falls back to a console exporter for local
+  debugging; `sample_ratio` controls head-based sampling;
+  `resource_attributes` merges extra span attributes. Behind the new
+  `[otel]` extra — importing the SDK without it costs nothing and
+  never crashes. Complements `RequestIDMiddleware` (which correlates
+  logs).
+- **`SlowQueryLogger`** — attaches `before/after_cursor_execute`
+  listeners to a SQLAlchemy engine (sync or async) and logs every
+  statement slower than `threshold_ms`. Bind parameters are omitted
+  by default (PII); `log_parameters=True` and `explain=True` (runs
+  `EXPLAIN`) are opt-in for development. No extra required. Exposed
+  at the top level and from `tempest_fastapi_sdk.db`.
+- **`AsyncDatabaseManager.engine`** — public property returning the
+  live `AsyncEngine`, so instrumentation (`SlowQueryLogger`, the OTel
+  SQLAlchemy instrumentor) can attach to it directly.
+
+### Docs
+
+- New bilingual recipe **Observabilidade / Observability** covering
+  `setup_tracing` and `SlowQueryLogger`, added to the nav, the
+  recipes index, and the API reference.
+
+## [0.42.0] — 2026-06-11
+
+### Added
+
+- **`tempest user promote` / `tempest user revoke`** — flip `is_admin`
+  for an existing user, found by email (case-insensitive), without
+  hand-written SQL. `promote` grants `/admin` access (`is_admin=True`),
+  `revoke` removes it. Both exit `1` with `no user found` when no user
+  matches the email.
+- **`tempest generate --src`** — add the optional source layers
+  triggered by the project's pinned SDK extras to an existing project:
+  `[queue]` → `<root>/queue/` (FastStream broker + handlers stub),
+  `[tasks]` → `<root>/tasks/` (TaskIQ broker + jobs stub). The source
+  root (`src` or `app`) is auto-detected and generated imports point at
+  it. Idempotent — existing files are kept unless `--force` is passed.
+  `--docker` and `--src` can be combined in one invocation.
+- **`tempest new` now scaffolds the chosen extras' source layers.**
+  `tempest new svc --extras auth,queue` ships `src/queue/` out of the
+  box (and `src/tasks/` with `[tasks]`); projects without those extras
+  get no placeholder packages.
+
+### Changed
+
+- **Usage errors now print the offending command's full `--help`.**
+  An unknown command, an invalid option, or a missing required argument
+  renders the complete help (every parameter, default and description)
+  before the error line, instead of Click's terse `Try '... --help'`
+  hint. Quality-gate exit codes still propagate unchanged.
+- **`tempest user create` prompts for the admin flag interactively.**
+  When neither `--admin` nor `--no-admin` is passed in an interactive
+  terminal, it asks `Should this user be an administrator? [y/N]`.
+  Non-interactive runs (CI, pipes, scripts) skip the prompt and default
+  to a regular user — pass `--admin` explicitly to create an admin
+  without a TTY. The flag is now `--admin/--no-admin` (tri-state).
+
 ## [0.41.0] — 2026-06-07
 
 ### Changed (breaking)

{tempest_fastapi_sdk-0.41.0 → tempest_fastapi_sdk-0.43.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tempest-fastapi-sdk
-Version: 0.41.0
+Version: 0.43.0
 Summary: Shared FastAPI building blocks: base schemas, ORM model, async repository, exceptions, pagination and settings — the conventions used across Tempest projects.
 Project-URL: Homepage, https://github.com/mauriciobenjamin700/tempest-fastapi-sdk
 Project-URL: Repository, https://github.com/mauriciobenjamin700/tempest-fastapi-sdk
@@ -43,6 +43,11 @@ Requires-Dist: itsdangerous>=2.2.0; extra == 'all'
 Requires-Dist: jinja2>=3.1.0; extra == 'all'
 Requires-Dist: minio>=7.2.0; extra == 'all'
 Requires-Dist: nvidia-ml-py>=12.560.30; extra == 'all'
+Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.27.0; extra == 'all'
+Requires-Dist: opentelemetry-instrumentation-fastapi>=0.48b0; extra == 'all'
+Requires-Dist: opentelemetry-instrumentation-httpx>=0.48b0; extra == 'all'
+Requires-Dist: opentelemetry-instrumentation-sqlalchemy>=0.48b0; extra == 'all'
+Requires-Dist: opentelemetry-sdk>=1.27.0; extra == 'all'
 Requires-Dist: prometheus-client>=0.20.0; extra == 'all'
 Requires-Dist: psutil>=6.0.0; extra == 'all'
 Requires-Dist: pyjwt>=2.12.1; extra == 'all'
@@ -70,6 +75,12 @@ Provides-Extra: mfa
 Requires-Dist: pyotp>=2.9.0; extra == 'mfa'
 Provides-Extra: minio
 Requires-Dist: minio>=7.2.0; extra == 'minio'
+Provides-Extra: otel
+Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.27.0; extra == 'otel'
+Requires-Dist: opentelemetry-instrumentation-fastapi>=0.48b0; extra == 'otel'
+Requires-Dist: opentelemetry-instrumentation-httpx>=0.48b0; extra == 'otel'
+Requires-Dist: opentelemetry-instrumentation-sqlalchemy>=0.48b0; extra == 'otel'
+Requires-Dist: opentelemetry-sdk>=1.27.0; extra == 'otel'
 Provides-Extra: postgres
 Requires-Dist: asyncpg>=0.30.0; extra == 'postgres'
 Provides-Extra: prometheus
@@ -205,6 +216,7 @@ Feature-rich helpers pull in third-party dependencies that you only need when yo
 | `[http]` | `httpx` | `HTTPClient`, `RetryPolicy`, `CircuitOpenError`, OAuth2 / OIDC providers |
 | `[prometheus]` | `prometheus-client` | `PrometheusMiddleware`, `make_prometheus_router`, `make_prometheus_registry` |
 | `[mfa]` | `pyotp` | `TOTPHelper` + MFA/2FA endpoints on the bundled auth flow |
+| `[otel]` | `opentelemetry-sdk` + OTLP/gRPC exporter + FastAPI/SQLAlchemy/httpx instrumentors | `setup_tracing` — distributed tracing |
 | `[sqlite]` | `aiosqlite` | SQLite async driver for `sqlite+aiosqlite://` URLs (dev default) |
 | `[postgres]` | `asyncpg` | PostgreSQL async driver for `postgresql+asyncpg://` URLs (production) |
 | `[all]` | everything above | every helper |
@@ -226,10 +238,10 @@ Since `0.7.1` every optional dependency is imported lazily at first instantiatio
 | Module | Exports |
 | --- | --- |
 | `tempest_fastapi_sdk.schemas` | `BaseSchema`, `BaseResponseSchema`, `BasePaginationFilterSchema`, `BasePaginationSchema[T]`, `CursorPaginationFilterSchema`, `CursorPaginationSchema`, `LogEntrySchema`, `encode_cursor`, `decode_cursor`, `build_pagination_link_header` |
-| `tempest_fastapi_sdk.db` | `BaseModel`, `BaseUserModel`, `BaseUserTokenModel`, `BaseUserRecoveryCodeModel`, `make_user_recovery_code_model`, `UserTokenPurpose`, `BaseRepository[ModelType]`, `AsyncDatabaseManager`, `AlembicHelper`, `NAMING_CONVENTION`, `AuditMixin`, `SoftDeleteMixin`, `MFAMixin`, `BASE_COLUMN_ORDER`, `reorder_base_columns_first`, `compose_hooks` |
+| `tempest_fastapi_sdk.db` | `BaseModel`, `BaseUserModel`, `BaseUserTokenModel`, `BaseUserRecoveryCodeModel`, `make_user_recovery_code_model`, `UserTokenPurpose`, `BaseRepository[ModelType]`, `AsyncDatabaseManager`, `AlembicHelper`, `NAMING_CONVENTION`, `AuditMixin`, `SoftDeleteMixin`, `MFAMixin`, `BASE_COLUMN_ORDER`, `reorder_base_columns_first`, `compose_hooks`, `SlowQueryLogger` |
 | `tempest_fastapi_sdk.exceptions` | `AppException`, `NotFoundException`, `ConflictException`, `ValidationException`, `UnauthorizedException`, `ForbiddenException`, `InvalidTokenException`, `ExpiredTokenException`, `FileTooLargeException`, `InvalidFileTypeException`, `TooManyRequestsException` |
 | `tempest_fastapi_sdk.settings` | `BaseAppSettings`, `ServerSettings`, `LogSettings`, `DatabaseSettings`, `RedisSettings`, `RabbitMQSettings`, `JWTSettings`, `CORSSettings`, `EmailSettings`, `UploadSettings`, `TokenSettings`, `WebPushSettings`, `TaskIQSettings`, `MinIOSettings`, `AuthSettings` |
-| `tempest_fastapi_sdk.api` | `register_exception_handlers`, `app_exception_handler`, `apply_cors`, `make_health_router`, `make_logs_router`, `make_prometheus_router`, `make_prometheus_registry`, `PrometheusMiddleware`, `LogSource`, `make_tool_spec_router`, `make_token_dependency`, `make_bearer_token_dependency`, `make_jwt_user_dependency`, `make_role_dependency`, `make_permission_dependency`, `require_x_token`, `run_server`, `RequestIDMiddleware`, `RateLimitMiddleware`, `IdempotencyMiddleware`, `MemoryIdempotencyStore`, `RedisIdempotencyStore`, `BodySizeLimitMiddleware`, `CSRFMiddleware`, `make_csrf_token_dependency`, `WebhookSignatureVerifier`, `RSAWebhookSignatureVerifier`, OAuth2 (`GoogleOAuthClient`, `GitHubOAuthClient`, `OIDCProvider`), `HardenedStaticFiles`, `DEFAULT_STATIC_SECURITY_HEADERS`, `set_cookie`, `clear_cookie`, `SameSite`, `HealthCheck` |
+| `tempest_fastapi_sdk.api` | `register_exception_handlers`, `app_exception_handler`, `apply_cors`, `make_health_router`, `make_logs_router`, `make_prometheus_router`, `make_prometheus_registry`, `PrometheusMiddleware`, `LogSource`, `make_tool_spec_router`, `make_token_dependency`, `make_bearer_token_dependency`, `make_jwt_user_dependency`, `make_role_dependency`, `make_permission_dependency`, `require_x_token`, `run_server`, `RequestIDMiddleware`, `RateLimitMiddleware`, `IdempotencyMiddleware`, `MemoryIdempotencyStore`, `RedisIdempotencyStore`, `BodySizeLimitMiddleware`, `CSRFMiddleware`, `make_csrf_token_dependency`, `WebhookSignatureVerifier`, `RSAWebhookSignatureVerifier`, OAuth2 (`GoogleOAuthClient`, `GitHubOAuthClient`, `OIDCProvider`), `HardenedStaticFiles`, `DEFAULT_STATIC_SECURITY_HEADERS`, `set_cookie`, `clear_cookie`, `SameSite`, `HealthCheck`, `setup_tracing` *(extra: `[otel]`)* |
 | `tempest_fastapi_sdk.auth` *(extra: `[auth]`, opcional `[email]`, `[mfa]`)* | `UserAuthService`, `make_auth_router`, `SignupSchema` / `LoginSchema` / `PasswordResetRequestSchema` / `PasswordResetConfirmSchema` + responses, `ActivationToken`, `PasswordResetToken`, MFA schemas (`MFAEnrollResponseSchema` / `MFAConfirmSchema` / `MFAVerifySchema` / `MFADisableSchema`) — signup/activate/login/reset + TOTP 2FA out of the box |
 | `tempest_fastapi_sdk.controllers` | `BaseController` |
 | `tempest_fastapi_sdk.services` | `BaseService` |
@@ -3313,6 +3325,8 @@ tempest --help                                  # list every command
 tempest --version                               # show the SDK version
 ```
 
+On any usage error — unknown command, invalid option, missing required argument — the CLI prints that command's **full** `--help` (every parameter, default and description) right before the error line, instead of Click's terse `Try '... --help'` hint. The fix is on screen immediately.
+
 #### Scaffold a new service
 
 ```bash
@@ -3404,14 +3418,29 @@ tempest db history -v                            # revisions newest → oldest,
 Seeds or lists users via the project's concrete `UserModel` (default `src.db.models:UserModel`). Bootstraps the first admin row so `/admin` login works without manual SQL.
 
 ```bash
-tempest user create --email ana@example.com --password strong-pass-12
+tempest user create --email ana@example.com --password strong-pass-12 --no-admin
 tempest user create --email admin@local --password admin-pass-12 --admin
 tempest user create --email admin@local --admin       # prompt for password
 tempest user create --email x@y --password p --model myapp.models.user:User
+tempest user promote --email ana@example.com          # grant /admin access (is_admin=True)
+tempest user revoke  --email ana@example.com          # revoke it (is_admin=False)
 tempest user list                                     # everyone
 tempest user list --admin                             # admins only
 ```
 
+When `tempest user create` runs in an interactive terminal **without** `--admin`/`--no-admin`, it asks `Should this user be an administrator? [y/N]`. Non-interactive runs (CI, pipes) skip the prompt and create a regular user. `promote` / `revoke` look the user up by email (case-insensitive) and exit `1` with `no user found` when nothing matches.
+
+#### Generate artifacts in an existing project — `tempest generate`
+
+```bash
+tempest generate --docker                             # regen docker-compose.yaml + .env.example from pinned extras
+tempest generate --src                                # add the src layers triggered by pinned extras
+tempest generate --docker --src                       # both at once
+tempest generate --src --force                        # overwrite existing layer files
+```
+
+`--src` reads the SDK extras pinned in `pyproject.toml` and writes only the layers that match — `[queue]` → `src/queue/` (FastStream broker + handlers), `[tasks]` → `src/tasks/` (TaskIQ broker + jobs). The source root (`src` or `app`) is auto-detected. It is idempotent: existing files are kept unless `--force` is passed. `tempest new --extras auth,queue` already scaffolds those layers — `generate --src` is for extras added after the project exists.
+
 ### Admin site recipe
 
 Django-style management UI mounted under `/admin`. Operators sign in with a user row from the database (no separate admin password store) and browse every registered model from the browser, so the database port can stay closed on private networks. The panel is feature-complete (Django-admin parity): a list view with search / per-field filters / sortable columns, full CRUD (create / edit / delete), bulk actions, CSV/JSON export, FK-select widgets, a dashboard with live row counts + system metrics, optional TOTP MFA at login, and an audit trail stamping `created_by` / `updated_by`. Still on the roadmap: file upload and inline/related editing.

{tempest_fastapi_sdk-0.41.0 → tempest_fastapi_sdk-0.43.0}/README.md

@@ -114,6 +114,7 @@ Feature-rich helpers pull in third-party dependencies that you only need when yo
 | `[http]` | `httpx` | `HTTPClient`, `RetryPolicy`, `CircuitOpenError`, OAuth2 / OIDC providers |
 | `[prometheus]` | `prometheus-client` | `PrometheusMiddleware`, `make_prometheus_router`, `make_prometheus_registry` |
 | `[mfa]` | `pyotp` | `TOTPHelper` + MFA/2FA endpoints on the bundled auth flow |
+| `[otel]` | `opentelemetry-sdk` + OTLP/gRPC exporter + FastAPI/SQLAlchemy/httpx instrumentors | `setup_tracing` — distributed tracing |
 | `[sqlite]` | `aiosqlite` | SQLite async driver for `sqlite+aiosqlite://` URLs (dev default) |
 | `[postgres]` | `asyncpg` | PostgreSQL async driver for `postgresql+asyncpg://` URLs (production) |
 | `[all]` | everything above | every helper |
@@ -135,10 +136,10 @@ Since `0.7.1` every optional dependency is imported lazily at first instantiatio
 | Module | Exports |
 | --- | --- |
 | `tempest_fastapi_sdk.schemas` | `BaseSchema`, `BaseResponseSchema`, `BasePaginationFilterSchema`, `BasePaginationSchema[T]`, `CursorPaginationFilterSchema`, `CursorPaginationSchema`, `LogEntrySchema`, `encode_cursor`, `decode_cursor`, `build_pagination_link_header` |
-| `tempest_fastapi_sdk.db` | `BaseModel`, `BaseUserModel`, `BaseUserTokenModel`, `BaseUserRecoveryCodeModel`, `make_user_recovery_code_model`, `UserTokenPurpose`, `BaseRepository[ModelType]`, `AsyncDatabaseManager`, `AlembicHelper`, `NAMING_CONVENTION`, `AuditMixin`, `SoftDeleteMixin`, `MFAMixin`, `BASE_COLUMN_ORDER`, `reorder_base_columns_first`, `compose_hooks` |
+| `tempest_fastapi_sdk.db` | `BaseModel`, `BaseUserModel`, `BaseUserTokenModel`, `BaseUserRecoveryCodeModel`, `make_user_recovery_code_model`, `UserTokenPurpose`, `BaseRepository[ModelType]`, `AsyncDatabaseManager`, `AlembicHelper`, `NAMING_CONVENTION`, `AuditMixin`, `SoftDeleteMixin`, `MFAMixin`, `BASE_COLUMN_ORDER`, `reorder_base_columns_first`, `compose_hooks`, `SlowQueryLogger` |
 | `tempest_fastapi_sdk.exceptions` | `AppException`, `NotFoundException`, `ConflictException`, `ValidationException`, `UnauthorizedException`, `ForbiddenException`, `InvalidTokenException`, `ExpiredTokenException`, `FileTooLargeException`, `InvalidFileTypeException`, `TooManyRequestsException` |
 | `tempest_fastapi_sdk.settings` | `BaseAppSettings`, `ServerSettings`, `LogSettings`, `DatabaseSettings`, `RedisSettings`, `RabbitMQSettings`, `JWTSettings`, `CORSSettings`, `EmailSettings`, `UploadSettings`, `TokenSettings`, `WebPushSettings`, `TaskIQSettings`, `MinIOSettings`, `AuthSettings` |
-| `tempest_fastapi_sdk.api` | `register_exception_handlers`, `app_exception_handler`, `apply_cors`, `make_health_router`, `make_logs_router`, `make_prometheus_router`, `make_prometheus_registry`, `PrometheusMiddleware`, `LogSource`, `make_tool_spec_router`, `make_token_dependency`, `make_bearer_token_dependency`, `make_jwt_user_dependency`, `make_role_dependency`, `make_permission_dependency`, `require_x_token`, `run_server`, `RequestIDMiddleware`, `RateLimitMiddleware`, `IdempotencyMiddleware`, `MemoryIdempotencyStore`, `RedisIdempotencyStore`, `BodySizeLimitMiddleware`, `CSRFMiddleware`, `make_csrf_token_dependency`, `WebhookSignatureVerifier`, `RSAWebhookSignatureVerifier`, OAuth2 (`GoogleOAuthClient`, `GitHubOAuthClient`, `OIDCProvider`), `HardenedStaticFiles`, `DEFAULT_STATIC_SECURITY_HEADERS`, `set_cookie`, `clear_cookie`, `SameSite`, `HealthCheck` |
+| `tempest_fastapi_sdk.api` | `register_exception_handlers`, `app_exception_handler`, `apply_cors`, `make_health_router`, `make_logs_router`, `make_prometheus_router`, `make_prometheus_registry`, `PrometheusMiddleware`, `LogSource`, `make_tool_spec_router`, `make_token_dependency`, `make_bearer_token_dependency`, `make_jwt_user_dependency`, `make_role_dependency`, `make_permission_dependency`, `require_x_token`, `run_server`, `RequestIDMiddleware`, `RateLimitMiddleware`, `IdempotencyMiddleware`, `MemoryIdempotencyStore`, `RedisIdempotencyStore`, `BodySizeLimitMiddleware`, `CSRFMiddleware`, `make_csrf_token_dependency`, `WebhookSignatureVerifier`, `RSAWebhookSignatureVerifier`, OAuth2 (`GoogleOAuthClient`, `GitHubOAuthClient`, `OIDCProvider`), `HardenedStaticFiles`, `DEFAULT_STATIC_SECURITY_HEADERS`, `set_cookie`, `clear_cookie`, `SameSite`, `HealthCheck`, `setup_tracing` *(extra: `[otel]`)* |
 | `tempest_fastapi_sdk.auth` *(extra: `[auth]`, opcional `[email]`, `[mfa]`)* | `UserAuthService`, `make_auth_router`, `SignupSchema` / `LoginSchema` / `PasswordResetRequestSchema` / `PasswordResetConfirmSchema` + responses, `ActivationToken`, `PasswordResetToken`, MFA schemas (`MFAEnrollResponseSchema` / `MFAConfirmSchema` / `MFAVerifySchema` / `MFADisableSchema`) — signup/activate/login/reset + TOTP 2FA out of the box |
 | `tempest_fastapi_sdk.controllers` | `BaseController` |
 | `tempest_fastapi_sdk.services` | `BaseService` |
@@ -3222,6 +3223,8 @@ tempest --help                                  # list every command
 tempest --version                               # show the SDK version
 ```
 
+On any usage error — unknown command, invalid option, missing required argument — the CLI prints that command's **full** `--help` (every parameter, default and description) right before the error line, instead of Click's terse `Try '... --help'` hint. The fix is on screen immediately.
+
 #### Scaffold a new service
 
 ```bash
@@ -3313,14 +3316,29 @@ tempest db history -v                            # revisions newest → oldest,
 Seeds or lists users via the project's concrete `UserModel` (default `src.db.models:UserModel`). Bootstraps the first admin row so `/admin` login works without manual SQL.
 
 ```bash
-tempest user create --email ana@example.com --password strong-pass-12
+tempest user create --email ana@example.com --password strong-pass-12 --no-admin
 tempest user create --email admin@local --password admin-pass-12 --admin
 tempest user create --email admin@local --admin       # prompt for password
 tempest user create --email x@y --password p --model myapp.models.user:User
+tempest user promote --email ana@example.com          # grant /admin access (is_admin=True)
+tempest user revoke  --email ana@example.com          # revoke it (is_admin=False)
 tempest user list                                     # everyone
 tempest user list --admin                             # admins only
 ```
 
+When `tempest user create` runs in an interactive terminal **without** `--admin`/`--no-admin`, it asks `Should this user be an administrator? [y/N]`. Non-interactive runs (CI, pipes) skip the prompt and create a regular user. `promote` / `revoke` look the user up by email (case-insensitive) and exit `1` with `no user found` when nothing matches.
+
+#### Generate artifacts in an existing project — `tempest generate`
+
+```bash
+tempest generate --docker                             # regen docker-compose.yaml + .env.example from pinned extras
+tempest generate --src                                # add the src layers triggered by pinned extras
+tempest generate --docker --src                       # both at once
+tempest generate --src --force                        # overwrite existing layer files
+```
+
+`--src` reads the SDK extras pinned in `pyproject.toml` and writes only the layers that match — `[queue]` → `src/queue/` (FastStream broker + handlers), `[tasks]` → `src/tasks/` (TaskIQ broker + jobs). The source root (`src` or `app`) is auto-detected. It is idempotent: existing files are kept unless `--force` is passed. `tempest new --extras auth,queue` already scaffolds those layers — `generate --src` is for extras added after the project exists.
+
 ### Admin site recipe
 
 Django-style management UI mounted under `/admin`. Operators sign in with a user row from the database (no separate admin password store) and browse every registered model from the browser, so the database port can stay closed on private networks. The panel is feature-complete (Django-admin parity): a list view with search / per-field filters / sortable columns, full CRUD (create / edit / delete), bulk actions, CSV/JSON export, FK-select widgets, a dashboard with live row counts + system metrics, optional TOTP MFA at login, and an audit trail stamping `created_by` / `updated_by`. Still on the roadmap: file upload and inline/related editing.

{tempest_fastapi_sdk-0.41.0 → tempest_fastapi_sdk-0.43.0}/docs/recipes/cli.en.md

@@ -8,6 +8,19 @@ tempest --help                                  # list every command
 tempest --version                               # show the SDK version
 ```
 
+!!! tip "Usage error? The full help shows up with it"
+    When you type an unknown command, an invalid option, or forget a
+    required argument, `tempest` prints that command's **complete**
+    `--help` (every parameter, default and description) **before** the
+    error line — instead of Click's terse `Try '... --help'`. You fix
+    it on the spot, without re-running with `--help`.
+
+    ```bash
+    tempest user create            # forgot --email
+    # ... full `user create` help (every option) ...
+    # Error: Missing option '--email' / '-e'.
+    ```
+
 #### Scaffold a new service
 
 ```bash
@@ -135,7 +148,7 @@ Seed and list users using the project's concrete ``UserModel`` (default ``src.db
 
 ```bash
 # Create a regular user
-tempest user create --email ana@example.com --password strong-pass-12
+tempest user create --email ana@example.com --password strong-pass-12 --no-admin
 
 # Create an admin (can log into /admin)
 tempest user create --email admin@local --password admin-pass-12 --admin
@@ -146,11 +159,25 @@ tempest user create --email admin@local --admin
 # Custom model outside the scaffolded layout — MUST be a BaseUserModel subclass
 tempest user create --email x@y --password pass-12-chars --model myapp.models.user:UserModel
 
+# Promote / demote an existing user (toggles is_admin)
+tempest user promote --email ana@example.com    # becomes admin
+tempest user revoke  --email ana@example.com    # back to a regular account
+
 # List
 tempest user list                                # everyone
 tempest user list --admin                        # admins only
 ```
 
+!!! tip "Without `--admin`/`--no-admin`, create asks"
+    When you pass **neither** `--admin` nor `--no-admin` in an
+    interactive terminal, `tempest user create` prompts
+    `Should this user be an administrator? [y/N]`. Non-interactive runs
+    (CI, pipes, scripts) skip the prompt and create a regular user
+    (`is_admin=False`) — pass `--admin` explicitly to create an admin
+    without a TTY.
+
+`tempest user promote` / `tempest user revoke` find the user by email (case-insensitive) and only flip `is_admin`. When no user matches the email they exit with code 1 and a `no user found` message.
+
 ``DATABASE_URL`` resolves the same way as ``tempest db`` (env var > settings > alembic.ini).
 
 ### Regenerating `docker-compose.yaml` in an existing project
@@ -166,6 +193,31 @@ tempest generate --docker --force                # overwrite an existing compose
 
 The command reads ``[project] name`` + extras from the current directory's `pyproject.toml` (pass `--path` for another). It refuses to overwrite without `--force` so hand edits don't get clobbered. The `.env.example` addendum is idempotent — re-running does not duplicate service blocks.
 
+### Generating the `src` layers from extras — `tempest generate --src`
+
+The always-present layers (`api`, `controllers`, `services`, `schemas`, `db`, `core`, `utils`) ship in the scaffold. The layers that only make sense with a specific extra — `[queue]` (FastStream) and `[tasks]` (TaskIQ) — are **not** part of the base skeleton: dropping empty placeholder packages in every service contradicts the layout rules. When you add one of those extras to an existing project (`uv add "tempest-fastapi-sdk[queue]"`), generate the matching layer with:
+
+```bash
+tempest generate --src                           # read extras from local pyproject.toml
+tempest generate --src --extras tasks            # force explicit extras
+tempest generate --src --force                   # overwrite existing files
+tempest generate --docker --src                  # compose + layers in one shot
+```
+
+Extra → generated layer mapping:
+
+| Extra | Files created (under `src/` or `app/`) |
+|-------|------------------------------------------|
+| `[queue]` | `queue/__init__.py` (broker + `AsyncBrokerManager` + `get_broker`), `queue/handlers.py` (example subscriber) |
+| `[tasks]` | `tasks/__init__.py` (broker + `AsyncTaskBrokerManager` + `get_task_manager`), `tasks/jobs.py` (example task) |
+
+The source root (`src` or `app`) is auto-detected, and generated imports (`from src.queue import broker`) already point at it. The operation is **idempotent**: existing files are **kept** unless you pass `--force`, so a hand-edited handler is never clobbered silently — a sibling file that doesn't exist yet is still written. Extras with no associated layer (e.g. just `[cache]`) generate nothing and the command says so.
+
+!!! note "`tempest new` already generates the chosen extras' layers"
+    A `tempest new my_service --extras auth,queue` already ships
+    `src/queue/` — `generate --src` is for when you add the extra
+    **after** creating the project.
+
 After scaffolding:
 
 ```bash

{tempest_fastapi_sdk-0.41.0 → tempest_fastapi_sdk-0.43.0}/docs/recipes/cli.md

@@ -8,6 +8,19 @@ tempest --help                                  # lista todos os comandos
 tempest --version                               # mostra a versão do SDK
 ```
 
+!!! tip "Erro de uso? O help completo aparece junto"
+    Quando você digita um comando inexistente, uma opção inválida ou
+    esquece um argumento obrigatório, o `tempest` imprime o `--help`
+    **completo** daquele comando (todos os parâmetros, defaults e
+    descrições) **antes** da linha de erro — em vez do `Try '... --help'`
+    enxuto do Click. Você corrige na hora, sem reexecutar com `--help`.
+
+    ```bash
+    tempest user create            # esqueceu --email
+    # ... help completo do `user create` (todas as opções) ...
+    # Error: Missing option '--email' / '-e'.
+    ```
+
 #### Gerar um novo serviço
 
 ```bash
@@ -118,6 +131,31 @@ tempest generate --docker --force                # sobrescreve compose existente
 
 O comando lê o `[project] name` + extras do `pyproject.toml` do diretório atual (use `--path` pra outro). Recusa overwrite sem `--force` pra não pisar em edits manuais. O `.env.example` é atualizado de forma idempotente — re-rodar não duplica blocos.
 
+### Gerar as camadas `src` dos extras — `tempest generate --src`
+
+As camadas sempre presentes (`api`, `controllers`, `services`, `schemas`, `db`, `core`, `utils`) já vêm no scaffold. As camadas que só fazem sentido com um extra específico — `[queue]` (FastStream) e `[tasks]` (TaskIQ) — **não** entram no esqueleto base: deixar pacotes placeholder vazios em todo serviço contraria as regras de layout. Quando você adiciona um desses extras a um projeto existente (`uv add "tempest-fastapi-sdk[queue]"`), gere a camada correspondente com:
+
+```bash
+tempest generate --src                           # lê extras do pyproject.toml local
+tempest generate --src --extras tasks            # força extras explícitos
+tempest generate --src --force                   # sobrescreve arquivos existentes
+tempest generate --docker --src                  # compose + camadas numa tacada
+```
+
+Mapeamento extra → camada gerada:
+
+| Extra | Arquivos criados (sob `src/` ou `app/`) |
+|-------|------------------------------------------|
+| `[queue]` | `queue/__init__.py` (broker + `AsyncBrokerManager` + `get_broker`), `queue/handlers.py` (subscriber de exemplo) |
+| `[tasks]` | `tasks/__init__.py` (broker + `AsyncTaskBrokerManager` + `get_task_manager`), `tasks/jobs.py` (task de exemplo) |
+
+A raiz (`src` ou `app`) é detectada automaticamente, e os imports gerados (`from src.queue import broker`) já apontam pra ela. A operação é **idempotente**: arquivos existentes são **mantidos** a menos que você passe `--force`, então um handler editado à mão nunca é sobrescrito silenciosamente — o arquivo irmão que ainda não existe é criado normalmente. Extras sem camada associada (ex.: só `[cache]`) não geram nada e o comando avisa.
+
+!!! note "`tempest new` já gera as camadas dos extras escolhidos"
+    Um `tempest new my_service --extras auth,queue` já entrega
+    `src/queue/` pronto — o `generate --src` é pra quando você adiciona
+    o extra **depois** de criar o projeto.
+
 Depois de gerar:
 
 ```bash
@@ -158,7 +196,7 @@ Insere/lista usuários direto no banco usando o `UserModel` concreto do projeto
 
 ```bash
 # Cria usuário comum
-tempest user create --email ana@example.com --password senha-forte-12
+tempest user create --email ana@example.com --password senha-forte-12 --no-admin
 
 # Cria admin (pode logar no /admin)
 tempest user create --email admin@local --password admin-pass-12 --admin
@@ -169,11 +207,25 @@ tempest user create --email admin@local --admin
 # Modelo customizado fora do layout scaffoldado — DEVE ser subclasse de BaseUserModel
 tempest user create --email x@y --password pass-12-chars --model myapp.models.user:UserModel
 
+# Promove/rebaixa um usuário existente (liga/desliga is_admin)
+tempest user promote --email ana@example.com    # vira admin
+tempest user revoke  --email ana@example.com    # volta a ser comum
+
 # Lista
 tempest user list                                # todos
 tempest user list --admin                        # só admins
 ```
 
+!!! tip "Sem `--admin`/`--no-admin`, o create pergunta"
+    Quando você **não** passa nem `--admin` nem `--no-admin` num
+    terminal interativo, o `tempest user create` pergunta
+    `Should this user be an administrator? [y/N]`. Em execuções
+    não-interativas (CI, pipes, scripts) o prompt é pulado e o usuário
+    nasce comum (`is_admin=False`) — passe `--admin` explicitamente pra
+    criar admin sem TTY.
+
+`tempest user promote` / `tempest user revoke` localizam o usuário por email (case-insensitive) e só alternam `is_admin`. Quando nenhum usuário casa com o email, saem com código 1 e a mensagem `no user found`.
+
 Resolução do `DATABASE_URL` igual ao `tempest db` (env var > settings > alembic.ini).
 
 #### Gates de qualidade

{tempest_fastapi_sdk-0.41.0 → tempest_fastapi_sdk-0.43.0}/docs/recipes/index.en.md

@@ -19,6 +19,7 @@ Bite-sized "I want to wire X" walkthroughs. Each page starts with **what problem
 | **[Web Push »](webpush.md)** | `WebPushDispatcher`, VAPID schemas, broadcast with pruning |
 | **[Logging »](logging.md)** | `LogUtils`, structured JSON logging, request-ID propagation |
 | **[Metrics »](metrics.md)** | `MetricsUtils` — CPU / RAM / disk / GPU snapshots |
+| **[Observability (tracing) »](observability.md)** | `setup_tracing` (OpenTelemetry), `SlowQueryLogger` |
 | **[Admin site »](admin.md)** | `AdminSite`, `AdminModel`, `make_admin_router`, `BaseUserModel` |
 | **[Downloads »](downloads.md)** | `DownloadUtils` — `file_response`, `stream`, `build_content_disposition`, path-traversal safe |
 | **[Utilities »](utilities.md)** | `utcnow`/`to_utc`, `modify_dict`, `get_client_ip`, opaque tokens (`generate_opaque_token`) |

{tempest_fastapi_sdk-0.41.0 → tempest_fastapi_sdk-0.43.0}/docs/recipes/index.md

@@ -19,6 +19,7 @@ Passo a passo curtos no estilo "quero conectar X". Cada página começa com **qu
 | **[Web Push »](webpush.md)** | `WebPushDispatcher`, schemas VAPID, broadcast com poda |
 | **[Logging »](logging.md)** | `LogUtils`, logging JSON estruturado, propagação de request-ID |
 | **[Métricas »](metrics.md)** | `MetricsUtils` — snapshots de CPU / RAM / disco / GPU |
+| **[Observabilidade (tracing) »](observability.md)** | `setup_tracing` (OpenTelemetry), `SlowQueryLogger` |
 | **[Painel admin »](admin.md)** | `AdminSite`, `AdminModel`, `make_admin_router`, `BaseUserModel` |
 | **[Downloads »](downloads.md)** | `DownloadUtils` — `file_response`, `stream`, `build_content_disposition`, anti path-traversal |
 | **[Utilitários »](utilities.md)** | `utcnow`/`to_utc`, `modify_dict`, `get_client_ip`, tokens opacos (`generate_opaque_token`) |

tempest_fastapi_sdk-0.43.0/docs/recipes/observability.en.md

@@ -0,0 +1,163 @@
+# Observability (tracing + slow queries)
+
+Logs tell you **what** happened in a service; distributed tracing tells you
+**where** the time went on a request that crosses several services, and the
+`SlowQueryLogger` points at **which** query is dragging your p99. This
+recipe covers both.
+
+!!! info "Where this fits"
+    The [`RequestIDMiddleware`](http.md) correlates **logs** per request;
+    OpenTelemetry correlates **spans** across services. They complement each
+    other — use them together.
+
+## Distributed tracing with OpenTelemetry
+
+`setup_tracing` installs an OpenTelemetry provider and auto-instruments the
+common layers of a Tempest service: FastAPI (incoming requests), SQLAlchemy
+(queries), and httpx (outbound calls). Requires the `[otel]` extra:
+
+```bash
+pip install "tempest-fastapi-sdk[otel]"
+```
+
+Call it once at startup, after the app exists and (when you want to trace
+queries) after the database has connected:
+
+```python
+from fastapi import FastAPI
+
+from tempest_fastapi_sdk import AsyncDatabaseManager, setup_tracing
+
+app: FastAPI = FastAPI()
+db: AsyncDatabaseManager = AsyncDatabaseManager("postgresql+asyncpg://...")
+
+
+@app.on_event("startup")
+async def _startup() -> None:
+    """Connect the database and turn tracing on."""
+    await db.connect()
+    setup_tracing(
+        app,
+        service_name="orders-api",
+        otlp_endpoint="http://otel-collector:4317",
+        sqlalchemy_engine=db.engine,
+    )
+```
+
+That's it: every request becomes a parent span, every query and every httpx
+call becomes a child span, and the whole trace shows up in Jaeger / Tempo /
+Honeycomb under the name `orders-api`.
+
+### No collector (local debugging)
+
+Pass `otlp_endpoint=None` to install a console exporter — spans print to
+stdout, no collector required:
+
+```python
+from fastapi import FastAPI
+
+from tempest_fastapi_sdk import setup_tracing
+
+app: FastAPI = FastAPI()
+setup_tracing(app, service_name="orders-api", otlp_endpoint=None)
+```
+
+### Sampling
+
+In high-traffic production, tracing 100% of requests is expensive. Pass
+`sample_ratio` to sample a fraction (a head-based decision propagated to
+child spans):
+
+```python
+from fastapi import FastAPI
+
+from tempest_fastapi_sdk import setup_tracing
+
+app: FastAPI = FastAPI()
+setup_tracing(
+    app,
+    service_name="orders-api",
+    otlp_endpoint="http://otel-collector:4317",
+    sample_ratio=0.1,  # ~10% of requests
+    resource_attributes={"deployment.environment": "prod"},
+)
+```
+
+!!! tip "Arguments, not env vars"
+    The endpoint, the sampling and the attributes come from the function
+    **arguments** — the call site is the single source of truth. No
+    configuring half in code and half in `OTEL_*` env vars.
+
+!!! note "Best-effort instrumentation"
+    SQLAlchemy and httpx are only instrumented when the
+    `opentelemetry-instrumentation-sqlalchemy` / `...-httpx` packages are
+    installed (the `[otel]` extra ships both). If they are missing,
+    instrumentation is silently skipped instead of breaking boot.
+
+## Slow query logger
+
+`SlowQueryLogger` registers a listener on the SQLAlchemy engine events and
+emits a log line whenever a statement exceeds a configurable threshold. It
+is the cheapest way to find the N+1 or the missing index. **No extra
+needed** — it uses only SQLAlchemy.
+
+```python
+import logging
+
+from tempest_fastapi_sdk import AsyncDatabaseManager, SlowQueryLogger
+
+db: AsyncDatabaseManager = AsyncDatabaseManager("postgresql+asyncpg://...")
+
+
+async def wire_slow_query_log() -> None:
+    """Turn slow-query logging on at startup."""
+    await db.connect()
+    slow: SlowQueryLogger = SlowQueryLogger(
+        db.engine,
+        threshold_ms=200.0,       # logs queries >= 200ms
+        level=logging.WARNING,
+    )
+    slow.attach()
+```
+
+Each slow query becomes a line like:
+
+```text
+WARNING ... slow query: 312.4ms >= 200.0ms threshold | SELECT users.id, ...
+```
+
+### Parameters and EXPLAIN (dev only)
+
+By default, bind parameters are **not** logged (they often carry
+PII/secrets). In development, turn on `log_parameters=True` and/or
+`explain=True` to see the execution plan:
+
+```python
+import logging
+
+from tempest_fastapi_sdk import SlowQueryLogger
+
+slow: SlowQueryLogger = SlowQueryLogger(
+    db.engine,
+    threshold_ms=50.0,
+    log_parameters=True,  # include the binds — dev only
+    explain=True,         # run EXPLAIN and append the plan — costs 1 round-trip
+)
+slow.attach()
+```
+
+!!! warning "EXPLAIN costs a round-trip"
+    With `explain=True` every slow query fires an extra `EXPLAIN`. Keep it
+    off in production, turn it on only while hunting a bad plan.
+
+To turn it off (e.g. on shutdown or in a test), call `slow.detach()`.
+
+## Recap
+
+- `setup_tracing(app, service_name=..., otlp_endpoint=...)` turns on
+  distributed tracing with FastAPI/SQLAlchemy/httpx auto-instrumentation —
+  `[otel]` extra.
+- `otlp_endpoint=None` exports spans to the console (local debugging);
+  `sample_ratio` controls sampling.
+- `SlowQueryLogger(engine, threshold_ms=...).attach()` logs slow queries
+  with no extra at all; parameters and `EXPLAIN` sit behind opt-in flags.