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

pierre/_generated/scopes.py

@@ -0,0 +1,12 @@
+# Generated by sdkgen. Do not edit this file.
+"""The scopes of the operations of the API."""
+
+from typing import Literal, Tuple
+
+__all__ = ["SCOPES", "Scope"]
+
+# A scope that an operation of this SDK version needs.
+Scope = Literal["git:read", "git:write", "org:read", "repo:write"]
+
+# Each scope that an operation of this SDK version needs, in name order.
+SCOPES: Tuple[Scope, ...] = ("git:read", "git:write", "org:read", "repo:write")

pierre/_generated/webhooks.py

@@ -0,0 +1,30 @@
+# Generated by sdkgen. Do not edit this file.
+"""The webhook events of the API, each with its type."""
+
+from typing import Literal, Tuple, Union
+
+from pierre._generated import schemas
+
+__all__ = [
+    "KnownWebhookEvent",
+    "WebhookEventType",
+]
+
+# An event of a type that this SDK version knows: the payload schema of its type.
+KnownWebhookEvent = Union[
+    schemas.GitPushEvent,
+    schemas.GitSyncFailedEvent,
+    schemas.GitSyncStartedEvent,
+    schemas.GitSyncSucceededEvent,
+]
+
+# The type of an event that this SDK version knows.
+WebhookEventType = Literal["push", "repo.sync.failed", "repo.sync.started", "repo.sync.succeeded"]
+
+# Each event type that `verify_webhook` types, in name order.
+WEBHOOK_EVENT_TYPES: Tuple[WebhookEventType, ...] = (
+    "push",
+    "repo.sync.failed",
+    "repo.sync.started",
+    "repo.sync.succeeded",
+)

pierre/_helpers/__init__.py

@@ -0,0 +1 @@
+"""Hand-written helpers over the runtime."""

pierre/_helpers/commits.py

