pyapi-service-kit 0.0.1__tar.gz

pyapi_service_kit-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jayshan Raghunandan
+
+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.

pyapi_service_kit-0.0.1/PKG-INFO

@@ -0,0 +1,25 @@
+Metadata-Version: 2.3
+Name: pyapi-service-kit
+Version: 0.0.1
+Summary: some utiltiies used by backend python services
+License: LICENSE
+Author: jr200
+Author-email: jayshan+git@gmail.com
+Requires-Python: >=3.12,<4.0
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: nats-py (>=2.10.0,<3.0.0)
+Requires-Dist: nkeys (>=0.2.1,<0.3.0)
+Requires-Dist: polars (>=1.30.0,<2.0.0)
+Requires-Dist: polars-hist-db (>=0.8.0)
+Requires-Dist: python-dateutil (>=2.9.0.post0,<3.0.0)
+Requires-Dist: pytz (>=2025.2,<2026.0)
+Requires-Dist: pyyaml (>=6.0.2,<7.0.0)
+Description-Content-Type: text/markdown
+
+# pyapi-service-kit (wip)
+
+Collection of functions, types, utiltiies used by backend python services.
+

pyapi_service_kit-0.0.1/README.md

@@ -0,0 +1,3 @@
+# pyapi-service-kit (wip)
+
+Collection of functions, types, utiltiies used by backend python services.

pyapi_service_kit-0.0.1/pyproject.toml

@@ -0,0 +1,34 @@
+[project]
+name = "pyapi-service-kit"
+version = "0.0.1"
+description = "some utiltiies used by backend python services"
+license = "LICENSE"
+authors = [
+    {name = "jr200", email = "jayshan+git@gmail.com"}
+]
+readme = "README.md"
+requires-python = ">=3.12,<4.0"
+
+dependencies = [
+    "nats-py (>=2.10.0,<3.0.0)",
+    "nkeys (>=0.2.1,<0.3.0)",
+    "polars (>=1.30.0,<2.0.0)",
+    "pyyaml (>=6.0.2,<7.0.0)",
+    "python-dateutil (>=2.9.0.post0,<3.0.0)",
+    "pytz (>=2025.2,<2026.0)",
+    "polars-hist-db (>=0.8.0)",
+]
+
+[tool.poetry]
+packages = [{include = "pyapi_service_kit", from = "src"}]
+
+[tool.poetry.group.dev.dependencies]
+ruff = "^0.11.13"
+mypy = "^1.16.0"
+types-pyyaml = "^6.0.12.20250516"
+types-pytz = "^2025.2.0.20250516"
+types-python-dateutil = "^2.9.0.20250809"
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"

pyapi_service_kit-0.0.1/src/pyapi_service_kit/db/generic.py

@@ -0,0 +1,51 @@
+import json
+import logging
+from typing import Awaitable, Callable
+
+from polars import DataFrame
+from polars_hist_db.core import TimeHint
+from sqlalchemy.engine import Connection
+
+from nats.aio.msg import Msg
+
+from ..nats.nats_payload import NatsPayload
+from ..utils.time import parse_zoned_iso
+
+LOGGER = logging.getLogger(__name__)
+
+QueryFn = Callable[[Connection, TimeHint], Awaitable[DataFrame]]
+
+
+async def run_query_asof(
+    msg: Msg,
+    query_fn: QueryFn,
+    connection: Connection,
+) -> NatsPayload:
+    try:
+        payload = json.loads(msg.data)
+        asof_utc = parse_zoned_iso(payload["data"]["asof_utc"])
+        LOGGER.info(f"Running query for {msg.subject} asof {asof_utc.isoformat()}")
+        time_hint = TimeHint(mode="asof", asof_utc=asof_utc)
+        return await _run_query_with_time_hint(time_hint, query_fn, connection)
+    except Exception as e:
+        return NatsPayload(type="error", data=str(e))
+
+
+async def run_query_simple(
+    msg: Msg,
+    query_fn: QueryFn,
+    connection: Connection,
+) -> NatsPayload:
+    LOGGER.info(f"Running query for {msg.subject}")
+
+    time_hint = TimeHint(mode="none")
+    return await _run_query_with_time_hint(time_hint, query_fn, connection)
+
+
+async def _run_query_with_time_hint(
+    time_hint: TimeHint,
+    query_fn: QueryFn,
+    connection: Connection,
+) -> NatsPayload:
+    df = await query_fn(connection, time_hint)
+    return NatsPayload(type="ipc", data=df)

