fastgrpc2 0.2.0__tar.gz

fastgrpc2-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ruslan Kiradiev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fastgrpc2-0.2.0/PKG-INFO

@@ -0,0 +1,110 @@
+Metadata-Version: 2.4
+Name: fastgrpc2
+Version: 0.2.0
+Summary: FastAPI-like developer experience for gRPC: pydantic-first, async, built on grpc.aio
+Author: Ruslan Kiradiev
+License-Expression: MIT
+Keywords: grpc,async,fastapi,pydantic,microservices,rpc
+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: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Distributed Computing
+Classifier: Framework :: AsyncIO
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic>=2
+Requires-Dist: grpcio>=1.60
+Requires-Dist: protobuf>=4.21
+Requires-Dist: typing-extensions>=4.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Dynamic: license-file
+
+# fastgrpc2
+
+FastAPI-подобная эргономика для gRPC. Pydantic на входе и выходе, вся механика
+`grpc.aio` — внутри. Сестра [fastkafka2](../fastkafka2): тот же стиль `App` /
+группа / декораторы / lifespan, но для gRPC.
+
+Стек — чистый Python на `grpc.aio` (C-ядро gRPC + upb + pydantic-core). Это
+тонкий эргономичный слой, не новый транспорт: потолок = `grpc.aio`, цена —
+FastAPI-стиль, а не скорость компилируемых языков.
+
+## Пример
+
+Сервер:
+
+```python
+from pydantic import BaseModel
+from fastgrpc2 import GrpcApp, GrpcService, Context, Depends, GrpcError, StatusCode
+
+class GetOrderRequest(BaseModel):
+    order_number: str
+
+class OrderReply(BaseModel):
+    order_number: str
+    status: str
+
+service = GrpcService("Orders")
+
+@service.unary("GetOrder")
+async def get_order(request: GetOrderRequest, ctx: Context) -> OrderReply:
+    if not request.order_number:
+        raise GrpcError(StatusCode.INVALID_ARGUMENT, "order_number required")
+    return OrderReply(order_number=request.order_number, status="paid")
+
+app = GrpcApp("orders", address="0.0.0.0:50051")
+app.add_service(service)
+# await app.run()
+```
+
+Клиент:
+
+```python
+from fastgrpc2 import GrpcClient, Channel
+
+class OrderClient(GrpcClient):
+    service = "Orders"
+    get_order = GrpcClient.unary("GetOrder", GetOrderRequest, OrderReply)
+
+async with Channel("127.0.0.1:50051", default_timeout=5.0) as ch:
+    client = OrderClient(ch)
+    reply = await client.get_order(GetOrderRequest(order_number="A-100"))
+    print(reply.status)  # -> "paid"
+```
+
+## Статус (v0.2) — v1-скоуп закрыт, всё проверено прогоном
+
+- **4 типа вызовов**: `@service.unary` / `unary_stream` / `stream_unary` / `stream_stream`.
+- **codec pydantic↔protobuf**: динамические дескрипторы; `bool/int/float/str/bytes`,
+  вложенные `BaseModel`, `list[...]`, `Optional[...]` (с proto3-presence). Не
+  поддержанное (enum/dict/datetime/Union) — явный `TypeError`, не заглушка.
+- **`export_proto()`** — .proto-контракт из моделей.
+- **Context**: metadata, deadline (`time_remaining`), trailing-metadata, peer.
+- **Metadata** multimap; **GrpcError + StatusCode** + rich-детали (`BadRequest`/
+  `ErrorInfo`, через `grpc-status-details-bin`).
+- **Клиент**: `Channel` (переиспользуемый) + типизированный `GrpcClient`,
+  per-call `timeout`/`metadata`.
+- **Безопасность**: `TLS` / `MTLS` / `Insecure` / `BearerToken`.
+- **Интерсепторы** (pre-hook auth/логирование), **`Depends` + `dependency_overrides`**.
+- **Lifespan**, **graceful `stop(grace)`**, **`run()`**.
+- **`enable_health()`** (grpc.health.v1), **`TestClient`** (in-process).
+- **Ручки**: `Compression`, `max_send_bytes`/`max_recv_bytes`, `RetryPolicy`,
+  `Keepalive`; **deadline-propagation** по цепочке.
+
+Проверочные прогоны (из корня пакета): `smoke_test.py` (вызовы/presence/rich-errors),
+`features_test.py` (TestClient/health/bearer/overrides), `tls_test.py` (mTLS),
+`config_test.py` (compression/size/interceptor/deadline), `bench.py` (клей-налог
+над голым grpc.aio — единицы %).
+
+Later (не v1): write()/done_writing() для bidi-клиента, server reflection, OTel,
+Connect/gRPC-Web, отмена-propagation, полный набор 10 google.rpc деталей с
+google-namespace type_url.

