taskadence 0.1.0__py3-none-any.whl

taskadence/__init__.py

@@ -0,0 +1,100 @@
+"""TasKadence for Python.
+
+    from taskadence import Taskadence
+
+    tm = Taskadence(token="tkd_live_…")              # or set TASKADENCE_TOKEN
+    for task in tm.tasks.list(org_id="O123456"):
+        print(task.task_id, task.title)
+    tm.views.rows("V…").to_dataframe()             # pip install "taskadence[pandas]"
+
+`tm.<resource>.<verb>(…)` exists for every public operation of the API (`tm.tasks.list`, `tm.projects.read`, …); the
+models are in `taskadence.models`, the exceptions in `taskadence.errors`, webhook verification in `taskadence.webhooks`.
+`0.x` is a pre-release: no compatibility promise until 1.0.
+"""
+
+from . import errors, models, webhooks
+from ._client import AsyncTaskadence, Taskadence
+from ._core import AUTO, ConfigurationError, FileInput, NotModified, NotModifiedType, Operation
+from ._operations import API_VERSION, DEFAULT_BASE_URL, OPERATIONS
+from ._uploads import UploadProgress
+from ._version import __version__
+from .errors import (
+    APIConnectionError,
+    APIError,
+    APITimeoutError,
+    AuthenticationError,
+    BadRequestError,
+    BlobUploadError,
+    ConflictError,
+    ForbiddenError,
+    IdempotencyKeyInFlightError,
+    IdempotencyKeyInvalidError,
+    IdempotencyKeyReusedError,
+    InsufficientScopeError,
+    InternalError,
+    InvalidParameterError,
+    InvalidValueError,
+    NotFoundError,
+    PreconditionFailedError,
+    RateLimitedError,
+    ResponseValidationError,
+    TaskadenceError,
+    TestTokenReadOnlyError,
+    TokenExpiredError,
+    TokenInvalidError,
+    TokenPolicyError,
+    TokenRevokedError,
+    UnprocessableEntityError,
+    UrlRefusedError,
+    ValidationError,
+)
+from .pagination import AsyncPage, Page
+
+__all__ = [
+    "API_VERSION",
+    "AUTO",
+    "DEFAULT_BASE_URL",
+    "OPERATIONS",
+    "APIConnectionError",
+    "APIError",
+    "APITimeoutError",
+    "AsyncPage",
+    "AsyncTaskadence",
+    "AuthenticationError",
+    "BadRequestError",
+    "BlobUploadError",
+    "ConfigurationError",
+    "ConflictError",
+    "FileInput",
+    "ForbiddenError",
+    "IdempotencyKeyInFlightError",
+    "IdempotencyKeyInvalidError",
+    "IdempotencyKeyReusedError",
+    "InsufficientScopeError",
+    "InternalError",
+    "InvalidParameterError",
+    "InvalidValueError",
+    "NotFoundError",
+    "NotModified",
+    "NotModifiedType",
+    "Operation",
+    "Page",
+    "PreconditionFailedError",
+    "RateLimitedError",
+    "ResponseValidationError",
+    "Taskadence",
+    "TaskadenceError",
+    "TestTokenReadOnlyError",
+    "TokenExpiredError",
+    "TokenInvalidError",
+    "TokenPolicyError",
+    "TokenRevokedError",
+    "UnprocessableEntityError",
+    "UploadProgress",
+    "UrlRefusedError",
+    "ValidationError",
+    "__version__",
+    "errors",
+    "models",
+    "webhooks",
+]

taskadence/_brand.py

