Skip to content

Commit 49aa4ae

Browse files
b-longCopilotgemini-code-assist[bot]
authored
fix: improve docs (#106)
* fix: update docs * fix: remove rewrite reference * fix: correct command * fix: update docs * Update otdf-python-proto/scripts/build_connect_proto.sh Co-authored-by: Copilot <[email protected]> * fix: update link * remove unused 'TDFReaderConfig' * cleanup docs * Update docs/CONNECT_RPC.md Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> * Update otdf-python-proto/scripts/build_connect_proto.sh Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> * Update otdf-python-proto/README.md Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> * cleanup docs --------- Co-authored-by: Copilot <[email protected]> Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
1 parent 80973e3 commit 49aa4ae

File tree

7 files changed

+159
-426
lines changed

7 files changed

+159
-426
lines changed

‎.github/workflows/build-python.yaml‎

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,6 @@
11
# Build otdf-python wheel using uv and output the wheel path for downstream workflows
22
name: "Build Python Wheel"
33
on:
4-
push:
5-
branches:
6-
- chore/rewrite
74
pull_request:
85

96
jobs:

‎README.md‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -83,8 +83,6 @@ with open("encrypted.tdf", "wb") as f:
8383
### Decrypt Data
8484

8585
```python
86-
from otdf_python.tdf import TDFReaderConfig
87-
8886
# Read encrypted TDF file
8987
with open("encrypted.tdf", "rb") as f:
9088
encrypted_data = f.read()

‎docs/CONNECT_RPC.md‎

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
# Connect RPC in OpenTDF Python SDK
2+
3+
This document describes the Connect RPC implementation in the OpenTDF Python SDK, which provides a modern HTTP-friendly alternative to traditional gRPC.
4+
5+
## Overview
6+
7+
Connect RPC is a protocol that brings the benefits of RPC to HTTP APIs. It's designed to be:
8+
- **HTTP-compatible**: Works with standard HTTP infrastructure
9+
- **Type-safe**: Generated from Protocol Buffer definitions
10+
- **Efficient**: Binary protocol with JSON fallback
11+
- **Simple**: Easy to debug and integrate
12+
13+
## Architecture
14+
15+
The SDK uses a two-module structure for protocol buffer generation:
16+
17+
- **Main SDK**: `src/otdf_python/` - Core SDK functionality
18+
- **Protocol Generation**: `otdf-python-proto/` - Generated Connect RPC and protobuf files
19+
20+
### Generated Files
21+
22+
Connect RPC generates the following files in `otdf-python-proto/src/otdf_python_proto/`:
23+
24+
- `*_connect.py` - Connect RPC client implementations (recommended)
25+
- `*_pb2.py` - Protocol buffer message definitions
26+
- `legacy_grpc/*_pb2_grpc.py` - Traditional gRPC clients (backward compatibility)
27+
28+
## Usage
29+
30+
### Client Creation
31+
32+
Connect RPC clients are created using the generated `*_connect.py` modules:
33+
34+
```python
35+
from otdf_python_proto.kas import kas_connect
36+
from otdf_python_proto.policy import policy_connect
37+
38+
# Create Connect RPC clients
39+
kas_client = kas_connect.KeyAccessServiceClient(base_url="https://example.com")
40+
policy_client = policy_connect.PolicyServiceClient(base_url="https://your-policy-endpoint")
41+
```
42+
43+
### Authentication
44+
45+
Connect RPC clients support standard HTTP authentication:
46+
47+
```python
48+
import httpx
49+
50+
# Create authenticated HTTP client, assuming `token` holds your auth token
51+
http_client = httpx.Client(
52+
headers={"Authorization": f"Bearer {token}"}
53+
)
54+
55+
# Use with Connect RPC client
56+
kas_client = kas_connect.KeyAccessServiceClient(
57+
base_url="https://example.com",
58+
http_client=http_client
59+
)
60+
```
61+
62+
## Regenerating Connect RPC Files
63+
64+
To regenerate the Connect RPC and protobuf files:
65+
66+
```bash
67+
cd otdf-python-proto
68+
uv run python scripts/generate_connect_proto.py
69+
```
70+
71+
### Download Fresh Proto Files
72+
73+
To download the latest protocol definitions:
74+
75+
```bash
76+
cd otdf-python-proto
77+
uv run python scripts/generate_connect_proto.py --download
78+
```
79+
80+
### Requirements
81+
82+
- `buf` tool: `brew install bufbuild/buf/buf` (or see [official installation guide](https://buf.build/docs/installation))
83+
- Python dependencies managed by `uv`
84+
85+
## Benefits Over gRPC
86+
87+
1. **HTTP Compatibility**: Works with load balancers, proxies, and other HTTP infrastructure
88+
2. **Debugging**: Easy to inspect with standard HTTP tools
89+
3. **Flexibility**: Supports both binary and JSON encoding
90+
4. **Simplicity**: No special HTTP/2 requirements
91+
92+
## Migration from gRPC
93+
94+
If migrating from legacy gRPC clients:
95+
96+
1. Replace `*_pb2_grpc.py` imports with `*_connect.py`
97+
2. Update client instantiation to use base URLs instead of channels
98+
3. Leverage HTTP client features for authentication and configuration
99+
100+
## Testing
101+
102+
Connect RPC clients can be easily mocked and tested using standard HTTP testing tools:
103+
104+
```python
105+
import httpx
106+
import respx
107+
from otdf_python_proto.kas import kas_pb2, kas_connect
108+
109+
@respx.mock
110+
def test_connect_rpc_client():
111+
# 1. Create a sample protobuf response message
112+
expected_response = kas_pb2.RewrapResponse(
113+
entity_wrapped_key=b'some-unwrapped-key'
114+
)
115+
116+
# 2. Mock the correct Connect RPC endpoint URL
117+
respx.post("https://example.com/kas.AccessService/Rewrap").mock(
118+
return_value=httpx.Response(
119+
200,
120+
# 3. Return the serialized protobuf message as content
121+
content=expected_response.SerializeToString(),
122+
headers={'Content-Type': 'application/proto'}
123+
)
124+
)
125+
126+
client = kas_connect.KeyAccessServiceClient(base_url="https://example.com")
127+
# Test client calls...
128+
```
129+
130+
## Error Handling
131+
132+
Connect RPC provides structured error handling through standard HTTP status codes and error details:
133+
134+
```python
135+
from connectrpc import ConnectError
136+
137+
try:
138+
# Assuming `kas_client` and `request` are defined as in previous examples
139+
response = kas_client.rewrap(request)
140+
except ConnectError as e:
141+
print(f"Connect RPC error: {e.code} - {e.message}")
142+
# Handle specific error types
143+
```
144+
145+
## Performance Considerations
146+
147+
- Use connection pooling with `httpx.Client` for better performance
148+
- Configure appropriate timeouts for your use case
149+
- Consider using binary encoding for high-throughput scenarios
150+
151+
## Additional Resources
152+
153+
For more information, see:
154+
- [Connect RPC Documentation](https://connectrpc.com/docs/)
155+
- [Connect Python Repository](https://github.com/connectrpc/connect-python)
156+
- [OpenTDF Platform](https://github.com/opentdf/platform)

0 commit comments

Comments
 (0)