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

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

@@ -5,6 +5,22 @@ 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.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.77.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tempest-fastapi-sdk
-Version: 0.76.0
+Version: 0.77.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`).

{tempest_fastapi_sdk-0.76.0 → tempest_fastapi_sdk-0.77.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`).

tempest_fastapi_sdk-0.77.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.77.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.77.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.77.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tempest-fastapi-sdk"
-version = "0.76.0"
+version = "0.77.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.77.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.77.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.77.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",

tempest_fastapi_sdk-0.77.0/tempest_fastapi_sdk/utils/fields.py

@@ -0,0 +1,116 @@
+"""Reusable Pydantic field types with built-in validation rules.
+
+These are generic ``Annotated`` aliases that bake a validation rule into
+the type itself, so a schema field reads as *what it is* instead of
+repeating ``Field(gt=0, ...)`` at every use site:
+
+    from tempest_fastapi_sdk.utils import CentsField, PercentField, SlugField
+
+    class ProductCreateSchema(BaseSchema):
+        price_cents: CentsField        # int >= 0 (money in minor units)
+        discount: PercentField         # float in [0, 100]
+        slug: SlugField                # lower-kebab-case string
+
+They follow the same ``*Field`` naming convention as the BR field types
+(``CPFField`` / ``UFField`` / ...), so anything ending in ``Field`` is a
+drop-in schema field type. Invalid values raise ``ValidationError`` ->
+HTTP 422 via the SDK exception handler.
+"""
+
+from __future__ import annotations
+
+from decimal import Decimal
+from typing import Annotated
+
+from annotated_types import Ge, Gt, Le
+from pydantic import Field, StringConstraints
+
+# --- Integers -------------------------------------------------------------
+
+PositiveIntField = Annotated[int, Gt(0)]
+"""Integer strictly greater than zero (quantities, counts, 1-based ids)."""
+
+NonNegativeIntField = Annotated[int, Ge(0)]
+"""Integer greater than or equal to zero."""
+
+CentsField = Annotated[int, Ge(0)]
+"""Monetary amount in minor units (cents): a non-negative integer.
+
+Storing money as integer cents avoids binary float rounding. Use this for
+prices/balances and divide by 100 only at the presentation edge.
+"""
+
+PortField = Annotated[int, Ge(1), Le(65535)]
+"""TCP/UDP port number in the valid range ``1..65535``."""
+
+# --- Floats ---------------------------------------------------------------
+
+PositiveFloatField = Annotated[float, Gt(0)]
+"""Float strictly greater than zero."""
+
+NonNegativeFloatField = Annotated[float, Ge(0)]
+"""Float greater than or equal to zero."""
+
+PercentField = Annotated[float, Ge(0), Le(100)]
+"""Percentage in the inclusive range ``0..100``."""
+
+RatioField = Annotated[float, Ge(0), Le(1)]
+"""Fraction/probability in the inclusive range ``0..1``."""
+
+LatitudeField = Annotated[float, Ge(-90), Le(90)]
+"""Geographic latitude in degrees, ``-90..90``."""
+
+LongitudeField = Annotated[float, Ge(-180), Le(180)]
+"""Geographic longitude in degrees, ``-180..180``."""
+
+# --- Decimals -------------------------------------------------------------
+
+PriceField = Annotated[Decimal, Field(ge=0, decimal_places=2)]
+"""Non-negative monetary amount as a :class:`~decimal.Decimal`, 2 places.
+
+Prefer :data:`CentsField` (integer cents) for storage; use ``PriceField``
+when an exact decimal with two fractional digits is the contract (e.g. a
+payment gateway payload).
+"""
+
+# --- Strings --------------------------------------------------------------
+
+NonEmptyStrField = Annotated[
+    str,
+    StringConstraints(strip_whitespace=True, min_length=1),
+]
+"""String trimmed of surrounding whitespace, rejected when empty.
+
+Whitespace-only input fails because it is stripped to ``""`` before the
+``min_length=1`` check.
+"""
+
+SlugField = Annotated[
+    str,
+    StringConstraints(pattern=r"^[a-z0-9]+(?:-[a-z0-9]+)*$"),
+]
+"""URL-safe slug: lowercase alphanumerics in kebab-case (``my-post-1``)."""
+
+HexColorField = Annotated[
+    str,
+    StringConstraints(pattern=r"^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$"),
+]
+"""CSS hex color, 3 or 6 hex digits with a leading ``#`` (``#fff`` / ``#abc123``)."""
+
+
+__all__: list[str] = [
+    "CentsField",
+    "HexColorField",
+    "LatitudeField",
+    "LongitudeField",
+    "NonEmptyStrField",
+    "NonNegativeFloatField",
+    "NonNegativeIntField",
+    "PercentField",
+    "PortField",
+    "PositiveFloatField",
+    "PositiveIntField",
+    "PriceField",
+    "RatioField",
+    "SlugField",
+]