@@ -0,0 +1,87 @@
+"""The product's name and every name derived from it, in ONE place — plus the pre-rename (TasksMate) spellings that
+are still accepted on input. Nothing here is emitted under the old name: the legacy values are read, never sent.
+
+- `BRAND_NAME`: the wordmark, what prose, messages and help text call the product (5.8c). Identifiers, package names,
+  imports, environment variables and URLs stay `Taskadence` / `taskadence`; `wordmark()` applies it to generated prose.
+- Environment: `TASKADENCE_*` first; a `TASKSMATE_*` variable still works, with a `DeprecationWarning` (`getenv`).
+- Problem types: the API emits `urn:taskadence:problem:…`; `urn:tasksmate:problem:…` (older servers) is read the same.
+- Access tokens: issued as `tkd_live_…` / `tkd_test_…`; `tm_live_…` / `tm_test_…` tokens minted before the rename
+  keep working.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import sys
+import warnings
+from types import FrameType
+
+BRAND_NAME = "TasKadence"
+SLUG = "taskadence"
+
+ENV_PREFIX = "TASKADENCE_"
+LEGACY_ENV_PREFIX = "TASKSMATE_"  # pre-rename; read with a DeprecationWarning
+
+URN_PREFIX = "urn:taskadence:problem:"
+LEGACY_URN_PREFIX = "urn:tasksmate:problem:"  # pre-rename servers
+URN_PREFIXES = (URN_PREFIX, LEGACY_URN_PREFIX)
+
+TOKEN_PREFIXES = ("tkd_live_", "tkd_test_")
+LEGACY_TOKEN_PREFIXES = ("tm_live_", "tm_test_")  # minted before the rename; still valid
+ACCEPTED_TOKEN_PREFIXES = TOKEN_PREFIXES + LEGACY_TOKEN_PREFIXES
+
+# The class-style name in running prose: not inside code (`Taskadence(...)`, `AsyncTaskadence`, `TaskadenceError`,
+# `X-Taskadence-Event`, `Taskadence-Version`) and not a path or URL.
+_PROSE_NAME = re.compile(r"(?<![\w`./-])Taskadence(?![\w(`/-])")
+
+LEGACY_SLUG = "tasksmate"  # the CLI's keyring service and config directory before the rename (read, then migrated)
+
+
+def getenv(name: str) -> str | None:
+    """`TASKADENCE_<name>`, else the deprecated `TASKSMATE_<name>` (with a `DeprecationWarning`), else None.
+
+    `name` is the full new name (`TASKADENCE_TOKEN`) or its suffix (`TOKEN`). An empty value counts as unset.
+    """
+    suffix = name.removeprefix(ENV_PREFIX)
+    value = os.environ.get(ENV_PREFIX + suffix)
+    if value:
+        return value
+    legacy = os.environ.get(LEGACY_ENV_PREFIX + suffix)
+    if legacy:
+        warnings.warn(
+            f"{LEGACY_ENV_PREFIX}{suffix} is deprecated: {BRAND_NAME} reads {ENV_PREFIX}{suffix}. "
+            f"Rename the variable; the old name will stop working in a future release.",
+            DeprecationWarning,
+            stacklevel=_caller_level(),
+        )
+        return legacy
+    return None
+
+
+def _caller_level() -> int:
+    """The `stacklevel` that points the warning at the first frame outside this package (the user's code)."""
+    level = 2
+    frame: FrameType | None = sys._getframe(2)
+    while frame is not None and str(frame.f_globals.get("__name__", "")).startswith(SLUG):
+        level, frame = level + 1, frame.f_back
+    return level
+
+
+def wordmark(text: str) -> str:
+    """`text` with the product name in prose spelled as the wordmark; code spans (`…`) are left as they are."""
+    parts = text.split("`")
+    return "`".join(part if i % 2 else _PROSE_NAME.sub(BRAND_NAME, part) for i, part in enumerate(parts))
+
+
+def problem_slug(type_: str) -> str | None:
+    """`token-expired` for `urn:taskadence:problem:token-expired` (or the legacy `urn:tasksmate:…`); else None."""
+    for prefix in URN_PREFIXES:
+        if type_.startswith(prefix):
+            return type_[len(prefix) :]
+    return None
+
+
+def is_access_token(value: str) -> bool:
+    """True for a token-shaped access token: `tkd_live_` / `tkd_test_`, or the pre-rename `tm_live_` / `tm_test_`."""
+    return value.startswith(ACCEPTED_TOKEN_PREFIXES)

taskadence/_client.py

@@ -0,0 +1,144 @@
+"""`Taskadence` and `AsyncTaskadence`: configuration, the resource namespaces, lifetime."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from types import TracebackType
+
+import httpx
+
+from ._core import AsyncCore, SyncCore
+from ._generated import models
+from ._operations import API_VERSION, DEFAULT_BASE_URL
+from .resources import AsyncResources, SyncResources
+
+DEFAULT_TIMEOUT = 30.0
+DEFAULT_MAX_RETRIES = 3
+DEFAULT_MAX_RETRY_AFTER = 60.0
+
+
+class Taskadence(SyncResources):
+    """The TasKadence API.
+
+        from taskadence import Taskadence
+
+        tm = Taskadence()                                  # token from TASKADENCE_TOKEN
+        for task in tm.tasks.list(org_id="O123456", filter={"status": ["in_progress"]}):
+            print(task.task_id, task.title)
+
+    `token`: a TasKadence access token (`tkd_live_…`; a pre-rename `tm_live_…` works too), else `TASKADENCE_TOKEN`.
+    `base_url`: else `TASKADENCE_API_URL`, else the spec's first server (`taskadence.DEFAULT_BASE_URL`); a trailing
+    `/v1` is accepted. Safe requests are retried `max_retries` times (see `taskadence._core`); a `Retry-After` over
+    `max_retry_after` seconds is not waited out.
+    `api_version` is sent as `Taskadence-Version` (default: the API date this SDK was generated from).
+    """
+
+    def __init__(
+        self,
+        token: str | None = None,
+        base_url: str | None = None,
+        *,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        api_version: str | None = None,
+        max_retry_after: float = DEFAULT_MAX_RETRY_AFTER,
+        headers: Mapping[str, str] | None = None,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        self._core = SyncCore(
+            token,
+            base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+            api_version=api_version,
+            default_base_url=DEFAULT_BASE_URL,
+            spec_version=API_VERSION,
+            max_retry_after=max_retry_after,
+            headers=headers,
+            http_client=http_client,
+        )
+        self._attach(self._core)
+
+    @property
+    def base_url(self) -> str:
+        return self._core.base_url
+
+    @property
+    def api_version(self) -> str:
+        return self._core.api_version
+
+    def close(self) -> None:
+        """Close the HTTP connection pool (not an `http_client` you passed in)."""
+        self._core.close()
+
+    def __enter__(self) -> Taskadence:
+        return self
+
+    def __exit__(
+        self, exc_type: type[BaseException] | None, exc: BaseException | None, tb: TracebackType | None
+    ) -> None:
+        self.close()
+
+    def __repr__(self) -> str:
+        return f"Taskadence(base_url={self.base_url!r})"
+
+
+class AsyncTaskadence(AsyncResources):
+    """`Taskadence` for asyncio: the same namespaces and methods, awaited; lists are `AsyncPage`s (`async for`).
+
+    async with AsyncTaskadence() as tm:
+        me = await tm.me()
+        async for task in await tm.tasks.list(org_id=me.organizations[0].org_id):
+            ...
+    """
+
+    def __init__(
+        self,
+        token: str | None = None,
+        base_url: str | None = None,
+        *,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        api_version: str | None = None,
+        max_retry_after: float = DEFAULT_MAX_RETRY_AFTER,
+        headers: Mapping[str, str] | None = None,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self._core = AsyncCore(
+            token,
+            base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+            api_version=api_version,
+            default_base_url=DEFAULT_BASE_URL,
+            spec_version=API_VERSION,
+            max_retry_after=max_retry_after,
+            headers=headers,
+            http_client=http_client,
+        )
+        self._attach(self._core)
+
+    @property
+    def base_url(self) -> str:
+        return self._core.base_url
+
+    @property
+    def api_version(self) -> str:
+        return self._core.api_version
+
+    async def close(self) -> None:
+        await self._core.aclose()
+
+    async def __aenter__(self) -> AsyncTaskadence:
+        return self
+
+    async def __aexit__(
+        self, exc_type: type[BaseException] | None, exc: BaseException | None, tb: TracebackType | None
+    ) -> None:
+        await self.close()
+
+    def __repr__(self) -> str:
+        return f"AsyncTaskadence(base_url={self.base_url!r})"
+
+
+__all__ = ["AsyncTaskadence", "Taskadence", "models"]