pierre-sdk 0.1.0.dev4__py3-none-any.whl

pierre/_types.py

@@ -0,0 +1,73 @@
+"""Types that the generated layer and the runtime share."""
+
+from dataclasses import dataclass
+from typing import Generic, List, Literal, Mapping, Sequence, TypeVar, Union
+
+from pierre._compat import NotRequired, TypedDict
+
+
+class NotGiven:
+    """The default of each optional argument. The SDK does not send it, and sends `None` as
+    `null`."""
+
+    def __bool__(self) -> Literal[False]:
+        return False
+
+    def __repr__(self) -> str:
+        return "NOT_GIVEN"
+
+
+NOT_GIVEN = NotGiven()
+
+RefPolicyOp = Union[Literal["no-push", "no-force-push", "verify-sig"], str]
+
+
+class RefPolicy(TypedDict):
+    """One ordered rule of the `refs` claim. The first rule whose pattern
+    matches a ref applies."""
+
+    # A full ref name (`refs/heads/main`), a branch name (`main`), a prefix that ends with `/*`
+    # (`refs/heads/feature/*`), or `*` for every ref. The gateway rejects another form.
+    pattern: str
+    # The policy operations. The gateway rejects an op that it does not know.
+    ops: NotRequired[Sequence[RefPolicyOp]]
+
+
+class TokenRequest(TypedDict):
+    """The token that a request needs. `get_token` receives it."""
+
+    # The scopes of the operation.
+    scopes: List[str]
+    # The `repo` claim, for a repository-scoped operation.
+    repo: NotRequired[str]
+    # The lifetime of the token, in seconds.
+    ttl: int
+    # The rules of the `refs` claim. Absent when the call has none.
+    ref_policies: NotRequired[List[RefPolicy]]
+
+
+Headers = TypeVar("Headers")
+
+
+class HeadersResult(TypedDict, Generic[Headers]):
+    """The result of an operation whose response has no body. `headers` holds the declared
+    response headers, and is empty when the document declares none."""
+
+    status: int
+    headers: Headers
+
+
+class NoHeaders(TypedDict, total=False):
+    """The declared response headers of an operation that declares none."""
+
+
+@dataclass(frozen=True)
+class RequestOptions:
+    """The keyword arguments of one call."""
+
+    extra_headers: Union[Mapping[str, str], NotGiven] = NOT_GIVEN
+    timeout: Union[float, NotGiven] = NOT_GIVEN
+    max_retries: Union[int, NotGiven] = NOT_GIVEN
+    idempotency_key: Union[str, NotGiven] = NOT_GIVEN
+    token_ttl: Union[int, NotGiven] = NOT_GIVEN
+    ref_policies: Union[Sequence[RefPolicy], NotGiven] = NOT_GIVEN

pierre/_version.py

@@ -0,0 +1,3 @@
+"""The version of the package. It equals the version in pyproject.toml."""
+
+__version__ = "0.1.0.dev4"

pierre/auth.py