@@ -0,0 +1,220 @@
+"""The public form of the streaming commit writes. The wire form sends a
+metadata line, then the content of each file as base64 chunk lines. These helpers take the
+content itself and write the chunks."""
+
+import base64
+import inspect
+import uuid
+from typing import (
+    Any,
+    AsyncIterable,
+    AsyncIterator,
+    Awaitable,
+    Callable,
+    Dict,
+    Iterable,
+    Iterator,
+    List,
+    Literal,
+    Mapping,
+    Tuple,
+    Union,
+)
+
+from pierre._compat import NotRequired, TypedDict
+from pierre._content import (
+    Content,
+    async_chunks,
+    async_close,
+    chunks,
+    close,
+)
+from pierre._errors import PierreError
+from pierre._operation import OperationSpec
+from pierre._runtime import AsyncRuntime, SyncRuntime
+from pierre._types import RequestOptions
+
+__all__ = [
+    "CommitFile",
+    "Content",
+    "FileContent",
+    "async_create_commit",
+    "async_create_commit_from_diff",
+    "create_commit",
+    "create_commit_from_diff",
+]
+
+# File content, or a function that returns it when the SDK sends the file. In `AsyncPierre`, the
+# function can be async.
+FileContent = Union[Content, Callable[[], Union[Content, Awaitable[Content]]]]
+
+
+class CommitFile(TypedDict):
+    """One file of a commit."""
+
+    # The repository path of the file.
+    path: str
+    # `upsert` by default.
+    operation: NotRequired[Literal["upsert", "delete"]]
+    # The Git file mode. `100644` by default for an upsert.
+    mode: NotRequired[str]
+    # The file content. An upsert needs it, and a delete must not have it.
+    #
+    # The SDK reads all of `files` before it sends any content, because the first NDJSON line
+    # names every file. To open only one file at a time, give a function, for example
+    # `lambda: open(path, "rb")`. The SDK calls the function when it sends that file, and closes
+    # the file that the function returns. The SDK copies a `bytearray` or a `memoryview` when it
+    # reads the entry, so a caller can reuse a buffer.
+    content: NotRequired[FileContent]
+
+
+# One checked file: the file fields, its content, and its content ID.
+_Entry = Tuple[Dict[str, Any], object, str]
+
+
+def _entry(file: object) -> _Entry:
+    if not isinstance(file, Mapping) or not isinstance(file.get("path"), str):
+        raise PierreError("Each file needs `path`.")
+    path = file["path"]
+    operation = file.get("operation", "upsert")
+    content = file.get("content")
+    if operation == "upsert" and content is None:
+        raise PierreError(f"The file {path} needs `content`.")
+    if operation == "delete" and content is not None:
+        raise PierreError(f"The delete of {path} must not have `content`.")
+    if isinstance(content, (bytearray, memoryview)):
+        content = bytes(content)
+    wire: Dict[str, Any] = {"path": path, "content_id": str(uuid.uuid4()), "operation": operation}
+    if operation == "upsert":
+        wire["mode"] = file.get("mode", "100644")
+    return wire, content, wire["content_id"]
+
+
+def _is_function(content: object) -> bool:
+    return (
+        callable(content)
+        and not callable(getattr(content, "read", None))
+        and not isinstance(content, (Iterable, AsyncIterable))
+    )
+
+
+def _blob_chunk(content_id: str, data: bytes, eof: bool) -> Dict[str, Any]:
+    return {
+        "blob_chunk": {
+            "content_id": content_id,
+            "data": base64.b64encode(data).decode("ascii"),
+            "eof": eof,
+        }
+    }
+
+
+def _sync_files(files: object) -> Iterable[object]:
+    if hasattr(files, "__aiter__") or not isinstance(files, Iterable):
+        raise PierreError(
+            "`Pierre` takes a list or an iterable of files. Use `AsyncPierre` for an async iterable."
+        )
+    return files
+
+
+def create_commit(
+    runtime: SyncRuntime,
+    operation: OperationSpec[Any],
+    params: Mapping[str, Any],
+    options: RequestOptions,
+) -> Any:
+    """`pierre.repos.commits.create`. The SDK reads all of `files` before the request."""
+    metadata = {name: value for name, value in params.items() if name != "files"}
+    entries = [_entry(file) for file in _sync_files(params["files"])]
+
+    def blob_chunks() -> Iterator[Dict[str, Any]]:
+        for _, content, content_id in entries:
+            if content is None:
+                continue
+            source = content() if _is_function(content) else content  # type: ignore[operator]
+            if inspect.isawaitable(source):
+                if inspect.iscoroutine(source):
+                    source.close()
+                raise PierreError("`Pierre` takes a content function that is not async.")
+            try:
+                for data, eof in chunks(source):
+                    yield _blob_chunk(content_id, data, eof)
+            finally:
+                if source is not content:
+                    close(source)
+
+    wire = {**metadata, "files": [entry[0] for entry in entries], "chunks": blob_chunks()}
+    return runtime.request(operation, wire, options)
+
+
+async def async_create_commit(
+    runtime: AsyncRuntime,
+    operation: OperationSpec[Any],
+    params: Mapping[str, Any],
+    options: RequestOptions,
+) -> Any:
+    """`pierre.repos.commits.create` of `AsyncPierre`, which also takes async files and content."""
+    metadata = {name: value for name, value in params.items() if name != "files"}
+    files = params["files"]
+    entries: List[_Entry] = []
+    if isinstance(files, AsyncIterable):
+        async for file in files:
+            entries.append(_entry(file))
+    elif isinstance(files, Iterable):
+        entries = [_entry(file) for file in files]
+    else:
+        raise PierreError("`files` must be a list, an iterable, or an async iterable of files.")
+
+    async def blob_chunks() -> AsyncIterator[Dict[str, Any]]:
+        for _, content, content_id in entries:
+            if content is None:
+                continue
+            source = content() if _is_function(content) else content  # type: ignore[operator]
+            if inspect.isawaitable(source):
+                source = await source
+            try:
+                async for data, eof in async_chunks(source):
+                    yield _blob_chunk(content_id, data, eof)
+            finally:
+                if source is not content:
+                    await async_close(source)
+
+    wire = {**metadata, "files": [entry[0] for entry in entries], "chunks": blob_chunks()}
+    return await runtime.request(operation, wire, options)
+
+
+def _diff_chunk(data: bytes, eof: bool) -> Dict[str, Any]:
+    return {"diff_chunk": {"data": base64.b64encode(data).decode("ascii"), "eof": eof}}
+
+
+def create_commit_from_diff(
+    runtime: SyncRuntime,
+    operation: OperationSpec[Any],
+    params: Mapping[str, Any],
+    options: RequestOptions,
+) -> Any:
+    """`pierre.repos.commits.create_from_diff`: the diff as `diff_chunk` lines."""
+    metadata = {name: value for name, value in params.items() if name != "diff"}
+    diff = params["diff"]
+
+    def diff_chunks() -> Iterator[Dict[str, Any]]:
+        for data, eof in chunks(diff):
+            yield _diff_chunk(data, eof)
+
+    return runtime.request(operation, {**metadata, "chunks": diff_chunks()}, options)
+
+
+async def async_create_commit_from_diff(
+    runtime: AsyncRuntime,
+    operation: OperationSpec[Any],
+    params: Mapping[str, Any],
+    options: RequestOptions,
+) -> Any:
+    """`pierre.repos.commits.create_from_diff` of `AsyncPierre`."""
+    metadata = {name: value for name, value in params.items() if name != "diff"}
+    diff = params["diff"]
+
+    async def diff_chunks() -> AsyncIterator[Dict[str, Any]]:
+        async for data, eof in async_chunks(diff):
+            yield _diff_chunk(data, eof)
+
+    return await runtime.request(operation, {**metadata, "chunks": diff_chunks()}, options)

