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

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

@@ -5,6 +5,35 @@ 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.76.0] — 2026-06-27
+
+### Changed
+
+- **BR field types now carry a `Field` suffix.** The Pydantic
+  annotated-type aliases were renamed to make their role obvious at the
+  import site, matching `UFField` / `CityNameField`: `CPF` -> `CPFField`,
+  `CNPJ` -> `CNPJField`, `CPFOrCNPJ` -> `CPFOrCNPJField`,
+  `PhoneBR` -> `PhoneBRField`, `CEP` -> `CEPField`. The old names remain
+  exported as **deprecated aliases** (identical types), so existing
+  imports keep working; prefer the `*Field` names. Slated for removal in
+  a future major.
+
+## [0.75.0] — 2026-06-27
+
+### Added
+
+- **Frontend `<select>` choices for BR localities (`ChoiceBR`,
+  `uf_choices`, `region_choices`, `city_choices`).** The bundled
+  states/cities dataset already backed the `UFField` / `CityNameField`
+  validation fields; these helpers make the *other* role first-class —
+  feeding dropdowns. Each returns `list[ChoiceBR]`, a typed Pydantic
+  schema (`value`/`label`) that serializes as
+  `{"value": ..., "label": ...}` and shows up typed in OpenAPI:
+  `uf_choices()` pairs each acronym (the same value `UFField` validates)
+  with the full state name, `region_choices()` lists the 5 IBGE
+  macro-regions, and `city_choices(uf)` lists a state's municipalities.
+  Exported from `tempest_fastapi_sdk` and `tempest_fastapi_sdk.utils`.
+
 ## [0.74.0] — 2026-06-27
 
 ### Added

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tempest-fastapi-sdk
-Version: 0.74.0
+Version: 0.76.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 (`CPF`, `CNPJ`, `CPFOrCNPJ`, `PhoneBR`, `CEP`, `is_valid_*`, `normalize_*`, `only_digits`, `*_PATTERN`), BR states/cities (`UF`, `Region`, `StateBR`, `CityBR`, `UFField`, `CityNameField`, `list_states`, `get_state`, `cities_by_uf`, `states_by_region`, `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]`)*, 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`).
@@ -1609,7 +1609,7 @@ Every helper has its own recipe — this section is the quick map:
 | `DownloadUtils`, `build_content_disposition` | [Serving private files through the API](#serving-private-files-through-the-api-downloadutils) |
 | `LogUtils` + `configure_logging` | [Structured logging & request IDs recipe](#structured-logging--request-ids-recipe) |
 | `MetricsUtils` (CPU/memory/disk/GPU) | [System metrics recipe](#system-metrics-recipe) |
-| `CPF`, `CNPJ`, `CPFOrCNPJ`, `PhoneBR`, `is_valid_*`, `normalize_*`, `only_digits` | [BR document & phone validation recipe](#br-document--phone-validation-recipe) |
+| `CPFField`, `CNPJField`, `CPFOrCNPJField`, `PhoneBRField`, `CEPField`, `is_valid_*`, `normalize_*`, `only_digits` | [BR document & phone validation recipe](#br-document--phone-validation-recipe) |
 
 ### BR document & phone validation recipe
 
@@ -1622,7 +1622,7 @@ Every helper has its own recipe — this section is the quick map:
 | `is_valid_phone_br` | `(str) -> bool` | BR phone shape: optional `+55`, optional DDD, optional 9th digit. |
 | `normalize_cpf`, `normalize_cnpj`, `normalize_cpf_cnpj`, `normalize_phone_br` | `(str) -> str` | Strip mask to digits-only; raise `ValueError` if invalid. |
 | `only_digits` | `(str) -> str` | Strip every non-digit character. |
-| `CPF`, `CNPJ`, `CPFOrCNPJ`, `PhoneBR` | `Annotated[str, AfterValidator(...)]` | Drop-in Pydantic field types — validate + normalize automatically. |
+| `CPFField`, `CNPJField`, `CPFOrCNPJField`, `PhoneBRField`, `CEPField` | `Annotated[str, AfterValidator(...)]` | Drop-in Pydantic field types — validate + normalize automatically. The old names without the `Field` suffix (`CPF`, `CNPJ`, …) remain as deprecated aliases since v0.76. |
 
 #### Schema usage
 
@@ -1630,7 +1630,7 @@ Every helper has its own recipe — this section is the quick map:
 from pydantic import EmailStr, Field
 
 from tempest_fastapi_sdk import BaseSchema
-from tempest_fastapi_sdk.utils import CPF, CPFOrCNPJ, PhoneBR
+from tempest_fastapi_sdk.utils import CPFOrCNPJField, PhoneBRField
 
 
 class CustomerCreateSchema(BaseSchema):
@@ -1644,8 +1644,8 @@ class CustomerCreateSchema(BaseSchema):
 
     name: str = Field(min_length=1, max_length=128)
     email: EmailStr
-    document: CPFOrCNPJ
-    phone: PhoneBR
+    document: CPFOrCNPJField
+    phone: PhoneBRField
 ```
 
 Valid input:
@@ -2830,15 +2830,15 @@ async def update_perms(user_id: UUID) -> None:
 
 ### CEP (Brazilian zipcode) recipe
 
-`CEP` is an `Annotated[str, AfterValidator(normalize_cep)]` type — drop it into a Pydantic schema and inbound values are accepted as `"01310-100"` or `"01310100"`, normalized to 8 digits, and rejected (`ValidationError` → HTTP 422 envelope) when they don't match the shape. CEPs have no check digits, so validation is format-only.
+`CEPField` is an `Annotated[str, AfterValidator(normalize_cep)]` type — drop it into a Pydantic schema and inbound values are accepted as `"01310-100"` or `"01310100"`, normalized to 8 digits, and rejected (`ValidationError` → HTTP 422 envelope) when they don't match the shape. CEPs have no check digits, so validation is format-only.
 
 ```python
 from tempest_fastapi_sdk import BaseSchema
-from tempest_fastapi_sdk.utils import CEP
+from tempest_fastapi_sdk.utils import CEPField
 
 
 class AddressCreateSchema(BaseSchema):
-    cep: CEP
+    cep: CEPField
     street: str
     number: str
 ```

{tempest_fastapi_sdk-0.74.0 → tempest_fastapi_sdk-0.76.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 (`CPF`, `CNPJ`, `CPFOrCNPJ`, `PhoneBR`, `CEP`, `is_valid_*`, `normalize_*`, `only_digits`, `*_PATTERN`), BR states/cities (`UF`, `Region`, `StateBR`, `CityBR`, `UFField`, `CityNameField`, `list_states`, `get_state`, `cities_by_uf`, `states_by_region`, `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]`)*, 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`).
@@ -1506,7 +1506,7 @@ Every helper has its own recipe — this section is the quick map:
 | `DownloadUtils`, `build_content_disposition` | [Serving private files through the API](#serving-private-files-through-the-api-downloadutils) |
 | `LogUtils` + `configure_logging` | [Structured logging & request IDs recipe](#structured-logging--request-ids-recipe) |
 | `MetricsUtils` (CPU/memory/disk/GPU) | [System metrics recipe](#system-metrics-recipe) |
-| `CPF`, `CNPJ`, `CPFOrCNPJ`, `PhoneBR`, `is_valid_*`, `normalize_*`, `only_digits` | [BR document & phone validation recipe](#br-document--phone-validation-recipe) |
+| `CPFField`, `CNPJField`, `CPFOrCNPJField`, `PhoneBRField`, `CEPField`, `is_valid_*`, `normalize_*`, `only_digits` | [BR document & phone validation recipe](#br-document--phone-validation-recipe) |
 
 ### BR document & phone validation recipe
 
@@ -1519,7 +1519,7 @@ Every helper has its own recipe — this section is the quick map:
 | `is_valid_phone_br` | `(str) -> bool` | BR phone shape: optional `+55`, optional DDD, optional 9th digit. |
 | `normalize_cpf`, `normalize_cnpj`, `normalize_cpf_cnpj`, `normalize_phone_br` | `(str) -> str` | Strip mask to digits-only; raise `ValueError` if invalid. |
 | `only_digits` | `(str) -> str` | Strip every non-digit character. |
-| `CPF`, `CNPJ`, `CPFOrCNPJ`, `PhoneBR` | `Annotated[str, AfterValidator(...)]` | Drop-in Pydantic field types — validate + normalize automatically. |
+| `CPFField`, `CNPJField`, `CPFOrCNPJField`, `PhoneBRField`, `CEPField` | `Annotated[str, AfterValidator(...)]` | Drop-in Pydantic field types — validate + normalize automatically. The old names without the `Field` suffix (`CPF`, `CNPJ`, …) remain as deprecated aliases since v0.76. |
 
 #### Schema usage
 
@@ -1527,7 +1527,7 @@ Every helper has its own recipe — this section is the quick map:
 from pydantic import EmailStr, Field
 
 from tempest_fastapi_sdk import BaseSchema
-from tempest_fastapi_sdk.utils import CPF, CPFOrCNPJ, PhoneBR
+from tempest_fastapi_sdk.utils import CPFOrCNPJField, PhoneBRField
 
 
 class CustomerCreateSchema(BaseSchema):
@@ -1541,8 +1541,8 @@ class CustomerCreateSchema(BaseSchema):
 
     name: str = Field(min_length=1, max_length=128)
     email: EmailStr
-    document: CPFOrCNPJ
-    phone: PhoneBR
+    document: CPFOrCNPJField
+    phone: PhoneBRField
 ```
 
 Valid input:
@@ -2727,15 +2727,15 @@ async def update_perms(user_id: UUID) -> None:
 
 ### CEP (Brazilian zipcode) recipe
 
-`CEP` is an `Annotated[str, AfterValidator(normalize_cep)]` type — drop it into a Pydantic schema and inbound values are accepted as `"01310-100"` or `"01310100"`, normalized to 8 digits, and rejected (`ValidationError` → HTTP 422 envelope) when they don't match the shape. CEPs have no check digits, so validation is format-only.
+`CEPField` is an `Annotated[str, AfterValidator(normalize_cep)]` type — drop it into a Pydantic schema and inbound values are accepted as `"01310-100"` or `"01310100"`, normalized to 8 digits, and rejected (`ValidationError` → HTTP 422 envelope) when they don't match the shape. CEPs have no check digits, so validation is format-only.
 
 ```python
 from tempest_fastapi_sdk import BaseSchema
-from tempest_fastapi_sdk.utils import CEP
+from tempest_fastapi_sdk.utils import CEPField
 
 
 class AddressCreateSchema(BaseSchema):
-    cep: CEP
+    cep: CEPField
     street: str
     number: str
 ```

{tempest_fastapi_sdk-0.74.0 → tempest_fastapi_sdk-0.76.0}/docs/recipes/br-helpers.en.md

@@ -14,7 +14,10 @@ Document validators (CPF, CNPJ, CEP) and phone number normalizer/validator for B
 | `is_valid_phone_br` | `(str) -> bool` | BR phone shape: optional `+55`, optional DDD, optional 9th digit. |
 | `normalize_cpf`, `normalize_cnpj`, `normalize_cpf_cnpj`, `normalize_phone_br` | `(str) -> str` | Strip mask to digits-only; raise `ValueError` if invalid. |
 | `only_digits` | `(str) -> str` | Strip every non-digit character. |
-| `CPF`, `CNPJ`, `CPFOrCNPJ`, `PhoneBR` | `Annotated[str, AfterValidator(...)]` | Drop-in Pydantic field types — validate + normalize automatically. |
+| `CPFField`, `CNPJField`, `CPFOrCNPJField`, `PhoneBRField` | `Annotated[str, AfterValidator(...)]` | Drop-in Pydantic field types — validate + normalize automatically. |
+
+!!! info "`Field` suffix (since v0.76)"
+    The field types now carry a `Field` suffix (`CPFField`, `CNPJField`, `CPFOrCNPJField`, `PhoneBRField`, `CEPField`) to make it obvious they are schema field types — like `UFField` / `CityNameField`. The old names (`CPF`, `CNPJ`, `CPFOrCNPJ`, `PhoneBR`, `CEP`) still work as **deprecated aliases**; prefer the new ones.
 
 #### Schema usage
 
@@ -22,7 +25,7 @@ Document validators (CPF, CNPJ, CEP) and phone number normalizer/validator for B
 from pydantic import EmailStr, Field
 
 from tempest_fastapi_sdk import BaseSchema
-from tempest_fastapi_sdk.utils import CPF, CPFOrCNPJ, PhoneBR
+from tempest_fastapi_sdk.utils import CPFOrCNPJField, PhoneBRField
 
 
 class CustomerCreateSchema(BaseSchema):
@@ -36,8 +39,8 @@ class CustomerCreateSchema(BaseSchema):
 
     name: str = Field(min_length=1, max_length=128)
     email: EmailStr
-    document: CPFOrCNPJ
-    phone: PhoneBR
+    document: CPFOrCNPJField
+    phone: PhoneBRField
 ```
 
 Valid input:
@@ -87,15 +90,15 @@ await repo.get({"document": normalize_cpf_cnpj(query)})
 ## CEP (zipcode)
 
 
-`CEP` is an `Annotated[str, AfterValidator(normalize_cep)]` type — drop it into a Pydantic schema and inbound values are accepted as `"01310-100"` or `"01310100"`, normalized to 8 digits, and rejected (`ValidationError` → HTTP 422 envelope) when they don't match the shape. CEPs have no check digits, so validation is format-only.
+`CEPField` is an `Annotated[str, AfterValidator(normalize_cep)]` type — drop it into a Pydantic schema and inbound values are accepted as `"01310-100"` or `"01310100"`, normalized to 8 digits, and rejected (`ValidationError` → HTTP 422 envelope) when they don't match the shape. CEPs have no check digits, so validation is format-only.
 
 ```python
 from tempest_fastapi_sdk import BaseSchema
-from tempest_fastapi_sdk.utils import CEP
+from tempest_fastapi_sdk.utils import CEPField
 
 
 class AddressCreateSchema(BaseSchema):
-    cep: CEP
+    cep: CEPField
     street: str
     number: str
 ```
@@ -174,6 +177,57 @@ def validate_address(uf: UF, city: str) -> str:
 !!! tip "City lookup ignores accents and case"
     `is_valid_city("SP", "sao paulo")` and `normalize_city("rj", "RIO DE JANEIRO")` both work — the comparison strips accents, case and surrounding whitespace. `normalize_city` always returns the canonical proper-case name (`"São Paulo"`, `"Rio de Janeiro"`).
 
+### Choices ready for a frontend `<select>`
+
+The same data serves **two roles**: validating input (the `UFField` /
+`CityNameField` fields above) **and** feeding the frontend dropdowns. For
+the latter, `uf_choices`, `region_choices` and `city_choices` return
+`list[ChoiceBR]` — each item a `value` (what you store/submit) + `label`
+(what the user sees), exactly the shape an `<option>` wants:
+
+```python
+from fastapi import APIRouter
+
+from tempest_fastapi_sdk.utils import ChoiceBR, city_choices, region_choices, uf_choices
+
+router = APIRouter(prefix="/api/locations", tags=["locations"])
+
+
+@router.get("/states")
+def list_uf_choices() -> list[ChoiceBR]:
+    """UF choices: value = acronym, label = state name."""
+    return uf_choices()
+
+
+@router.get("/regions")
+def list_region_choices() -> list[ChoiceBR]:
+    """Choices for the 5 IBGE macro-regions."""
+    return region_choices()
+
+
+@router.get("/states/{uf}/cities")
+def list_city_choices(uf: str) -> list[ChoiceBR]:
+    """City choices for a UF: value = label = municipality name."""
+    return city_choices(uf)
+```
+
+The `value` of `uf_choices()` is the acronym — the same value `UFField`
+validates on the way back, so whatever the `<select>` submits drops
+straight into your schema:
+
+```python
+uf_choices()[0]          # ChoiceBR(value="AC", label="Acre")
+region_choices()[0]      # ChoiceBR(value="Norte", label="Norte")
+city_choices("sp")[0]    # ChoiceBR(value="Adamantina", label="Adamantina")
+```
+
+!!! info "Why `ChoiceBR` instead of a tuple?"
+    `ChoiceBR` is a Pydantic schema (`value: str`, `label: str`), so it
+    serializes as `{"value": ..., "label": ...}` in JSON and shows up
+    typed in OpenAPI/Swagger — no untyped "magic field". For the classic
+    state→city case, the frontend calls `/states`, then `/states/{uf}/cities`
+    once a UF is picked.
+
 ### Imperative variants
 
 | Function | What it does |
@@ -185,13 +239,14 @@ def validate_address(uf: UF, city: str) -> str:
 | `normalize_city(uf, city)` | Canonical municipality name; raises `ValueError` when unknown. |
 
 !!! note "A states/cities endpoint for the frontend"
-    To populate state and city `<select>`s, return `list_states()` directly (each `StateBR` already carries `cities`), or a lean `GET /states/{uf}/cities` endpoint returning `cities_by_uf(uf)`. Since it's in-memory data, it never touches the database.
+    For `<select>`s, prefer `uf_choices()` / `region_choices()` / `city_choices(uf)` (value/label shape). If you need the whole state with its city list, `list_states()` returns each `StateBR` with its `cities`. Since it's all in-memory, it never touches the database.
 
 #### Recap
 
 - `UF` (StrEnum, 27 acronyms) + `Region` (5 IBGE macro-regions).
-- `StateBR` / `CityBR` for typed responses.
+- `StateBR` / `CityBR` for typed responses; `ChoiceBR` (`value`/`label`) for dropdowns.
 - `list_states`, `get_state`, `cities_by_uf`, `states_by_region` to query the bundled table.
+- `uf_choices`, `region_choices`, `city_choices` for frontend `<select>`s.
 - `UFField` / `CityNameField` for schema fields; `is_valid_*` / `normalize_*` for imperative validation in the service.
 
 
@@ -267,6 +322,6 @@ Every helper has its own recipe — this section is the quick map:
 | `DownloadUtils`, `build_content_disposition` | [Serving private files through the API](http.md#serving-private-files-through-the-api-downloadutils) |
 | `LogUtils` + `configure_logging` | [Structured logging & request IDs recipe](logging.md) |
 | `MetricsUtils` (CPU/memory/disk/GPU) | [System metrics recipe](metrics.md) |
-| `CPF`, `CNPJ`, `CPFOrCNPJ`, `PhoneBR`, `is_valid_*`, `normalize_*`, `only_digits` | [CPF / CNPJ / phone](#cpf-cnpj-phone) |
-| `UF`, `Region`, `StateBR`, `CityBR`, `UFField`, `CityNameField`, `list_states`, `get_state`, `cities_by_uf`, `states_by_region`, `is_valid_uf`, `normalize_uf`, `is_valid_city`, `normalize_city` | [States and municipalities](#states-and-municipalities) |
+| `CPFField`, `CNPJField`, `CPFOrCNPJField`, `PhoneBRField`, `CEPField`, `is_valid_*`, `normalize_*`, `only_digits` | [CPF / CNPJ / phone](#cpf-cnpj-phone) |
+| `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` | [States and municipalities](#states-and-municipalities) |
 

{tempest_fastapi_sdk-0.74.0 → tempest_fastapi_sdk-0.76.0}/docs/recipes/br-helpers.md

@@ -14,7 +14,10 @@ Validadores de documentos (CPF, CNPJ, CEP) e normalizador/validador de telefone
 | `is_valid_phone_br` | `(str) -> bool` | Formato de telefone BR: `+55` opcional, DDD opcional, nono dígito opcional. |
 | `normalize_cpf`, `normalize_cnpj`, `normalize_cpf_cnpj`, `normalize_phone_br` | `(str) -> str` | Remove a máscara deixando só dígitos; levanta `ValueError` se inválido. |
 | `only_digits` | `(str) -> str` | Remove todo caractere que não é dígito. |
-| `CPF`, `CNPJ`, `CPFOrCNPJ`, `PhoneBR` | `Annotated[str, AfterValidator(...)]` | Tipos de campo Pydantic plug-and-play — validam + normalizam automaticamente. |
+| `CPFField`, `CNPJField`, `CPFOrCNPJField`, `PhoneBRField` | `Annotated[str, AfterValidator(...)]` | Tipos de campo Pydantic plug-and-play — validam + normalizam automaticamente. |
+
+!!! info "Sufixo `Field` (a partir da v0.76)"
+    Os tipos de campo passaram a usar o sufixo `Field` (`CPFField`, `CNPJField`, `CPFOrCNPJField`, `PhoneBRField`, `CEPField`) pra deixar claro que são campos de schema — igual `UFField` / `CityNameField`. Os nomes antigos (`CPF`, `CNPJ`, `CPFOrCNPJ`, `PhoneBR`, `CEP`) continuam funcionando como **alias deprecado**; prefira os novos.
 
 #### Uso em schema
 
@@ -22,7 +25,7 @@ Validadores de documentos (CPF, CNPJ, CEP) e normalizador/validador de telefone
 from pydantic import EmailStr, Field
 
 from tempest_fastapi_sdk import BaseSchema
-from tempest_fastapi_sdk.utils import CPF, CPFOrCNPJ, PhoneBR
+from tempest_fastapi_sdk.utils import CPFOrCNPJField, PhoneBRField
 
 
 class CustomerCreateSchema(BaseSchema):
@@ -36,8 +39,8 @@ class CustomerCreateSchema(BaseSchema):
 
     name: str = Field(min_length=1, max_length=128)
     email: EmailStr
-    document: CPFOrCNPJ
-    phone: PhoneBR
+    document: CPFOrCNPJField
+    phone: PhoneBRField
 ```
 
 Entrada válida:
@@ -87,15 +90,15 @@ await repo.get({"document": normalize_cpf_cnpj(query)})
 ## CEP
 
 
-`CEP` é um tipo `Annotated[str, AfterValidator(normalize_cep)]` — coloque-o em um schema Pydantic e os valores de entrada são aceitos como `"01310-100"` ou `"01310100"`, normalizados para 8 dígitos, e rejeitados (`ValidationError` → envelope HTTP 422) quando não casam com o formato. CEPs não têm dígitos verificadores, então a validação é só de formato.
+`CEPField` é um tipo `Annotated[str, AfterValidator(normalize_cep)]` — coloque-o em um schema Pydantic e os valores de entrada são aceitos como `"01310-100"` ou `"01310100"`, normalizados para 8 dígitos, e rejeitados (`ValidationError` → envelope HTTP 422) quando não casam com o formato. CEPs não têm dígitos verificadores, então a validação é só de formato.
 
 ```python
 from tempest_fastapi_sdk import BaseSchema
-from tempest_fastapi_sdk.utils import CEP
+from tempest_fastapi_sdk.utils import CEPField
 
 
 class AddressCreateSchema(BaseSchema):
-    cep: CEP
+    cep: CEPField
     street: str
     number: str
 ```
@@ -174,6 +177,49 @@ def validate_address(uf: UF, city: str) -> str:
 !!! tip "A busca de cidade ignora acentos e caixa"
     `is_valid_city("SP", "sao paulo")` e `normalize_city("rj", "RIO DE JANEIRO")` funcionam — a comparação derruba acentos, caixa e espaços nas pontas. `normalize_city` sempre devolve o nome canônico em caixa correta (`"São Paulo"`, `"Rio de Janeiro"`).
 
+### Choices prontas para o `<select>` do frontend
+
+Os mesmos dados servem para **dois papéis**: validar a entrada (os campos `UFField` / `CityNameField` acima) **e** alimentar os dropdowns do frontend. Para o segundo, `uf_choices`, `region_choices` e `city_choices` devolvem `list[ChoiceBR]` — cada item é um `value` (o que você guarda/envia) + `label` (o que o usuário vê), exatamente o formato que um `<option>` quer:
+
+```python
+from uuid import UUID
+
+from fastapi import APIRouter
+
+from tempest_fastapi_sdk.utils import ChoiceBR, city_choices, region_choices, uf_choices
+
+router = APIRouter(prefix="/api/localidades", tags=["localidades"])
+
+
+@router.get("/ufs")
+def list_uf_choices() -> list[ChoiceBR]:
+    """Choices de UF: value = sigla, label = nome do estado."""
+    return uf_choices()
+
+
+@router.get("/regioes")
+def list_region_choices() -> list[ChoiceBR]:
+    """Choices das 5 macro-regiões do IBGE."""
+    return region_choices()
+
+
+@router.get("/ufs/{uf}/cidades")
+def list_city_choices(uf: str) -> list[ChoiceBR]:
+    """Choices de cidade de uma UF: value = label = nome do município."""
+    return city_choices(uf)
+```
+
+O `value` de `uf_choices()` é a sigla — o mesmo valor que `UFField` valida na volta, então o que o `<select>` envia já entra direto no seu schema:
+
+```python
+uf_choices()[0]          # ChoiceBR(value="AC", label="Acre")
+region_choices()[0]      # ChoiceBR(value="Norte", label="Norte")
+city_choices("sp")[0]    # ChoiceBR(value="Adamantina", label="Adamantina")
+```
+
+!!! info "Por que `ChoiceBR` e não uma tupla?"
+    `ChoiceBR` é um schema Pydantic (`value: str`, `label: str`), então serializa como `{"value": ..., "label": ...}` no JSON e aparece tipado no OpenAPI/Swagger — sem o "campo mágico sem tipo". Para o caso clássico estado→cidade, o front chama `/ufs`, e ao escolher uma UF chama `/ufs/{uf}/cidades`.
+
 ### Variantes imperativas
 
 | Função | O que faz |
@@ -185,13 +231,14 @@ def validate_address(uf: UF, city: str) -> str:
 | `normalize_city(uf, city)` | Nome canônico do município; levanta `ValueError` se não existe. |
 
 !!! note "Endpoint de estados/cidades para o frontend"
-    Para popular `<select>` de estado e cidade, devolva `list_states()` direto (cada `StateBR` já traz `cities`), ou um endpoint enxuto `GET /estados/{uf}/cidades` que retorna `cities_by_uf(uf)`. Como é dado em memória, não precisa tocar o banco.
+    Para `<select>`, prefira `uf_choices()` / `region_choices()` / `city_choices(uf)` (formato `value`/`label`). Se precisar do estado inteiro com a lista de cidades junto, `list_states()` devolve cada `StateBR` com seu `cities`. Como é tudo em memória, não toca o banco.
 
 #### Recapitulando
 
 - `UF` (StrEnum, 27 siglas) + `Region` (5 macro-regiões do IBGE).
-- `StateBR` / `CityBR` para respostas tipadas.
+- `StateBR` / `CityBR` para respostas tipadas; `ChoiceBR` (`value`/`label`) para dropdowns.
 - `list_states`, `get_state`, `cities_by_uf`, `states_by_region` para consultar a tabela embutida.
+- `uf_choices`, `region_choices`, `city_choices` para `<select>` do frontend.
 - `UFField` / `CityNameField` para campos de schema; `is_valid_*` / `normalize_*` para validação imperativa no service.
 
 
@@ -267,5 +314,5 @@ Todo helper tem sua própria receita — esta seção é o mapa rápido:
 | `DownloadUtils`, `build_content_disposition` | [Servindo arquivos privados pela API](http.md#servindo-arquivos-privados-pela-api-downloadutils) |
 | `LogUtils` + `configure_logging` | [Receita de logging estruturado & request IDs](logging.md) |
 | `MetricsUtils` (CPU/memória/disco/GPU) | [Receita de métricas do sistema](metrics.md) |
-| `CPF`, `CNPJ`, `CPFOrCNPJ`, `PhoneBR`, `is_valid_*`, `normalize_*`, `only_digits` | [CPF / CNPJ / telefone](#cpf-cnpj-telefone) |
-| `UF`, `Region`, `StateBR`, `CityBR`, `UFField`, `CityNameField`, `list_states`, `get_state`, `cities_by_uf`, `states_by_region`, `is_valid_uf`, `normalize_uf`, `is_valid_city`, `normalize_city` | [Estados e municípios](#estados-e-municipios) |
+| `CPFField`, `CNPJField`, `CPFOrCNPJField`, `PhoneBRField`, `CEPField`, `is_valid_*`, `normalize_*`, `only_digits` | [CPF / CNPJ / telefone](#cpf-cnpj-telefone) |
+| `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` | [Estados e municípios](#estados-e-municipios) |

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

@@ -1,6 +1,6 @@
 [project]
 name = "tempest-fastapi-sdk"
-version = "0.74.0"
+version = "0.76.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.74.0 → tempest_fastapi_sdk-0.76.0}/tempest_fastapi_sdk/__init__.py

@@ -245,10 +245,15 @@ from tempest_fastapi_sdk.utils import (
     REQUEST_ID_HEADER,
     UF,
     AttemptThrottle,
+    CEPField,
+    ChoiceBR,
     CircuitOpenError,
     CityBR,
     CityNameField,
+    CNPJField,
+    CPFField,
     CPFOrCNPJ,
+    CPFOrCNPJField,
     CPUMetrics,
     DiskMetrics,
     DownloadUtils,
@@ -263,6 +268,7 @@ from tempest_fastapi_sdk.utils import (
     MinIOUploadStorage,
     PasswordUtils,
     PhoneBR,
+    PhoneBRField,
     Region,
     RetryPolicy,
     StateBR,
@@ -276,6 +282,7 @@ from tempest_fastapi_sdk.utils import (
     UploadUtils,
     build_content_disposition,
     cities_by_uf,
+    city_choices,
     generate_opaque_token,
     get_client_ip,
     get_client_ip_from_scope,
@@ -298,9 +305,11 @@ from tempest_fastapi_sdk.utils import (
     normalize_phone_br,
     normalize_uf,
     only_digits,
+    region_choices,
     sniff_mime,
     states_by_region,
     to_utc,
+    uf_choices,
     utcnow,
     verify_opaque_token,
 )
@@ -319,7 +328,7 @@ from tempest_fastapi_sdk.websockets import (
     make_websocket_router,
 )
 
-__version__: str = "0.74.0"
+__version__: str = "0.76.0"
 
 __all__: list[str] = [
     "BASE_COLUMN_ORDER",
@@ -376,11 +385,16 @@ __all__: list[str] = [
     "BaseUserRefreshTokenModel",
     "BaseUserTokenModel",
     "BodySizeLimitMiddleware",
+    "CEPField",
+    "CNPJField",
     "CORSSettings",
+    "CPFField",
     "CPFOrCNPJ",
+    "CPFOrCNPJField",
     "CPUMetrics",
     "CSRFMiddleware",
     "CachedResponse",
+    "ChoiceBR",
     "CircuitOpenError",
     "CityBR",
     "CityNameField",
@@ -455,6 +469,7 @@ __all__: list[str] = [
     "PasswordResetToken",
     "PasswordUtils",
     "PhoneBR",
+    "PhoneBRField",
     "PrometheusMiddleware",
     "RSAWebhookSignatureVerifier",
     "RabbitMQSettings",
@@ -529,6 +544,7 @@ __all__: list[str] = [
     "build_content_disposition",
     "build_pagination_link_header",
     "cities_by_uf",
+    "city_choices",
     "clear_cookie",
     "clear_request_id",
     "coerce_flag",
@@ -595,6 +611,7 @@ __all__: list[str] = [
     "normalize_uf",
     "only_digits",
     "parse_accept_language",
+    "region_choices",
     "register_exception_handlers",
     "reorder_base_columns_first",
     "request_id_ctx",
@@ -614,6 +631,7 @@ __all__: list[str] = [
     "strict_types",
     "to_utc",
     "typed",
+    "uf_choices",
     "utcnow",
     "verify_opaque_token",
 ]

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

@@ -30,19 +30,23 @@ from tempest_fastapi_sdk.utils.http_client import (
 from tempest_fastapi_sdk.utils.jwt import JWTUtils
 from tempest_fastapi_sdk.utils.locations import (
     UF,
+    ChoiceBR,
     CityBR,
     CityNameField,
     Region,
     StateBR,
     UFField,
     cities_by_uf,
+    city_choices,
     get_state,
     is_valid_city,
     is_valid_uf,
     list_states,
     normalize_city,
     normalize_uf,
+    region_choices,
     states_by_region,
+    uf_choices,
 )
 from tempest_fastapi_sdk.utils.log import LogUtils
 from tempest_fastapi_sdk.utils.metrics import (
@@ -68,8 +72,13 @@ from tempest_fastapi_sdk.utils.regex import (
     CPF_CNPJ_PATTERN,
     CPF_PATTERN,
     PHONE_BR_PATTERN,
+    CEPField,
+    CNPJField,
+    CPFField,
     CPFOrCNPJ,
+    CPFOrCNPJField,
     PhoneBR,
+    PhoneBRField,
     is_valid_cep,
     is_valid_cnpj,
     is_valid_cpf,
@@ -108,8 +117,13 @@ __all__: list[str] = [
     "REQUEST_ID_HEADER",
     "UF",
     "AttemptThrottle",
+    "CEPField",
+    "CNPJField",
+    "CPFField",
     "CPFOrCNPJ",
+    "CPFOrCNPJField",
     "CPUMetrics",
+    "ChoiceBR",
     "CircuitOpenError",
     "CityBR",
     "CityNameField",
@@ -126,6 +140,7 @@ __all__: list[str] = [
     "MinIOUploadStorage",
     "PasswordUtils",
     "PhoneBR",
+    "PhoneBRField",
     "Region",
     "RetryPolicy",
     "StateBR",
@@ -139,6 +154,7 @@ __all__: list[str] = [
     "UploadUtils",
     "build_content_disposition",
     "cities_by_uf",
+    "city_choices",
     "generate_opaque_token",
     "get_client_ip",
     "get_client_ip_from_scope",
@@ -161,9 +177,11 @@ __all__: list[str] = [
     "normalize_phone_br",
     "normalize_uf",
     "only_digits",
+    "region_choices",
     "sniff_mime",
     "states_by_region",
     "to_utc",
+    "uf_choices",
     "utcnow",
     "verify_opaque_token",
 ]