pyapi_service_kit-0.0.1/src/pyapi_service_kit/db/testing.py

@@ -0,0 +1,49 @@
+import logging
+import json
+from datetime import datetime
+from dateutil.relativedelta import relativedelta
+
+from nats.aio.client import Client as NATS
+from nats.aio.msg import Msg
+import polars as pl
+
+from ..nats.nats_payload import NatsPayload
+
+LOGGER = logging.getLogger(__name__)
+
+
+async def simulate_db_update(
+    nc: NATS,
+    publish_subject: str,
+    counter: int,
+    initial_time: datetime,
+    time_increment: relativedelta,
+):
+    parts = publish_subject.split(".")
+    fqtn = ".".join(parts[-2:])
+
+    ts = initial_time + time_increment * counter
+
+    response = NatsPayload(
+        type="json", data={"action": "update", "asof_utc": ts.isoformat()}
+    )
+    LOGGER.info(
+        f"Simulating DB table update[{counter}] for {fqtn} at {response.data['asof_utc']}"
+    )
+
+    await nc.publish(publish_subject, response.as_bytes())
+    LOGGER.info(f"Published DB table update for {fqtn}")
+
+
+async def simulate_request_reply_json(msg: Msg) -> NatsPayload:
+    request_data = json.loads(msg.data)
+    return NatsPayload(type="json", data={"msg": f"Hello '{request_data['data']}'"})
+
+
+async def simulate_request_reply_ipc(msg: Msg) -> NatsPayload:
+    request_data = json.loads(msg.data)
+
+    n = 10000
+    data = pl.DataFrame({"a": list(range(n)), "b": [request_data["data"]] * n})
+
+    return NatsPayload(type="ipc", data=data)

pyapi_service_kit-0.0.1/src/pyapi_service_kit/logging.yaml

@@ -0,0 +1,20 @@
+version: 1
+disable_existing_loggers: true
+formatters:
+  simple:
+    format: "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+
+handlers:
+  console:
+    class: logging.StreamHandler
+    formatter: simple
+    stream: ext://sys.stdout
+
+loggers:
+  pyapi_service_kit:
+    level: DEBUG
+
+root:
+  level: DEBUG
+  handlers:
+    - console

pyapi_service_kit-0.0.1/src/pyapi_service_kit/nats/core.py

@@ -0,0 +1,44 @@
+import logging
+from nats.aio.client import Client as NATS
+from nats.js.client import JetStreamContext
+
+from typing import Any, Dict
+
+LOGGER = logging.getLogger(__name__)
+
+
+async def make_nats_client(
+    nats_config: Dict[str, Any],
+) -> tuple[NATS, JetStreamContext]:
+    nc = NATS()
+
+    async def error_cb(e):
+        LOGGER.error("Error:", e)
+
+    async def disconnected_cb():
+        LOGGER.warning("Got disconnected!")
+
+    async def reconnected_cb():
+        if nc.connected_url:
+            LOGGER.info("Got reconnected to {url}".format(url=nc.connected_url.netloc))
+
+    try:
+        await nc.connect(
+            servers=nats_config["servers"],
+            disconnected_cb=disconnected_cb,
+            error_cb=error_cb,
+            reconnected_cb=reconnected_cb,
+            **nats_config["options"],
+        )
+
+        if nc.connected_url:
+            LOGGER.info("Connected to NATS at %s" % nc.connected_url.netloc)
+        else:
+            LOGGER.error("Connected to NATS but URL information not available")
+
+        js = nc.jetstream()
+
+        return nc, js
+    except Exception as e:
+        LOGGER.error(f"Failed to connect to NATS: {e}")
+        raise

pyapi_service_kit-0.0.1/src/pyapi_service_kit/nats/jetstream.py