pierre/_helpers/repos.py

@@ -0,0 +1,58 @@
+"""The repository create. A copy reads its source with a token, and the SDK adds
+that token when the caller gives none."""
+
+from typing import Any, Mapping, Optional
+
+from pierre._operation import OperationSpec
+from pierre._runtime import AsyncRuntime, SyncRuntime
+from pierre._types import RequestOptions
+
+
+def _source(params: Mapping[str, Any]) -> Optional[Mapping[str, Any]]:
+    """The source of a copy that needs a token, or `None`."""
+    source = params.get("base_repo")
+    if not isinstance(source, Mapping):
+        return None
+    auth = source.get("auth")
+    # The deprecated sync form, with `provider`, reads no Code Storage repository.
+    if source.get("provider") is not None or (isinstance(auth, Mapping) and "token" in auth):
+        return None
+    # The server rejects a copy with no source name.
+    return source if isinstance(source.get("name"), str) else None
+
+
+def _with_token(params: Mapping[str, Any], source: Mapping[str, Any], token: str) -> Any:
+    auth = source.get("auth")
+    return {
+        **params,
+        "base_repo": {
+            **source,
+            "auth": {**(auth if isinstance(auth, Mapping) else {}), "token": token},
+        },
+    }
+
+
+def create_repo(
+    runtime: SyncRuntime,
+    operation: OperationSpec[Any],
+    params: Mapping[str, Any],
+    options: RequestOptions,
+) -> Any:
+    """`pierre.repos.create`, with a `git:read` token for the source repository of a copy."""
+    source = _source(params)
+    if source is not None:
+        params = _with_token(params, source, runtime.read_token(source["name"], options))
+    return runtime.request(operation, params, options)
+
+
+async def async_create_repo(
+    runtime: AsyncRuntime,
+    operation: OperationSpec[Any],
+    params: Mapping[str, Any],
+    options: RequestOptions,
+) -> Any:
+    """`pierre.repos.create` of `AsyncPierre`."""
+    source = _source(params)
+    if source is not None:
+        params = _with_token(params, source, await runtime.read_token(source["name"], options))
+    return await runtime.request(operation, params, options)

pierre/_operation.py

@@ -0,0 +1,66 @@
+"""The facts of one operation, from the SDK model. The generated layer defines one spec for each
+operation, and the runtime reads it to send the request."""
+
+from dataclasses import dataclass
+from typing import Generic, Literal, Optional, Tuple, TypeVar, Union
+
+Headers = TypeVar("Headers")
+
+
+@dataclass(frozen=True)
+class ParameterSpec:
+    """A path, query, or header parameter."""
+
+    location: Literal["path", "query", "header"]
+    # The wire name.
+    name: str
+    # The keyword argument.
+    field: str
+
+
+@dataclass(frozen=True)
+class JsonBodySpec:
+    """A JSON body: the runtime sends these arguments. When the body is optional and the call
+    gives none of them, the runtime sends no body."""
+
+    required: bool
+    fields: Tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class NdjsonBodySpec:
+    """An NDJSON body: the first line is `{first: <these arguments>}`, and the argument `chunks`
+    gives each later line when `rest` is true."""
+
+    first: str
+    fields: Tuple[str, ...]
+    rest: bool
+
+
+@dataclass(frozen=True)
+class HeaderSpec:
+    """A declared response header, by its wire name and its field."""
+
+    name: str
+    field: str
+
+
+@dataclass(frozen=True)
+class OperationSpec(Generic[Headers]):
+    """One operation. `Headers` is the type of its declared response headers."""
+
+    id: str
+    method: Literal["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE"]
+    path: str
+    parameters: Tuple[ParameterSpec, ...]
+    body: Union[JsonBodySpec, NdjsonBodySpec, None]
+    response_encoding: Literal["json", "ndjson", "bytes", "none"]
+    response_headers: Tuple[HeaderSpec, ...]
+    # Whether a 304 response is a result, not an error.
+    not_modified: bool
+    scopes: Tuple[str, ...]
+    # Whether the token needs a `repo` claim.
+    repo_claim: bool
+    # The response field that holds the items of a list, or `None` for another operation.
+    item_field: Optional[str]
+    idempotency_key: bool

