tempest-fastapi-sdk 0.76.0__tar.gz → 0.78.0__tar.gz

{tempest_fastapi_sdk-0.76.0 → tempest_fastapi_sdk-0.78.0}/CHANGELOG.md

@@ -5,6 +5,36 @@ 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.78.0] — 2026-06-27
+
+### Added
+
+- **`BaseService.update` (and `BaseController.update`).** The service
+  skeleton now ships a generic update method: fetch by primary key, copy
+  the fields present in the payload (`data.to_dict()`, which drops unset
+  and ``None`` values) onto the instance, persist via
+  ``repository.update`` and return the mapped response. Because unset
+  fields are skipped, the same method serves full (PUT) and partial
+  (PATCH) updates. ``BaseController.update`` forwards to it, matching the
+  existing pass-through layer. Override either when an update needs
+  orchestration.
+
+## [0.77.0] — 2026-06-27
+
+### Added
+
+- **Generic validated field types (`tempest_fastapi_sdk.utils.fields`).**
+  A base set of `Annotated` Pydantic types that bake a validation rule
+  into the type, following the `*Field` convention (so the schema reads as
+  what it is instead of repeating `Field(gt=0, ...)`): integers
+  `PositiveIntField`, `NonNegativeIntField`, `CentsField` (money in minor
+  units), `PortField`; floats `PositiveFloatField`, `NonNegativeFloatField`,
+  `PercentField` (0..100), `RatioField` (0..1), `LatitudeField`,
+  `LongitudeField`; `PriceField` (non-negative `Decimal`, 2 places); and
+  strings `NonEmptyStrField` (trim + non-empty), `SlugField`,
+  `HexColorField`. Exported from `tempest_fastapi_sdk` and
+  `tempest_fastapi_sdk.utils`.
+
 ## [0.76.0] — 2026-06-27
 
 ### Changed