fastgrpc2-0.2.0/README.md

@@ -0,0 +1,80 @@
+# fastgrpc2
+
+FastAPI-подобная эргономика для gRPC. Pydantic на входе и выходе, вся механика
+`grpc.aio` — внутри. Сестра [fastkafka2](../fastkafka2): тот же стиль `App` /
+группа / декораторы / lifespan, но для gRPC.
+
+Стек — чистый Python на `grpc.aio` (C-ядро gRPC + upb + pydantic-core). Это
+тонкий эргономичный слой, не новый транспорт: потолок = `grpc.aio`, цена —
+FastAPI-стиль, а не скорость компилируемых языков.
+
+## Пример
+
+Сервер:
+
+```python
+from pydantic import BaseModel
+from fastgrpc2 import GrpcApp, GrpcService, Context, Depends, GrpcError, StatusCode
+
+class GetOrderRequest(BaseModel):
+    order_number: str
+
+class OrderReply(BaseModel):
+    order_number: str
+    status: str
+
+service = GrpcService("Orders")
+
+@service.unary("GetOrder")
+async def get_order(request: GetOrderRequest, ctx: Context) -> OrderReply:
+    if not request.order_number:
+        raise GrpcError(StatusCode.INVALID_ARGUMENT, "order_number required")
+    return OrderReply(order_number=request.order_number, status="paid")
+
+app = GrpcApp("orders", address="0.0.0.0:50051")
+app.add_service(service)
+# await app.run()
+```
+
+Клиент:
+
+```python
+from fastgrpc2 import GrpcClient, Channel
+
+class OrderClient(GrpcClient):
+    service = "Orders"
+    get_order = GrpcClient.unary("GetOrder", GetOrderRequest, OrderReply)
+
+async with Channel("127.0.0.1:50051", default_timeout=5.0) as ch:
+    client = OrderClient(ch)
+    reply = await client.get_order(GetOrderRequest(order_number="A-100"))
+    print(reply.status)  # -> "paid"
+```
+
+## Статус (v0.2) — v1-скоуп закрыт, всё проверено прогоном
+
+- **4 типа вызовов**: `@service.unary` / `unary_stream` / `stream_unary` / `stream_stream`.
+- **codec pydantic↔protobuf**: динамические дескрипторы; `bool/int/float/str/bytes`,
+  вложенные `BaseModel`, `list[...]`, `Optional[...]` (с proto3-presence). Не
+  поддержанное (enum/dict/datetime/Union) — явный `TypeError`, не заглушка.
+- **`export_proto()`** — .proto-контракт из моделей.
+- **Context**: metadata, deadline (`time_remaining`), trailing-metadata, peer.
+- **Metadata** multimap; **GrpcError + StatusCode** + rich-детали (`BadRequest`/
+  `ErrorInfo`, через `grpc-status-details-bin`).
+- **Клиент**: `Channel` (переиспользуемый) + типизированный `GrpcClient`,
+  per-call `timeout`/`metadata`.
+- **Безопасность**: `TLS` / `MTLS` / `Insecure` / `BearerToken`.
+- **Интерсепторы** (pre-hook auth/логирование), **`Depends` + `dependency_overrides`**.
+- **Lifespan**, **graceful `stop(grace)`**, **`run()`**.
+- **`enable_health()`** (grpc.health.v1), **`TestClient`** (in-process).
+- **Ручки**: `Compression`, `max_send_bytes`/`max_recv_bytes`, `RetryPolicy`,
+  `Keepalive`; **deadline-propagation** по цепочке.
+
+Проверочные прогоны (из корня пакета): `smoke_test.py` (вызовы/presence/rich-errors),
+`features_test.py` (TestClient/health/bearer/overrides), `tls_test.py` (mTLS),
+`config_test.py` (compression/size/interceptor/deadline), `bench.py` (клей-налог
+над голым grpc.aio — единицы %).
+
+Later (не v1): write()/done_writing() для bidi-клиента, server reflection, OTel,
+Connect/gRPC-Web, отмена-propagation, полный набор 10 google.rpc деталей с
+google-namespace type_url.