pierre/_page.py

@@ -0,0 +1,154 @@
+"""List pages."""
+
+import asyncio
+from typing import (
+    Any,
+    AsyncIterator,
+    Awaitable,
+    Callable,
+    Generator,
+    Generic,
+    Iterator,
+    List,
+    Optional,
+    TypeVar,
+)
+
+import httpx
+
+from pierre._errors import PierreError
+
+Item = TypeVar("Item")
+Body = TypeVar("Body")
+
+
+def _next_cursor(has_more: bool, next_cursor: Optional[str]) -> Optional[str]:
+    return next_cursor if has_more and next_cursor else None
+
+
+_NO_NEXT_PAGE = "No next page. Call `has_next_page()` before `get_next_page()`."
+
+
+class Page(Generic[Item, Body]):
+    """One page of a list in `Pierre`. `body` is the full response body, with the fields beside
+    the items. Iteration gives the items of this page and of each next page. To serialize a page,
+    serialize `body`, the response that the API sent: `json.dumps(page.body)`."""
+
+    def __init__(
+        self,
+        *,
+        data: List[Item],
+        has_more: bool,
+        next_cursor: Optional[str],
+        body: Body,
+        response: httpx.Response,
+        fetch: Callable[[str], "Page[Item, Body]"],
+    ) -> None:
+        self.data = data
+        self.has_more = has_more
+        self.next_cursor = next_cursor
+        self.body = body
+        # The `httpx.Response` of this page. The SDK read its body.
+        self.response = response
+        self._fetch = fetch
+
+    def has_next_page(self) -> bool:
+        """Whether a next page exists: `has_more` is true, and `next_cursor` is not empty."""
+        return _next_cursor(self.has_more, self.next_cursor) is not None
+
+    def get_next_page(self) -> "Page[Item, Body]":
+        """Gets the next page, with the arguments of the first call. Call `has_next_page()` first:
+        with no next page, it raises `PierreError`."""
+        cursor = _next_cursor(self.has_more, self.next_cursor)
+        if cursor is None:
+            raise PierreError(_NO_NEXT_PAGE)
+        return self._fetch(cursor)
+
+    def iter_pages(self) -> Iterator["Page[Item, Body]"]:
+        """This page, then each next page."""
+        page = self
+        while True:
+            yield page
+            if not page.has_next_page():
+                return
+            page = page.get_next_page()
+
+    def __iter__(self) -> Iterator[Item]:
+        for page in self.iter_pages():
+            yield from page.data
+
+
+class AsyncPage(Generic[Item, Body]):
+    """One page of a list in `AsyncPierre`. `async for` gives the items of this page and of each
+    next page. To serialize a page, serialize `body`, the response that the API sent:
+    `json.dumps(page.body)`."""
+
+    def __init__(
+        self,
+        *,
+        data: List[Item],
+        has_more: bool,
+        next_cursor: Optional[str],
+        body: Body,
+        response: httpx.Response,
+        fetch: Callable[[str], Awaitable["AsyncPage[Item, Body]"]],
+    ) -> None:
+        self.data = data
+        self.has_more = has_more
+        self.next_cursor = next_cursor
+        self.body = body
+        # The `httpx.Response` of this page. The SDK read its body.
+        self.response = response
+        self._fetch = fetch
+
+    def has_next_page(self) -> bool:
+        """Whether a next page exists: `has_more` is true, and `next_cursor` is not empty."""
+        return _next_cursor(self.has_more, self.next_cursor) is not None
+
+    async def get_next_page(self) -> "AsyncPage[Item, Body]":
+        """Gets the next page, with the arguments of the first call. Call `has_next_page()` first:
+        with no next page, it raises `PierreError`."""
+        cursor = _next_cursor(self.has_more, self.next_cursor)
+        if cursor is None:
+            raise PierreError(_NO_NEXT_PAGE)
+        return await self._fetch(cursor)
+
+    async def iter_pages(self) -> AsyncIterator["AsyncPage[Item, Body]"]:
+        """This page, then each next page."""
+        page = self
+        while True:
+            yield page
+            if not page.has_next_page():
+                return
+            page = await page.get_next_page()
+
+    async def __aiter__(self) -> AsyncIterator[Item]:
+        async for page in self.iter_pages():
+            for item in page.data:
+                yield item
+
+
+class AsyncPaginator(Generic[Item, Body]):
+    """The result of a list method of `AsyncPierre`. `await` gives the first page, and
+    `async for` gives the items of every page. The request starts at the first use, and every use
+    reads that one request."""
+
+    def __init__(self, start: Callable[[], Awaitable[AsyncPage[Item, Body]]]) -> None:
+        self._start = start
+        self._first: "Optional[asyncio.Future[AsyncPage[Item, Body]]]" = None
+
+    async def _page(self) -> AsyncPage[Item, Body]:
+        # One task holds the first request, so that uses at the same time share its result or
+        # its error. A cancel stops only the use that the caller cancels, so a later use still
+        # reads the request.
+        if self._first is None:
+            self._first = asyncio.ensure_future(self._start())
+        return await asyncio.shield(self._first)
+
+    def __await__(self) -> Generator[Any, None, AsyncPage[Item, Body]]:
+        return self._page().__await__()
+
+    async def __aiter__(self) -> AsyncIterator[Item]:
+        page = await self._page()
+        async for item in page:
+            yield item

