teepin 0.2.0__py3-none-any.whl

teepin/__init__.py

@@ -0,0 +1,187 @@
+# Copyright 2026 TEEPIN Project
+# Licensed under the Apache License, Version 2.0
+
+"""The Python SDK of Teepin Web Services (TWS): Teepin Storage, Teepin
+Inference and compute.
+
+    >>> from teepin import Client
+    >>> client = Client(api_key="tpk_...")
+    >>> client.storage.upload_file("my-bucket", "videos/a.mp4", "a.mp4")
+    >>> client.chat.completions.create(model="teepin/llama-3.3-70b",
+    ...                                messages=[{"role": "user", "content": "Hello"}])
+
+:class:`AsyncClient` is the same API for asyncio.
+"""
+
+from ._core import (
+    DEFAULT_CONCURRENCY,
+    DEFAULT_PART_SIZE,
+    MAX_OBJECT_SIZE,
+    MAX_PART_SIZE,
+    MAX_PARTS,
+    MAX_PUT_SIZE,
+    MIN_PART_SIZE,
+    MULTIPART_THRESHOLD,
+    ProgressFunc,
+    compute_etag,
+    part_size_for,
+)
+from ._inference import ChatCompletionParams, ChatMessageParam
+from ._version import __version__
+from .async_client import AsyncClient, AsyncInstancesService
+from .async_inference import (
+    AsyncChatCompletionsService,
+    AsyncChatCompletionStream,
+    AsyncChatService,
+    AsyncModelsService,
+)
+from .async_storage import AsyncObjectReader, AsyncStorageService
+from .client import Client, InstancesService
+from .exceptions import (
+    APIConnectionError,
+    APIError,
+    BadRequestError,
+    ChecksumMismatchError,
+    ConflictError,
+    ForbiddenError,
+    InsufficientCreditError,
+    NoCreditError,
+    NotFoundError,
+    ObjectChangedError,
+    OnHoldError,
+    PaymentRequiredError,
+    PermissionDeniedError,
+    PreconditionFailedError,
+    RateLimitError,
+    StreamError,
+    TeepinError,
+    TooLargeError,
+    UnauthorizedError,
+    UploadError,
+    error_code,
+    is_retryable,
+)
+from .inference import ChatCompletionsService, ChatCompletionStream, ChatService, ModelsService
+from .models import (
+    Bucket,
+    ChatCompletion,
+    ChatCompletionChunk,
+    ChatMessage,
+    Choice,
+    ChoiceDelta,
+    ChunkChoice,
+    CompletedPart,
+    CreateInstanceRequest,
+    DeleteError,
+    DeleteResult,
+    FunctionCall,
+    Hold,
+    InferenceModel,
+    Instance,
+    InstanceType,
+    ModelAttestation,
+    ModelPricing,
+    ObjectInfo,
+    ObjectPage,
+    Part,
+    PortMapping,
+    RateLimit,
+    ResponseMeta,
+    SignedUpload,
+    SignedURL,
+    StorageObject,
+    ToolCall,
+    Upload,
+    Usage,
+)
+from .storage import ObjectReader, StorageService
+
+__all__ = [
+    "__version__",
+    # clients
+    "Client",
+    "AsyncClient",
+    "StorageService",
+    "AsyncStorageService",
+    "InstancesService",
+    "AsyncInstancesService",
+    "ObjectReader",
+    "AsyncObjectReader",
+    "ModelsService",
+    "AsyncModelsService",
+    "ChatService",
+    "AsyncChatService",
+    "ChatCompletionsService",
+    "AsyncChatCompletionsService",
+    "ChatCompletionStream",
+    "AsyncChatCompletionStream",
+    # storage
+    "Bucket",
+    "StorageObject",
+    "ObjectInfo",
+    "ObjectPage",
+    "Hold",
+    "DeleteError",
+    "DeleteResult",
+    "SignedURL",
+    "SignedUpload",
+    "Upload",
+    "Part",
+    "CompletedPart",
+    "compute_etag",
+    "part_size_for",
+    "ProgressFunc",
+    "MIN_PART_SIZE",
+    "MAX_PART_SIZE",
+    "MAX_PARTS",
+    "MAX_OBJECT_SIZE",
+    "MAX_PUT_SIZE",
+    "DEFAULT_PART_SIZE",
+    "MULTIPART_THRESHOLD",
+    "DEFAULT_CONCURRENCY",
+    # compute
+    "Instance",
+    "CreateInstanceRequest",
+    "InstanceType",
+    "PortMapping",
+    # inference
+    "InferenceModel",
+    "ModelPricing",
+    "ModelAttestation",
+    "ChatMessageParam",
+    "ChatCompletionParams",
+    "ChatCompletion",
+    "ChatMessage",
+    "Choice",
+    "ChatCompletionChunk",
+    "ChunkChoice",
+    "ChoiceDelta",
+    "ToolCall",
+    "FunctionCall",
+    "Usage",
+    "ResponseMeta",
+    "RateLimit",
+    # errors
+    "TeepinError",
+    "APIError",
+    "BadRequestError",
+    "UnauthorizedError",
+    "PaymentRequiredError",
+    "NoCreditError",
+    "InsufficientCreditError",
+    "OnHoldError",
+    "ForbiddenError",
+    "PermissionDeniedError",
+    "RateLimitError",
+    "StreamError",
+    "NotFoundError",
+    "ConflictError",
+    "PreconditionFailedError",
+    "TooLargeError",
+    "APIConnectionError",
+    "ObjectChangedError",
+    "ChecksumMismatchError",
+    "UploadError",
+    "error_code",
+    "is_retryable",
+]