fastgrpc2-0.2.0/fastgrpc2/__init__.py

@@ -0,0 +1,39 @@
+"""fastgrpc2 — FastAPI-подобная эргономика для gRPC.
+
+Pydantic на входе и выходе, вся механика grpc.aio — внутри. Юзер пишет
+голые pydantic-модели и async-функции и не трогает grpc/_pb2/ServicerContext.
+"""
+from .app import GrpcApp
+from .service import GrpcService
+from .context import Context
+from .dependencies import Depends
+from .client import Channel, GrpcClient
+from .config import Compression, Keepalive, RetryPolicy
+from .errors import BadRequest, ErrorInfo, FieldViolation, GrpcError, StatusCode, register_detail
+from .metadata import Metadata
+from .security import BearerToken, Insecure, MTLS, TLS
+
+__all__ = [
+    "GrpcApp",
+    "GrpcService",
+    "Context",
+    "Depends",
+    "Channel",
+    "GrpcClient",
+    "GrpcError",
+    "StatusCode",
+    "Metadata",
+    "TLS",
+    "MTLS",
+    "Insecure",
+    "BearerToken",
+    "ErrorInfo",
+    "BadRequest",
+    "FieldViolation",
+    "register_detail",
+    "Compression",
+    "RetryPolicy",
+    "Keepalive",
+]
+
+__version__ = "0.2.0"

fastgrpc2-0.2.0/fastgrpc2/app.py

@@ -0,0 +1,110 @@
+"""GrpcApp — приложение/сервер (аналог KafkaApp в fastkafka2, FastAPI в REST).
+
+Сервисы, grpc.aio.server, lifespan, graceful-stop, health, интерсепторы.
+TLS/mTLS — tls=TLS(...)/MTLS(...); по умолчанию insecure (dev).
+Ручки: max_send_bytes/max_recv_bytes, compression, keepalive.
+add_interceptor(fn) — pre-hook (auth/logging) перед каждым хендлером.
+dependency_overrides — подмена Depends (тесты). export_proto() — .proto-контракт.
+"""
+from __future__ import annotations
+
+from typing import Awaitable, Callable
+
+import grpc
+import grpc.aio
+
+from . import codec, config, security
+from .context import Context
+from .health import HealthService
+from .service import GrpcService
+
+
+class GrpcApp:
+    def __init__(
+        self,
+        title: str = "",
+        description: str = "",
+        *,
+        address: str = "0.0.0.0:50051",
+        tls=None,
+        compression=None,
+        max_send_bytes: int | None = None,
+        max_recv_bytes: int | None = None,
+        keepalive=None,
+        lifespan: Callable[["GrpcApp"], object] | None = None,
+    ) -> None:
+        self.title = title
+        self.description = description
+        self.address = address
+        self.tls = tls
+        self.compression = compression
+        self.max_send_bytes = max_send_bytes
+        self.max_recv_bytes = max_recv_bytes
+        self.keepalive = keepalive
+        self.dependency_overrides: dict = {}
+        self.bound_port: int | None = None
+        self._interceptors: list[Callable[[Context], Awaitable[None]]] = []
+        self._lifespan_func = lifespan
+        self._lifespan_cm = None
+        self._services: list[GrpcService] = []
+        self._health: HealthService | None = None
+        self._server: grpc.aio.Server | None = None
+
+    def add_service(self, service: GrpcService) -> None:
+        self._services.append(service)
+
+    include_service = add_service  # alias под доктрину include_*
+
+    def add_interceptor(self, interceptor: Callable[[Context], Awaitable[None]]) -> None:
+        """Pre-hook перед каждым хендлером (любого типа): auth/логирование.
+        Бросает GrpcError -> отказ. Порядок = порядок добавления."""
+        self._interceptors.append(interceptor)
+
+    def enable_health(self) -> HealthService:
+        """grpc.health.v1.Health (k8s/LB-пробы). overall=SERVING после старта."""
+        self._health = HealthService()
+        return self._health
+
+    def export_proto(self) -> str:
+        return codec.render_proto(self._services)
+
+    async def start(self) -> None:
+        if self._lifespan_func is not None:
+            self._lifespan_cm = self._lifespan_func(self)
+            await self._lifespan_cm.__aenter__()
+
+        options = config.channel_options(self.max_send_bytes, self.max_recv_bytes, None, self.keepalive) or None
+        self._server = grpc.aio.server(options=options, compression=self.compression)
+
+        interceptors = tuple(self._interceptors)
+        for svc in self._services:
+            self._server.add_generic_rpc_handlers([svc._generic_handler(self.dependency_overrides, interceptors)])
+        if self._health is not None:
+            self._server.add_generic_rpc_handlers([self._health._generic_handler()])
+
+        if security.is_secure(self.tls):
+            self.bound_port = self._server.add_secure_port(self.address, security.server_credentials(self.tls))
+        else:
+            self.bound_port = self._server.add_insecure_port(self.address)
+
+        await self._server.start()
+        if self._health is not None:
+            self._health.set_serving("")
+
+    async def stop(self, grace: float | None = None) -> None:
+        if self._server is not None:
+            await self._server.stop(grace)
+            self._server = None
+        if self._lifespan_cm is not None:
+            await self._lifespan_cm.__aexit__(None, None, None)
+            self._lifespan_cm = None
+
+    async def run(self) -> None:
+        await self.start()
+        try:
+            await self._server.wait_for_termination()
+        finally:
+            await self.stop()
+
+
+__all__ = ["GrpcApp"]