pierre/_response.py

@@ -0,0 +1,92 @@
+"""`pierre.with_raw_response`: each method gives its result with the response.
+The `with_raw_response` namespaces wrap the methods of the client namespaces, so they take the
+same arguments."""
+
+import functools
+from contextvars import ContextVar
+from dataclasses import dataclass
+from typing import Awaitable, Callable, Generic, Optional, TypeVar, cast
+
+import httpx
+
+from pierre._compat import ParamSpec
+from pierre._errors import PierreError
+from pierre._operation import OperationSpec
+
+Data = TypeVar("Data")
+Headers = TypeVar("Headers")
+Params = ParamSpec("Params")
+
+
+@dataclass(frozen=True)
+class RawResponse(Generic[Data, Headers]):
+    """The result of a method of `pierre.with_raw_response`."""
+
+    # What the method of the client returns.
+    data: Data
+    # The `httpx.Response` of the last attempt. The SDK read its body, except for a byte stream,
+    # whose `data` is this response.
+    response: httpx.Response
+    # The response headers that the document declares, by the wire form of each name.
+    headers: Headers
+    # The `X-Request-Id` header, or `None` when the server does not send it.
+    request_id: Optional[str]
+
+
+class _Claim:
+    """Marks the first request of a `with_raw_response` call. A request inside the call, such as
+    one from a content function, gives its plain result."""
+
+    claimed = False
+
+
+_RAW: "ContextVar[Optional[_Claim]]" = ContextVar("pierre_raw_response", default=None)
+
+
+def claim_raw() -> bool:
+    """Whether this request is the first request of a `with_raw_response` call."""
+    claim = _RAW.get()
+    if claim is None or claim.claimed:
+        return False
+    claim.claimed = True
+    return True
+
+
+def _checked(result: object) -> object:
+    if not isinstance(result, RawResponse):
+        raise PierreError("The method sent no request, so it has no response.")
+    return result
+
+
+def raw_method(
+    method: Callable[Params, Data], operation: OperationSpec[Headers]
+) -> Callable[Params, RawResponse[Data, Headers]]:
+    """The method of `Pierre` that returns a `RawResponse`. `operation` gives the headers type."""
+
+    @functools.wraps(method)
+    def call(*args: Params.args, **kwargs: Params.kwargs) -> RawResponse[Data, Headers]:
+        token = _RAW.set(_Claim())
+        try:
+            result: object = method(*args, **kwargs)
+        finally:
+            _RAW.reset(token)
+        return cast(RawResponse[Data, Headers], _checked(result))
+
+    return call
+
+
+def async_raw_method(
+    method: Callable[Params, Awaitable[Data]], operation: OperationSpec[Headers]
+) -> Callable[Params, Awaitable[RawResponse[Data, Headers]]]:
+    """The method of `AsyncPierre` that returns a `RawResponse`."""
+
+    @functools.wraps(method)
+    async def call(*args: Params.args, **kwargs: Params.kwargs) -> RawResponse[Data, Headers]:
+        token = _RAW.set(_Claim())
+        try:
+            result: object = await method(*args, **kwargs)
+        finally:
+            _RAW.reset(token)
+        return cast(RawResponse[Data, Headers], _checked(result))
+
+    return call