truewire-core 0.1.0__tar.gz

truewire_core-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tribulnation Labs, S.L. and Truewire contributors
+
+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.

truewire_core-0.1.0/PKG-INFO

@@ -0,0 +1,159 @@
+Metadata-Version: 2.4
+Name: truewire-core
+Version: 0.1.0
+Summary: Runtime for Truewire-generated API clients: async HTTP and WebSocket transport, response validation, paging, timestamps, errors.
+Author: Truewire contributors
+License-Expression: MIT
+Project-URL: Repository, https://github.com/truewire-dev/truewire
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typing-extensions
+Requires-Dist: httpx
+Requires-Dist: websockets
+Requires-Dist: orjson
+Requires-Dist: pydantic
+Requires-Dist: lazy-loader
+Provides-Extra: grpc
+Requires-Dist: grpclib; extra == "grpc"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: grpclib; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Dynamic: license-file
+
+# Truewire Core
+
+> Runtime for Truewire-generated API clients
+
+[![PyPI version](https://img.shields.io/pypi/v/truewire-core.svg)](https://pypi.org/project/truewire-core/)
+[![License](https://img.shields.io/pypi/l/truewire-core.svg)](LICENSE)
+
+Every client generated by [Truewire](https://github.com/truewire-dev/truewire) depends on this
+package. It holds the parts of a client that are the same for every API — async HTTP and
+WebSocket transport, response validation, paging, timestamp conversion and the error
+hierarchy — so that generated code only has to carry what is genuinely specific to one API:
+envelope extraction, error mapping, request signing, wire quirks.
+
+You do not normally install it directly; a generated client lists it as a dependency. You
+will import from it when catching errors, converting timestamps, or driving a paginated walk.
+
+## Installation
+
+```bash
+pip install truewire-core
+```
+
+Optional extras:
+
+```bash
+pip install 'truewire-core[grpc]'   # gRPC transport (grpclib)
+```
+
+## What it provides
+
+| module | contents |
+| --- | --- |
+| `truewire_core.exceptions` | `Error`, `NetworkError`, `ValidationError`, `ApiError` (`BadRequest`, `AuthError`, `RateLimited`), `LogicError` |
+| `truewire_core.http` | `HttpClient`, an async HTTP client wrapping `httpx` with lazy connection and `NetworkError` mapping |
+| `truewire_core.ws` | WebSocket base classes: `Socket`, `Streams`, `Rpc`, `StreamsRpc`, `SerialReplies` |
+| `truewire_core.grpc` | `GrpcClient`, `GrpcEndpoint`, `wrap_exceptions` (requires the `grpc` extra) |
+| `truewire_core.validation` | `validator[T]`, a cached pydantic adapter that validates and dumps wire shapes, and a base `TypedDict` that tolerates undocumented fields |
+| `truewire_core.times` | `TimeConverter`, `EpochConverter`, `IsoConverter`, `DateConverter` — parse/dump between a wire timestamp and a real `datetime`/`date` |
+| `truewire_core.util` | `PaginatedResponse`/`Page`, `Stream`/`StreamManager`, `RateLimit`, and small numeric/path helpers |
+
+### Errors
+
+Every failure a client raises derives from `truewire_core.exceptions.Error`:
+
+```python
+from truewire_core.exceptions import ApiError, AuthError, NetworkError, RateLimited
+
+try:
+  order = await client.orders.get(id='ord_123')
+except AuthError:
+  ...          # bad or missing credentials
+except RateLimited:
+  ...          # the API told us to slow down
+except ApiError as e:
+  ...          # any other error the API itself returned (BadRequest, ...)
+except NetworkError:
+  ...          # couldn't reach the server, or the connection dropped
+```
+
+Generated clients re-export these from their own package root, so `from my_client import
+AuthError` works too. Route such re-exports through `lazy_loader.attach_stub` (with a matching
+`__init__.pyi`), not a plain `from truewire_core.exceptions import ...` in an `__init__.py` —
+the latter breaks type-checking for every downstream consumer of a `py.typed` package.
+
+### Timestamps
+
+APIs put timestamps on the wire in many shapes: epoch seconds, milliseconds, microseconds or
+nanoseconds; RFC 3339 strings with or without a `Z`; plain calendar dates. Each converter
+turns one such shape into a real `datetime` (or `date`) and back:
+
+```python
+from datetime import timezone
+from truewire_core.times import DateConverter, EpochConverter, IsoConverter
+
+timestamp_millis = EpochConverter.milliseconds(tz=timezone.utc)   # 1717072496123 <-> datetime
+timestamp_seconds = EpochConverter.seconds(tz=timezone.utc)       # 1717072496 <-> datetime
+timestamp_iso = IsoConverter()                                    # '2024-05-30T12:34:56Z' <-> datetime
+calendar_date = DateConverter()                                   # '2024-05-30' <-> date
+
+dt = timestamp_iso.parse('2024-05-30T12:34:56.123456789Z')       # any fraction length, any Python >= 3.10
+timestamp_millis.dump(dt)                                         # 1717072496123
+```
+
+A generated client wires these into its field types through pydantic, so a response field
+declared as a millisecond epoch arrives as a `datetime` and a request parameter typed as one
+is serialized back to the wire format the API expects.
+
+### Paging
+
+Every generated `<method>_paged` returns a `PaginatedResponse`: awaitable (every row,
+flattened) and async-iterable (one page of rows at a time). Each page is one pure
+`next(state)` call, so a caller can retry or resume a single page rather than the whole walk.
+
+```python
+from truewire_core import PaginatedResponse
+
+paging = client.orders.list_paged(status='open')
+orders = await paging                        # every row, flattened
+async for rows in paging: ...                # one page at a time
+async for page in paging.pages():            # Page(rows, state, next), for checkpointing
+  checkpoint(page.next)
+paging.resume(saved_state)                   # restart from a checkpointed state
+paging.via(retried)                          # route every page fetch through a middleware
+```
+
+`via(call)` hands each page fetch to `call` as one zero-argument coroutine function, so a
+retry or logging layer wraps a page without unrolling the loop by hand.
+
+### Validation
+
+Generated response types are `TypedDict`s. `validator` wraps a cached pydantic `TypeAdapter`
+around one and raises `truewire_core.exceptions.ValidationError` (not pydantic's own) when
+the wire body doesn't match:
+
+```python
+from truewire_core.validation import TypedDict, validator
+
+class Order(TypedDict):
+  id: str
+  amount: str
+
+order = validator(Order)(b'{"id": "ord_123", "amount": "10.5", "extra": true}')
+# {'id': 'ord_123', 'amount': '10.5', 'extra': True} -- undocumented fields are kept, not rejected
+validator(Order).dump(order)   # b'{"id":"ord_123","amount":"10.5","extra":true}'
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

truewire_core-0.1.0/README.md

@@ -0,0 +1,129 @@
+# Truewire Core
+
+> Runtime for Truewire-generated API clients
+
+[![PyPI version](https://img.shields.io/pypi/v/truewire-core.svg)](https://pypi.org/project/truewire-core/)
+[![License](https://img.shields.io/pypi/l/truewire-core.svg)](LICENSE)
+
+Every client generated by [Truewire](https://github.com/truewire-dev/truewire) depends on this
+package. It holds the parts of a client that are the same for every API — async HTTP and
+WebSocket transport, response validation, paging, timestamp conversion and the error
+hierarchy — so that generated code only has to carry what is genuinely specific to one API:
+envelope extraction, error mapping, request signing, wire quirks.
+
+You do not normally install it directly; a generated client lists it as a dependency. You
+will import from it when catching errors, converting timestamps, or driving a paginated walk.
+
+## Installation
+
+```bash
+pip install truewire-core
+```
+
+Optional extras:
+
+```bash
+pip install 'truewire-core[grpc]'   # gRPC transport (grpclib)
+```
+
+## What it provides
+
+| module | contents |
+| --- | --- |
+| `truewire_core.exceptions` | `Error`, `NetworkError`, `ValidationError`, `ApiError` (`BadRequest`, `AuthError`, `RateLimited`), `LogicError` |
+| `truewire_core.http` | `HttpClient`, an async HTTP client wrapping `httpx` with lazy connection and `NetworkError` mapping |
+| `truewire_core.ws` | WebSocket base classes: `Socket`, `Streams`, `Rpc`, `StreamsRpc`, `SerialReplies` |
+| `truewire_core.grpc` | `GrpcClient`, `GrpcEndpoint`, `wrap_exceptions` (requires the `grpc` extra) |
+| `truewire_core.validation` | `validator[T]`, a cached pydantic adapter that validates and dumps wire shapes, and a base `TypedDict` that tolerates undocumented fields |
+| `truewire_core.times` | `TimeConverter`, `EpochConverter`, `IsoConverter`, `DateConverter` — parse/dump between a wire timestamp and a real `datetime`/`date` |
+| `truewire_core.util` | `PaginatedResponse`/`Page`, `Stream`/`StreamManager`, `RateLimit`, and small numeric/path helpers |
+
+### Errors
+
+Every failure a client raises derives from `truewire_core.exceptions.Error`:
+
+```python
+from truewire_core.exceptions import ApiError, AuthError, NetworkError, RateLimited
+
+try:
+  order = await client.orders.get(id='ord_123')
+except AuthError:
+  ...          # bad or missing credentials
+except RateLimited:
+  ...          # the API told us to slow down
+except ApiError as e:
+  ...          # any other error the API itself returned (BadRequest, ...)
+except NetworkError:
+  ...          # couldn't reach the server, or the connection dropped
+```
+
+Generated clients re-export these from their own package root, so `from my_client import
+AuthError` works too. Route such re-exports through `lazy_loader.attach_stub` (with a matching
+`__init__.pyi`), not a plain `from truewire_core.exceptions import ...` in an `__init__.py` —
+the latter breaks type-checking for every downstream consumer of a `py.typed` package.
+
+### Timestamps
+
+APIs put timestamps on the wire in many shapes: epoch seconds, milliseconds, microseconds or
+nanoseconds; RFC 3339 strings with or without a `Z`; plain calendar dates. Each converter
+turns one such shape into a real `datetime` (or `date`) and back:
+
+```python
+from datetime import timezone
+from truewire_core.times import DateConverter, EpochConverter, IsoConverter
+
+timestamp_millis = EpochConverter.milliseconds(tz=timezone.utc)   # 1717072496123 <-> datetime
+timestamp_seconds = EpochConverter.seconds(tz=timezone.utc)       # 1717072496 <-> datetime
+timestamp_iso = IsoConverter()                                    # '2024-05-30T12:34:56Z' <-> datetime
+calendar_date = DateConverter()                                   # '2024-05-30' <-> date
+
+dt = timestamp_iso.parse('2024-05-30T12:34:56.123456789Z')       # any fraction length, any Python >= 3.10
+timestamp_millis.dump(dt)                                         # 1717072496123
+```
+
+A generated client wires these into its field types through pydantic, so a response field
+declared as a millisecond epoch arrives as a `datetime` and a request parameter typed as one
+is serialized back to the wire format the API expects.
+
+### Paging
+
+Every generated `<method>_paged` returns a `PaginatedResponse`: awaitable (every row,
+flattened) and async-iterable (one page of rows at a time). Each page is one pure
+`next(state)` call, so a caller can retry or resume a single page rather than the whole walk.
+
+```python
+from truewire_core import PaginatedResponse
+
+paging = client.orders.list_paged(status='open')
+orders = await paging                        # every row, flattened
+async for rows in paging: ...                # one page at a time
+async for page in paging.pages():            # Page(rows, state, next), for checkpointing
+  checkpoint(page.next)
+paging.resume(saved_state)                   # restart from a checkpointed state
+paging.via(retried)                          # route every page fetch through a middleware
+```
+
+`via(call)` hands each page fetch to `call` as one zero-argument coroutine function, so a
+retry or logging layer wraps a page without unrolling the loop by hand.
+
+### Validation
+
+Generated response types are `TypedDict`s. `validator` wraps a cached pydantic `TypeAdapter`
+around one and raises `truewire_core.exceptions.ValidationError` (not pydantic's own) when
+the wire body doesn't match:
+
+```python
+from truewire_core.validation import TypedDict, validator
+
+class Order(TypedDict):
+  id: str
+  amount: str
+
+order = validator(Order)(b'{"id": "ord_123", "amount": "10.5", "extra": true}')
+# {'id': 'ord_123', 'amount': '10.5', 'extra': True} -- undocumented fields are kept, not rejected
+validator(Order).dump(order)   # b'{"id":"ord_123","amount":"10.5","extra":true}'
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

truewire_core-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["setuptools", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "truewire-core"
+version = "0.1.0"
+authors = [
+  {name="Truewire contributors"}
+]
+description = "Runtime for Truewire-generated API clients: async HTTP and WebSocket transport, response validation, paging, timestamps, errors."
+license = "MIT"
+license-files = ["LICENSE"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Typing :: Typed",
+]
+dependencies = [
+  "typing-extensions", "httpx", "websockets", "orjson", "pydantic",
+  "lazy-loader",
+]
+requires-python = ">=3.10"
+readme = {file="README.md", content-type="text/markdown"}
+
+[project.optional-dependencies]
+grpc = ["grpclib"]
+dev = ["pytest", "pytest-asyncio", "grpclib", "ruff"]
+
+[project.urls]
+Repository = "https://github.com/truewire-dev/truewire"
+
+[tool.setuptools.package-data]
+truewire_core = ["py.typed", "**/*.pyi"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["test"]

truewire_core-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

truewire_core-0.1.0/src/truewire_core/__init__.py

@@ -0,0 +1,2 @@
+import lazy_loader as lazy
+__getattr__, __dir__, __all__ = lazy.attach_stub(__name__, __file__)

truewire_core-0.1.0/src/truewire_core/__init__.pyi

@@ -0,0 +1,14 @@
+from .exceptions import (
+  Error, NetworkError, ValidationError,
+  ApiError, BadRequest, AuthError, RateLimited, LogicError
+)
+from .http import HttpClient
+from . import ws
+from .util import round2tick, trunc2tick, ceil2tick, path_join, PaginatedResponse, Page
+
+__all__ = [
+  'Error', 'NetworkError', 'ValidationError',
+  'ApiError', 'BadRequest', 'AuthError', 'RateLimited', 'LogicError',
+  'HttpClient', 'ws',
+  'round2tick', 'trunc2tick', 'ceil2tick', 'path_join', 'PaginatedResponse', 'Page',
+]

truewire_core-0.1.0/src/truewire_core/exceptions.py

@@ -0,0 +1,41 @@
+class Error(Exception):
+  """Base exception"""
+  def __str__(self):
+    args = list(map(str, self.args))
+    args = self.args[0] if len(self.args) == 1 else ', '.join(map(str, self.args))
+    return f'{self.__class__.__name__}({args})'
+
+class NetworkError(Error):
+  """Error reaching the server."""
+  def __str__(self):
+    return super().__str__()
+
+class ValidationError(Error):
+  """Invalid response format."""
+  def __str__(self):
+    return super().__str__()
+
+class ApiError(Error):
+  """Error returned by the API."""
+  def __str__(self):
+    return super().__str__()
+
+class BadRequest(ApiError):
+  """Bad request: invalid request, invalid input, etc."""
+  def __str__(self):
+    return super().__str__()
+
+class AuthError(ApiError):
+  """Authentication error: invalid API key, invalid API secret, etc."""
+  def __str__(self):
+    return super().__str__()
+
+class RateLimited(ApiError):
+  """Rate limited: the API has reached the rate limit."""
+  def __str__(self):
+    return super().__str__()
+
+class LogicError(Error):
+  """Logic error: invalid assumptions, logic, or other bugs on the SDK side."""
+  def __str__(self):
+    return super().__str__()

truewire_core-0.1.0/src/truewire_core/grpc.py

@@ -0,0 +1,94 @@
+"""Shared gRPC transport primitives."""
+
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass, field
+from functools import wraps
+from types import TracebackType
+
+from grpclib.client import Channel
+from grpclib.const import Status
+from grpclib.exceptions import GRPCError, ProtocolError, StreamTerminatedError
+from typing_extensions import ParamSpec, Self, TypeVar
+
+from .exceptions import NetworkError
+
+# gRPC statuses that represent transport failures rather than API/business errors.
+_NETWORK_STATUSES = frozenset({Status.UNAVAILABLE})
+
+P = ParamSpec('P')
+T = TypeVar('T')
+
+def wrap_exceptions(fn: Callable[P, Awaitable[T]]) -> Callable[P, Awaitable[T]]:
+  """Map grpclib transport failures from a gRPC call to truewire_core NetworkError.
+
+  Transport-level failures (GOAWAY, HTTP/2 protocol errors, terminated streams, and
+  gRPC unavailable/502 responses) are raised as NetworkError. Business/API errors,
+  which arrive either in a successful response payload or as a non-transport GRPCError,
+  are left untouched.
+  """
+  @wraps(fn)
+  async def wrapper(*args: P.args, **kwargs: P.kwargs) -> T:
+    """Await the wrapped gRPC call, normalizing transport exceptions."""
+    try:
+      return await fn(*args, **kwargs)
+    except (ProtocolError, StreamTerminatedError, ConnectionError, TimeoutError) as exc:
+      raise NetworkError(str(exc)) from exc
+    except GRPCError as exc:
+      if exc.status in _NETWORK_STATUSES:
+        raise NetworkError(str(exc)) from exc
+      raise
+  return wrapper
+
+@dataclass(kw_only=True)
+class GrpcClient:
+  """Async gRPC transport that owns a lazily opened channel.
+
+  Not frozen, unlike `GrpcEndpoint` below -- it needs a real mutable `_channel` slot
+  to cache into, the same shape `HttpClient._client` already uses for the identical
+  lazy-open/close contract on the HTTP side. `GrpcEndpoint`'s own freeze is a separate
+  concern (matching every other `Endpoint` composition base) and doesn't require the
+  `Client` object it merely holds a reference to to be frozen too.
+  """
+
+  host: str
+  port: int = 443
+  ssl: bool = True
+  _channel: Channel | None = field(default=None, init=False, repr=False)
+
+  @property
+  def channel(self) -> Channel:
+    """Return the gRPC channel, creating it on first use."""
+    if self._channel is None:
+      self._channel = Channel(self.host, self.port, ssl=self.ssl)
+    return self._channel
+
+  async def __aenter__(self) -> Self:
+    """Take ownership without connecting -- the channel opens lazily on first use,
+    matching `HttpClient.__aenter__`'s own contract."""
+    return self
+
+  async def __aexit__(
+    self,
+    exc_type: type[BaseException] | None,
+    exc: BaseException | None,
+    traceback: TracebackType | None,
+  ):
+    """Close the channel for an async client context."""
+    self.close()
+
+  def close(self):
+    """Close the open channel, if one was created."""
+    if self._channel is not None:
+      self._channel.close()
+      self._channel = None
+
+@dataclass(kw_only=True, frozen=True)
+class GrpcEndpoint:
+  """Base for every generated/hand-written gRPC module -- talks only to `client`."""
+
+  client: GrpcClient
+
+  @property
+  def channel(self) -> Channel:
+    """Return the active shared gRPC channel."""
+    return self.client.channel

truewire_core-0.1.0/src/truewire_core/http.py

@@ -0,0 +1,68 @@
+from typing_extensions import Any, Mapping
+from dataclasses import dataclass, field
+import asyncio
+import os
+import httpx
+
+from truewire_core.exceptions import NetworkError
+
+def _default_limits() -> httpx.Limits:
+  if os.environ.get('HTTPS_PROXY') or os.environ.get('HTTP_PROXY'):
+    return httpx.Limits(max_keepalive_connections=0)
+  return httpx.Limits()
+
+@dataclass
+class HttpClient:
+  """Managed HTTP client, wrapping `httpx.AsyncClient`.
+
+  ### Concurrency Contract
+  1. Connection: single owner via `async with`, also supports lazy no-owner use
+  2. Requests: many concurrent callers OK
+  """
+  limits: httpx.Limits = field(default_factory=_default_limits)
+  lock: asyncio.Lock = field(default_factory=asyncio.Lock, init=False, repr=False)
+  _client: httpx.AsyncClient | None = None
+
+  @property
+  async def client(self) -> httpx.AsyncClient:
+    async with self.lock:
+      if self._client is None:
+        self._client = await httpx.AsyncClient(limits=self.limits).__aenter__()
+      return self._client
+
+  async def __aenter__(self):
+    """Take ownership without connecting; the underlying client opens lazily on first use."""
+    return self
+
+  async def __aexit__(self, exc_type, exc_value, traceback):
+    async with self.lock:
+      if self._client is not None:
+        await self._client.__aexit__(exc_type, exc_value, traceback)
+        self._client = None
+
+  async def request(
+    self, method: str, url: str,
+    *,
+    content: httpx._types.RequestContent | None = None,
+    data: httpx._types.RequestData | None = None,
+    files: httpx._types.RequestFiles | None = None,
+    json: Any | None = None,
+    params: Mapping[str, Any] | None = None,
+    headers: Mapping | None = None,
+    cookies: httpx._types.CookieTypes | None = None,
+    auth: httpx._types.AuthTypes | httpx._client.UseClientDefault | None = httpx.USE_CLIENT_DEFAULT,
+    follow_redirects: bool | httpx._client.UseClientDefault = httpx.USE_CLIENT_DEFAULT,
+    timeout: httpx._types.TimeoutTypes | httpx._client.UseClientDefault = httpx.USE_CLIENT_DEFAULT,
+    extensions: httpx._types.RequestExtensions | None = None,
+  ):
+    try:
+      client = await self.client
+      return await client.request(
+        method, url, params=params, cookies=cookies, json=json,
+        content=content, data=data, files=files, auth=auth, follow_redirects=follow_redirects,
+        timeout=timeout, extensions=extensions,
+        headers=headers,
+      )
+    except httpx.HTTPError as e:
+      req = f'{method} {url}'
+      raise NetworkError(f'Error sending request to {req}', *e.args) from e

truewire_core-0.1.0/src/truewire_core/times/__init__.py

@@ -0,0 +1,2 @@
+import lazy_loader as lazy
+__getattr__, __dir__, __all__ = lazy.attach_stub(__name__, __file__)

truewire_core-0.1.0/src/truewire_core/times/__init__.pyi

@@ -0,0 +1,6 @@
+from .base import TimeConverter
+from .date import DateConverter
+from .iso import IsoConverter
+from .ms import EpochConverter
+
+__all__ = ['TimeConverter', 'DateConverter', 'IsoConverter', 'EpochConverter']

truewire_core-0.1.0/src/truewire_core/times/base.py

@@ -0,0 +1,20 @@
+from typing_extensions import TypeVar, Generic
+from abc import ABC, abstractmethod
+from datetime import datetime
+
+T = TypeVar('T')
+
+class TimeConverter(ABC, Generic[T]):
+  """Abstract base class for time conversion between wire format and `datetime`."""
+
+  @abstractmethod
+  def parse(self, value: T) -> datetime:
+    ...
+
+  @abstractmethod
+  def dump(self, dt: datetime) -> T:
+    ...
+
+  @abstractmethod
+  def now(self) -> T:
+    ...

truewire_core-0.1.0/src/truewire_core/times/date.py

@@ -0,0 +1,37 @@
+from dataclasses import dataclass
+from datetime import date, datetime
+
+@dataclass(kw_only=True)
+class DateConverter:
+  """Converter for a plain calendar date, with no time component.
+
+  Not a `TimeConverter` -- that base class's contract is fixed to `datetime` (see
+  `base.py`), and a calendar date has no time-of-day to round-trip through one. Widening
+  `TimeConverter` itself to cover this would ripple its return type into every existing
+  subclass for the sake of this one converter; standing alone keeps the blast radius to
+  just this file.
+  """
+
+  pattern: str = '%Y-%m-%d'
+  """`datetime.strptime`/`strftime` directive for the wire string, e.g. `'%Y%m%d'` for a
+  compact `YYYYMMDD` date with no separators (`"date": "20260101"`). Defaults to RFC
+  3339's `YYYY-MM-DD`. Generic on the pattern the same way `EpochConverter` is generic on
+  `unit`/`tz` -- an API's exact wire encoding is a detail each project's own
+  `core_package` supplies, not something this converter should special-case per format.
+  """
+
+  def parse(self, value: str) -> date:
+    """Parse a wire calendar date.
+
+    Args:
+      value: The wire date, e.g. `'2026-08-03'` for the default pattern.
+    """
+    return datetime.strptime(value, self.pattern).date()
+
+  def dump(self, d: date) -> str:
+    """Render a `date` back to the wire pattern."""
+    return d.strftime(self.pattern)
+
+  def now(self) -> date:
+    """Today's date."""
+    return date.today()