From edbc2a696821034fc3a1791cb55dc64ca72004f6 Mon Sep 17 00:00:00 2001 From: hideyukiMORI Date: Wed, 20 May 2026 00:20:48 +0900 Subject: [PATCH 1/2] =?UTF-8?q?docs:=20framework-modules=20=E3=83=AA?= =?UTF-8?q?=E3=83=95=E3=82=A1=E3=83=AC=E3=83=B3=E3=82=B9=E3=81=AB=E5=85=AC?= =?UTF-8?q?=E9=96=8BAPI=E3=81=AE=E6=9C=AA=E8=A8=98=E8=BC=89=E3=82=A8?= =?UTF-8?q?=E3=83=B3=E3=83=88=E3=83=AA=E3=82=92=E8=BF=BD=E5=8A=A0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit __all__ に含まれているがドキュメント化されていなかった公開 API を EN/JA 両版に追加: nene2.http: - PaginationQuery — PaginationQueryParser.parse() の戻り値型 - HealthCheckProtocol / HealthStatus — ヘルスチェック契約と結果型 nene2.database: - DatabaseHealthCheck — HealthCheckProtocol 実装、DB接続確認 - DatabaseConnectionException — DB接続不能時の例外 nene2.mcp: - McpHttpResponse — HttpxMcpClient の戻り値型（status_code / body / is_successful()） - McpHttpClientProtocol — カスタム MCP HTTP クライアントの構造的契約 Co-Authored-By: Claude Sonnet 4.6 --- docs/ja/reference/framework-modules.md | 48 ++++++++++++++++++++++++++ docs/reference/framework-modules.md | 47 +++++++++++++++++++++++++ 2 files changed, 95 insertions(+) diff --git a/docs/ja/reference/framework-modules.md b/docs/ja/reference/framework-modules.md index 1c74843..737ce47 100644 --- a/docs/ja/reference/framework-modules.md +++ b/docs/ja/reference/framework-modules.md @@ -39,6 +39,25 @@ from nene2.http import problem_details_response return problem_details_response("not-found", "Not Found", 404, "Note 42 not found.") ``` +### `PaginationQuery` + +`PaginationQueryParser.parse()` が返すデータクラス。`limit: int` と `offset: int` を持ちます。 + +### `HealthCheckProtocol` / `HealthStatus` + +ヘルスチェックの契約と結果型。 + +```python +from nene2.http import HealthCheckProtocol, HealthStatus + +class MyHealthCheck: + def check(self) -> HealthStatus: + return HealthStatus(status="ok") +``` + +`HealthStatus` フィールド: `status: str`（`"ok"` または `"error"`）、`checks: dict[str, str]`。 +`is_healthy` プロパティは `status == "ok"` のとき `True`。 + --- ## nene2.use_case @@ -283,6 +302,24 @@ class TransferUseCase: 詳細なパターンと InMemory テスト実装は [sqlalchemy-repository.md](../how-to/sqlalchemy-repository.md) を参照してください。 +### `DatabaseHealthCheck` + +`HealthCheckProtocol` を実装し、DB 接続を確認して `HealthStatus` を返します。 + +```python +from nene2.database import DatabaseHealthCheck +from nene2.http import HealthStatus + +health = DatabaseHealthCheck(engine) +status: HealthStatus = health.check() +# status.status → "ok" または "error" +# status.checks → {"db": "ok"} または {"db": "error: "} +``` + +### `DatabaseConnectionException` + +DB 接続不能時に `DatabaseHealthCheck` やリポジトリ操作から raise されます。 + --- ## nene2.mcp @@ -312,8 +349,19 @@ from nene2.mcp import HttpxMcpClient client = HttpxMcpClient("bearer-token") response = client.get("http://localhost:8080", "/notes") response.is_successful() # True +response.body # dict | list — パース済み JSON +response.status_code # int ``` +### `McpHttpResponse` + +`HttpxMcpClient` メソッドの戻り値型。フィールド: `status_code: int`、`body: dict | list`。 +メソッド: `is_successful() -> bool`（`200 ≤ status_code < 300` のとき `True`）。 + +### `McpHttpClientProtocol` + +カスタム MCP HTTP クライアントの構造的契約。`get()`・`post()`・`put()`・`delete()` を実装して `McpHttpResponse` を返します。 + --- ## nene2.log diff --git a/docs/reference/framework-modules.md b/docs/reference/framework-modules.md index fd1b34f..7423ad9 100644 --- a/docs/reference/framework-modules.md +++ b/docs/reference/framework-modules.md @@ -39,6 +39,25 @@ from nene2.http import problem_details_response return problem_details_response("not-found", "Not Found", 404, "Note 42 not found.") ``` +### `PaginationQuery` + +Dataclass returned by `PaginationQueryParser.parse()`. Contains `limit: int` and `offset: int`. + +### `HealthCheckProtocol` / `HealthStatus` + +Contract and result type for application health checks. + +```python +from nene2.http import HealthCheckProtocol, HealthStatus + +class MyHealthCheck: + def check(self) -> HealthStatus: + return HealthStatus(status="ok") +``` + +`HealthStatus` fields: `status: str` (`"ok"` or `"error"`), `checks: dict[str, str]`. +`is_healthy` property returns `True` when `status == "ok"`. + --- ## nene2.use_case @@ -328,6 +347,24 @@ class TransferUseCase: **Testing with InMemory:** Implement `DatabaseTransactionManagerInterface` with a no-op executor that calls the callback directly. The `_in_tx` methods on the InMemory repository ignore the executor and operate on their in-memory store. +### `DatabaseHealthCheck` + +Implements `HealthCheckProtocol` — verifies the database connection and returns a `HealthStatus`. + +```python +from nene2.database import DatabaseHealthCheck +from nene2.http import HealthStatus + +health = DatabaseHealthCheck(engine) +status: HealthStatus = health.check() +# status.status → "ok" or "error" +# status.checks → {"db": "ok"} or {"db": "error: "} +``` + +### `DatabaseConnectionException` + +Raised by `DatabaseHealthCheck` or repository operations when the database is unreachable. + --- ## nene2.mcp @@ -357,8 +394,18 @@ from nene2.mcp import HttpxMcpClient client = HttpxMcpClient("bearer-token") response = client.get("http://localhost:8080", "/notes") response.is_successful() # True +response.body # dict | list — parsed JSON +response.status_code # int ``` +### `McpHttpResponse` + +Return type of `HttpxMcpClient` methods. Fields: `status_code: int`, `body: dict | list`. Method: `is_successful() -> bool` (`True` when `200 ≤ status_code < 300`). + +### `McpHttpClientProtocol` + +Structural contract for custom MCP HTTP clients. Implement `get()`, `post()`, `put()`, `delete()` returning `McpHttpResponse`. + --- ## nene2.log From 285577512d3918579551024f531ef33e7e875d22 Mon Sep 17 00:00:00 2001 From: hideyukiMORI Date: Wed, 20 May 2026 00:40:02 +0900 Subject: [PATCH 2/2] =?UTF-8?q?docs:=20McpHttpResponse=20=E3=81=AE=20body?= =?UTF-8?q?=20=E5=9E=8B=E8=AA=A4=E8=A8=98=E3=82=92=E4=BF=AE=E6=AD=A3=20(#1?= =?UTF-8?q?07)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - body: dict | list → body: str（生のレスポンステキスト）に修正 - headers: dict[str, str] フィールドを追記 - request_id() -> str | None メソッドを追記 - McpHttpClientProtocol に has_authentication() を追記 - EN / JA 両ドキュメントに適用 Co-Authored-By: Claude Sonnet 4.6 --- docs/ja/reference/framework-modules.md | 14 ++++++++++---- docs/reference/framework-modules.md | 13 ++++++++++--- 2 files changed, 20 insertions(+), 7 deletions(-) diff --git a/docs/ja/reference/framework-modules.md b/docs/ja/reference/framework-modules.md index 737ce47..ea10458 100644 --- a/docs/ja/reference/framework-modules.md +++ b/docs/ja/reference/framework-modules.md @@ -349,18 +349,24 @@ from nene2.mcp import HttpxMcpClient client = HttpxMcpClient("bearer-token") response = client.get("http://localhost:8080", "/notes") response.is_successful() # True -response.body # dict | list — パース済み JSON +response.body # str — 生のレスポンステキスト response.status_code # int +response.request_id() # str | None — X-Request-ID ヘッダーの値 ``` ### `McpHttpResponse` -`HttpxMcpClient` メソッドの戻り値型。フィールド: `status_code: int`、`body: dict | list`。 -メソッド: `is_successful() -> bool`（`200 ≤ status_code < 300` のとき `True`）。 +`HttpxMcpClient` メソッドの戻り値型。 + +フィールド: `status_code: int`、`headers: dict[str, str]`、`body: str`（生のレスポンステキスト）。 + +メソッド: +- `is_successful() -> bool`（`200 ≤ status_code < 300` のとき `True`） +- `request_id() -> str | None` — `X-Request-ID` レスポンスヘッダーの値を返す（なければ `None`） ### `McpHttpClientProtocol` -カスタム MCP HTTP クライアントの構造的契約。`get()`・`post()`・`put()`・`delete()` を実装して `McpHttpResponse` を返します。 +カスタム MCP HTTP クライアントの構造的契約。`get()`・`post()`・`put()`・`delete()` で `McpHttpResponse` を返し、`has_authentication() -> bool` を実装します。 --- diff --git a/docs/reference/framework-modules.md b/docs/reference/framework-modules.md index 7423ad9..0e5cb64 100644 --- a/docs/reference/framework-modules.md +++ b/docs/reference/framework-modules.md @@ -394,17 +394,24 @@ from nene2.mcp import HttpxMcpClient client = HttpxMcpClient("bearer-token") response = client.get("http://localhost:8080", "/notes") response.is_successful() # True -response.body # dict | list — parsed JSON +response.body # str — raw response text response.status_code # int +response.request_id() # str | None — value of X-Request-ID header ``` ### `McpHttpResponse` -Return type of `HttpxMcpClient` methods. Fields: `status_code: int`, `body: dict | list`. Method: `is_successful() -> bool` (`True` when `200 ≤ status_code < 300`). +Return type of `HttpxMcpClient` methods. + +Fields: `status_code: int`, `headers: dict[str, str]`, `body: str` (raw response text). + +Methods: +- `is_successful() -> bool` — `True` when `200 ≤ status_code < 300` +- `request_id() -> str | None` — returns the `X-Request-ID` response header value, or `None` ### `McpHttpClientProtocol` -Structural contract for custom MCP HTTP clients. Implement `get()`, `post()`, `put()`, `delete()` returning `McpHttpResponse`. +Structural contract for custom MCP HTTP clients. Implement `get()`, `post()`, `put()`, `delete()` returning `McpHttpResponse`, and `has_authentication() -> bool`. ---