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

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

@@ -5,6 +5,19 @@ 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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tempest-fastapi-sdk
-Version: 0.75.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`, `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]`)*, 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.75.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`, `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]`)*, 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.75.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
 ```
@@ -319,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) |
+| `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.75.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
 ```
@@ -311,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) |
+| `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.75.0 → tempest_fastapi_sdk-0.76.0}/pyproject.toml

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

@@ -245,11 +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,
@@ -264,6 +268,7 @@ from tempest_fastapi_sdk.utils import (
     MinIOUploadStorage,
     PasswordUtils,
     PhoneBR,
+    PhoneBRField,
     Region,
     RetryPolicy,
     StateBR,
@@ -323,7 +328,7 @@ from tempest_fastapi_sdk.websockets import (
     make_websocket_router,
 )
 
-__version__: str = "0.75.0"
+__version__: str = "0.76.0"
 
 __all__: list[str] = [
     "BASE_COLUMN_ORDER",
@@ -380,8 +385,12 @@ __all__: list[str] = [
     "BaseUserRefreshTokenModel",
     "BaseUserTokenModel",
     "BodySizeLimitMiddleware",
+    "CEPField",
+    "CNPJField",
     "CORSSettings",
+    "CPFField",
     "CPFOrCNPJ",
+    "CPFOrCNPJField",
     "CPUMetrics",
     "CSRFMiddleware",
     "CachedResponse",
@@ -460,6 +469,7 @@ __all__: list[str] = [
     "PasswordResetToken",
     "PasswordUtils",
     "PhoneBR",
+    "PhoneBRField",
     "PrometheusMiddleware",
     "RSAWebhookSignatureVerifier",
     "RabbitMQSettings",

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

@@ -72,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,
@@ -112,7 +117,11 @@ __all__: list[str] = [
     "REQUEST_ID_HEADER",
     "UF",
     "AttemptThrottle",
+    "CEPField",
+    "CNPJField",
+    "CPFField",
     "CPFOrCNPJ",
+    "CPFOrCNPJField",
     "CPUMetrics",
     "ChoiceBR",
     "CircuitOpenError",
@@ -131,6 +140,7 @@ __all__: list[str] = [
     "MinIOUploadStorage",
     "PasswordUtils",
     "PhoneBR",
+    "PhoneBRField",
     "Region",
     "RetryPolicy",
     "StateBR",

{tempest_fastapi_sdk-0.75.0 → tempest_fastapi_sdk-0.76.0}/tempest_fastapi_sdk/utils/regex.py

@@ -279,20 +279,29 @@ def normalize_phone_br(value: str) -> str:
     return only_digits(value)
 
 
-CPF = Annotated[str, AfterValidator(normalize_cpf)]
-"""Pydantic type that validates and normalizes a CPF to 11 digits."""
+CPFField = Annotated[str, AfterValidator(normalize_cpf)]
+"""Pydantic field type that validates and normalizes a CPF to 11 digits."""
 
-CNPJ = Annotated[str, AfterValidator(normalize_cnpj)]
-"""Pydantic type that validates and normalizes a CNPJ to 14 digits."""
+CNPJField = Annotated[str, AfterValidator(normalize_cnpj)]
+"""Pydantic field type that validates and normalizes a CNPJ to 14 digits."""
 
-CPFOrCNPJ = Annotated[str, AfterValidator(normalize_cpf_cnpj)]
-"""Pydantic type that accepts either a CPF or a CNPJ."""
+CPFOrCNPJField = Annotated[str, AfterValidator(normalize_cpf_cnpj)]
+"""Pydantic field type that accepts either a CPF or a CNPJ."""
 
-PhoneBR = Annotated[str, AfterValidator(normalize_phone_br)]
-"""Pydantic type that validates a BR phone and normalizes to digits."""
+PhoneBRField = Annotated[str, AfterValidator(normalize_phone_br)]
+"""Pydantic field type that validates a BR phone and normalizes to digits."""
 
-CEP = Annotated[str, AfterValidator(normalize_cep)]
-"""Pydantic type that validates a Brazilian CEP and normalizes to 8 digits."""
+CEPField = Annotated[str, AfterValidator(normalize_cep)]
+"""Pydantic field type that validates a Brazilian CEP, normalized to 8 digits."""
+
+# Deprecated aliases (pre-0.76 names without the ``Field`` suffix). Kept
+# so existing imports keep working; prefer the ``*Field`` names. Slated
+# for removal in a future major.
+CPF = CPFField
+CNPJ = CNPJField
+CPFOrCNPJ = CPFOrCNPJField
+PhoneBR = PhoneBRField
+CEP = CEPField
 
 
 __all__: list[str] = [
@@ -304,8 +313,13 @@ __all__: list[str] = [
     "CPF_CNPJ_PATTERN",
     "CPF_PATTERN",
     "PHONE_BR_PATTERN",
+    "CEPField",
+    "CNPJField",
+    "CPFField",
     "CPFOrCNPJ",
+    "CPFOrCNPJField",
     "PhoneBR",
+    "PhoneBRField",
     "is_valid_cep",
     "is_valid_cnpj",
     "is_valid_cpf",

{tempest_fastapi_sdk-0.75.0 → tempest_fastapi_sdk-0.76.0}/tests/utils/test_regex.py

@@ -7,8 +7,13 @@ from tempest_fastapi_sdk.utils import (
     CEP,
     CNPJ,
     CPF,
+    CEPField,
+    CNPJField,
+    CPFField,
     CPFOrCNPJ,
+    CPFOrCNPJField,
     PhoneBR,
+    PhoneBRField,
     is_valid_cep,
     is_valid_cnpj,
     is_valid_cpf,
@@ -165,19 +170,23 @@ class TestNormalize:
 
 
 class CPFSchema(BaseModel):
-    document: CPF
+    document: CPFField
 
 
 class CNPJSchema(BaseModel):
-    document: CNPJ
+    document: CNPJField
 
 
 class CPFOrCNPJSchema(BaseModel):
-    document: CPFOrCNPJ
+    document: CPFOrCNPJField
 
 
 class PhoneSchema(BaseModel):
-    phone: PhoneBR
+    phone: PhoneBRField
+
+
+class CEPSchema(BaseModel):
+    cep: CEPField
 
 
 class TestPydanticTypes:
@@ -201,6 +210,19 @@ class TestPydanticTypes:
         assert CPFOrCNPJSchema(document=VALID_CPF_MASKED).document == VALID_CPF
         assert CPFOrCNPJSchema(document=VALID_CNPJ_MASKED).document == VALID_CNPJ
 
+    def test_cep_type_normalizes(self) -> None:
+        assert CEPSchema(cep="01310-100").cep == "01310100"
+
+
+class TestDeprecatedAliases:
+    def test_old_names_alias_the_field_types(self) -> None:
+        """Pre-0.76 names still resolve to the same ``*Field`` types."""
+        assert CPF is CPFField
+        assert CNPJ is CNPJField
+        assert CPFOrCNPJ is CPFOrCNPJField
+        assert PhoneBR is PhoneBRField
+        assert CEP is CEPField
+
     def test_phone_type_normalizes(self) -> None:
         result = PhoneSchema(phone="(11) 98888-7777")
         assert result.phone == "11988887777"

{tempest_fastapi_sdk-0.75.0 → tempest_fastapi_sdk-0.76.0}/uv.lock

@@ -2822,7 +2822,7 @@ wheels = [
 
 [[package]]
 name = "tempest-fastapi-sdk"
-version = "0.75.0"
+version = "0.76.0"
 source = { editable = "." }
 dependencies = [
     { name = "alembic" },