connectrpc 0.0.1__py3-none-any.whl

connectrpc/__init__.py

@@ -0,0 +1,84 @@
+# Copyright 2025 Gaudiy Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""Connect-Python: A Python implementation of the Connect protocol."""
+
+from connectrpc.call_options import CallOptions
+from connectrpc.client import Client, ClientConfig
+from connectrpc.code import Code
+from connectrpc.codec import Codec, ProtoBinaryCodec, ProtoJSONCodec
+from connectrpc.compression import Compression, GZipCompression
+from connectrpc.connect import (
+    Peer,
+    Spec,
+    StreamingClientConn,
+    StreamingHandlerConn,
+    StreamRequest,
+    StreamResponse,
+    StreamType,
+    UnaryRequest,
+    UnaryResponse,
+)
+from connectrpc.content_stream import AsyncByteStream
+from connectrpc.error import ConnectError
+from connectrpc.handler import Handler
+from connectrpc.handler_context import HandlerContext
+from connectrpc.headers import Headers
+from connectrpc.idempotency_level import IdempotencyLevel
+from connectrpc.middleware import ConnectMiddleware
+from connectrpc.options import ClientOptions, HandlerOptions
+from connectrpc.protocol import Protocol
+from connectrpc.request import Request
+from connectrpc.response import Response as HTTPResponse
+from connectrpc.response import StreamingResponse
+from connectrpc.response_writer import ServerResponseWriter
+from connectrpc.version import __version__
+
+__all__ = [
+    "__version__",
+    "AsyncByteStream",
+    "CallOptions",
+    "Client",
+    "ClientConfig",
+    "ClientOptions",
+    "Code",
+    "Codec",
+    "Compression",
+    "ConnectError",
+    "ConnectMiddleware",
+    "HandlerOptions",
+    "GZipCompression",
+    "Handler",
+    "HandlerContext",
+    "Headers",
+    "HTTPResponse",
+    "IdempotencyLevel",
+    "Peer",
+    "Protocol",
+    "ProtoBinaryCodec",
+    "ProtoJSONCodec",
+    "Request",
+    "ServerResponseWriter",
+    "Spec",
+    "StreamingClientConn",
+    "StreamingHandlerConn",
+    "StreamingResponse",
+    "StreamRequest",
+    "StreamResponse",
+    "StreamType",
+    "UnaryRequest",
+    "UnaryResponse",
+]

connectrpc/asgi_helpers/__init__.py

@@ -0,0 +1,15 @@
+# Copyright 2025 Gaudiy Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# SPDX-License-Identifier: Apache-2.0

connectrpc/asgi_helpers/utils.py

@@ -0,0 +1,93 @@
+# Copyright 2025 Gaudiy Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""Utility functions for ASGI helpers, including request/response decorators and route path extraction."""
+
+import typing
+from collections.abc import (
+    Awaitable,
+    Callable,
+)
+
+from starlette.requests import Request
+from starlette.responses import Response
+from starlette.types import ASGIApp, Receive, Scope, Send
+
+from connectrpc.utils import is_async_callable, run_in_threadpool
+
+
+def request_response(func: Callable[[Request], Awaitable[Response] | Response]) -> ASGIApp:
+    """Convert a request handler function into an ASGI application.
+
+    This decorator takes a function that handles a request and returns a response,
+    and wraps it into an ASGI application callable. The handler function can be either
+    synchronous or asynchronous.
+
+    Args:
+        func (Callable[[Request], Awaitable[Response] | Response]): The request handler function.
+            It can be a synchronous function returning a Response or an asynchronous function
+            returning an Awaitable of Response.
+
+    Returns:
+        ASGIApp: An ASGI application callable that can be used to handle ASGI requests.
+
+    """
+
+    async def async_func(request: Request) -> Response:
+        if is_async_callable(func):
+            return await func(request)
+        else:
+            return typing.cast(Response, await run_in_threadpool(func, request))
+
+    f: Callable[[Request], Awaitable[Response]] = async_func
+
+    async def app(scope: Scope, receive: Receive, send: Send) -> None:
+        request = Request(scope, receive, send)
+        response = await f(request)
+        await response(scope, receive, send)
+
+    return app
+
+
+def get_route_path(scope: Scope) -> str:
+    """Extract the route path from the given scope.
+
+    Args:
+        scope (Scope): The scope dictionary containing the request information.
+
+    Returns:
+        str: The extracted route path. If a root path is specified in the scope,
+            the function returns the path relative to the root path. If the path
+            does not start with the root path or if the path is equal to the root
+            path, the function returns the original path or an empty string,
+            respectively.
+
+    """
+    path: str = scope["path"]
+    root_path = scope.get("root_path", "")
+    if not root_path:
+        return path
+
+    if not path.startswith(root_path):
+        return path
+
+    if path == root_path:
+        return ""
+
+    if path[len(root_path)] == "/":
+        return path[len(root_path) :]
+
+    return path