@@ -0,0 +1,28 @@
+import logging
+from typing import Any, Mapping
+
+from nats.js.client import JetStreamContext
+
+
+LOGGER = logging.getLogger(__name__)
+
+
+async def try_delete_stream(js: JetStreamContext, stream_name: str):
+    try:
+        await js.delete_stream(stream_name)
+        return True
+    except Exception:
+        return False
+
+
+async def create_jetstream_streams(js: JetStreamContext, config: Mapping[str, Any]):
+    for stream_name, stream_config in config.items():
+        try:
+            if stream_config.get("recreate_if_exists", False):
+                await try_delete_stream(js, stream_name)
+
+            await js.add_stream(name=stream_name, **stream_config["options"])
+            LOGGER.info(f"JetStream stream {stream_name} created")
+        except Exception as e:
+            LOGGER.error(f"Error creating JetStream stream {stream_name}: {e}")
+            raise

pyapi_service_kit-0.0.1/src/pyapi_service_kit/nats/kv.py

@@ -0,0 +1,28 @@
+import logging
+from typing import Any, Mapping
+
+from nats.js.client import JetStreamContext
+
+
+LOGGER = logging.getLogger(__name__)
+
+
+async def _try_delete_key_value_bucket(js: JetStreamContext, bucket_name: str):
+    try:
+        await js.delete_key_value(bucket_name)
+        return True
+    except Exception:
+        return False
+
+
+async def create_nats_key_value_bucket(js: JetStreamContext, config: Mapping[str, Any]):
+    for kv_bucket_name, kv_config in config.items():
+        try:
+            if kv_config.get("recreate_if_exists", False):
+                await _try_delete_key_value_bucket(js, kv_bucket_name)
+
+            await js.create_key_value(bucket=kv_bucket_name, **kv_config["options"])
+            LOGGER.info(f"KV bucket {kv_bucket_name} created")
+        except Exception as e:
+            LOGGER.error(f"Error creating KV bucket {kv_bucket_name}: {e}")
+            raise

pyapi_service_kit-0.0.1/src/pyapi_service_kit/nats/nats_payload.py

@@ -0,0 +1,48 @@
+import json
+from datetime import datetime
+
+from dataclasses import dataclass
+from typing import Any, Literal
+
+from polars_hist_db.utils import to_ipc_b64
+
+
+@dataclass
+class NatsPayload:
+    type: Literal["json", "ipc", "epoch_ms", "error"]
+    data: Any
+
+    def as_bytes(self) -> bytes:
+        encodable_result: str | int | bytes
+        if self.type == "ipc":
+            encodable_result = to_ipc_b64(self.data, "zlib").decode()
+        elif self.type == "epoch_ms":
+            if isinstance(self.data, datetime):
+                encodable_result = int(self.data.timestamp() * 1000)
+            else:
+                assert isinstance(self.data, int), (
+                    "Data must be a integer object (milliseconds since epoch)"
+                )
+                encodable_result = self.data
+        else:
+            # its a json-encodable object
+            encodable_result = self.data
+
+        json_result = json.dumps(
+            {
+                "data": encodable_result,
+                "type": self.type,
+            }
+        )
+
+        result = json_result.encode("utf-8")
+        return result
+
+    def __str__(self) -> str:
+        match self.type:
+            case "json":
+                return f"Response(type={self.type}, len={len(self.data)})"
+            case "ipc":
+                return f"Response(type={self.type}, rowcount={len(self.data)})"
+            case _:
+                return f"Response(type={self.type})"

pyapi_service_kit-0.0.1/src/pyapi_service_kit/nats/tasks.py

