a2ui-project / a2ui-project/a2ui
[Python SDK] Use abstract collection types (Sequence, Mapping) for parameters in schema manager and inference formats
- Ngôn ngữ chính
- TypeScript
- Star
- 16.4k
- Fork
- 1.3k
- Merge trung bình
- 2 ngày 13 giờ
- Pull request đã merge (30 ngày)
- 134
Mô tả
- [x] I have searched the existing issues to make sure this feature has not already been requested.
## Is your feature request related to a problem? Please describe.
In the Python SDK (`agent_sdks/python/a2ui_agent`), several core function parameters and schema models currently specify concrete, invariant collection types (`list[T]` and `dict[K, V]`) in signatures where only iteration or read-only lookup is performed:
1. **`agent_sdks/python/a2ui_agent/src/a2ui/schema/manager.py` & `agent_sdks/python/a2ui_agent/src/a2ui/inference_formats/direct_json/format.py`**:
- `catalogs`: Typed as `Optional[list[CatalogConfig]] = None`. Callers passing immutable collections (e.g., `tuple[CatalogConfig, ...]`) fail static type checking due to collection invariance (PEP 484).
- `schema_modifiers`: Typed as `Optional[list[Callable[[dict[str, Any]], dict[str, Any]]]] = None`. Callers passing tuples or other sequences of modifier functions fail type checks unless converted to mutable `list`.
- `client_ui_capabilities`: Typed as `Optional[Union[dict[str, Any], V09Capabilities]] = None`. Callers passing read-only mappings, immutable dictionaries, or protobuf `Mapping[str, Any]` structures fail type checking.
2. **`agent_sdks/python/a2ui_agent/src/a2ui/schema/catalog.py`**:
- `common_types_schema`: Defined as `Dict[str, Any]` without an optional fallback, requiring dummy empty dictionaries when common types are not defined.
Under strict static type checkers (e.g., Mypy, Pyre, Pytype), callers are forced to perform defensive `list(...)` and `dict(...)` conversions at every call site.
## Describe the Proposed Solution
Adopt abstract container protocols (`Sequence`, `Mapping`) from `typing` / `collections.abc` for read-only input parameters across the Python SDK:
1. **`schema/manager.py` & `inference_formats/direct_json/format.py`**:
- `catalogs: Optional[Sequence[CatalogConfig]] = None`
- `schema_modifiers: Optional[Sequence[Callable[..., Any]]] = None`
- `client_ui_capabilities: Optional[Union[dict[str, Any], Mapping[str, Any], V09Capabilities]] = None`
2. **`schema/catalog.py`**:
- `common_types_schema: Optional[Dict[str, Any]] = None` (or `Optional[Mapping[str, Any]] = None`)
## Describe Alternatives Considered
- Keep `list` and `dict` concrete types, requiring all downstream callers to convert tuples/mappings to mutable lists and dicts prior to calling `create_schema_manager()` and format generators. This adds boilerplate and runtime copying overhead.
## Additional Context
Per standard Python typing guidelines (PEP 484):
> "Arguments should be annotated with abstract collection types (such as `Sequence`, `Mapping`, `Iterable`) rather than concrete collection types (such as `list`, `dict`), unless mutation of the object is required."
Hướng dẫn đóng góp
Hướng nghiên cứu
The issue specifies the exact files to change: agent_sdks/python/a2ui_agent/src/a2ui/schema/manager.py, inference_formats/direct_json/format.py, and schema/catalog.py. Start by reading the current type annotations in those files. Understand the difference between concrete types (list, dict) and abstract types (Sequence, Mapping) from the typing module. Change the parameter types as described, then run the project's type checker (likely mypy) to verify the changes are correct. Look for existing tests related to schema creation to ensure nothing breaks.
Do mô hình lập chỉ mục viết ra từ nội dung của issue.
Đánh giá
- Công nghệ
- python
- Lĩnh vực
- api, backend, tooling
- Loại issue
- Tái cấu trúc
- Độ khó
- 2/5
- Thời gian dự kiến
- 1-3 giờ
- Mức độ hoạt động
- Sôi nổi
- Độ rõ ràng
- Đặc tả rõ ràng
- Mức phù hợp với người mới
- 70/100