Skip to content

Commit 085794e

Browse files
DinisCruzDinisCruz
committed
Merge branch 'distracted-shirley' into dev
* distracted-shirley: implemented todos and refactored service registry code added lessons learned started adding the Fast_API registry classes
2 parents 4c581ac + f14db99 commit 085794e

38 files changed

Lines changed: 1407 additions & 1 deletion

File tree

docs/dev-briefs/v1.33.0__create-services-registry/v1.33.0__dev-brief__create-services-registry.md renamed to docs/dev-briefs/v0.32.0__create-services-registry/v0.32.0__dev-brief__create-services-registry.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Dev Brief: Create Services Registry
22

3-
**Version**: v1.33.0
3+
**Version**: v0.32.0
44
**Date**: January 2025
55
**Status**: Ready for Implementation
66
**Target Package**: `osbot_fast_api_serverless`

‎docs/dev-briefs/v0.32.1__improve-test-coverage/v0.32.1__lessons-learned__improve-test-coverage.md‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
# Lessons Learned: Improve Test Coverage
2+
3+
**Version**: v0.32.1
4+
**Date**: January 2025
5+
**Related Brief**: `v0.32.1__dev-brief__improve-test-coverage.md`
6+
**Related Debrief**: `v0.32.1__debrief__improve-test-coverage.md`
7+
8+
---
9+
10+
## User Guidance Received During Session
11+
12+
This document captures the specific guidance and corrections provided by the developer during the test coverage improvement session. These patterns should be followed in future sessions.
13+
14+
---
15+
16+
## 1. Bug Documentation Convention
17+
18+
### Guidance Received
19+
20+
When discovering bugs during testing:
21+
22+
**a) Naming Convention**: Add `__bug__` to the test method name
23+
24+
```python
25+
# Instead of:
26+
def test__enhance_with_signature__type_safe_detection(self):
27+
28+
# Use:
29+
def test__bug__enhance_with_signature__type_safe_detection(self):
30+
```
31+
32+
**b) Comment Format**: Prefix bug comments with `todo:` for IDE visibility
33+
34+
```python
35+
# Instead of:
36+
# Note: The actual _enhance_with_signature has a bug where...
37+
assert endpoint.request_schema is None # BUG: stays None
38+
39+
# Use:
40+
# todo: BUG: The actual _enhance_with_signature tries to set request_schema
41+
# to a string but schema expects Type. Exception is silently caught.
42+
assert endpoint.request_schema is None # todo: BUG: stays None due to type mismatch
43+
```
44+
45+
**Reason**: The `todo:` prefix makes bugs visible in PyCharm's TODO panel, making them easier to track and fix later.
46+
47+
---
48+
49+
## 2. Import Organization
50+
51+
### Guidance Received
52+
53+
Never add imports inline within test methods. Always add them at the module level with correct alignment.
54+
55+
```python
56+
# Instead of:
57+
def test__enhance_with_signature__with_path_param_update(self):
58+
with self.extractor as _:
59+
from osbot_fast_api.client.schemas.enums.Enum__Param__Location import Enum__Param__Location
60+
# ... test code
61+
62+
# Use:
63+
from osbot_fast_api.client.schemas.enums.Enum__Param__Location import Enum__Param__Location
64+
65+
def test__enhance_with_signature__with_path_param_update(self):
66+
with self.extractor as _:
67+
# ... test code
68+
```
69+
70+
**Reason**: Keeps imports organized and consistent with project conventions. Imports should be alphabetically sorted and aligned.
71+
72+
---
73+
74+
## 3. Document Separation
75+
76+
### Guidance Received (from Session 1)
77+
78+
Keep the original dev-brief document unchanged as a historical record of the plan. Create a separate debrief document to track progress and capture what was actually done.
79+
80+
**Document Structure**:
81+
- `v0.32.1__dev-brief__*.md` - Original plan (immutable after creation)
82+
- `v0.32.1__debrief__*.md` - Progress tracking, stats, session log
83+
- `v0.32.1__lessons-learned__*.md` - Guidance received, patterns learned
84+
85+
**Reason**: Preserves the original intent and allows comparison between planned vs actual work.
86+
87+
---
88+
89+
## 4. Type_Safe Testing Patterns
90+
91+
### From Project Guidance Documents
92+
93+
The project has specific testing conventions documented in `docs/llm-briefs/type_safety/`:
94+
95+
**Context Manager Pattern**:
96+
```python
97+
def test_something(self):
98+
with SomeClass() as _:
99+
assert _.field == expected_value
100+
```
101+
102+
**Inline Comments (Not Docstrings)**:
103+
```python
104+
def test_something(self): # Brief description of test
105+
with SomeClass() as _:
106+
result = _.method() # explain what this does
107+
assert result == expected # explain the assertion
108+
```
109+
110+
**Method Naming**:
111+
```
112+
test__<method_name>__<scenario>
113+
```
114+
115+
---
116+
117+
## Summary of Key Patterns
118+
119+
| Pattern | Convention |
120+
|---------|------------|
121+
| Bug tests | Prefix with `test__bug__` |
122+
| Bug comments | Use `# todo: BUG:` prefix |
123+
| Imports | Module level only, aligned |
124+
| Dev docs | Separate brief/debrief/lessons |
125+
| Folder names | Don't hardcode, be flexible |
126+
| Test style | Context manager with `_`, inline comments |