{tempest_fastapi_sdk-0.76.0 → tempest_fastapi_sdk-0.78.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tempest-fastapi-sdk
-Version: 0.76.0
+Version: 0.78.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
@@ -259,7 +259,7 @@ Since `0.7.1` every optional dependency is imported lazily at first instantiatio
 | `tempest_fastapi_sdk.utils.http_client` *(extra: `[http]`)* | `HTTPClient`, `RetryPolicy`, `CircuitOpenError`, `REQUEST_ID_HEADER` — typed httpx wrapper |
 | `tempest_fastapi_sdk.utils.storage_backends` *(extra: `[upload]`)* | `UploadStorage` protocol, `LocalUploadStorage`, `MinIOUploadStorage`, `UploadResult`, `ContentValidator` |
 | `tempest_fastapi_sdk.tasks` *(extra: `[tasks]`)* | `AsyncTaskBrokerManager` (TaskIQ lifecycle wrapper), `AsyncTaskScheduler` (periodic / cron tasks) |
-| `tempest_fastapi_sdk.utils` | `to_utc`, `utcnow`, `modify_dict`, `LogUtils`, `AttemptThrottle`/`ThrottleBackend`/`ThrottleStatus`, `generate_opaque_token`/`hash_opaque_token`/`verify_opaque_token`, `get_client_ip`/`get_client_ip_from_scope`, `PasswordUtils` *(extra: `[auth]`)*, `JWTUtils` *(extra: `[auth]`)*, `TOTPHelper` *(extra: `[mfa]`)*, `EmailUtils` *(extra: `[email]`)*, `UploadUtils`/`sniff_mime` *(extra: `[upload]`)*, `DownloadUtils`/`build_content_disposition` *(no extra)*, `MetricsUtils`/`CPUMetrics`/`MemoryMetrics`/`DiskMetrics`/`GPUMetrics`/`SystemMetrics` *(extra: `[metrics]`)*, BR regex helpers (`CPFField`, `CNPJField`, `CPFOrCNPJField`, `PhoneBRField`, `CEPField` — old names without the suffix kept as deprecated aliases — `is_valid_*`, `normalize_*`, `only_digits`, `*_PATTERN`), BR states/cities (`UF`, `Region`, `StateBR`, `CityBR`, `ChoiceBR`, `UFField`, `CityNameField`, `list_states`, `get_state`, `cities_by_uf`, `states_by_region`, `uf_choices`/`region_choices`/`city_choices`, `is_valid_uf`/`normalize_uf`, `is_valid_city`/`normalize_city`) |
+| `tempest_fastapi_sdk.utils` | `to_utc`, `utcnow`, `modify_dict`, `LogUtils`, `AttemptThrottle`/`ThrottleBackend`/`ThrottleStatus`, `generate_opaque_token`/`hash_opaque_token`/`verify_opaque_token`, `get_client_ip`/`get_client_ip_from_scope`, `PasswordUtils` *(extra: `[auth]`)*, `JWTUtils` *(extra: `[auth]`)*, `TOTPHelper` *(extra: `[mfa]`)*, `EmailUtils` *(extra: `[email]`)*, `UploadUtils`/`sniff_mime` *(extra: `[upload]`)*, `DownloadUtils`/`build_content_disposition` *(no extra)*, `MetricsUtils`/`CPUMetrics`/`MemoryMetrics`/`DiskMetrics`/`GPUMetrics`/`SystemMetrics` *(extra: `[metrics]`)*, validated field types (`PositiveIntField`, `NonNegativeIntField`, `CentsField`, `PortField`, `PositiveFloatField`, `NonNegativeFloatField`, `PercentField`, `RatioField`, `LatitudeField`, `LongitudeField`, `PriceField`, `NonEmptyStrField`, `SlugField`, `HexColorField`), BR regex helpers (`CPFField`, `CNPJField`, `CPFOrCNPJField`, `PhoneBRField`, `CEPField` — old names without the suffix kept as deprecated aliases — `is_valid_*`, `normalize_*`, `only_digits`, `*_PATTERN`), BR states/cities (`UF`, `Region`, `StateBR`, `CityBR`, `ChoiceBR`, `UFField`, `CityNameField`, `list_states`, `get_state`, `cities_by_uf`, `states_by_region`, `uf_choices`/`region_choices`/`city_choices`, `is_valid_uf`/`normalize_uf`, `is_valid_city`/`normalize_city`) |
 | `tempest_fastapi_sdk.cli` | `tempest` console script — `new <name>` (scaffold layered service), `lint` / `format` / `fmt-check` / `type` / `test` / `check` (run preferred quality gates), `version` / `--version` |
 
 Core primitives are re-exported from `tempest_fastapi_sdk` at the top level — `from tempest_fastapi_sdk import BaseModel, BaseRepository, AppException` always works. The extras-gated managers in `tempest_fastapi_sdk.cache`, `tempest_fastapi_sdk.queue` and `tempest_fastapi_sdk.tasks` must be imported from their own submodule (`from tempest_fastapi_sdk.queue import AsyncBrokerManager`).
@@ -714,7 +714,7 @@ The highlighted block (under the divider comment) is what you typically add per
 
 The service is where business rules live. It calls one or more repositories and never touches HTTP or SQLAlchemy types directly.
 
-Inherit from `BaseService[RepositoryT, ResponseT]`. Doing so gives you `get_by_id`, `get_or_none`, `list`, `paginate`, `count`, `exists` and `delete` for free — every one is already wired to `repository.map_to_response` (sync or async). Override only the methods that need domain logic; add new ones for use cases the base doesn't cover (signup, password reset, etc.):
+Inherit from `BaseService[RepositoryT, ResponseT]`. Doing so gives you `get_by_id`, `get_or_none`, `list`, `paginate`, `count`, `exists`, `update` and `delete` for free — every one is already wired to `repository.map_to_response` (sync or async). Override only the methods that need domain logic; add new ones for use cases the base doesn't cover (signup, password reset, etc.):
 
 ```python
 # src/services/user.py
@@ -811,7 +811,7 @@ class UserService(BaseService[UserRepository, UserResponseSchema]):
 
 Even when there's no orchestration to do, `controllers/` exists as a **thin pass-through** so the import graph stays uniform across services. The day a use case needs to coordinate two services (or fan out to a queue), the controller is already there.
 
-Inherit from `BaseController[ServiceT, ResponseT]`. The base forwards `get_by_id`, `list`, `paginate`, `count` and `delete` to the service for you — you only declare methods that add cross-service coordination or that don't exist on the service (custom use cases like `signup`):
+Inherit from `BaseController[ServiceT, ResponseT]`. The base forwards `get_by_id`, `list`, `paginate`, `count`, `update` and `delete` to the service for you — you only declare methods that add cross-service coordination or that don't exist on the service (custom use cases like `signup`):
 
 ```python
 # src/controllers/user.py
@@ -2136,6 +2136,7 @@ What you inherit by subclassing `BaseService[RepositoryT, ResponseT]`:
 | `paginate(filters=None, order_by=None, page=1, page_size=20, ascending=True)` | `dict` with mapped `items` + `total`/`page`/`size`/`pages`. | Offset pagination via `repository.paginate`. |
 | `count(filters=None)` | `int` | Pass-through to `repository.count`. |
 | `exists(filters)` | `bool` | Pass-through to `repository.exists`. |
+| `update(id, data)` | `ResponseT` | Fetch by id, copy the fields present in `data` (a `BaseSchema`) onto the row, persist, map. `to_dict()` drops unset/`None`, so it serves PUT and PATCH alike. |
 | `delete(id)` | `None` | Hard delete via `repository.delete`. |
 
 `map_to_response` is `await`-ed when it returns a coroutine, so async mappers work transparently — no method override needed.
@@ -2148,6 +2149,7 @@ What you inherit by subclassing `BaseController[ServiceT, ResponseT]`:
 | `list(filters, order_by, ascending)` | `service.list` | Same. |
 | `paginate(filters, order_by, page, page_size, ascending)` | `service.paginate` | Same. |
 | `count(filters)` | `service.count` | Same. |
+| `update(id, data)` | `service.update` | Same. |
 | `delete(id)` | `service.delete` | Same. |
 
 When a use case needs domain rules, override the inherited method in the service. When a use case needs to coordinate more than one service, override the inherited method (or add a new one) in the controller. The router never grows — it only depends on the controller.

{tempest_fastapi_sdk-0.76.0 → tempest_fastapi_sdk-0.78.0}/README.md

@@ -156,7 +156,7 @@ Since `0.7.1` every optional dependency is imported lazily at first instantiatio
 | `tempest_fastapi_sdk.utils.http_client` *(extra: `[http]`)* | `HTTPClient`, `RetryPolicy`, `CircuitOpenError`, `REQUEST_ID_HEADER` — typed httpx wrapper |
 | `tempest_fastapi_sdk.utils.storage_backends` *(extra: `[upload]`)* | `UploadStorage` protocol, `LocalUploadStorage`, `MinIOUploadStorage`, `UploadResult`, `ContentValidator` |
 | `tempest_fastapi_sdk.tasks` *(extra: `[tasks]`)* | `AsyncTaskBrokerManager` (TaskIQ lifecycle wrapper), `AsyncTaskScheduler` (periodic / cron tasks) |
-| `tempest_fastapi_sdk.utils` | `to_utc`, `utcnow`, `modify_dict`, `LogUtils`, `AttemptThrottle`/`ThrottleBackend`/`ThrottleStatus`, `generate_opaque_token`/`hash_opaque_token`/`verify_opaque_token`, `get_client_ip`/`get_client_ip_from_scope`, `PasswordUtils` *(extra: `[auth]`)*, `JWTUtils` *(extra: `[auth]`)*, `TOTPHelper` *(extra: `[mfa]`)*, `EmailUtils` *(extra: `[email]`)*, `UploadUtils`/`sniff_mime` *(extra: `[upload]`)*, `DownloadUtils`/`build_content_disposition` *(no extra)*, `MetricsUtils`/`CPUMetrics`/`MemoryMetrics`/`DiskMetrics`/`GPUMetrics`/`SystemMetrics` *(extra: `[metrics]`)*, BR regex helpers (`CPFField`, `CNPJField`, `CPFOrCNPJField`, `PhoneBRField`, `CEPField` — old names without the suffix kept as deprecated aliases — `is_valid_*`, `normalize_*`, `only_digits`, `*_PATTERN`), BR states/cities (`UF`, `Region`, `StateBR`, `CityBR`, `ChoiceBR`, `UFField`, `CityNameField`, `list_states`, `get_state`, `cities_by_uf`, `states_by_region`, `uf_choices`/`region_choices`/`city_choices`, `is_valid_uf`/`normalize_uf`, `is_valid_city`/`normalize_city`) |
+| `tempest_fastapi_sdk.utils` | `to_utc`, `utcnow`, `modify_dict`, `LogUtils`, `AttemptThrottle`/`ThrottleBackend`/`ThrottleStatus`, `generate_opaque_token`/`hash_opaque_token`/`verify_opaque_token`, `get_client_ip`/`get_client_ip_from_scope`, `PasswordUtils` *(extra: `[auth]`)*, `JWTUtils` *(extra: `[auth]`)*, `TOTPHelper` *(extra: `[mfa]`)*, `EmailUtils` *(extra: `[email]`)*, `UploadUtils`/`sniff_mime` *(extra: `[upload]`)*, `DownloadUtils`/`build_content_disposition` *(no extra)*, `MetricsUtils`/`CPUMetrics`/`MemoryMetrics`/`DiskMetrics`/`GPUMetrics`/`SystemMetrics` *(extra: `[metrics]`)*, validated field types (`PositiveIntField`, `NonNegativeIntField`, `CentsField`, `PortField`, `PositiveFloatField`, `NonNegativeFloatField`, `PercentField`, `RatioField`, `LatitudeField`, `LongitudeField`, `PriceField`, `NonEmptyStrField`, `SlugField`, `HexColorField`), BR regex helpers (`CPFField`, `CNPJField`, `CPFOrCNPJField`, `PhoneBRField`, `CEPField` — old names without the suffix kept as deprecated aliases — `is_valid_*`, `normalize_*`, `only_digits`, `*_PATTERN`), BR states/cities (`UF`, `Region`, `StateBR`, `CityBR`, `ChoiceBR`, `UFField`, `CityNameField`, `list_states`, `get_state`, `cities_by_uf`, `states_by_region`, `uf_choices`/`region_choices`/`city_choices`, `is_valid_uf`/`normalize_uf`, `is_valid_city`/`normalize_city`) |
 | `tempest_fastapi_sdk.cli` | `tempest` console script — `new <name>` (scaffold layered service), `lint` / `format` / `fmt-check` / `type` / `test` / `check` (run preferred quality gates), `version` / `--version` |
 
 Core primitives are re-exported from `tempest_fastapi_sdk` at the top level — `from tempest_fastapi_sdk import BaseModel, BaseRepository, AppException` always works. The extras-gated managers in `tempest_fastapi_sdk.cache`, `tempest_fastapi_sdk.queue` and `tempest_fastapi_sdk.tasks` must be imported from their own submodule (`from tempest_fastapi_sdk.queue import AsyncBrokerManager`).
@@ -611,7 +611,7 @@ The highlighted block (under the divider comment) is what you typically add per
 
 The service is where business rules live. It calls one or more repositories and never touches HTTP or SQLAlchemy types directly.
 
-Inherit from `BaseService[RepositoryT, ResponseT]`. Doing so gives you `get_by_id`, `get_or_none`, `list`, `paginate`, `count`, `exists` and `delete` for free — every one is already wired to `repository.map_to_response` (sync or async). Override only the methods that need domain logic; add new ones for use cases the base doesn't cover (signup, password reset, etc.):
+Inherit from `BaseService[RepositoryT, ResponseT]`. Doing so gives you `get_by_id`, `get_or_none`, `list`, `paginate`, `count`, `exists`, `update` and `delete` for free — every one is already wired to `repository.map_to_response` (sync or async). Override only the methods that need domain logic; add new ones for use cases the base doesn't cover (signup, password reset, etc.):
 
 ```python
 # src/services/user.py
@@ -708,7 +708,7 @@ class UserService(BaseService[UserRepository, UserResponseSchema]):
 
 Even when there's no orchestration to do, `controllers/` exists as a **thin pass-through** so the import graph stays uniform across services. The day a use case needs to coordinate two services (or fan out to a queue), the controller is already there.
 
-Inherit from `BaseController[ServiceT, ResponseT]`. The base forwards `get_by_id`, `list`, `paginate`, `count` and `delete` to the service for you — you only declare methods that add cross-service coordination or that don't exist on the service (custom use cases like `signup`):
+Inherit from `BaseController[ServiceT, ResponseT]`. The base forwards `get_by_id`, `list`, `paginate`, `count`, `update` and `delete` to the service for you — you only declare methods that add cross-service coordination or that don't exist on the service (custom use cases like `signup`):
 
 ```python
 # src/controllers/user.py
@@ -2033,6 +2033,7 @@ What you inherit by subclassing `BaseService[RepositoryT, ResponseT]`:
 | `paginate(filters=None, order_by=None, page=1, page_size=20, ascending=True)` | `dict` with mapped `items` + `total`/`page`/`size`/`pages`. | Offset pagination via `repository.paginate`. |
 | `count(filters=None)` | `int` | Pass-through to `repository.count`. |
 | `exists(filters)` | `bool` | Pass-through to `repository.exists`. |
+| `update(id, data)` | `ResponseT` | Fetch by id, copy the fields present in `data` (a `BaseSchema`) onto the row, persist, map. `to_dict()` drops unset/`None`, so it serves PUT and PATCH alike. |
 | `delete(id)` | `None` | Hard delete via `repository.delete`. |
 
 `map_to_response` is `await`-ed when it returns a coroutine, so async mappers work transparently — no method override needed.
@@ -2045,6 +2046,7 @@ What you inherit by subclassing `BaseController[ServiceT, ResponseT]`:
 | `list(filters, order_by, ascending)` | `service.list` | Same. |
 | `paginate(filters, order_by, page, page_size, ascending)` | `service.paginate` | Same. |
 | `count(filters)` | `service.count` | Same. |
+| `update(id, data)` | `service.update` | Same. |
 | `delete(id)` | `service.delete` | Same. |
 
 When a use case needs domain rules, override the inherited method in the service. When a use case needs to coordinate more than one service, override the inherited method (or add a new one) in the controller. The router never grows — it only depends on the controller.

{tempest_fastapi_sdk-0.76.0 → tempest_fastapi_sdk-0.78.0}/docs/architecture.en.md

@@ -147,6 +147,7 @@ What you inherit by subclassing `BaseService[RepositoryT, ResponseT]`:
 | `paginate(filters=None, order_by=None, page=1, page_size=20, ascending=True)` | `dict` with mapped `items` + `total`/`page`/`page_size`/`pages`. | Offset pagination via `repository.paginate`. |
 | `count(filters=None)` | `int` | Pass-through to `repository.count`. |
 | `exists(filters)` | `bool` | Pass-through to `repository.exists`. |
+| `update(id, data)` | `ResponseT` | Fetch by id, copy the fields present in `data` (a `BaseSchema`) onto the row, persist, map. `to_dict()` drops unset/`None`, so it serves PUT and PATCH. |
 | `delete(id)` | `None` | Hard delete via `repository.delete`. |
 
 `map_to_response` is `await`-ed when it returns a coroutine, so async mappers work transparently — no method override needed.
@@ -159,6 +160,7 @@ What you inherit by subclassing `BaseController[ServiceT, ResponseT]`:
 | `list(filters, order_by, ascending)` | `service.list` | Same. |
 | `paginate(filters, order_by, page, page_size, ascending)` | `service.paginate` | Same. |
 | `count(filters)` | `service.count` | Same. |
+| `update(id, data)` | `service.update` | Same. |
 | `delete(id)` | `service.delete` | Same. |
 
 When a use case needs domain rules, override the inherited method in the service. When a use case needs to coordinate more than one service, override the inherited method (or add a new one) in the controller. The router never grows — it only depends on the controller.

{tempest_fastapi_sdk-0.76.0 → tempest_fastapi_sdk-0.78.0}/docs/architecture.md

@@ -147,6 +147,7 @@ O que você herda ao subclassear `BaseService[RepositoryT, ResponseT]`:
 | `paginate(filters=None, order_by=None, page=1, page_size=20, ascending=True)` | `dict` com `items` mapeados + `total`/`page`/`page_size`/`pages`. | Paginação por offset via `repository.paginate`. |
 | `count(filters=None)` | `int` | Pass-through para `repository.count`. |
 | `exists(filters)` | `bool` | Pass-through para `repository.exists`. |
+| `update(id, data)` | `ResponseT` | Busca por id, copia os campos presentes em `data` (um `BaseSchema`) na instância, persiste e mapeia. `to_dict()` descarta unset/`None`, então serve PUT e PATCH. |
 | `delete(id)` | `None` | Hard delete via `repository.delete`. |
 
 `map_to_response` é aguardado com `await` quando retorna uma coroutine, então mappers async funcionam de forma transparente — sem precisar sobrescrever o método.
@@ -159,6 +160,7 @@ O que você herda ao subclassear `BaseController[ServiceT, ResponseT]`:
 | `list(filters, order_by, ascending)` | `service.list` | Igual. |
 | `paginate(filters, order_by, page, page_size, ascending)` | `service.paginate` | Igual. |
 | `count(filters)` | `service.count` | Igual. |
+| `update(id, data)` | `service.update` | Igual. |
 | `delete(id)` | `service.delete` | Igual. |
 
 Quando um caso de uso precisa de regras de domínio, sobrescreva o método herdado no service. Quando um caso de uso precisa coordenar mais de um service, sobrescreva o método herdado (ou adicione um novo) no controller. O router nunca cresce — ele só depende do controller.

tempest_fastapi_sdk-0.78.0/docs/recipes/fields.en.md

@@ -0,0 +1,88 @@
+# Validated fields (ready-made types)
+
+Instead of repeating `Field(gt=0, ...)` on every schema, the SDK ships
+`Annotated` types with the validation rule baked in — the field becomes
+**self-describing**. They follow the same `*Field` convention as the BR
+fields (`CPFField`, `UFField`, ...): anything ending in `Field` is a
+ready-to-use schema field type. Invalid values raise `ValidationError` ->
+HTTP 422 via the SDK exception handler.
+
+```python
+from tempest_fastapi_sdk import BaseSchema
+from tempest_fastapi_sdk.utils import CentsField, PercentField, SlugField
+
+
+class ProductCreateSchema(BaseSchema):
+    slug: SlugField              # lowercase kebab-case
+    price_cents: CentsField      # int >= 0 (money in cents)
+    discount: PercentField       # float in [0, 100]
+```
+
+## Integers
+
+| Type | Rule | Use |
+| --- | --- | --- |
+| `PositiveIntField` | `> 0` | quantities, counts, 1-based ids |
+| `NonNegativeIntField` | `>= 0` | counters that reset to zero |
+| `CentsField` | `>= 0` | money in minor units (cents) |
+| `PortField` | `1..65535` | TCP/UDP port |
+
+!!! tip "Money in cents"
+    Store monetary values as an **integer of cents** (`CentsField`) to
+    dodge binary float rounding. Divide by 100 only at the presentation
+    edge. When the contract requires an exact decimal (e.g. a gateway
+    payload), use `PriceField`.
+
+## Floats
+
+| Type | Rule |
+| --- | --- |
+| `PositiveFloatField` | `> 0` |
+| `NonNegativeFloatField` | `>= 0` |
+| `PercentField` | `0..100` |
+| `RatioField` | `0..1` (fractions/probabilities) |
+| `LatitudeField` | `-90..90` |
+| `LongitudeField` | `-180..180` |
+
+## Decimals
+
+`PriceField` is a non-negative `Decimal` with 2 places:
+
+```python
+from tempest_fastapi_sdk import BaseSchema
+from tempest_fastapi_sdk.utils import PriceField
+
+
+class InvoiceSchema(BaseSchema):
+    total: PriceField     # "9.99" -> Decimal("9.99"); "1.999" and "-1" rejected
+```
+
+## Strings
+
+| Type | Rule |
+| --- | --- |
+| `NonEmptyStrField` | trims whitespace and rejects empty (whitespace-only too) |
+| `SlugField` | lowercase kebab-case (`my-post-1`) |
+| `HexColorField` | CSS hex color (`#fff` or `#abc123`) |
+
+```python
+from tempest_fastapi_sdk import BaseSchema
+from tempest_fastapi_sdk.utils import HexColorField, NonEmptyStrField, SlugField
+
+
+class CategorySchema(BaseSchema):
+    name: NonEmptyStrField     # "  Drinks " -> "Drinks"; "   " rejected
+    slug: SlugField
+    color: HexColorField
+```
+
+## Recap
+
+- Everything is `Annotated[..., rule]` with a `*Field` suffix —
+  self-describing, no repeated `Field(...)` in the schema.
+- Integers: `PositiveIntField`, `NonNegativeIntField`, `CentsField`, `PortField`.
+- Floats: `PositiveFloatField`, `NonNegativeFloatField`, `PercentField`,
+  `RatioField`, `LatitudeField`, `LongitudeField`.
+- Decimal: `PriceField` (2 places, `>= 0`).
+- Strings: `NonEmptyStrField`, `SlugField`, `HexColorField`.
+- Money: prefer `CentsField` (integer) for storage; `PriceField` for a decimal contract.

tempest_fastapi_sdk-0.78.0/docs/recipes/fields.md

@@ -0,0 +1,88 @@
+# Campos validados (tipos prontos)
+
+Em vez de repetir `Field(gt=0, ...)` em cada schema, o SDK traz tipos
+`Annotated` com a regra de validação embutida — o campo passa a se
+**autodescrever**. Seguem a mesma convenção `*Field` dos campos BR
+(`CPFField`, `UFField`, ...): tudo que termina em `Field` é um tipo de
+campo pronto pra schema. Valor inválido vira `ValidationError` → HTTP 422
+pelo handler do SDK.
+
+```python
+from tempest_fastapi_sdk import BaseSchema
+from tempest_fastapi_sdk.utils import CentsField, PercentField, SlugField
+
+
+class ProductCreateSchema(BaseSchema):
+    slug: SlugField              # kebab-case minúsculo
+    price_cents: CentsField      # int >= 0 (dinheiro em centavos)
+    discount: PercentField       # float em [0, 100]
+```
+
+## Inteiros
+
+| Tipo | Regra | Uso |
+| --- | --- | --- |
+| `PositiveIntField` | `> 0` | quantidades, contagens, ids 1-based |
+| `NonNegativeIntField` | `>= 0` | contadores que zeram |
+| `CentsField` | `>= 0` | dinheiro em unidades menores (centavos) |
+| `PortField` | `1..65535` | porta TCP/UDP |
+
+!!! tip "Dinheiro em centavos"
+    Guarde valores monetários como **inteiro de centavos** (`CentsField`)
+    pra fugir do arredondamento de float binário. Divida por 100 só na
+    borda de apresentação. Quando o contrato exige decimal exato (ex.:
+    payload de gateway), use `PriceField`.
+
+## Floats
+
+| Tipo | Regra |
+| --- | --- |
+| `PositiveFloatField` | `> 0` |
+| `NonNegativeFloatField` | `>= 0` |
+| `PercentField` | `0..100` |
+| `RatioField` | `0..1` (frações/probabilidades) |
+| `LatitudeField` | `-90..90` |
+| `LongitudeField` | `-180..180` |
+
+## Decimais
+
+`PriceField` é um `Decimal` não-negativo com 2 casas:
+
+```python
+from tempest_fastapi_sdk import BaseSchema
+from tempest_fastapi_sdk.utils import PriceField
+
+
+class InvoiceSchema(BaseSchema):
+    total: PriceField     # "9.99" -> Decimal("9.99"); "1.999" e "-1" rejeitados
+```
+
+## Strings
+
+| Tipo | Regra |
+| --- | --- |
+| `NonEmptyStrField` | apara espaços e rejeita vazio (só-espaço também) |
+| `SlugField` | kebab-case minúsculo (`meu-post-1`) |
+| `HexColorField` | cor hex CSS (`#fff` ou `#abc123`) |
+
+```python
+from tempest_fastapi_sdk import BaseSchema
+from tempest_fastapi_sdk.utils import HexColorField, NonEmptyStrField, SlugField
+
+
+class CategorySchema(BaseSchema):
+    name: NonEmptyStrField     # "  Bebidas " -> "Bebidas"; "   " rejeitado
+    slug: SlugField
+    color: HexColorField
+```
+
+## Recap
+
+- Tudo `Annotated[..., regra]`, com sufixo `*Field` — autodescritivo,
+  sem repetir `Field(...)` no schema.
+- Inteiros: `PositiveIntField`, `NonNegativeIntField`, `CentsField`, `PortField`.
+- Floats: `PositiveFloatField`, `NonNegativeFloatField`, `PercentField`,
+  `RatioField`, `LatitudeField`, `LongitudeField`.
+- Decimal: `PriceField` (2 casas, `>= 0`).
+- Strings: `NonEmptyStrField`, `SlugField`, `HexColorField`.
+- Dinheiro: prefira `CentsField` (inteiro) pra guardar; `PriceField` no contrato decimal.

{tempest_fastapi_sdk-0.76.0 → tempest_fastapi_sdk-0.78.0}/mkdocs.yml

@@ -219,6 +219,7 @@ nav:
       - CLI: recipes/cli.md
       - "Deploy seguro (migrations + shutdown)": recipes/deploy-safety.md
       - Downloads: recipes/downloads.md
+      - "Campos validados (tipos prontos)": recipes/fields.md
       - Email transacional: recipes/email.md
       - Feature flags: recipes/feature-flags.md
       - Fila e Tarefas: recipes/queue-tasks.md

{tempest_fastapi_sdk-0.76.0 → tempest_fastapi_sdk-0.78.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tempest-fastapi-sdk"
-version = "0.76.0"
+version = "0.78.0"
 description = "Shared FastAPI building blocks: base schemas, ORM model, async repository, exceptions, pagination and settings — the conventions used across Tempest projects."
 readme = "README.md"
 requires-python = ">=3.11"

{tempest_fastapi_sdk-0.76.0 → tempest_fastapi_sdk-0.78.0}/tempest_fastapi_sdk/__init__.py

@@ -245,6 +245,7 @@ from tempest_fastapi_sdk.utils import (
     REQUEST_ID_HEADER,
     UF,
     AttemptThrottle,
+    CentsField,
     CEPField,
     ChoiceBR,
     CircuitOpenError,
@@ -259,18 +260,31 @@ from tempest_fastapi_sdk.utils import (
     DownloadUtils,
     EmailUtils,
     GPUMetrics,
+    HexColorField,
     HTTPClient,
     JWTUtils,
+    LatitudeField,
     LocalUploadStorage,
     LogUtils,
+    LongitudeField,
     MemoryMetrics,
     MetricsUtils,
     MinIOUploadStorage,
+    NonEmptyStrField,
+    NonNegativeFloatField,
+    NonNegativeIntField,
     PasswordUtils,
+    PercentField,
     PhoneBR,
     PhoneBRField,
+    PortField,
+    PositiveFloatField,
+    PositiveIntField,
+    PriceField,
+    RatioField,
     Region,
     RetryPolicy,
+    SlugField,
     StateBR,
     SystemMetrics,
     ThrottleBackend,
@@ -328,7 +342,7 @@ from tempest_fastapi_sdk.websockets import (
     make_websocket_router,
 )
 
-__version__: str = "0.76.0"
+__version__: str = "0.78.0"
 
 __all__: list[str] = [
     "BASE_COLUMN_ORDER",
@@ -394,6 +408,7 @@ __all__: list[str] = [
     "CPUMetrics",
     "CSRFMiddleware",
     "CachedResponse",
+    "CentsField",
     "ChoiceBR",
     "CircuitOpenError",
     "CityBR",
@@ -424,6 +439,7 @@ __all__: list[str] = [
     "HTTPClient",
     "HardenedStaticFiles",
     "HealthCheck",
+    "HexColorField",
     "IdempotencyMiddleware",
     "IdempotencyStore",
     "InvalidFileTypeException",
@@ -431,6 +447,7 @@ __all__: list[str] = [
     "JSONFormatter",
     "JWTSettings",
     "JWTUtils",
+    "LatitudeField",
     "LocalUploadStorage",
     "LogEntrySchema",
     "LogSettings",
@@ -439,6 +456,7 @@ __all__: list[str] = [
     "LoginResponseSchema",
     "LoginSchema",
     "LogoutSchema",
+    "LongitudeField",
     "MFAConfirmSchema",
     "MFADisableSchema",
     "MFAEnrollResponseSchema",
@@ -453,6 +471,9 @@ __all__: list[str] = [
     "MetricsUtils",
     "MinIOSettings",
     "MinIOUploadStorage",
+    "NonEmptyStrField",
+    "NonNegativeFloatField",
+    "NonNegativeIntField",
     "NotFoundException",
     "OAuthError",
     "OAuthTokens",
@@ -468,14 +489,20 @@ __all__: list[str] = [
     "PasswordResetResponseSchema",
     "PasswordResetToken",
     "PasswordUtils",
+    "PercentField",
     "PhoneBR",
     "PhoneBRField",
+    "PortField",
+    "PositiveFloatField",
+    "PositiveIntField",
+    "PriceField",
     "PrometheusMiddleware",
     "RSAWebhookSignatureVerifier",
     "RabbitMQSettings",
     "RateLimitMiddleware",
     "RateLimitResult",
     "RateLimitStore",
+    "RatioField",
     "RedisFeatureFlagBackend",
     "RedisIdempotencyStore",
     "RedisRateLimitStore",
@@ -499,6 +526,7 @@ __all__: list[str] = [
     "SignupResponseSchema",
     "SignupSchema",
     "SlowQueryLogger",
+    "SlugField",
     "SoftDeleteMixin",
     "StateBR",
     "StoredFileServiceMixin",

{tempest_fastapi_sdk-0.76.0 → tempest_fastapi_sdk-0.78.0}/tempest_fastapi_sdk/controllers/base.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 from typing import Any, Generic, TypeVar, cast
 from uuid import UUID
 
+from tempest_fastapi_sdk.schemas.base import BaseSchema
 from tempest_fastapi_sdk.services.base import BaseService
 
 ServiceT = TypeVar("ServiceT", bound=BaseService[Any, Any])
@@ -112,6 +113,18 @@ class BaseController(Generic[ServiceT, ResponseT]):
         """
         return await self.service.count(filters)
 
+    async def update(self, id: UUID, data: BaseSchema) -> ResponseT:
+        """Pass-through to :meth:`BaseService.update`.
+
+        Args:
+            id (UUID): The primary key of the record to update.
+            data (BaseSchema): The update payload (unset fields skipped).
+
+        Returns:
+            ResponseT: The mapped, updated response.
+        """
+        return cast("ResponseT", await self.service.update(id, data))
+
     async def delete(self, id: UUID) -> None:
         """Pass-through to :meth:`BaseService.delete`.
 

{tempest_fastapi_sdk-0.76.0 → tempest_fastapi_sdk-0.78.0}/tempest_fastapi_sdk/services/base.py

@@ -7,6 +7,7 @@ from typing import Any, Generic, TypeVar
 from uuid import UUID
 
 from tempest_fastapi_sdk.db.repository import BaseRepository
+from tempest_fastapi_sdk.schemas.base import BaseSchema
 
 RepositoryT = TypeVar("RepositoryT", bound=BaseRepository[Any])
 ResponseT = TypeVar("ResponseT")
@@ -168,6 +169,39 @@ class BaseService(Generic[RepositoryT, ResponseT]):
         """
         return await self.repository.exists(filters)
 
+    async def update(self, id: UUID, data: BaseSchema) -> ResponseT:
+        """Apply a partial update to a record and map it to a response.
+
+        Fetches the row by primary key, copies the fields present in
+        ``data`` onto the instance, persists, and returns the mapped
+        response. Because :meth:`BaseSchema.to_dict` drops unset and
+        ``None`` fields, only the values the caller actually supplied are
+        applied — so the same method serves both full (PUT) and partial
+        (PATCH) updates.
+
+        Override this in a concrete service when an update needs
+        orchestration (cross-repository writes, domain rules, side
+        effects); leave it untouched for plain field copies.
+
+        Args:
+            id (UUID): The primary key of the record to update.
+            data (BaseSchema): The update payload. Fields left unset (or
+                ``None``) are not applied.
+
+        Returns:
+            ResponseT: The mapped, updated response.
+
+        Raises:
+            AppException: ``repository.not_found_exception`` when no
+                record with ``id`` exists.
+            ConflictException: On integrity violations while persisting.
+        """
+        instance = await self.repository.get_by_id(id)
+        for field, value in data.to_dict().items():
+            setattr(instance, field, value)
+        updated = await self.repository.update(instance)
+        return await self._map_to_response(updated)
+
     async def delete(self, id: UUID) -> None:
         """Delete a row by primary key.
 

{tempest_fastapi_sdk-0.76.0 → tempest_fastapi_sdk-0.78.0}/tempest_fastapi_sdk/utils/__init__.py

@@ -21,6 +21,22 @@ from tempest_fastapi_sdk.utils.download import (
     build_content_disposition,
 )
 from tempest_fastapi_sdk.utils.email import EmailUtils
+from tempest_fastapi_sdk.utils.fields import (
+    CentsField,
+    HexColorField,
+    LatitudeField,
+    LongitudeField,
+    NonEmptyStrField,
+    NonNegativeFloatField,
+    NonNegativeIntField,
+    PercentField,
+    PortField,
+    PositiveFloatField,
+    PositiveIntField,
+    PriceField,
+    RatioField,
+    SlugField,
+)
 from tempest_fastapi_sdk.utils.http_client import (
     REQUEST_ID_HEADER,
     CircuitOpenError,
@@ -123,6 +139,7 @@ __all__: list[str] = [
     "CPFOrCNPJ",
     "CPFOrCNPJField",
     "CPUMetrics",
+    "CentsField",
     "ChoiceBR",
     "CircuitOpenError",
     "CityBR",
@@ -132,17 +149,30 @@ __all__: list[str] = [
     "EmailUtils",
     "GPUMetrics",
     "HTTPClient",
+    "HexColorField",
     "JWTUtils",
+    "LatitudeField",
     "LocalUploadStorage",
     "LogUtils",
+    "LongitudeField",
     "MemoryMetrics",
     "MetricsUtils",
     "MinIOUploadStorage",
+    "NonEmptyStrField",
+    "NonNegativeFloatField",
+    "NonNegativeIntField",
     "PasswordUtils",
+    "PercentField",
     "PhoneBR",
     "PhoneBRField",
+    "PortField",
+    "PositiveFloatField",
+    "PositiveIntField",
+    "PriceField",
+    "RatioField",
     "Region",
     "RetryPolicy",
+    "SlugField",
     "StateBR",
     "SystemMetrics",
     "TOTPHelper",