@@ -0,0 +1,142 @@
+import asyncio
+from datetime import datetime, timedelta
+import logging
+from typing import Any, Callable, Awaitable
+import pytz
+
+from nats.aio.client import Client as NATS
+
+from .nats_payload import NatsPayload
+
+LOGGER = logging.getLogger(__name__)
+
+
+async def check_health_task(nc: NATS, _subject: str, counter: int):
+    if not nc.is_connected:
+        LOGGER.warning("NATS connection lost, attempting to reconnect...")
+    else:
+        if counter % 10 == 0:
+            LOGGER.info("NATS connection healthy")
+
+
+async def subscribe_task(
+    nc, listen_subject: str, cb: Callable[..., Awaitable[NatsPayload]]
+):
+    async def subscription_wrapper():
+        try:
+            await nc.subscribe(listen_subject, cb=cb)
+            # Keep the task running until cancelled
+            while True:
+                await asyncio.sleep(3600)  # Sleep for a long time
+        except Exception as e:
+            LOGGER.error(f"Error in subscription {listen_subject}: {e}")
+            raise
+
+    return asyncio.create_task(subscription_wrapper())
+
+
+async def request_reply_task(
+    nc: NATS, api_subject: str, cb: Callable[..., Awaitable[Any]]
+):
+    async def request_response_wrapper():
+        try:
+            LOGGER.info(f"Subscribing to {api_subject}")
+            sub = await nc.subscribe(api_subject)
+            async for msg in sub.messages:
+                msg.headers = msg.headers or dict()
+                msg.headers["received_ts"] = datetime.now(
+                    pytz.timezone("UTC")
+                ).isoformat()
+                response = await cb(msg)
+                msg.headers["processed_ts"] = datetime.now(
+                    pytz.timezone("UTC")
+                ).isoformat()
+                await msg.respond(response.as_bytes())
+
+        except Exception as e:
+            LOGGER.error(f"Error in request_reply task {api_subject}: {e}")
+            raise
+
+    return asyncio.create_task(request_response_wrapper())
+
+
+async def periodic_publisher_task(
+    nc: NATS,
+    publish_subject: str,
+    timeout: timedelta,
+    cb: Callable[..., Awaitable[NatsPayload]],
+    *args: Any,
+    **kwargs: Any,
+) -> asyncio.Task:
+    async def periodic_wrapper():
+        counter = 0
+        while True:
+            try:
+                await cb(nc, publish_subject, counter, *args, **kwargs)
+                counter += 1
+            except Exception as e:
+                LOGGER.error(f"Error in periodic task {cb.__name__}: {e}")
+            await asyncio.sleep(timeout.total_seconds())
+
+    return asyncio.create_task(periodic_wrapper())
+
+
+async def triggered_js_publish_task(
+    nc: NATS,
+    listen_subject: str,
+    publish_subject: str,
+    cb: Callable[..., Awaitable[NatsPayload]],
+) -> asyncio.Task:
+    js = nc.jetstream()
+
+    async def message_handler(msg):
+        try:
+            result = await cb(msg)
+            # Publish to JetStream instead of regular NATS
+            await js.publish(publish_subject, result.as_bytes())
+            LOGGER.info(f"Published message to JetStream stream {publish_subject}")
+        except Exception as e:
+            LOGGER.error(f"Error handling message on {listen_subject}", exc_info=e)
+
+    return await subscribe_task(nc, listen_subject, message_handler)
+
+
+async def triggered_kv_put_task(
+    nc: NATS,
+    listen_subject: str,
+    kv_bucket: str,
+    key: str,
+    cb: Callable[..., Awaitable[NatsPayload]],
+) -> asyncio.Task:
+    js = nc.jetstream()
+
+    async def message_handler(msg):
+        try:
+            result = await cb(msg)
+            kv = await js.key_value(kv_bucket)
+            await kv.put(key, result.as_bytes())
+            LOGGER.info(f"Updated key-value {kv_bucket}[{key}] {str(result)}")
+        except Exception as e:
+            LOGGER.error(f"Error handling message on {listen_subject}", exc_info=e)
+
+    return await subscribe_task(nc, listen_subject, message_handler)
+
+
+async def once_kv_put_task(
+    nc: NATS,
+    kv_bucket: str,
+    key: str,
+    cb: Callable[..., Awaitable[NatsPayload]],
+) -> asyncio.Task:
+    js = nc.jetstream()
+
+    async def once_task():
+        try:
+            result = await cb()
+            kv = await js.key_value(kv_bucket)
+            await kv.put(key, result.as_bytes())
+            LOGGER.info(f"Updated key-value {kv_bucket}[{key}]")
+        except Exception as e:
+            LOGGER.error(f"Error handling message on {kv_bucket}[{key}]", exc_info=e)
+
+    return await once_task()

pyapi_service_kit-0.0.1/src/pyapi_service_kit/utils/guid.py