teepin/_core.py

@@ -0,0 +1,344 @@
+# Copyright 2026 TEEPIN Project
+# Licensed under the Apache License, Version 2.0
+
+"""What the synchronous and asynchronous clients share: retry rules, error
+decoding, ETags and part sizes. Nothing here does I/O on the network, so the
+two clients cannot drift apart on any of it.
+
+The rules match the Go and Node SDKs (teepin-go/teepin, teepin-node/src).
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import mimetypes
+import os
+import random
+import threading
+from datetime import datetime
+from enum import Enum
+from typing import IO, Callable, Dict, Iterable, List, Mapping, Optional, Tuple, Union
+from urllib.parse import quote
+
+from .exceptions import APIConnectionError, APIError, api_error
+
+DEFAULT_BASE_URL = "https://api.teepin.com"
+DEFAULT_TIMEOUT = 60.0
+#: Told the bytes moved so far and the total (-1 when not known yet).
+ProgressFunc = Callable[[int, int], None]
+
+#: How long a transfer may go without receiving a byte before it is cut off.
+DEFAULT_TRANSFER_READ_TIMEOUT = 300.0
+DEFAULT_RETRIES = 4
+#: Retries of a Teepin Inference request (INFERENCE-SDK-CONTRACT.md).
+DEFAULT_INFERENCE_RETRIES = 2
+#: How long a chat request waits for its answer (a stream: for its headers).
+#: A long answer takes minutes, and the server sends nothing until it is done.
+DEFAULT_CHAT_TIMEOUT = 600.0
+
+#: The smallest part but the last.
+MIN_PART_SIZE = 5 << 20
+#: The largest part.
+MAX_PART_SIZE = 5 << 30
+#: The most parts of one upload.
+MAX_PARTS = 10000
+#: The largest object.
+MAX_OBJECT_SIZE = 5 << 40
+#: The largest object one request may carry.
+MAX_PUT_SIZE = 5 << 30
+#: Part size of uploads in parts and of parallel download ranges.
+DEFAULT_PART_SIZE = 16 << 20
+#: Larger uploads go in parts.
+MULTIPART_THRESHOLD = 16 << 20
+#: Parts or ranges moved at once.
+DEFAULT_CONCURRENCY = 8
+
+META_PREFIX = "X-Teepin-Meta-"
+
+
+class RetryMode(Enum):
+    """When a failed request may be sent again."""
+
+    #: The request can be repeated with the same effect (reads, PUTs that
+    #: replace, deletes).
+    SAFE = "safe"
+    #: Only when the server certainly did not act on it: it never arrived, or
+    #: the server said it was busy and did nothing.
+    UNSENT = "unsent"
+    #: Teepin Inference's reads (models, attestation): 429, any 5xx and any
+    #: connection error, with backoff from 0.5 s up to 8 s and Retry-After
+    #: honoured up to 30 s.
+    INFERENCE = "inference"
+    #: A Teepin Inference chat request, which the server bills once it has the
+    #: model's answer, even if the client has gone: sent again only when it
+    #: certainly did not bill. That is a 429; Teepin's own 500 internal_error,
+    #: 502 upstream_error, 503 model_unavailable or billing_unavailable (told
+    #: by its OpenAI-style error body, unlike a proxy's 502 page); or a
+    #: connection that was never opened. Never after a timeout or a connection
+    #: lost once the request was sent, and never once a stream has started.
+    #: Backoff as INFERENCE.
+    INFERENCE_CHAT = "inference_chat"
+
+
+#: The 5xx answers of Teepin Inference that come before any billing.
+_UNBILLED_5XX = {
+    500: ("internal_error",),
+    502: ("upstream_error",),
+    503: ("model_unavailable", "billing_unavailable"),
+}
+
+
+def retryable_status(status: int, mode: RetryMode) -> bool:
+    """Whether an error status is worth another attempt. For INFERENCE_CHAT
+    only a 429 is, by its status alone; see retryable_error for the 5xx."""
+    if mode is RetryMode.INFERENCE:
+        return status in (429, 500, 502, 503, 504)
+    if mode is RetryMode.INFERENCE_CHAT:
+        return status == 429
+    if status in (429, 503):
+        return True  # busy, or credit could not be checked: nothing was done
+    if status == 502:
+        return True  # the storage backend failed; the API says nothing was stored
+    if status in (500, 504):
+        return mode is RetryMode.SAFE
+    return False
+
+
+def retryable_error(err: BaseException, mode: RetryMode) -> bool:
+    """Whether a failed attempt is worth another one."""
+    if isinstance(err, APIConnectionError):
+        return mode in (RetryMode.SAFE, RetryMode.INFERENCE) or bool(getattr(err, "unsent", False))
+    if isinstance(err, APIError):
+        if mode is RetryMode.INFERENCE_CHAT and err.status_code in _UNBILLED_5XX:
+            # Only Teepin's own answer says nothing was billed; a proxy's 502
+            # page may hide a task that died after billing.
+            return err._inference_envelope and err.code in _UNBILLED_5XX[err.status_code]
+        return retryable_status(err.status_code, mode)
+    return False
+
+
+def backoff(attempt: int, err: Optional[BaseException] = None, mode: RetryMode = RetryMode.SAFE) -> float:
+    """Seconds to wait before attempt+1: the server's Retry-After when it sent
+    one (at most a minute), else exponential with full jitter. Inference waits
+    0.5 s doubling up to 8 s, and at most 30 s for a Retry-After."""
+    if mode in (RetryMode.INFERENCE, RetryMode.INFERENCE_CHAT):
+        if isinstance(err, APIError) and err.retry_after:
+            return min(err.retry_after, 30.0)
+        return random.uniform(0, min(0.5 * (2**attempt), 8.0))
+    if isinstance(err, APIError) and err.retry_after:
+        return min(err.retry_after, 60.0)
+    ceiling = min(0.2 * (2**attempt), 10.0)
+    return random.uniform(0, ceiling) + 0.05
+
+
+def decode_error(status: int, headers: Mapping[str, str], body: bytes) -> APIError:
+    """The APIError for an error answer: ``{error, code}``, or Teepin Inference's
+    OpenAI-style ``{"error": {message, type, code}}``, with the request id,
+    Retry-After and, for storage_on_hold, delete_after."""
+    retry_after: Optional[float] = None
+    raw = headers.get("Retry-After") or headers.get("retry-after")
+    if raw:
+        try:
+            secs = int(raw.strip())
+            if secs > 0:
+                retry_after = float(secs)
+        except ValueError:
+            pass
+    request_id = headers.get("X-Request-ID") or headers.get("x-request-id")
+    message, code, error_type, delete_after = "", "", "", None
+    try:
+        data = json.loads(body[: 64 << 10] or b"null")
+    except ValueError:
+        data = None
+    if isinstance(data, dict) and isinstance(data.get("error"), dict):
+        envelope = data["error"]
+        message = str(envelope.get("message") or "")
+        code = str(envelope.get("code") or "")
+        error_type = str(envelope.get("type") or "")
+    elif isinstance(data, dict) and (data.get("error") or data.get("code")):
+        message = str(data.get("error") or "")
+        code = str(data.get("code") or "")
+        if data.get("delete_after"):
+            try:
+                delete_after = datetime.fromisoformat(str(data["delete_after"]).replace("Z", "+00:00"))
+            except ValueError:
+                pass
+    else:
+        message = body[: 64 << 10].decode("utf-8", "replace").strip()
+    if not message:
+        message = f"HTTP {status}"
+    err = api_error(status, message, code, request_id, retry_after, delete_after, error_type)
+    err._inference_envelope = isinstance(data, dict) and isinstance(data.get("error"), dict)
+    return err
+
+
+def bucket_path(bucket: str) -> str:
+    return "/v1/storage/buckets/" + quote(bucket, safe="")
+
+
+def upload_path(bucket: str, upload_id: str) -> str:
+    return bucket_path(bucket) + "/uploads/" + quote(upload_id, safe="")
+
+
+def quote_etag(etag: str) -> str:
+    if etag == "*" or etag.startswith('"') or etag.startswith('W/"'):
+        return etag
+    return f'"{etag}"'
+
+
+def unquote_etag(etag: Optional[str]) -> str:
+    if not etag:
+        return ""
+    etag = etag.strip()
+    if etag.startswith("W/"):
+        etag = etag[2:]
+    return etag.strip('"')
+
+
+def put_headers(
+    content_type: Optional[str] = None,
+    metadata: Optional[Mapping[str, str]] = None,
+    if_match: Optional[str] = None,
+    if_none_match: bool = False,
+) -> Dict[str, str]:
+    """Headers of a one-request upload."""
+    h: Dict[str, str] = {}
+    if content_type:
+        h["Content-Type"] = content_type
+    for name, value in (metadata or {}).items():
+        h[META_PREFIX + name] = value
+    if if_match:
+        h["If-Match"] = quote_etag(if_match)
+    if if_none_match:
+        h["If-None-Match"] = "*"
+    return h
+
+
+def range_header(start: int, end: Optional[int]) -> str:
+    """``bytes=start-end`` (inclusive); end None is to the end."""
+    return f"bytes={start}-" if end is None else f"bytes={start}-{end}"
+
+
+def total_size(headers: Mapping[str, str], fallback: int) -> int:
+    """The whole object's size from Content-Range (``bytes 0-99/1234``)."""
+    cr = headers.get("Content-Range") or headers.get("content-range") or ""
+    if "/" in cr:
+        try:
+            return int(cr.rsplit("/", 1)[1])
+        except ValueError:
+            pass
+    return fallback
+
+
+def guess_content_type(path: Union[str, os.PathLike]) -> Optional[str]:
+    return mimetypes.guess_type(str(path))[0]
+
+
+def part_size_for(size: int, want: int = 0) -> int:
+    """The part size an upload of ``size`` bytes uses when ``want`` (0 for the
+    default) is asked for: at least 5 MiB, doubled until the parts fit in
+    10,000."""
+    p = want if want > 0 else DEFAULT_PART_SIZE
+    p = max(p, MIN_PART_SIZE)
+    while p < MAX_PART_SIZE and (size + p - 1) // p > MAX_PARTS:
+        p *= 2
+    return min(p, MAX_PART_SIZE)
+
+
+def part_spans(size: int, part_size: int) -> List[Tuple[int, int, int]]:
+    """``(number, offset, length)`` of each part, numbered from 1."""
+    out = []
+    num, off = 1, 0
+    while off < size:
+        n = min(part_size, size - off)
+        out.append((num, off, n))
+        num += 1
+        off += n
+    return out
+
+
+def composite_etag(part_sha256s: Iterable[bytes]) -> str:
+    """``<sha256 of the parts' sha256s>-<parts>``: the ETag of an upload in parts."""
+    h = hashlib.sha256()
+    n = 0
+    for digest in part_sha256s:
+        h.update(digest)
+        n += 1
+    return f"{h.hexdigest()}-{n}"
+
+
+def compute_etag(
+    source: Union[str, os.PathLike, bytes, bytearray, memoryview, IO[bytes]],
+    part_size: int = 0,
+    parts: int = 0,
+) -> str:
+    """The ETag Teepin gives these bytes: the SHA-256 when ``parts`` is 0, or for
+    an upload in parts of ``part_size`` bytes the SHA-256 of the parts'
+    SHA-256s with ``-<parts>``. Compare it with ``Object.etag`` to tell whether
+    a local file and an object hold the same bytes.
+
+    ``source`` is a path, bytes, or a binary file object read from its start.
+    """
+    if isinstance(source, (bytes, bytearray, memoryview)):
+        data = bytes(source)
+        if parts == 0:
+            return hashlib.sha256(data).hexdigest()
+        _check_parts(len(data), part_size, parts)
+        return composite_etag(hashlib.sha256(data[o : o + n]).digest() for _, o, n in part_spans(len(data), part_size))
+    if isinstance(source, (str, os.PathLike)):
+        with open(source, "rb") as f:
+            return compute_etag(f, part_size, parts)
+    f = source
+    f.seek(0, os.SEEK_END)
+    size = f.tell()
+    if parts == 0:
+        f.seek(0)
+        h = hashlib.sha256()
+        for chunk in iter(lambda: f.read(1 << 20), b""):
+            h.update(chunk)
+        return h.hexdigest()
+    _check_parts(size, part_size, parts)
+    digests = []
+    for _, off, n in part_spans(size, part_size):
+        f.seek(off)
+        h = hashlib.sha256()
+        left = n
+        while left:
+            chunk = f.read(min(left, 1 << 20))
+            if not chunk:
+                raise ValueError("the file ended early")
+            h.update(chunk)
+            left -= len(chunk)
+        digests.append(h.digest())
+    return composite_etag(digests)
+
+
+def _check_parts(size: int, part_size: int, parts: int) -> None:
+    if part_size <= 0 or (size + part_size - 1) // part_size != parts:
+        raise ValueError(f"{size} bytes in parts of {part_size} is not {parts} parts")
+
+
+def absolute(base_url: str, path: str) -> str:
+    """A signed link the API returned as a path, made absolute."""
+    if path.startswith("http://") or path.startswith("https://"):
+        return path
+    return base_url + path
+
+
+class Progress:
+    """Adds up bytes moved and tells the caller's callback (done, total).
+    Thread safe; an attempt that failed can be taken back."""
+
+    def __init__(self, total: int, fn: Optional[ProgressFunc]) -> None:
+        self.total = total
+        self.done = 0
+        self.fn = fn
+        self._lock = threading.Lock()
+
+    def add(self, n: int) -> None:
+        if not self.fn or n == 0:
+            return
+        with self._lock:
+            self.done += n
+            self.fn(self.done, self.total)