fastgrpc2-0.2.0/fastgrpc2/client.py

@@ -0,0 +1,177 @@
+"""Клиент: Channel (переиспользуемое соединение) + типизированный GrpcClient.
+
+Все 4 типа вызова как дескрипторы-методы:
+    get_order = GrpcClient.unary("GetOrder", Req, Resp)          await -> Resp
+    watch     = GrpcClient.unary_stream("Watch", Req, Ev)        async for ev in ...
+    upload    = GrpcClient.stream_unary("Upload", Sample, Sum)   await(aiter) -> Sum
+    chat      = GrpcClient.stream_stream("Chat", In, Out)        async for out in ...(aiter)
+
+Канал держим один и шарим между вызовами. v0.1: insecure. TLS/mTLS, .call()
+с доступом к metadata/трейлерам, write()/done_writing() для bidi — later.
+"""
+from __future__ import annotations
+
+import grpc
+import grpc.aio
+
+from . import codec, config, security
+from .deadline import get_budget
+from .errors import TRAILER_KEY, GrpcError, unpack_details
+from .metadata import Metadata
+
+
+def _to_grpc_error(e: grpc.aio.AioRpcError) -> GrpcError:
+    details: list = []
+    try:
+        for k, v in e.trailing_metadata() or ():
+            if k == TRAILER_KEY:
+                details = unpack_details(v if isinstance(v, (bytes, bytearray)) else bytes(v))
+    except Exception:
+        pass
+    return GrpcError(e.code(), e.details(), details)
+
+
+class Channel:
+    def __init__(
+        self,
+        target: str,
+        *,
+        default_timeout: float | None = None,
+        tls=None,
+        auth=None,
+        compression=None,
+        max_send_bytes: int | None = None,
+        max_recv_bytes: int | None = None,
+        retry=None,
+        keepalive=None,
+    ) -> None:
+        self.target = target
+        self.default_timeout = default_timeout
+        self.auth = auth
+        options = config.channel_options(max_send_bytes, max_recv_bytes, retry, keepalive) or None
+        if security.is_secure(tls):
+            self._channel = grpc.aio.secure_channel(
+                target, security.channel_credentials(tls), options=options, compression=compression
+            )
+        else:
+            self._channel = grpc.aio.insecure_channel(target, options=options, compression=compression)
+
+    async def close(self, grace: float | None = None) -> None:
+        await self._channel.close(grace)
+
+    async def __aenter__(self) -> "Channel":
+        return self
+
+    async def __aexit__(self, *exc) -> None:
+        await self.close()
+
+
+async def _aiter_wrap(call):
+    try:
+        async for item in call:
+            yield item
+    except grpc.aio.AioRpcError as e:
+        raise _to_grpc_error(e) from e
+
+
+class _Method:
+    """Дескриптор метода клиента; kind = unary|unary_stream|stream_unary|stream_stream."""
+
+    def __init__(self, kind: str, rpc_name: str, request_model: type, response_model: type) -> None:
+        self.kind = kind
+        self.rpc_name = rpc_name
+        self.request_model = request_model
+        self.response_model = response_model
+
+    def __set_name__(self, owner, name: str) -> None:
+        self.attr = name
+
+    def __get__(self, instance, owner):
+        if instance is None:
+            return self
+        return _Bound(instance, self)
+
+
+class _Bound:
+    def __init__(self, client: "GrpcClient", method: _Method) -> None:
+        self._client = client
+        self._m = method
+
+    def _make_callable(self):
+        ch = self._client._channel._channel
+        path = f"/{self._client.full_service_name}/{self._m.rpc_name}"
+        ser = codec.serializer(self._m.request_model)
+        de = codec.deserializer(self._m.response_model)
+        factory = {
+            "unary": ch.unary_unary,
+            "unary_stream": ch.unary_stream,
+            "stream_unary": ch.stream_unary,
+            "stream_stream": ch.stream_stream,
+        }[self._m.kind]
+        return factory(path, request_serializer=ser, response_deserializer=de)
+
+    def __call__(self, request, *, timeout: float | None = None, metadata=None):
+        callable_ = self._make_callable()
+        ch = self._client._channel
+        pairs: list = []
+        if ch.auth is not None:
+            pairs.extend(ch.auth.metadata())
+        if isinstance(metadata, Metadata):
+            pairs.extend(metadata.to_grpc())
+        elif metadata:
+            pairs.extend(metadata)
+        md = pairs or None
+        to = timeout
+        if to is None:
+            to = get_budget()  # наследуем дедлайн-бюджет цепочки, если он есть
+        if to is None:
+            to = ch.default_timeout
+        if self._m.kind in ("unary_stream", "stream_stream"):
+            # стрим на выходе -> возвращаем async-итератор (его НЕ await-им, его итерируем)
+            return _aiter_wrap(callable_(request, timeout=to, metadata=md))
+        # одиночный ответ -> возвращаем корутину под await
+        return self._await(callable_, request, to, md)
+
+    async def _await(self, callable_, request, to, md):
+        try:
+            return await callable_(request, timeout=to, metadata=md)
+        except grpc.aio.AioRpcError as e:
+            raise _to_grpc_error(e) from e
+
+
+class GrpcClient:
+    """Базовый типизированный клиент. Наследник задаёт service и методы:
+
+        class OrderClient(GrpcClient):
+            service = "Orders"
+            get_order = GrpcClient.unary("GetOrder", GetOrderRequest, OrderReply)
+    """
+
+    package: str = "fastgrpc2"
+    service: str = ""
+
+    def __init__(self, channel: Channel) -> None:
+        self._channel = channel
+
+    @property
+    def full_service_name(self) -> str:
+        return f"{self.package}.{self.service}"
+
+    @staticmethod
+    def unary(rpc_name: str, request_model: type, response_model: type) -> _Method:
+        return _Method("unary", rpc_name, request_model, response_model)
+
+    @staticmethod
+    def unary_stream(rpc_name: str, request_model: type, response_model: type) -> _Method:
+        return _Method("unary_stream", rpc_name, request_model, response_model)
+
+    @staticmethod
+    def stream_unary(rpc_name: str, request_model: type, response_model: type) -> _Method:
+        return _Method("stream_unary", rpc_name, request_model, response_model)
+
+    @staticmethod
+    def stream_stream(rpc_name: str, request_model: type, response_model: type) -> _Method:
+        return _Method("stream_stream", rpc_name, request_model, response_model)
+
+
+__all__ = ["Channel", "GrpcClient"]