@@ -0,0 +1,84 @@
+"""`pierre.auth`: signs a token locally, with no HTTP call, and lists
+the scopes of the API."""
+
+from typing import Optional, Sequence, Union
+
+from pierre._client import AsyncPierre, Pierre
+from pierre._compat import TypedDict
+from pierre._credentials import (
+    SUBJECT,
+    Credentials,
+    Signer,
+    TokenNeeds,
+    check_ref_policies,
+    check_ttl,
+)
+from pierre._errors import PierreError
+from pierre._generated.scopes import SCOPES, Scope
+from pierre._types import RefPolicy
+
+__all__ = ["SCOPES", "KeyCredentials", "RefPolicy", "Scope", "create_token"]
+
+# A token from `create_token` lives 15 minutes by default.
+_DEFAULT_TTL_SECONDS = 15 * 60
+
+
+class KeyCredentials(TypedDict):
+    """A private key and its organization, for code with no client."""
+
+    org: str
+    # A PKCS #8 PEM private key.
+    private_key: str
+
+
+def _signing_credentials(credentials: Union[Pierre, AsyncPierre, KeyCredentials]) -> Credentials:
+    if isinstance(credentials, (Pierre, AsyncPierre)):
+        signing = credentials._resolved.credentials
+        if signing.kind != "private_key":
+            raise PierreError(
+                "`create_token` needs a client with a private key. "
+                "A client with `token` or `get_token` cannot sign."
+            )
+        return signing
+    if isinstance(credentials, dict):
+        org = credentials.get("org")
+        private_key = credentials.get("private_key")
+        if isinstance(org, str) and org != "" and isinstance(private_key, str):
+            return Credentials("private_key", org=org, signer=Signer(lambda: private_key))
+    raise PierreError('Give a client, or `{"org": ..., "private_key": ...}`.')
+
+
+def create_token(
+    credentials: Union[Pierre, AsyncPierre, KeyCredentials],
+    *,
+    scopes: Sequence[str],
+    repo: Optional[str] = None,
+    ttl: int = _DEFAULT_TTL_SECONDS,
+    ref_policies: Optional[Sequence[RefPolicy]] = None,
+    subject: Optional[str] = None,
+) -> str:
+    """Signs a token with a private key: the key of a client, or `{"org": ..., "private_key":
+    ...}`. A token in a URL or a config file is a bearer credential, so keep the lifetime short.
+
+    Args:
+        credentials: A client with a private key, or a `KeyCredentials` dict.
+        scopes: The scopes of the token, for example `["git:read"]`. `SCOPES` lists the scopes of
+            the API.
+        repo: The `repo` claim. Leave it out for a token whose scopes are all organization-wide.
+        ttl: The lifetime in seconds, from 1 to 3600. Default: 900 (15 minutes).
+        ref_policies: The rules of the `refs` claim. Default: the `ref_policies` of a client, and
+            none for a `KeyCredentials` dict. An empty list adds no claim.
+        subject: The `sub` claim. Default: `pierre-sdk-python`.
+
+    Docs: search for `createToken` in the docs MCP server, https://code.storage/docs/mcp.
+    """
+    signing = _signing_credentials(credentials)
+    if isinstance(scopes, str) or len(scopes) == 0:
+        raise PierreError("`scopes` must name at least one scope.")
+    rules = check_ref_policies(ref_policies, "ref_policies")
+    if rules is None and isinstance(credentials, (Pierre, AsyncPierre)):
+        rules = credentials._resolved.settings.rules
+    needs = TokenNeeds(
+        scopes=tuple(scopes), repo=repo, ttl=check_ttl(ttl, "ttl"), rules=rules or ()
+    )
+    return signing.sign(needs, SUBJECT if subject is None else subject)

pierre/git.py

