Subskill: Python Coding Standards, Typing & Verification Workflow
Activation Criteria
Activate this subskill when:
- Authoring, refactoring, or reviewing any Python file (
*.py) acrosspython/,eval/,samples/agent/,tools/, orscripts/. - Adding or modifying Pydantic v2 models, validators, exceptions, or imports.
- Running local Python formatting, type checking, unit tests, or build checks.
1. Coding Standards & Python Best Practices
Modern Typing & Pydantic v2
- Strict Type Annotations: All function signatures and module APIs must be fully typed. Use modern Python typing features (
T | Noneinstead ofOptional[T],list[T]instead ofList[T]). - Pydantic v2 Patterns:
- Use
model_dump(by_alias=True, exclude_none=True)for serialization. - Use
TypeAdapteror Pydantic models for JSON validation rather than hand-rolled validators. - Parameter metadata: Prefer
typing.Annotated[T, Field(description="...")]orAnnotated[T, "description"]over fragile, hand-rolled docstring parsing.
- Use
Error Hierarchy & Exception Handling
- Base Exception: All exceptions in the SDK inherit from
A2uiErrorina2ui.core. - Specialized Exceptions:
A2uiValidationError: Schema, property, or constraint violations.A2uiParseError: Syntax or formatting errors in LLM output.A2uiStateError: Surface lifecycle or state inconsistencies.A2uiCatalogError: Catalog negotiation or lookup failures.A2uiExpressionError: Local expression or function evaluation failures.
- Fail Loudly: Avoid silent fallbacks that swallow errors or mask invalid inputs. When an unknown schema node or format is encountered, raise an informative error naming the offending property or path.
Catalog-Agnostic Design
- Do not hardcode catalog-specific component names, property rules, or syntax filters into core parsers, prompt generators, or compilers.
- Component property rules, constraints, and hints must be dynamically derived from the component catalog JSON schema.
Import Organization and Sorting
Maintain strict, predictable import organization following standard Python (PEP 8) conventions:
- Future Imports: Place
from __future__ import annotationsat the very top of the file (directly below the module docstring/license header). - Three-Group Hierarchy: Group imports into three distinct sections separated by a single blank line:
- Standard library (e.g.,
import os,import sys,from typing import Any, Mapping) - Third-party packages (e.g.,
import pytest,from pydantic import BaseModel, Field) - First-party / repository packages (e.g.,
from a2ui.builder.v0_9 import Button, Card,from a2ui.core import DataModel)
- Standard library (e.g.,
- Alphabetical Sorting:
- Within each group, sort import statements alphabetically by module name.
- For multi-symbol
from <module> import (...)statements, sort the imported symbols alphabetically (e.g.,from a2ui.builder.v0_9 import Action, ActionEvent, Button, Card, Column, Text).
- No Wildcard Imports: Never use wildcard imports (
from module import *) in application, library, or test code. Explicitly name every imported symbol.
2. Tooling & Mandatory Verification Workflow
All Python code across the entire repository must pass formatting, type checking, and unit testing via uv before submission.
1. Synchronize Dependencies
uv sync --all-packages2. Formatting (fix_format.sh / Pyink)
Directly run the repository's formatting script to format code in place (faster and saves tokens compared to checking first):
./scripts/fix_format.shOr format Python code directly in place:
uv run pyink .3. Type Checking (Mypy)
Strict type checking must pass across all workspace packages:
uv run mypy .4. Unit & Conformance Tests (Pytest)
Run all pytest test suites:
# Run all tests
uv run pytest
# Run specific package tests
uv run pytest python/a2ui_core/tests
uv run pytest python/a2ui_agent/tests
uv run pytest python/a2ui_a2a/tests python/a2ui_adk/tests5. Build Verification
Verify that all packages build valid distributions:
uv build --all3. Pre-Submission Checklist for Python PRs
- Grounded in authoritative
specification/schemas andblueprints/. - Public symbols exported through package-level
__init__.pywith explicit__all__. - No deep internal module imports in code, tests, docstrings, or READMEs.
- Imports grouped (standard library, third-party, local) and sorted alphabetically.
- Formatted with
./scripts/fix_format.sh(oruv run pyink .). -
uv run mypy .passes with zero errors. -
uv run pytestpasses 100%. -
uv build --allcompletes successfully.