cnovatech-sdk-core 0.1.0__tar.gz

cnovatech_sdk_core-0.1.0/.gitignore

@@ -0,0 +1,26 @@
+# Environments and secrets
+.venv/
+.venv-*/
+.env
+.env.*
+!.env.example
+
+# Build output
+dist/
+build/
+*.egg-info/
+
+# Tool caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+coverage.xml
+htmlcov/
+__pycache__/
+*.pyc
+
+# Editors and OS
+.idea/
+.vscode/
+.DS_Store

cnovatech_sdk_core-0.1.0/CHANGELOG.md

@@ -0,0 +1,57 @@
+# Changelog
+
+All notable changes to `cnovatech-sdk-core` are documented here. The format
+follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the
+project uses [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-11-06
+
+First release, together with `cnovatech-datamarket`. Rehearsed on TestPyPI as
+0.1.0.dev1.
+
+### Added
+
+- `ProductSettings` and `ClientConfig` with validation of API key (printable
+  ASCII only, so a key copied with an invisible character or a line break is
+  refused before any request), base URL (HTTPS required outside loopback),
+  timeouts (read timeout capped at the server's 300 s), retry count and
+  budget. Explicit arguments win over environment variables, which win over
+  product defaults.
+- `Operation`: a transport-independent description of one API call, and
+  `Endpoint`: where a call lives, declared once per endpoint.
+- `BaseSyncClient` / `BaseAsyncClient` and `SyncResource` / `AsyncResource`:
+  the client and resource plumbing every product SDK shares.
+- `SyncTransport` and `AsyncTransport` over httpx, sharing request preparation
+  and response interpretation. Correlation ID per request, kept across
+  retries and reported on every error, including connection errors and
+  timeouts, even when the API does not echo it; descriptive `User-Agent`;
+  `None` query parameters omitted. Redirects are never followed and the
+  configured timeout applies per request, also through a user-supplied
+  `http_client`. Every `httpx.RequestError`, including a response body that
+  cannot be decoded, becomes an `APIConnectionError`.
+- `RetryPolicy`: connection failures that happen before the request is sent,
+  502/503 and the per-minute 429 are repeated with capped exponential
+  backoff and jitter, honouring `Retry-After`. Read timeouts, 504 (the
+  application may still be processing the request), connections dropped
+  mid-response, quota errors and other 4xx/5xx are never repeated. Each
+  retry is logged at INFO with structured fields.
+- `max_units_per_request`: an operation whose estimated cost is above the
+  ceiling raises `BudgetExceededError` before anything is sent.
+- Exception hierarchy rooted at `CnovatechError`, with `APIStatusError`
+  subclasses chosen by HTTP status and, for 429, by error code.
+  `APIConnectionError.retryable` says whether a repeat could bill twice.
+  Every exception can be pickled, so it crosses process pools intact.
+- `UsageTracker` and `RateLimitState`, fed by every response; a quota error
+  refreshes the last known balance without counting a call.
+- `APIResponse` base model (immutable, keeps unknown fields) with
+  `request_info`, `Record` for nested objects, plus `Usage`, `PaginationMeta`
+  and `ListMeta`.
+- `SyncPage` / `AsyncPage` with `iter_pages` and `iter_all` capped by
+  `max_pages` or `max_units`; pages can be pickled, without the ability to
+  fetch further pages. `TabularResponse.to_dataframe()` with nested rows,
+  envelope columns that collide with a row field prefixed by the response's
+  name, and pandas imported on first use.
+- Validation helpers accept `uuid.UUID` identifiers and any iterable of
+  strings as a batch.

cnovatech_sdk_core-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cnovatech
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cnovatech_sdk_core-0.1.0/PKG-INFO

@@ -0,0 +1,53 @@
+Metadata-Version: 2.5
+Name: cnovatech-sdk-core
+Version: 0.1.0
+Summary: Shared HTTP transport, configuration, errors and pagination for the Cnovatech Python SDKs.
+Project-URL: Homepage, https://cnovatech.com.br
+Project-URL: Repository, https://github.com/cnovatech-br/sdks
+Project-URL: Changelog, https://github.com/cnovatech-br/sdks/blob/main/core/CHANGELOG.md
+Author-email: Cnovatech <suporte@cnovatech.com.br>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: client,cnovatech,http,sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx<1.0,>=0.27
+Requires-Dist: pydantic<3.0,>=2.12
+Provides-Extra: pandas
+Requires-Dist: pandas>=2.0; extra == 'pandas'
+Description-Content-Type: text/markdown
+
+# cnovatech-sdk-core
+
+Shared foundation of the Cnovatech Python SDKs: configuration, HTTP transport
+(sync and async), error hierarchy, pagination and quota accounting.
+
+This package is not meant to be installed on its own. Product SDKs such as
+[`cnovatech-datamarket`](https://pypi.org/project/cnovatech-datamarket/)
+depend on it and re-export everything their users need. If you are
+integrating with a Cnovatech API, install the product SDK. Source and issues:
+<https://github.com/cnovatech-br/sdks>.
+
+## Boundary
+
+The core knows nothing about any product: no endpoint, no field name, no domain
+concept. CI fails if a product term appears under `core/src`. Product-specific
+behaviour reaches the core only through `ProductSettings` (environment prefix,
+base URL, API prefix, error overrides) and `Operation` objects built by the
+product's resources.
+
+## Versioning
+
+The core and the product SDKs are released together and share a version number.
+A product SDK pins the core to the same minor series.

cnovatech_sdk_core-0.1.0/README.md

@@ -0,0 +1,23 @@
+# cnovatech-sdk-core
+
+Shared foundation of the Cnovatech Python SDKs: configuration, HTTP transport
+(sync and async), error hierarchy, pagination and quota accounting.
+
+This package is not meant to be installed on its own. Product SDKs such as
+[`cnovatech-datamarket`](https://pypi.org/project/cnovatech-datamarket/)
+depend on it and re-export everything their users need. If you are
+integrating with a Cnovatech API, install the product SDK. Source and issues:
+<https://github.com/cnovatech-br/sdks>.
+
+## Boundary
+
+The core knows nothing about any product: no endpoint, no field name, no domain
+concept. CI fails if a product term appears under `core/src`. Product-specific
+behaviour reaches the core only through `ProductSettings` (environment prefix,
+base URL, API prefix, error overrides) and `Operation` objects built by the
+product's resources.
+
+## Versioning
+
+The core and the product SDKs are released together and share a version number.
+A product SDK pins the core to the same minor series.

cnovatech_sdk_core-0.1.0/pyproject.toml

@@ -0,0 +1,86 @@
+[project]
+name = "cnovatech-sdk-core"
+version = "0.1.0"
+description = "Shared HTTP transport, configuration, errors and pagination for the Cnovatech Python SDKs."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Cnovatech", email = "suporte@cnovatech.com.br" }]
+keywords = ["cnovatech", "sdk", "http", "client"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: 3.15",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+# pydantic 2.12 is the first release with wheels for Python 3.14.
+dependencies = [
+    "httpx>=0.27,<1.0",
+    "pydantic>=2.12,<3.0",
+]
+
+[project.optional-dependencies]
+pandas = ["pandas>=2.0"]
+
+[project.urls]
+Homepage = "https://cnovatech.com.br"
+Repository = "https://github.com/cnovatech-br/sdks"
+Changelog = "https://github.com/cnovatech-br/sdks/blob/main/core/CHANGELOG.md"
+
+[build-system]
+requires = ["hatchling>=1.27,<2"]
+build-backend = "hatchling.build"
+
+# `src/cnovatech/` has no __init__.py on purpose: it is a PEP 420 namespace
+# shared with the product SDKs (`cnovatech.datamarket`, ...).
+[tool.hatch.build.targets.wheel]
+packages = ["src/cnovatech"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "tests", "README.md", "CHANGELOG.md", "LICENSE", "pyproject.toml"]
+
+[tool.mypy]
+python_version = "3.10"
+files = ["src", "tests"]
+mypy_path = "src:tests"
+strict = true
+warn_unreachable = true
+namespace_packages = true
+explicit_package_bases = true
+plugins = ["pydantic.mypy"]
+
+[tool.pydantic-mypy]
+init_forbid_extra = true
+init_typed = true
+warn_required_dynamic_aliases = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+addopts = "-q --strict-markers --strict-config"
+filterwarnings = ["error"]
+
+[tool.coverage.run]
+source = ["src/cnovatech/sdk_core"]
+branch = true
+
+[tool.coverage.report]
+fail_under = 90
+show_missing = true
+exclude_also = [
+    "if TYPE_CHECKING:",
+    "if sys.version_info",
+    "@overload",
+    "raise NotImplementedError",
+    "\\.\\.\\.$",
+]

cnovatech_sdk_core-0.1.0/src/cnovatech/sdk_core/__init__.py

@@ -0,0 +1,24 @@
+"""Shared foundation of the Cnovatech Python SDKs.
+
+This package is not used directly by application code. The product SDKs build
+on its modules (``config``, ``transport``, ``client``, ``resource``, ``models``,
+``pagination``, ``errors``, ...) and re-export what their users need. It knows
+nothing about any product: no endpoint, field name or domain concept lives
+here, and CI enforces that boundary.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from .config import CORE_DISTRIBUTION_NAME
+from .metadata import read_distribution_version
+
+__version__ = read_distribution_version(CORE_DISTRIBUTION_NAME)
+
+# Libraries log but never configure logging. The null handler keeps Python from
+# printing "No handlers could be found" when the application has not set up
+# logging; the application routes the `cnovatech` logger wherever it wants.
+logging.getLogger("cnovatech").addHandler(logging.NullHandler())
+
+__all__ = ["__version__"]

cnovatech_sdk_core-0.1.0/src/cnovatech/sdk_core/client.py

@@ -0,0 +1,146 @@
+"""What every product client shares: configuration, transport, accounting and lifecycle.
+
+A product SDK subclasses :class:`BaseSyncClient` and :class:`BaseAsyncClient`,
+binds its :class:`ProductSettings` and attaches its resources. Everything
+else, from reading the environment to closing the connection pool, is here.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from .config import DEFAULT_MAX_RETRIES, DEFAULT_READ_TIMEOUT_SECONDS, build_client_config
+from .transport import AsyncTransport, SyncTransport
+
+if TYPE_CHECKING:
+    from types import TracebackType
+
+    import httpx
+    from typing_extensions import Self
+
+    from .config import ProductSettings
+    from .usage import RateLimitState, UsageTracker
+
+
+class BaseSyncClient:
+    """A client using blocking I/O. See the product client for the constructor arguments."""
+
+    def __init__(
+        self,
+        product: ProductSettings,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        timeout: float | httpx.Timeout = DEFAULT_READ_TIMEOUT_SECONDS,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        max_units_per_request: int | None = None,
+        http_client: httpx.Client | None = None,
+        transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        self._config = build_client_config(
+            product,
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+            max_units_per_request=max_units_per_request,
+        )
+        self._transport = SyncTransport(self._config, http_client=http_client, transport=transport)
+
+    @property
+    def base_url(self) -> str:
+        """Origin the client talks to."""
+        return self._config.base_url
+
+    @property
+    def usage(self) -> UsageTracker:
+        """Quota spent through this client: ``spent``, ``calls`` and the ``last`` usage block."""
+        return self._transport.usage
+
+    @property
+    def rate_limit(self) -> RateLimitState:
+        """The per-minute rate limit as last reported by the API."""
+        return self._transport.rate_limit
+
+    def close(self) -> None:
+        """Release the connection pool. Clients supplied through ``http_client`` are left open."""
+        self._transport.close()
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        self.close()
+
+    def __repr__(self) -> str:
+        return (
+            f"{type(self).__name__}(base_url={self._config.base_url!r}, "
+            f"api_key={self._config.masked_api_key!r})"
+        )
+
+
+class BaseAsyncClient:
+    """A client using asyncio. See the product client for the constructor arguments."""
+
+    def __init__(
+        self,
+        product: ProductSettings,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        timeout: float | httpx.Timeout = DEFAULT_READ_TIMEOUT_SECONDS,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        max_units_per_request: int | None = None,
+        http_client: httpx.AsyncClient | None = None,
+        transport: httpx.AsyncBaseTransport | None = None,
+    ) -> None:
+        self._config = build_client_config(
+            product,
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+            max_units_per_request=max_units_per_request,
+        )
+        self._transport = AsyncTransport(self._config, http_client=http_client, transport=transport)
+
+    @property
+    def base_url(self) -> str:
+        """Origin the client talks to."""
+        return self._config.base_url
+
+    @property
+    def usage(self) -> UsageTracker:
+        """Quota spent through this client: ``spent``, ``calls`` and the ``last`` usage block."""
+        return self._transport.usage
+
+    @property
+    def rate_limit(self) -> RateLimitState:
+        """The per-minute rate limit as last reported by the API."""
+        return self._transport.rate_limit
+
+    async def aclose(self) -> None:
+        """Release the connection pool. Clients supplied through ``http_client`` are left open."""
+        await self._transport.aclose()
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        await self.aclose()
+
+    def __repr__(self) -> str:
+        return (
+            f"{type(self).__name__}(base_url={self._config.base_url!r}, "
+            f"api_key={self._config.masked_api_key!r})"
+        )