connectrpc/call_options.py

@@ -0,0 +1,38 @@
+# Copyright 2025 Gaudiy Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""Call options configuration models."""
+
+import asyncio
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class CallOptions(BaseModel):
+    """Options for configuring a call.
+
+    Attributes:
+        timeout (float | None): Timeout for the call in seconds. If None, no timeout is applied.
+        abort_event (asyncio.Event | None): Event to abort the call. If set, the call can be cancelled by setting this event.
+    """
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    timeout: float | None = Field(default=None)
+    """Timeout for the call in seconds."""
+
+    abort_event: asyncio.Event | None = Field(default=None)
+    """Event to abort the call."""

connectrpc/client.py

@@ -0,0 +1,421 @@
+# Copyright 2025 Gaudiy Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""Provides the main client implementation for making Connect protocol RPCs."""
+
+import contextlib
+from collections.abc import AsyncGenerator, Awaitable, Callable
+from typing import Any
+
+import httpcore
+from yarl import URL
+
+from connectrpc.call_options import CallOptions
+from connectrpc.client_interceptor import apply_interceptors
+from connectrpc.code import Code
+from connectrpc.codec import Codec, CodecNameType, ProtoBinaryCodec, ProtoJSONCodec
+from connectrpc.compression import COMPRESSION_IDENTITY, Compression, GZipCompression, get_compression_from_name
+from connectrpc.connect import (
+    Spec,
+    StreamRequest,
+    StreamResponse,
+    StreamType,
+    UnaryRequest,
+    UnaryResponse,
+    receive_stream_response,
+    receive_unary_response,
+)
+from connectrpc.connection_pool import AsyncConnectionPool
+from connectrpc.error import ConnectError
+from connectrpc.idempotency_level import IdempotencyLevel
+from connectrpc.options import ClientOptions
+from connectrpc.protocol import Protocol, ProtocolClient, ProtocolClientParams
+from connectrpc.protocol_connect.connect_protocol import ProtocolConnect
+from connectrpc.protocol_grpc.grpc_protocol import ProtocolGRPC
+from connectrpc.utils import aiterate
+
+
+def parse_request_url(raw_url: str) -> URL:
+    """Parses and validates a request URL.
+
+    Args:
+        raw_url: The URL string to parse.
+
+    Returns:
+        A validated URL object.
+
+    Raises:
+        ConnectError: If the URL is missing a valid scheme (http or https).
+    """
+    url = URL(raw_url)
+
+    if url.scheme not in ["http", "https"]:
+        raise ConnectError(
+            f"URL {raw_url} missing scheme: use http:// or https://",
+            Code.UNAVAILABLE,
+        )
+
+    return url
+
+
+class ClientConfig:
+    """Configuration for a Connect client.
+
+    This class holds all the configuration required to make a request with the client,
+    parsing the raw URL and client options into a structured format.
+
+        url (URL): The parsed request URL.
+        protocol (Protocol): The protocol implementation to use (e.g., Connect, gRPC, gRPC-Web).
+        procedure (str): The full procedure string, including the service and method name (e.g., /acme.user.v1.UserService/GetUser).
+        codec (Codec): The codec for marshaling and unmarshaling request/response messages.
+        request_compression_name (str | None): The name of the compression algorithm to use for requests.
+        compressions (list[Compression]): A list of supported compression implementations.
+        descriptor (Any): The protobuf descriptor for the service.
+        idempotency_level (IdempotencyLevel): The idempotency level for the procedure.
+        compress_min_bytes (int): The minimum message size in bytes to be eligible for compression.
+        read_max_bytes (int): The maximum number of bytes to read from a response.
+        send_max_bytes (int): The maximum number of bytes to send in a request.
+        enable_get (bool): Whether to enable GET requests for idempotent procedures.
+    """
+
+    url: URL
+    protocol: Protocol
+    procedure: str
+    codec: Codec
+    request_compression_name: str | None
+    compressions: list[Compression]
+    descriptor: Any
+    idempotency_level: IdempotencyLevel
+    compress_min_bytes: int
+    read_max_bytes: int
+    send_max_bytes: int
+    enable_get: bool
+
+    def __init__(self, raw_url: str, options: ClientOptions):
+        """Initializes a new client instance.
+
+        This method configures the client based on the provided URL and options.
+        It sets up the protocol (Connect, gRPC, or gRPC-Web), the message codec
+        (Protobuf binary or JSON), compression settings, and other operational
+        parameters.
+
+        Args:
+            raw_url (str): The full URL for the RPC endpoint.
+            options (ClientOptions): An object containing configuration options for the client.
+
+        Raises:
+            ConnectError: If an unknown compression algorithm is specified in the options.
+        """
+        url = parse_request_url(raw_url)
+        proto_path = url.path
+
+        self.url = url
+        self.protocol = ProtocolConnect()
+        if options.protocol == "grpc":
+            self.protocol = ProtocolGRPC(web=False)
+        elif options.protocol == "grpc-web":
+            self.protocol = ProtocolGRPC(web=True)
+        self.procedure = proto_path
+
+        if options.use_binary_format:
+            self.codec = ProtoBinaryCodec()
+        else:
+            self.codec = ProtoJSONCodec(CodecNameType.JSON)
+
+        self.request_compression_name = options.request_compression_name
+        self.compressions = [GZipCompression()]
+        if self.request_compression_name and self.request_compression_name != COMPRESSION_IDENTITY:
+            compression = get_compression_from_name(self.request_compression_name, self.compressions)
+            if not compression:
+                raise ConnectError(
+                    f"unknown compression: {self.request_compression_name}",
+                    Code.UNKNOWN,
+                )
+        self.descriptor = options.descriptor
+        self.idempotency_level = options.idempotency_level
+        self.compress_min_bytes = options.compress_min_bytes
+        self.read_max_bytes = options.read_max_bytes
+        self.send_max_bytes = options.send_max_bytes
+        self.enable_get = options.enable_get
+
+    def spec(self, stream_type: StreamType) -> Spec:
+        """Builds a specification for a given stream type.
+
+        This method combines the procedure's general configuration (like procedure name,
+        descriptor, and idempotency level) with a specific stream type to create
+        a complete `Spec` object.
+
+        Args:
+            stream_type: The type of the stream for which to create the spec.
+
+        Returns:
+            A `Spec` object tailored to the specified stream type.
+        """
+        return Spec(
+            procedure=self.procedure,
+            descriptor=self.descriptor,
+            stream_type=stream_type,
+            idempotency_level=self.idempotency_level,
+        )
+
+
+class Client[T_Request, T_Response]:
+    """A generic client for making Connect protocol RPCs.
+
+    This client is responsible for making unary and streaming RPCs to a Connect-compliant server.
+    It is initialized with a connection pool, a server URL, request and response message types,
+    and optional configurations. It abstracts the underlying protocol details, allowing users
+    to make different types of RPC calls (unary, server-stream, client-stream, bidi-stream)
+    through a unified interface.
+
+    Type Parameters:
+        T_Request: The type of the request message.
+        T_Response: The type of the response message.
+
+
+    Attributes:
+        config (ClientConfig): The configuration used by the client.
+        protocol_client (ProtocolClient): The underlying protocol-specific client.
+    """
+
+    config: ClientConfig
+    protocol_client: ProtocolClient
+    _call_unary: Callable[[UnaryRequest[T_Request], CallOptions | None], Awaitable[UnaryResponse[T_Response]]]
+    _call_stream: Callable[
+        [StreamType, StreamRequest[T_Request], CallOptions | None], Awaitable[StreamResponse[T_Response]]
+    ]
+
+    def __init__(
+        self,
+        pool: AsyncConnectionPool,
+        url: str,
+        input: type[T_Request],
+        output: type[T_Response],
+        options: ClientOptions | None = None,
+    ) -> None:
+        """Initializes a client for a specific RPC method.
+
+        This constructor sets up the necessary components for making RPC calls to a single method.
+        It configures the protocol client based on the provided options and prepares wrapped,
+        interceptor-aware functions for both unary and streaming calls. These internal call
+        functions handle request/response validation, header manipulation, and the actual
+        network communication.
+
+        Args:
+            pool: The asynchronous connection pool to use for HTTP requests.
+            url: The full URL of the RPC method.
+            input: The expected type of the request message object.
+            output: The expected type of the response message object.
+            options: Optional client configuration.
+        """
+        options = options or ClientOptions()
+        config = ClientConfig(url, options)
+        self.config = config
+
+        protocol_client = config.protocol.client(
+            ProtocolClientParams(
+                pool=pool,
+                codec=config.codec,
+                url=config.url,
+                compression_name=config.request_compression_name,
+                compressions=config.compressions,
+                compress_min_bytes=config.compress_min_bytes,
+                read_max_bytes=config.read_max_bytes,
+                send_max_bytes=config.send_max_bytes,
+                enable_get=config.enable_get,
+            )
+        )
+        self.protocol_client = protocol_client
+
+        unary_spec = config.spec(StreamType.Unary)
+
+        async def _unary_func(request: UnaryRequest[T_Request], call_options: CallOptions) -> UnaryResponse[T_Response]:
+            conn = protocol_client.conn(unary_spec, request.headers)
+
+            def on_request_send(r: httpcore.Request) -> None:
+                method = r.method
+                try:
+                    request.method = method.decode("ascii")
+                except UnicodeDecodeError as e:
+                    raise TypeError(f"method must be ascii encoded: {method!r}") from e
+
+            conn.on_request_send(on_request_send)
+
+            await conn.send(aiterate([request.message]), call_options.timeout, abort_event=call_options.abort_event)
+
+            response = await receive_unary_response(conn=conn, t=output, abort_event=call_options.abort_event)
+            return response
+
+        unary_func = apply_interceptors(_unary_func, options.interceptors)
+
+        async def call_unary(
+            request: UnaryRequest[T_Request], call_options: CallOptions | None
+        ) -> UnaryResponse[T_Response]:
+            request.spec = unary_spec
+            request.peer = protocol_client.peer
+            protocol_client.write_request_headers(StreamType.Unary, request.headers)
+
+            call_options = call_options or CallOptions()
+
+            if not isinstance(request.message, input):
+                raise ConnectError(
+                    f"expected request of type: {input.__name__}",
+                    Code.INTERNAL,
+                )
+
+            response = await unary_func(request, call_options)
+
+            if not isinstance(response.message, output):
+                raise ConnectError(
+                    f"expected response of type: {output.__name__}",
+                    Code.INTERNAL,
+                )
+
+            return response
+
+        async def _stream_func(
+            request: StreamRequest[T_Request], call_options: CallOptions
+        ) -> StreamResponse[T_Response]:
+            conn = protocol_client.conn(request.spec, request.headers)
+
+            def on_request_send(r: httpcore.Request) -> None:
+                method = r.method
+                try:
+                    request.method = method.decode("ascii")
+                except UnicodeDecodeError as e:
+                    raise TypeError(f"method must be ascii encoded: {method!r}") from e
+
+            conn.on_request_send(on_request_send)
+
+            await conn.send(request.messages, call_options.timeout, call_options.abort_event)
+
+            response = await receive_stream_response(conn, output, request.spec, call_options.abort_event)
+            return response
+
+        stream_func = apply_interceptors(_stream_func, options.interceptors)
+
+        async def call_stream(
+            stream_type: StreamType, request: StreamRequest[T_Request], call_options: CallOptions | None
+        ) -> StreamResponse[T_Response]:
+            request.spec = config.spec(stream_type)
+            request.peer = protocol_client.peer
+            protocol_client.write_request_headers(stream_type, request.headers)
+
+            call_options = call_options or CallOptions()
+
+            return await stream_func(request, call_options)
+
+        self._call_unary = call_unary
+        self._call_stream = call_stream
+
+    async def call_unary(
+        self, request: UnaryRequest[T_Request], call_options: CallOptions | None = None
+    ) -> UnaryResponse[T_Response]:
+        """Calls a unary RPC method.
+
+        This method sends a single request to the server and receives a single
+        response. It is a simple request-response pattern.
+
+        Args:
+            request: The unary request object containing the message to be sent.
+            call_options: Optional configuration for the call, such as timeouts
+                or metadata.
+
+        Returns:
+            An awaitable that resolves to the unary response from the server.
+        """
+        return await self._call_unary(request, call_options)
+
+    @contextlib.asynccontextmanager
+    async def call_server_stream(
+        self, request: StreamRequest[T_Request], call_options: CallOptions | None = None
+    ) -> AsyncGenerator[StreamResponse[T_Response]]:
+        """Calls a server-streaming RPC.
+
+        Args:
+            request (StreamRequest[T_Request]): The request object for the RPC.
+            call_options (CallOptions | None): Optional call options for the RPC.
+
+        Yields:
+            AsyncGenerator[StreamResponse[T_Response]]: An asynchronous generator that yields
+            the response stream object. The caller is responsible for iterating over this
+            object to receive messages from the server. The stream is automatically closed
+            when the generator context is exited.
+        """
+        response = await self._call_stream(StreamType.ServerStream, request, call_options)
+        try:
+            yield response
+        finally:
+            await response.aclose()
+
+    @contextlib.asynccontextmanager
+    async def call_client_stream(
+        self, request: StreamRequest[T_Request], call_options: CallOptions | None = None
+    ) -> AsyncGenerator[StreamResponse[T_Response]]:
+        """Initiates a client-streaming RPC.
+
+        In a client-streaming RPC, the client sends a sequence of messages to the
+        server using a provided stream. Once the client has finished writing the
+        messages, it waits for the server to read them and return a single response.
+
+        This method returns an async generator that yields a single `StreamResponse`
+        object. The generator pattern is used to ensure that the underlying stream
+        is properly closed after use. You should use this method in an `async for`
+        loop to correctly manage the stream's lifecycle.
+
+        Args:
+            request: The `StreamRequest` object, which includes the RPC method
+                and an async iterable of request messages to be sent.
+            call_options: Optional configuration for the call, such as timeout
+                or metadata.
+
+        Yields:
+            A single `StreamResponse` object that can be used to receive the
+            server's final response message.
+        """
+        response = await self._call_stream(StreamType.ClientStream, request, call_options)
+        try:
+            yield response
+        finally:
+            await response.aclose()
+
+    @contextlib.asynccontextmanager
+    async def call_bidi_stream(
+        self, request: StreamRequest[T_Request], call_options: CallOptions | None = None
+    ) -> AsyncGenerator[StreamResponse[T_Response]]:
+        """Calls a bidirectional streaming method.
+
+        This method initiates a bidirectional streaming call and returns an async generator
+        that yields a single `StreamResponse` object. The caller is then responsible for
+        iterating over the yielded `StreamResponse` to receive the response messages from
+        the server.
+
+        The stream is automatically closed when the context manager exits.
+
+        Args:
+            request (StreamRequest[T_Request]): The request object, containing the
+                method details and an async iterable of request messages.
+            call_options (CallOptions | None): Optional call-specific configurations.
+
+        Yields:
+            StreamResponse[T_Response]: An async iterable response object that can be
+            iterated over to receive messages from the server.
+        """
+        response = await self._call_stream(StreamType.BiDiStream, request, call_options)
+        try:
+            yield response
+        finally:
+            await response.aclose()