‎docs/dev-briefs/v0.32.2__fast-api-registry-refactor/v0.32.2__debrief__fast-api-registry-refactor.md‎

Lines changed: 192 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,192 @@
1+
# Debrief: Fast API Registry Refactoring
2+
3+
**Version**: v0.32.2
4+
**Date**: January 2025
5+
**Status**: Complete (All Phases)
6+
**Related Brief**: `v0.32.2__dev-brief__fast-api-registry-refactor.md`
7+
8+
---
9+
10+
## Summary
11+
12+
Successfully completed all 4 phases from the dev brief:
13+
- Phase 1: Naming Convention Alignment
14+
- Phase 2: Architecture Refactoring
15+
- Phase 3: New Schema Types
16+
- Phase 4: Integration Tests
17+
18+
---
19+
20+
## Completed Tasks
21+
22+
### Phase 1: Class Renaming ✅
23+
24+
All classes renamed to follow `Fast_API__` prefix convention:
25+
26+
| Old Name | New Name | Status |
27+
|----------|----------|--------|
28+
| `Services__Registry` | `Fast_API__Service__Registry` | ✅ |
29+
| `Service__Client__Base` | `Fast_API__Service__Registry__Client__Base` | ✅ |
30+
| `Schema__Service__Client__Config` | `Fast_API__Service__Registry__Client__Config` | ✅ |
31+
| `Schema__Env_Var` | `Schema__Fast_API__Registry__Env_Var` | ✅ |
32+
| `Dict__Clients__By_Type` | `Dict__Fast_API__Service__Clients_By_Type` | ✅ |
33+
| `List__Client_Types` | `List__Fast_API__Service__Client_Types` | ✅ |
34+
| `List__Env_Vars` | `List__Fast_API__Registry__Env_Vars` | ✅ |
35+
| `Safe_Str__API_Key__Name` | `Safe_Str__Fast_API__Auth__Key_Name` | ✅ |
36+
| `Safe_Str__API_Key__Value` | `Safe_Str__Fast_API__Auth__Key_Value` | ✅ |
37+
38+
### Phase 2: Architecture Refactoring ✅
39+
40+
Converted `Services__Registry` from static class-based to Type_Safe instance-based:
41+
42+
**Before** (static with lazy init):
43+
```python
44+
class Services__Registry:
45+
_clients : Dict__Clients__By_Type = None
46+
47+
@classmethod
48+
def clients(cls) -> Dict__Clients__By_Type:
49+
if cls._clients is None:
50+
cls._clients = Dict__Clients__By_Type()
51+
return cls._clients
52+
```
53+
54+
**After** (Type_Safe instance-based):
55+
```python
56+
class Fast_API__Service__Registry(Type_Safe):
57+
clients : Dict__Fast_API__Service__Clients_By_Type
58+
59+
def register(self, client: Fast_API__Service__Registry__Client__Base) -> None:
60+
self.clients[type(client)] = client
61+
62+
fast_api__service__registry = Fast_API__Service__Registry()
63+
```
64+
65+
### Test Double Renaming ✅
66+
67+
Renamed mock clients to avoid pytest collection warnings:
68+
69+
| Old Name | New Name |
70+
|----------|----------|
71+
| `Mock__Client__Alpha` | `Fake__Client__Alpha` |
72+
| `Mock__Client__Beta` | `Fake__Client__Beta` |
73+
74+
Also renamed folder from `mock_clients/` to `test_clients/`.
75+
76+
---
77+
78+
## Files Changed
79+
80+
### New Source Files (9)
81+
- `osbot_fast_api/services/registry/Fast_API__Service__Registry.py`
82+
- `osbot_fast_api/services/registry/Fast_API__Service__Registry__Client__Base.py`
83+
- `osbot_fast_api/services/schemas/registry/Fast_API__Service__Registry__Client__Config.py`
84+
- `osbot_fast_api/services/schemas/registry/Schema__Fast_API__Registry__Env_Var.py`
85+
- `osbot_fast_api/services/schemas/registry/collections/Dict__Fast_API__Service__Clients_By_Type.py`
86+
- `osbot_fast_api/services/schemas/registry/collections/List__Fast_API__Service__Client_Types.py`
87+
- `osbot_fast_api/services/schemas/registry/collections/List__Fast_API__Registry__Env_Vars.py`
88+
- `osbot_fast_api/services/schemas/registry/safe_str/Safe_Str__Fast_API__Auth__Key_Name.py`
89+
- `osbot_fast_api/services/schemas/registry/safe_str/Safe_Str__Fast_API__Auth__Key_Value.py`
90+
91+
### Deleted Source Files (9)
92+
- `osbot_fast_api/services/registry/Services__Registry.py`
93+
- `osbot_fast_api/services/registry/Service__Client__Base.py`
94+
- `osbot_fast_api/services/schemas/registry/Schema__Env_Var.py`
95+
- `osbot_fast_api/services/schemas/registry/Schema__Service__Client__Config.py`
96+
- `osbot_fast_api/services/schemas/registry/collections/Dict__Clients__By_Type.py`
97+
- `osbot_fast_api/services/schemas/registry/collections/List__Client_Types.py`
98+
- `osbot_fast_api/services/schemas/registry/collections/List__Env_Vars.py`
99+
- `osbot_fast_api/services/schemas/registry/safe_str/Safe_Str__API_Key__Name.py`
100+
- `osbot_fast_api/services/schemas/registry/safe_str/Safe_Str__API_Key__Value.py`
101+
102+
### New Test Files (7)
103+
- `tests/unit/services/registry/test_Fast_API__Service__Registry.py`
104+
- `tests/unit/services/registry/test_Fast_API__Service__Registry__Client__Base.py`
105+
- `tests/unit/services/registry/test_clients/Fake__Client__Alpha.py`
106+
- `tests/unit/services/registry/test_clients/Fake__Client__Beta.py`
107+
- `tests/unit/services/schemas/registry/test_Schema__Fast_API__Registry__Env_Var.py`
108+
- `tests/unit/services/schemas/registry/test_Fast_API__Service__Registry__Client__Config.py`
109+
- `tests/unit/services/schemas/registry/collections/test_List__Fast_API__Registry__Env_Vars.py`
110+
111+
### Deleted Test Files (5)
112+
- `tests/unit/services/registry/test_Services__Registry.py`
113+
- `tests/unit/services/registry/test_Service__Client__Base.py`
114+
- `tests/unit/services/registry/mock_clients/` (entire folder)
115+
- `tests/unit/services/schemas/registry/test_Schema__Env_Var.py`
116+
- `tests/unit/services/schemas/registry/test_Schema__Service__Client__Config.py`
117+
- `tests/unit/services/schemas/registry/collections/test_List__Env_Vars.py`
118+
119+
---
120+
121+
## Test Results
122+
123+
```
124+
30 service registry unit tests passed
125+
11 service registry integration tests passed
126+
755 total tests passed (2 skipped)
127+
No regressions
128+
```
129+
130+
---
131+
132+
### Phase 3: New Schema Types ✅
133+
134+
Created type-safe environment variable types:
135+
136+
| New Type | Purpose |
137+
|----------|---------|
138+
| `Safe_Str__Env_Var__Name` | Type-safe env var name string |
139+
| `Safe_Str__Env_Var__Value` | Type-safe env var value string |
140+
141+
Updated `Schema__Fast_API__Registry__Env_Var` to use `Safe_Str__Env_Var__Name` for the `name` field.
142+
143+
### Phase 4: Integration Tests ✅
144+
145+
Created comprehensive integration tests using `Temp_Web_Server` from osbot_utils:
146+
147+
| Test Category | Tests |
148+
|---------------|-------|
149+
| **IN_MEMORY Mode** | Health check, GET request, POST request, TestClient verification |
150+
| **REMOTE Mode** | Health check, GET request, API key headers |
151+
| **Mode Switching** | IN_MEMORY to REMOTE switching |
152+
| **Multi-Client** | Different modes per client type |
153+
| **Error Handling** | Unconfigured mode, connection failure |
154+
155+
**New Integration Test File**:
156+
- `tests/integration/services/registry/test_Fast_API__Service__Registry__Integration.py` (11 tests)
157+
158+
---
159+
160+
## Key Decisions Made
161+
162+
1. **Naming**: Used `Fake__*` prefix for test doubles instead of `Mock__*` or `Test__*` to avoid pytest collection warnings and clarify intent
163+
2. **Singleton**: Renamed singleton variable from `fast_api__service_registry` to `fast_api__service__registry` (double underscore before `registry`) for consistency
164+
3. **Type_Safe**: Converted registry to Type_Safe to leverage automatic field initialization, removing manual lazy init pattern
165+
166+
---
167+
168+
## Session Log
169+
170+
### Session 1: January 2025
171+
172+
**Phase 1 & 2 Completion**:
173+
1. Extracted 11 TODOs from source files
174+
2. Created dev-brief document
175+
3. Renamed 9 source classes
176+
4. Converted Services__Registry to Type_Safe pattern
177+
5. Renamed 2 mock clients to Fake__* pattern
178+
6. Updated 7 test files
179+
7. Deleted 14 old files
180+
8. Verified 744 tests pass
181+
182+
**Phase 3 & 4 Completion**:
183+
9. Created `Safe_Str__Env_Var__Name` and `Safe_Str__Env_Var__Value` types
184+
10. Updated `Schema__Fast_API__Registry__Env_Var` to use new type
185+
11. Created integration test file with 11 tests
186+
12. Implemented IN_MEMORY mode tests (4 tests)
187+
13. Implemented REMOTE mode tests using Temp_Web_Server (3 tests)
188+
14. Implemented mode switching tests (2 tests)
189+
15. Implemented error handling tests (2 tests)
190+
16. Verified 755 tests pass
191+
192+
**Total Changes**: 20 new files, 14 deleted files

0 commit comments

Comments
 (0)