grpc-server-kit 0.1.0__tar.gz → 0.2.0__tar.gz

{grpc_server_kit-0.1.0 → grpc_server_kit-0.2.0}/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## [0.2.0](https://github.com/bedrock-python/grpc-server-kit/compare/grpc-server-kit-v0.1.1...grpc-server-kit-v0.2.0) (2026-09-14)
+
+
+### ⚠ BREAKING CHANGES
+
+* `BaseGrpcServerSettings(port=0)` now raises `ValidationError`; pass `allow_ephemeral_port=True` (or `GRPC__ALLOW_EPHEMERAL_PORT=true`) to bind an ephemeral port on purpose.
+
+### Features
+
+* BaseGrpcServerSettings rejects port=0 unless allow_ephemeral_port=True ([4a450e4](https://github.com/bedrock-python/grpc-server-kit/commit/4a450e4dbc7ffe0a7d5fd107e9b2d0e7e2c2d279)), closes [#24](https://github.com/bedrock-python/grpc-server-kit/issues/24)
+
+## [0.1.1](https://github.com/bedrock-python/grpc-server-kit/compare/grpc-server-kit-v0.1.0...grpc-server-kit-v0.1.1) (2026-09-06)
+
+
+### Bug Fixes
+
+* missing exports, context skip_methods, and compression "none" ([#17](https://github.com/bedrock-python/grpc-server-kit/issues/17)) ([9c70e9d](https://github.com/bedrock-python/grpc-server-kit/commit/9c70e9db467f8fc3c25c2426c98869b22a3ce0aa))
+
 ## 0.1.0 (2026-08-11)
 
 Initial release of grpc-server-kit.

{grpc_server_kit-0.1.0 → grpc_server_kit-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: grpc-server-kit
-Version: 0.1.0
+Version: 0.2.0
 Summary: Batteries-optional async gRPC server toolkit (app facade, builder, TLS, lifecycle, health, streaming-aware interceptors, observability)
 Project-URL: Repository, https://github.com/bedrock-python/grpc-server-kit
 Project-URL: Documentation, https://bedrock-python.github.io/grpc-server-kit/
@@ -277,6 +277,16 @@ Dishka DI, and typed pydantic settings.
 The core depends only on `grpcio`. Every integration is an opt-in extra, so you
 install exactly what you use.
 
+> [!TIP]
+> **Building this with an AI assistant?** Hand it
+> **[one page](https://bedrock-python.github.io/grpc-server-kit/agents/)** instead of
+> the whole site: the complete API surface, the ordering rules that break a server when
+> they are broken (build-then-configure, outermost-first interceptors, Sentry inside the
+> exception handler), the mistakes models actually make with `grpc.aio`, and a map of
+> which page to fetch for the rest. Every docs page is also served as raw Markdown at its
+> own URL, and a **Copy page** button at the top of each one hands it straight to a chat
+> window.
+
 ## Installation
 
 ```bash
@@ -479,6 +489,10 @@ Runnable, self-contained scripts in [`examples/`](examples/) — each prints wha
 
 Full documentation at [bedrock-python.github.io/grpc-server-kit](https://bedrock-python.github.io/grpc-server-kit/).
 
+- [For AI agents](https://bedrock-python.github.io/grpc-server-kit/agents/) — the whole
+  API surface, the rules that break a server when broken and a map of the rest, on one
+  page to hand to a coding assistant
+
 ## License
 
 Apache 2.0 — see [LICENSE](LICENSE).

{grpc_server_kit-0.1.0 → grpc_server_kit-0.2.0}/README.md

@@ -19,6 +19,16 @@ Dishka DI, and typed pydantic settings.
 The core depends only on `grpcio`. Every integration is an opt-in extra, so you
 install exactly what you use.
 
+> [!TIP]
+> **Building this with an AI assistant?** Hand it
+> **[one page](https://bedrock-python.github.io/grpc-server-kit/agents/)** instead of
+> the whole site: the complete API surface, the ordering rules that break a server when
+> they are broken (build-then-configure, outermost-first interceptors, Sentry inside the
+> exception handler), the mistakes models actually make with `grpc.aio`, and a map of
+> which page to fetch for the rest. Every docs page is also served as raw Markdown at its
+> own URL, and a **Copy page** button at the top of each one hands it straight to a chat
+> window.
+
 ## Installation
 
 ```bash
@@ -221,6 +231,10 @@ Runnable, self-contained scripts in [`examples/`](examples/) — each prints wha
 
 Full documentation at [bedrock-python.github.io/grpc-server-kit](https://bedrock-python.github.io/grpc-server-kit/).
 
+- [For AI agents](https://bedrock-python.github.io/grpc-server-kit/agents/) — the whole
+  API surface, the rules that break a server when broken and a map of the rest, on one
+  page to hand to a coding assistant
+
 ## License
 
 Apache 2.0 — see [LICENSE](LICENSE).

{grpc_server_kit-0.1.0 → grpc_server_kit-0.2.0}/grpc_server_kit/__init__.py

@@ -10,6 +10,7 @@ from .protocols import (
     GrpcAsyncServerProtocol,
     GrpcServerProtocol,
     GrpcServerSettingsProtocol,
+    GrpcServiceName,
     GrpcSettingsProtocol,
     GrpcSslSettingsProtocol,
 )
@@ -23,6 +24,7 @@ __all__ = [
     "GrpcServerConfig",
     "GrpcServerProtocol",
     "GrpcServerSettingsProtocol",
+    "GrpcServiceName",
     "GrpcSettingsProtocol",
     "GrpcSslSettingsProtocol",
     "__version__",

grpc_server_kit-0.2.0/grpc_server_kit/__version__.py

@@ -0,0 +1 @@
+__version__ = "0.2.0"

{grpc_server_kit-0.1.0 → grpc_server_kit-0.2.0}/grpc_server_kit/aio/__init__.py

@@ -7,11 +7,17 @@ from ..protocols import (
     GrpcAsyncServerProtocol,
     GrpcServerProtocol,
     GrpcServerSettingsProtocol,
+    GrpcServiceName,
     GrpcSettingsProtocol,
     GrpcSslSettingsProtocol,
 )
 from ..server import bind_server_port
-from ..signals import reset_signal_handlers, setup_signal_handlers
+from ..signals import (
+    SignalManager,
+    reset_signal_handlers,
+    reset_signal_handlers_async,
+    setup_signal_handlers,
+)
 from .app import GrpcApp
 from .builder import AsyncGrpcServerBuilder
 from .runtime import ServerLifecycleManager, run_async_grpc_server
@@ -30,15 +36,18 @@ __all__ = [
     "GrpcServerConfig",
     "GrpcServerProtocol",
     "GrpcServerSettingsProtocol",
+    "GrpcServiceName",
     "GrpcSettingsProtocol",
     "GrpcSslSettingsProtocol",
     "ServerLifecycleManager",
+    "SignalManager",
     "bind_server_port",
     "build_grpc_options",
     "create_async_grpc_server",
     "create_base_async_grpc_server",
     "load_server_credentials",
     "reset_signal_handlers",
+    "reset_signal_handlers_async",
     "run_async_grpc_server",
     "setup_signal_handlers",
 ]

{grpc_server_kit-0.1.0 → grpc_server_kit-0.2.0}/grpc_server_kit/aio/interceptors/context.py

@@ -12,7 +12,7 @@ from .base import AsyncServerInterceptor, RpcCall
 from .metadata import get_metadata_dict
 
 if TYPE_CHECKING:
-    from collections.abc import AsyncIterator, Callable
+    from collections.abc import AsyncIterator, Callable, Collection
 
     import structlog
 else:
@@ -62,6 +62,8 @@ class AsyncContextInterceptor(AsyncServerInterceptor):
         bind_method_name: bool = True,
         bind_structlog: bool = True,
         method_key: str = "grpc_method",
+        *,
+        skip_methods: Collection[str] = (),
     ) -> None:
         """Initialize interceptor with header configurations.
 
@@ -71,8 +73,13 @@ class AsyncContextInterceptor(AsyncServerInterceptor):
             bind_structlog: Whether to bind extracted variables to structlog context
                 (no-op if structlog is not installed).
             method_key: Key for the gRPC method name in context.
+            skip_methods: Full RPC method names to leave unwrapped. Empty by
+                default — unlike the observability interceptors, this one binds
+                values the handler itself may read, so nothing is skipped
+                unless you say so. Pass ``SKIPPED_HEALTH_METHODS`` to keep
+                health probes out (required headers included).
         """
-        super().__init__()
+        super().__init__(skip_methods=skip_methods)
         self._header_configs = header_configs
         self._bind_method_name = bind_method_name
         self._bind_structlog = bind_structlog

{grpc_server_kit-0.1.0 → grpc_server_kit-0.2.0}/grpc_server_kit/settings.py

@@ -30,7 +30,10 @@ from grpc_server_kit.constants import (
     DEFAULT_PORT,
 )
 
-GrpcCompressionAlgorithm = Literal["deflate", "gzip"]
+# Mirrors the keys of ``grpc_server_kit.options.COMPRESSION_ALGORITHMS``:
+# "none" is gRPC's explicit no-compression algorithm, not the absence of a
+# setting (that is ``None``).
+GrpcCompressionAlgorithm = Literal["none", "deflate", "gzip"]
 
 
 class BaseHealthSettings(BaseModel):
@@ -59,6 +62,10 @@ class BaseGrpcServerSettings(BaseModel):
     # Basic
     host: str = Field(default=DEFAULT_HOST, min_length=1, description="gRPC server host")
     port: int = Field(default=DEFAULT_PORT, ge=0, le=65535, description="gRPC server port (0 = ephemeral)")
+    allow_ephemeral_port: bool = Field(
+        default=False,
+        description="Accept port=0 (ephemeral); off by default, a Service targeting a fixed port cannot reach one",
+    )
 
     # TLS/SSL settings
     ssl_enabled: bool = Field(default=False, description="Enable TLS/SSL")
@@ -106,7 +113,7 @@ class BaseGrpcServerSettings(BaseModel):
     # Compression
     compression_algorithm: GrpcCompressionAlgorithm | None = Field(
         default=None,
-        description="Default compression: deflate or gzip (None = no compression)",
+        description="Default compression: none, deflate or gzip (None = leave the gRPC default alone)",
     )
 
     # Flow control settings
@@ -132,6 +139,15 @@ class BaseGrpcServerSettings(BaseModel):
     # Health (consumed by GrpcApp.enable_health as its defaults)
     health: BaseHealthSettings = Field(default_factory=BaseHealthSettings, description="Health check configuration")
 
+    @model_validator(mode="after")
+    def _validate_port(self) -> "BaseGrpcServerSettings":
+        if self.port == 0 and not self.allow_ephemeral_port:
+            raise ValueError(
+                "gRPC port=0 binds an ephemeral port and a Service targeting a fixed port will not reach this "
+                "process; set allow_ephemeral_port=True if that is intended"
+            )
+        return self
+
     @model_validator(mode="after")
     def _validate_ssl(self) -> "BaseGrpcServerSettings":
         if self.ssl_enabled:

{grpc_server_kit-0.1.0 → grpc_server_kit-0.2.0}/pyproject.toml

@@ -122,6 +122,10 @@ warn_unreachable = true
 [tool.ruff]
 line-length = 120
 target-version = "py312"
+# The Markdown guides hold fragments -- a keyword argument on its own, a body
+# without its def -- that read as code to a formatter and come out as
+# something else. ruff 0.16 formats fenced Python in Markdown by default.
+extend-exclude = ["*.md"]
 
 [tool.ruff.lint]
 select = ["F", "E", "W", "I", "B", "N", "S", "C4", "DTZ", "SIM", "TRY", "PERF", "RUF", "UP", "ANN", "T20", "PTH", "PLC", "PLE", "PLW"]

grpc_server_kit-0.1.0/grpc_server_kit/__version__.py

@@ -1 +0,0 @@
-__version__ = "0.1.0"