@@ -0,0 +1,18 @@
+import re
+
+
+def validate_guid(guid: str) -> str:
+    if not guid or not isinstance(guid, str):
+        raise ValueError("GUID must be a non-empty string")
+
+    guid = guid.strip()
+    if not guid:
+        raise ValueError("GUID cannot be empty or whitespace")
+
+    if not re.match(r"^[a-zA-Z0-9_-]+$", guid):
+        raise ValueError(
+            f"GUID contains invalid characters: {guid}. "
+            "Only alphanumeric characters, dots, hyphens, and underscores are allowed."
+        )
+
+    return guid

pyapi_service_kit-0.0.1/src/pyapi_service_kit/utils/initalisation.py

@@ -0,0 +1,68 @@
+import argparse
+import asyncio
+from importlib.resources import files
+import logging
+import logging.config
+import signal
+import sys
+import yaml
+
+ROOT_DIR = ".."
+DEFAULT_CONFIG_FILE = str(files(__package__).joinpath(ROOT_DIR, "config.yaml"))
+
+
+def parse_args() -> argparse.Namespace:
+    argv = sys.argv[1:]
+    parser = argparse.ArgumentParser(add_help=True)
+
+    parser.add_argument(
+        "-f", "--config", help="Path to config file", default=None, dest="CONFIG_FILE"
+    )
+
+    parser.add_argument(
+        "-l",
+        "--log-config",
+        help="Path to logger config",
+        default=str(files(__package__).joinpath(ROOT_DIR, "logging.yaml")),
+        action="store",
+        dest="CONFIG_LOG",
+    )
+
+    args = parser.parse_args(argv)
+
+    if not args.CONFIG_FILE:
+        args.CONFIG_FILE = DEFAULT_CONFIG_FILE
+
+    return args
+
+
+def initialise_logging(filename: str) -> None:
+    try:
+        with open(filename, "r") as file:
+            logging_dict = yaml.safe_load(file)
+        logging.config.dictConfig(logging_dict)
+    except FileNotFoundError:
+        print(f"Logger config file not found at {filename}")
+    except Exception as e:
+        logger = logging.getLogger("UNCAUGHT_EXCEPTION")
+        logger.fatal("", exc_info=e)
+
+    # Set up exception hook
+    def handle_exception(exc_type, exc_value, exc_traceback):
+        if issubclass(exc_type, KeyboardInterrupt):
+            sys.__excepthook__(exc_type, exc_value, exc_traceback)
+            return
+
+        logger = logging.getLogger("UNCAUGHT_EXCEPTION")
+        logger.fatal("", exc_info=(exc_type, exc_value, exc_traceback))
+
+    sys.excepthook = handle_exception
+
+
+def create_stop_event():
+    stop = asyncio.Future()
+
+    for sig in (signal.SIGINT, signal.SIGTERM):
+        asyncio.get_event_loop().add_signal_handler(sig, lambda: stop.set_result(None))
+
+    return stop

pyapi_service_kit-0.0.1/src/pyapi_service_kit/utils/nested_enum.py

@@ -0,0 +1,22 @@
+from enum import Enum, EnumMeta
+
+
+class NestedEnum(Enum):
+    def __new__(cls, *args):
+        obj = object.__new__(cls)
+        value = None
+        if len(args) == 1:
+            value = args[0]
+
+        if len(args) == 2:
+            value = args[0]
+
+        if value:
+            obj._value_ = value
+
+        return obj
+
+    def __init__(self, items_or_value):
+        if isinstance(items_or_value, EnumMeta):
+            for enm in items_or_value:
+                self.__setattr__(enm.name, enm)

pyapi_service_kit-0.0.1/src/pyapi_service_kit/utils/templated_enum.py