@@ -0,0 +1,161 @@
+"""`pierre.git`: builds a Git remote URL with a token in it."""
+
+import re
+from typing import Coroutine, Literal, Optional, Sequence, Tuple, Union, overload
+from urllib.parse import quote
+
+from pierre._client import AsyncPierre, Pierre
+from pierre._credentials import TokenNeeds, check_ref_policies, check_ttl
+from pierre._errors import PierreError
+from pierre._types import RefPolicy
+
+__all__ = ["RefPolicy", "remote_url"]
+
+_SUFFIXES = {"default": "", "ephemeral": "+ephemeral", "import": "+import"}
+
+_DEFAULT_SCOPES = ("git:read", "git:write")
+
+# A token in a remote URL lives 15 minutes by default.
+_DEFAULT_TTL_SECONDS = 15 * 60
+
+# A host name or an IP address, with an optional port.
+_LABEL = r"[A-Za-z0-9_](?:[A-Za-z0-9_-]{0,61}[A-Za-z0-9_])?"
+_HOST = re.compile(rf"(?:{_LABEL}(?:\.{_LABEL})*|\[[0-9A-Fa-f:.]+\])(?::([0-9]{{1,5}}))?")
+
+# The characters that `encodeURIComponent` keeps, so that a path is the same in every SDK.
+_SEGMENT_SAFE = "!~*'()"
+
+Kind = Literal["default", "ephemeral", "import"]
+
+
+def _host(git_host: Optional[str]) -> str:
+    """The Git host of the client: a host name with an optional port. A scheme, a path, or another
+    URL part would send the token to another host."""
+    if git_host is None:
+        raise PierreError("`remote_url` needs the Git host. Set `org` or `git_host`.")
+    match = _HOST.fullmatch(git_host)
+    if match is None:
+        raise PierreError(
+            "`git_host` must be a host name with an optional port, for example `acme.code.storage`."
+        )
+    host = git_host.lower()
+    # A URL drops the default port.
+    return host[: -len(":443")] if match.group(1) == "443" else host
+
+
+def _repository_path(name: object) -> str:
+    """The URL path of a repository name: each segment percent-encoded, with `/` between them."""
+    if not isinstance(name, str) or name == "":
+        raise PierreError("`repo_name` must be a non-empty string.")
+    segments = name.split("/")
+    # A URL parser resolves `.` and `..`, which would name another repository.
+    if any(segment in ("", ".", "..") for segment in segments):
+        raise PierreError(f"`repo_name` cannot have an empty, `.`, or `..` segment: {name}")
+    return "/".join(quote(segment, safe=_SEGMENT_SAFE) for segment in segments)
+
+
+def _prepare(
+    client: Union[Pierre, AsyncPierre],
+    repo_name: str,
+    scopes: Optional[Sequence[str]],
+    ttl: int,
+    ref_policies: Optional[Sequence[RefPolicy]],
+    kind: str,
+) -> Tuple[str, TokenNeeds]:
+    """The URL without the token, as a template, and the token that it needs."""
+    if not isinstance(client, (Pierre, AsyncPierre)):
+        raise PierreError("Give a client from `Pierre()` or `AsyncPierre()`.")
+    if client._resolved.credentials.fixed:
+        raise PierreError(
+            "`remote_url` needs a client with `private_key` or `get_token`. "
+            "A client with a fixed `token` cannot set the claims of its token."
+        )
+    host = _host(client.options.git_host)
+    path = _repository_path(repo_name)
+    suffix = _SUFFIXES.get(kind) if isinstance(kind, str) else None
+    if suffix is None:
+        raise PierreError("`kind` must be `default`, `ephemeral`, or `import`.")
+    token_scopes = _DEFAULT_SCOPES if scopes is None else tuple(scopes)
+    if isinstance(scopes, str) or len(token_scopes) == 0:
+        raise PierreError("`scopes` must name at least one scope.")
+    rules = check_ref_policies(ref_policies, "ref_policies")
+    if rules is None:
+        rules = client._resolved.settings.rules or ()
+    # An ephemeral or import remote uses the token of its repository.
+    needs = TokenNeeds(scopes=token_scopes, repo=repo_name, ttl=check_ttl(ttl, "ttl"), rules=rules)
+    return f"https://t:{{token}}@{host}/{path}{suffix}.git", needs
+
+
+def _url(template: str, token: str) -> str:
+    return template.replace("{token}", quote(token, safe=""), 1)
+
+
+async def _async_remote_url(
+    client: AsyncPierre,
+    repo_name: str,
+    scopes: Optional[Sequence[str]],
+    ttl: int,
+    ref_policies: Optional[Sequence[RefPolicy]],
+    kind: str,
+) -> str:
+    template, needs = _prepare(client, repo_name, scopes, ttl, ref_policies, kind)
+    return _url(template, await client._resolved.credentials.async_token(needs))
+
+
+@overload
+def remote_url(
+    client: Pierre,
+    *,
+    repo_name: str,
+    scopes: Optional[Sequence[str]] = None,
+    ttl: int = _DEFAULT_TTL_SECONDS,
+    ref_policies: Optional[Sequence[RefPolicy]] = None,
+    kind: Kind = "default",
+) -> str: ...
+
+
+@overload
+def remote_url(
+    client: AsyncPierre,
+    *,
+    repo_name: str,
+    scopes: Optional[Sequence[str]] = None,
+    ttl: int = _DEFAULT_TTL_SECONDS,
+    ref_policies: Optional[Sequence[RefPolicy]] = None,
+    kind: Kind = "default",
+) -> Coroutine[None, None, str]: ...
+
+
+def remote_url(
+    client: Union[Pierre, AsyncPierre],
+    *,
+    repo_name: str,
+    scopes: Optional[Sequence[str]] = None,
+    ttl: int = _DEFAULT_TTL_SECONDS,
+    ref_policies: Optional[Sequence[RefPolicy]] = None,
+    kind: Kind = "default",
+) -> Union[str, Coroutine[None, None, str]]:
+    """Builds `https://t:<token>@{git_host}/{repo_name}.git` for `git clone`, `git fetch`, and
+    `git push`. The token is a bearer credential that Git copies into `.git/config`, so keep the
+    lifetime short. Longer work uses the credential helper (`pierre auth setup-git`).
+
+    The client signs the token with its private key, or gets it from `get_token`. A client with a
+    fixed `token` cannot set the claims of its token, so it raises `PierreError`. With
+    `AsyncPierre`, await the result.
+
+    Args:
+        client: A `Pierre` or `AsyncPierre` client.
+        repo_name: The repository name, for example `acme/web`.
+        scopes: The scopes of the token. Default: `git:read` and `git:write`.
+        ttl: The lifetime of the token in seconds, from 1 to 3600. Default: 900 (15 minutes).
+        ref_policies: The rules of the `refs` claim. Default: the client's `ref_policies`, so a
+            confined client stays confined through Git. An empty list adds no claim.
+        kind: The form of the remote: `default`, `ephemeral` (`+ephemeral`), or `import`
+            (`+import`).
+
+    Docs: search for `remoteUrl` in the docs MCP server, https://code.storage/docs/mcp.
+    """
+    if isinstance(client, AsyncPierre):
+        return _async_remote_url(client, repo_name, scopes, ttl, ref_policies, kind)
+    template, needs = _prepare(client, repo_name, scopes, ttl, ref_policies, kind)
+    return _url(template, client._resolved.credentials.token(needs))

pierre/types.py

@@ -0,0 +1,14 @@
+"""The types of the SDK: the named schemas of the API, with the wire name of each field, the
+declared response headers of each operation, the webhook events, and the types of the arguments
+that the methods take."""
+
+from pierre._content import Content as Content
+from pierre._generated.headers import *  # noqa: F403
+from pierre._generated.schemas import *  # noqa: F403
+from pierre._generated.webhooks import *  # noqa: F403
+from pierre._helpers.commits import CommitFile as CommitFile
+from pierre._helpers.commits import FileContent as FileContent
+from pierre._types import HeadersResult as HeadersResult
+from pierre._types import NoHeaders as NoHeaders
+from pierre._types import RefPolicy as RefPolicy
+from pierre._types import TokenRequest as TokenRequest

pierre/webhooks.py

@@ -0,0 +1,145 @@
+"""`pierre.webhooks`: verifies a webhook delivery and returns the typed event."""
+
+import hashlib
+import hmac
+import json
+import re
+import time
+from typing import Any, Dict, List, Literal, Mapping, Optional, Sequence, Tuple, Union, cast
+
+from pierre._compat import TypedDict
+from pierre._errors import PierreError, WebhookVerificationError, WebhookVerificationFailure
+from pierre._generated.webhooks import WEBHOOK_EVENT_TYPES, KnownWebhookEvent, WebhookEventType
+
+__all__ = [
+    "WEBHOOK_EVENT_TYPES",
+    "KnownWebhookEvent",
+    "UnknownWebhookEvent",
+    "WebhookEventType",
+    "WebhookVerificationError",
+    "WebhookVerificationFailure",
+    "verify_webhook",
+]
+
+_DEFAULT_TOLERANCE_SECONDS = 300
+_KNOWN_TYPES = frozenset(WEBHOOK_EVENT_TYPES)
+# ASCII digits only: `\d` also matches other digits, which `int()` reads.
+_HEX_SIGNATURE = re.compile(r"[0-9a-fA-F]{64}")
+_TIMESTAMP = re.compile(r"[0-9]+")
+
+
+class UnknownWebhookEvent(TypedDict):
+    """An event of a type that this SDK version does not know. Handle it in a default branch.
+
+    `type` is `unknown`, not the type that Pierre sent, so that a check of `type` narrows the
+    union. No Pierre event has the type `unknown`, because each type has the form
+    `<resource>.<subject>.<verb>`, or is `push`."""
+
+    type: Literal["unknown"]
+    # The event type that Pierre sent, for example a type from a newer API version.
+    event_type: str
+    # The parsed payload.
+    body: Dict[str, Any]
+
+
+HeaderValue = Union[str, Sequence[str], None]
+
+
+def _header(headers: Mapping[str, HeaderValue], name: str) -> Optional[str]:
+    """A header of a mapping such as `httpx.Headers` or a dict, with any case."""
+    for key, value in headers.items():
+        if key.lower() != name:
+            continue
+        if value is None or isinstance(value, str):
+            return value
+        return value[0] if len(value) > 0 else None
+    return None
+
+
+def _parse_signature(header: str) -> Tuple[str, List[bytes]]:
+    """The timestamp and the signatures of `t=<unix seconds>,sha256=<hex>[,sha256=<hex>...]`."""
+    timestamp: Optional[str] = None
+    signatures: List[bytes] = []
+    for element in header.split(","):
+        name, _, value = element.strip().partition("=")
+        if name == "t" and _TIMESTAMP.fullmatch(value):
+            timestamp = value
+        if name == "sha256" and _HEX_SIGNATURE.fullmatch(value):
+            signatures.append(bytes.fromhex(value))
+    if timestamp is None or len(signatures) == 0:
+        raise WebhookVerificationError(
+            "malformed_signature",
+            "X-Pierre-Signature must have the form `t=<unix seconds>,sha256=<hex>`.",
+        )
+    return timestamp, signatures
+
+
+def verify_webhook(
+    *,
+    payload: Union[str, bytes, bytearray, memoryview],
+    headers: Mapping[str, HeaderValue],
+    secret: str,
+    tolerance_seconds: float = _DEFAULT_TOLERANCE_SECONDS,
+) -> Union[KnownWebhookEvent, UnknownWebhookEvent]:
+    """Checks the `X-Pierre-Signature` header of a delivery: an HMAC-SHA256 of `<t>.<payload>`
+    with the secret, and a timestamp `t` within `tolerance_seconds` of now. Returns the event, a
+    union on `type`. Raises `WebhookVerificationError` when the check fails.
+
+    Args:
+        payload: The raw request body, before a JSON parse changes its bytes.
+        headers: The request headers: `httpx.Headers`, or a dict such as the headers of a web
+            framework.
+        secret: The secret of the webhook subscription.
+        tolerance_seconds: The largest difference between the delivery time and now, in seconds.
+            Default: 300.
+
+    Docs: search for `verifyWebhook` in the docs MCP server, https://code.storage/docs/mcp.
+    """
+    if isinstance(tolerance_seconds, bool) or not tolerance_seconds >= 0:
+        raise PierreError("`tolerance_seconds` must be 0 or more.")
+    if secret == "":
+        raise PierreError("`secret` must not be empty.")
+    header = _header(headers, "x-pierre-signature")
+    if header is None:
+        raise WebhookVerificationError(
+            "missing_signature", "The request has no X-Pierre-Signature header."
+        )
+    timestamp, signatures = _parse_signature(header)
+    body_bytes = payload.encode("utf-8") if isinstance(payload, str) else bytes(payload)
+    expected = hmac.new(
+        secret.encode("utf-8"), timestamp.encode("ascii") + b"." + body_bytes, hashlib.sha256
+    ).digest()
+    # `compare_digest` compares in constant time.
+    valid = False
+    for signature in signatures:
+        if hmac.compare_digest(signature, expected):
+            valid = True
+    if not valid:
+        raise WebhookVerificationError(
+            "signature_mismatch", "The signature does not match the payload and the secret."
+        )
+    age = int(time.time()) - int(timestamp)
+    if abs(age) > tolerance_seconds:
+        raise WebhookVerificationError(
+            "timestamp_out_of_range",
+            f"The delivery is {age} seconds old, and the tolerance is {tolerance_seconds:g} seconds.",
+        )
+
+    try:
+        body = json.loads(body_bytes)
+    except ValueError:
+        raise WebhookVerificationError("invalid_payload", "The payload is not JSON.") from None
+    if not isinstance(body, dict):
+        raise WebhookVerificationError("invalid_payload", "The payload is not a JSON object.")
+    # Older push deliveries have no `type`. The `X-Pierre-Event` header is not signed, so the SDK
+    # uses it only to name such a push.
+    body_type = body.get("type")
+    event_type: Optional[str] = body_type if isinstance(body_type, str) else None
+    if event_type is None and _header(headers, "x-pierre-event") == "push":
+        event_type = "push"
+    if event_type is None or event_type == "":
+        raise WebhookVerificationError("invalid_payload", "The payload has no event type.")
+    if event_type in _KNOWN_TYPES:
+        # The type is a known event type, and the payload follows its schema.
+        return cast(KnownWebhookEvent, {**body, "type": event_type})
+    return {"type": "unknown", "event_type": event_type, "body": body}