@@ -0,0 +1,118 @@
+from enum import Enum
+from typing import Any, Callable
+
+
+class TemplatedEnum(Enum):
+    def __getattribute__(self, name: str) -> Any:
+        if name == "value":
+            raise AttributeError(
+                f"Direct access to '{name}' is not allowed. "
+                f"Use '{self.name}.resolved' to get the resolved subject or '{self.name}.template' for the template."
+            )
+        return super().__getattribute__(name)
+
+    @classmethod
+    def __getattr__(cls, name: str) -> Any:
+        if name in cls.__members__:
+            raise AttributeError(
+                f"Direct access to enum member '{name}' is not allowed. "
+                f"Use '{name}.resolved' or '{name}.template' to access the subject."
+            )
+        raise AttributeError(f"'{cls.__name__}' has no attribute '{name}'")
+
+    def __init__(self, *args: Any) -> None:
+        # Enum calls __init__ with (cls, *args) where args[0] is the value
+        template = args[0] if args else ""
+        if not isinstance(template, str):
+            raise TypeError(f"Template must be a string, got {type(template)}")
+        if not template.strip():
+            raise ValueError("Template cannot be empty or whitespace")
+        self._template: str = template
+
+    @classmethod
+    def set_resolver(cls, resolver: Callable[[str], Any]) -> None:
+        if not callable(resolver):
+            raise TypeError("Resolver must be callable")
+
+        setattr(cls, "_resolver", resolver)
+
+    @classmethod
+    def remove_resolver(cls) -> None:
+        """Remove the resolver function from the class."""
+        if hasattr(cls, "_resolver"):
+            delattr(cls, "_resolver")
+
+    @property
+    def template(self) -> str:
+        return self._template
+
+    @property
+    def resolved(self) -> Any:
+        if not hasattr(self.__class__, "_resolver"):
+            raise RuntimeError(
+                f"Resolver not set for {self.__class__.__name__}. Call set_resolver() first."
+            )
+
+        result = self.__class__._resolver(self._template)
+        return result
+
+    @property
+    def raw_value(self) -> str:
+        """Access the raw enum value for debugging purposes."""
+        return self._value_
+
+    def __str__(self) -> str:
+        try:
+            resolved_value = self.resolved
+            return str(resolved_value)
+        except Exception as e:
+            return f"{self.__class__.__name__}.{self.name}[ERROR: {e}]"
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}.{self.name}"
+
+
+class NestedTemplatedEnum(TemplatedEnum):
+    def __init__(self, *args: Any) -> None:
+        super().__init__(*args)
+        # Store the nested enum class as a class attribute
+        self._nested_enum = None
+
+    @classmethod
+    def set_nested_enum(cls, nested_enum_class):
+        """Set the nested enum class for this templated enum."""
+        cls._nested_enum = nested_enum_class
+
+    @property
+    def resolved(self) -> Any:
+        if not hasattr(self.__class__, "_resolver"):
+            raise RuntimeError(
+                f"Resolver not set for {self.__class__.__name__}. Call set_resolver() first."
+            )
+
+        # Get the resolved base key from the resolver
+        resolved_base = self.__class__._resolver(self._template)
+
+        # Return a simple object that combines the base key with enum values
+        class ResolvedNested:
+            def __init__(self, base_key: str, enum_class):
+                self.base_key = base_key
+                self.enum_class = enum_class
+
+            def __getattr__(self, name: str):
+                if hasattr(self.enum_class, name):
+                    enum_value = getattr(self.enum_class, name)
+                    return enum_value
+                if name == "value":
+                    return self.base_key
+                raise AttributeError(
+                    f"'{self.enum_class.__name__}' has no attribute '{name}'"
+                )
+
+            def __str__(self) -> str:
+                return self.base_key
+
+            def __repr__(self) -> str:
+                return f"ResolvedNested(base_key='{self.base_key}', enum_class={self.enum_class.__name__})"
+
+        return ResolvedNested(resolved_base, self.__class__._nested_enum)

pyapi_service_kit-0.0.1/src/pyapi_service_kit/utils/time.py

@@ -0,0 +1,22 @@
+from datetime import datetime
+from dateutil.parser import isoparse
+import pytz
+
+
+def parse_zoned_iso(s: str) -> datetime:
+    if "[" in s and s.endswith("]"):
+        base, zone = s.split("[")
+        zone = zone.strip("]")
+    else:
+        base = s
+        zone = None
+
+    dt = isoparse(base)
+    if zone:
+        try:
+            tz = pytz.timezone(zone)
+            dt = dt.astimezone(tz)
+        except Exception:
+            # Fallback: use the parsed offset
+            pass
+    return dt