pierre_sdk-0.1.0.dev4.dist-info/METADATA

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: pierre-sdk
+Version: 0.1.0.dev4
+Summary: The Pierre SDK for Python
+Author: Pierre
+Author-email: Pierre <support@pierre.co>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+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: Typing :: Typed
+Requires-Dist: cryptography>=41.0.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: typing-extensions>=4.5.0 ; python_full_version < '3.11'
+Requires-Python: >=3.10
+Project-URL: Homepage, https://pierre.computer
+Description-Content-Type: text/markdown
+
+# Pierre SDK for Python
+
+The Python SDK of Pierre: `Pierre` for blocking code, and `AsyncPierre` for `asyncio` code. Both
+clients have the same namespaces, helpers, errors, pagination, and retries as `@pierre/sdk` in
+TypeScript.
+
+## Use the client
+
+`Pierre()` reads `PIERRE_ORG` and `PIERRE_PRIVATE_KEY`, or the other variables in
+[Credentials](#credentials). Each method path is the catalog ID of its operation, with each segment
+in snake_case. Each method takes keyword arguments with the wire names of the HTTP API.
+
+```python
+from pierre import Pierre
+
+pierre = Pierre()
+pierre.repos.create(repo_name="acme/web", default_branch="main")
+pierre.repos.branches.create(repo_name="acme/web", target_branch="feat", base_ref="main")
+pierre.repos.commits.create(
+    repo_name="acme/web",
+    target_branch="feat",
+    commit_message="Add readme",
+    author={"name": "Bot", "email": "bot@acme.dev"},
+    files=[{"path": "README.md", "content": "# Web"}],
+)
+for repo in pierre.repos.list(q="web"):
+    print(repo["repo_name"])
+```
+
+`AsyncPierre` takes the same arguments, and each method is async:
+
+```python
+from pierre import AsyncPierre
+
+pierre = AsyncPierre()
+repo = await pierre.repos.get(repo_name="acme/web")
+async for branch in pierre.repos.branches.list(repo_name="acme/web"):
+    print(branch["name"])
+```
+
+A result is a dict with the wire names of the response, typed as a `TypedDict` from `pierre.types`.
+A byte response, such as `repos.files.get`, returns the `httpx.Response`, which the caller reads or
+closes.
+
+## Credentials
+
+Give one credential. A credential in the options replaces every credential in the environment.
+
+| Option        | Variable                                                       | Use                                                                                     |
+| ------------- | -------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| `private_key` | `PIERRE_PRIVATE_KEY`, or the file at `PIERRE_PRIVATE_KEY_FILE` | The SDK signs a 5-minute token for each request, with only the scopes of the operation. |
+| `token`       | `PIERRE_TOKEN`                                                 | A fixed token. The server checks its scopes.                                            |
+| `get_token`   | none                                                           | A function that returns a token for each request, for a client with no private key.     |
+
+With no credential in the options, the SDK uses the first variable that is set: `PIERRE_TOKEN`, then
+`PIERRE_PRIVATE_KEY`, then `PIERRE_PRIVATE_KEY_FILE`.
+
+`org` (`PIERRE_ORG`) names the organization. With `token`, the SDK reads it from the `iss` claim.
+`base_url` (`PIERRE_API_BASE_URL`) and `git_host` (`PIERRE_GIT_HOST`) replace the default hosts,
+`https://api.{org}.code.storage` and `{org}.code.storage`. The base URL ends before `/api`, because
+each operation path starts with `/api`: for example `https://api.acme.code.storage`, not
+`https://api.acme.code.storage/api/v1`. A path in front of `/api`, such as the prefix of a proxy,
+stays in the base URL. The Git host is a host name with an optional port and no scheme, for example
+`acme.code.storage`.
+
+## Options
+
+The client options are `org`, `private_key`, `token`, `get_token`, `base_url`, `git_host`, `timeout`
+(seconds, default 60), `max_retries` (default 2), `default_headers`, `http_client`, and
+`ref_policies`. `pierre.options` holds the settings with no credential, and `pierre.with_options()`
+returns a copy with changed options.
+
+A client keeps one httpx client. `with Pierre() as pierre:` and
+`async with AsyncPierre() as pierre:` close the httpx client that the SDK made at the end of the
+block. An `http_client` that you give stays open.
+
+Each method also takes the request options `extra_headers`, `timeout`, `max_retries`,
+`idempotency_key`, `token_ttl`, and `ref_policies` for one call.
+
+`idempotency_key` applies only to an operation that accepts an `Idempotency-Key`. On any other
+operation, the call raises `PierreError` and sends no request.
+
+An optional argument has the default `NOT_GIVEN`, which the SDK does not send. `None` sends `null`.
+
+## Responses, pages, and errors
+
+- `pierre.with_raw_response` has the namespaces of the client. Each method returns a `RawResponse`
+  with `data`, `response` (the `httpx.Response`), `headers` (the declared response headers), and
+  `request_id`.
+- A list method returns a `Page` in `Pierre`. In `AsyncPierre`, it returns an `AsyncPaginator`:
+  `await` gives the first `AsyncPage`, and `async for` gives every item. A page has `data`,
+  `has_more`, `next_cursor`, `body`, `response`, `has_next_page()`, `get_next_page()`, and
+  `iter_pages()`. To serialize a page, serialize `page.body`, the response that the API sent.
+- Every error extends `PierreError`. An HTTP error is an `APIError` with `status`, `code`, `title`,
+  `detail`, `request_id`, `headers`, `body`, and `doc_url`, with a subclass for each status family,
+  and `MergeConflictError` and `RefUpdateError` for codes. `RefUpdateError.result` is a
+  `RefUpdateResult`, or a `NotesWriteResult` for a notes write, so `error.result["status"]` gives
+  the reason with no cast, for example `conflict`. A failed ref guard, with the code
+  `ref_guard_failed`, raises `RefGuardError`, a `ConflictError` with `guard` and `current_sha`: send
+  `current_sha` as the guard of the next attempt.
+
+## Local utilities
+
+Import the modules of the local utilities before you name a client `pierre`, because the client name
+hides the package:
+
+```python
+from pierre import Pierre, auth, git, webhooks
+
+pierre = Pierre()
+token = auth.create_token(pierre, scopes=["git:read"], repo="acme/web")
+url = git.remote_url(pierre, repo_name="acme/web")
+```
+
+- `auth.create_token(client, scopes=[...])` signs a token with no HTTP call. `auth.SCOPES` lists the
+  scopes of the API, and `auth.Scope` is their type.
+- `git.remote_url(client, repo_name=...)` builds a Git remote URL with a 15-minute token. With
+  `AsyncPierre`, await the result.
+- `webhooks.verify_webhook(payload=..., headers=..., secret=...)` checks a webhook delivery and
+  returns the typed event.
+
+## Differences from the TypeScript SDK
+
+- A timeout is in seconds, as in `httpx`. It covers each attempt: the token, the upload, the
+  response headers, and a JSON body. `Pierre` cannot stop a blocking `get_token`, so the attempt
+  fails when the token arrives after the deadline.
+- There is no `signal`. To stop an `AsyncPierre` call, cancel its task.
+- An async method starts its request when the caller awaits it, as a coroutine does.
+- `pierre.with_raw_response` replaces `withResponse()`. The SDK reads the body of a JSON response,
+  so there is no `asResponse()`. A byte response stays a stream.

pierre_sdk-0.1.0.dev4.dist-info/RECORD

@@ -0,0 +1,34 @@
+pierre/__init__.py,sha256=4_4z7hVkZqQrh3qeYkGEGXpWNJrRR4rwPyDcFvM5OgE,1495
+pierre/_client.py,sha256=xK61G2hw3vnykcmx_OfWneLE4wpGIJmMH_tbASwsgwU,21006
+pierre/_compat.py,sha256=yj2hvrYOJKoNniwW8GVGEkB0NUl0najQa3mYukL-Bjo,519
+pierre/_content.py,sha256=GwT6Gi_Ka5yWIE_5Aj3rqY5Kby7EKO9BNkJvQ_1FIdo,5214
+pierre/_credentials.py,sha256=1SBnwepDPZo0xnan_f9MY2vD8Ooo7sTTZxLh2LyJIxY,11393
+pierre/_errors.py,sha256=vJa8zAywAee5PnX3Wz7Q8LtAR14LEvoqpMYYrzCGCwI,7010
+pierre/_generated/__init__.py,sha256=gSsN54e_mcTHjk_7QHTDzkysYvcuDqqBljGpHbdtnjI,84
+pierre/_generated/client.py,sha256=mzDRaNcMjsPD8iDwpx7t15mLEudyTv_ov_HjZB8N3Ts,1772
+pierre/_generated/headers.py,sha256=JCaDyOX6P7R5Isr8Q7jsYT6eX3sHWmySyppvshCJ0Ps,3035
+pierre/_generated/namespaces/__init__.py,sha256=c53ApOKBEFmqvDOw97_M4X0h7xZm3hCLQbb55cuVAfs,93
+pierre/_generated/namespaces/meta.py,sha256=q9ZJJEhiZIHYA25uPgegfxtbd9a4JyGlFNu8vMkQbdw,4688
+pierre/_generated/namespaces/repos.py,sha256=-UXNqt3FRPSDReCtHA5BeQbE4ql43Zl7FDjI8ySD6-I,245623
+pierre/_generated/schemas.py,sha256=2CToWi6qF5l5w-10tsjqE17j1oXdBUBPAK77VGKzjV8,55888
+pierre/_generated/scopes.py,sha256=UsEF3i3kPrZWFvu_YUdTz8w75gItVEVFafwne1qimpg,436
+pierre/_generated/webhooks.py,sha256=xIj_OyyMwSu7i1lpGLitDTEkOqyDmYHNncXTtC_RQVc,845
+pierre/_helpers/__init__.py,sha256=15Bi6tFtWZCEGM9PxIi95lu0Oc7QvCrN_jOjLm9n_XU,45
+pierre/_helpers/commits.py,sha256=bUtnSd9rKClGMHgNH3kIN3rc6kbAD2PXBqil0LXXWco,7691
+pierre/_helpers/repos.py,sha256=Shk4VmtSv6y7LfcM4YxSAxmapbfKQbnfGVME7RNCh8U,2056
+pierre/_operation.py,sha256=_1gBkbzufm44j63lQD5upitaKeQdEQOV7nbqWIc9_mA,1919
+pierre/_page.py,sha256=iXcYsPSkCuL6qHvFzpmUwWNOttbXOQ_chWAAXlbyH_I,5254
+pierre/_response.py,sha256=52IuQt0up-ig7dl-ZQOsTqaWc9zS4U_u0neqqL9Tuv4,3027
+pierre/_retry.py,sha256=1LOp8E54Clkpbi6bujM34EmVYiEbEtXIkVVsoDw7E2Q,2341
+pierre/_runtime.py,sha256=3L8qWvF6JRwxpWxWhEcFodGdLsmnbHJALf949t6RbMA,31014
+pierre/_types.py,sha256=lH_XJ1G56npnfG34GtwZnNxWwpSgdo20ZSLGwLbohGw,2277
+pierre/_version.py,sha256=1-LX3ui0nSM78mxTnqVrkzgOhzHfb0DyhIoXNbT7SX8,103
+pierre/auth.py,sha256=9NZ80xib0schk6LjWxVRfoFQv7nfeEtjA3J8wPbmq6I,3402
+pierre/git.py,sha256=xGdBaxCAVjntS6202FCvuGkqDLnxbQz2Ywel3X6-tzs,6529
+pierre/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pierre/types.py,sha256=Et4uy1SMITTVDCt56eVLBwsf0OZNoyum-nIdHlH9ydw,760
+pierre/webhooks.py,sha256=2HD7OIMEhbQCJs_znNXX0FQje_zowKsnJhKJpj7SmmI,6049
+pierre_sdk-0.1.0.dev4.dist-info/licenses/LICENSE,sha256=Z2_yAs4OlHHd6hkv_CA5UlN1Qwuy0EyfkFXdEC988dw,10899
+pierre_sdk-0.1.0.dev4.dist-info/WHEEL,sha256=cmC5s21ojypbVslldL7IJq3hjZH-tINy4rziKePFsG0,81
+pierre_sdk-0.1.0.dev4.dist-info/METADATA,sha256=pJwn9O-5KRdW3asDw2hegLWbFSTvhFc-S8qddN7tdfE,7638
+pierre_sdk-0.1.0.dev4.dist-info/RECORD,,