[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7BWN2C1GZCZYBPP263W4QRN":3,"skill-same:01M7BWN2C1GZCZYBPP263W4QRN":47},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":27,"repositoryHtmlUrl":28,"repositoryHomepageUrl":29,"ownerHtmlUrl":30,"ownerBlogUrl":6,"ownerDescription":31,"updatedAt":32,"install":33,"resources":46},"01M7BWN2C1GZCZYBPP263W4QRN","python-type-safety",null,"Python type safety with type hints, generics, protocols, and strict type checking. Use when adding type annotations, implementing generic classes, defining structural interfaces, or configuring mypy\u002Fpyright.","YYC-Cube\u002FYYC3-Knowledge-Base","YYC-Cube","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F235006543?v=4","01M79J2PH4SWD2X0825X6PN748","yyc3","01M79J2PHVK3F6ZBYT8K2SCZCW",1,"MIT","https:\u002F\u002Fgithub.com\u002FYYC-Cube\u002FYYC3-Knowledge-Base\u002Fblob\u002Fmain\u002FYYC3-Plugin-插件协议\u002FYYC3-Plugin-插件协议-plugins-claude\u002Fpython-development\u002Fskills\u002Fpython-type-safety\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: python-type-safety\ndescription: Python type safety with type hints, generics, protocols, and strict type checking. Use when adding type annotations, implementing generic classes, defining structural interfaces, or configuring mypy\u002Fpyright.\n---\n\n# Python Type Safety\n\nLeverage Python's type system to catch errors at static analysis time. Type annotations serve as enforced documentation that tooling validates automatically.\n\n## When to Use This Skill\n\n- Adding type hints to existing code\n- Creating generic, reusable classes\n- Defining structural interfaces with protocols\n- Configuring mypy or pyright for strict checking\n- Understanding type narrowing and guards\n- Building type-safe APIs and libraries\n\n## Core Concepts\n\n### 1. Type Annotations\n\nDeclare expected types for function parameters, return values, and variables.\n\n### 2. Generics\n\nWrite reusable code that preserves type information across different types.\n\n### 3. Protocols\n\nDefine structural interfaces without inheritance (duck typing with type safety).\n\n### 4. Type Narrowing\n\nUse guards and conditionals to narrow types within code blocks.\n\n## Quick Start\n\n```python\ndef get_user(user_id: str) -> User | None:\n    \"\"\"Return type makes 'might not exist' explicit.\"\"\"\n    ...\n\n# Type checker enforces handling None case\nuser = get_user(\"123\")\nif user is None:\n    raise UserNotFoundError(\"123\")\nprint(user.name)  # Type checker knows user is User here\n```\n\n## Fundamental Patterns\n\n### Pattern 1: Annotate All Public Signatures\n\nEvery public function, method, and class should have type annotations.\n\n```python\ndef get_user(user_id: str) -> User:\n    \"\"\"Retrieve user by ID.\"\"\"\n    ...\n\ndef process_batch(\n    items: list[Item],\n    max_workers: int = 4,\n) -> BatchResult[ProcessedItem]:\n    \"\"\"Process items concurrently.\"\"\"\n    ...\n\nclass UserRepository:\n    def __init__(self, db: Database) -> None:\n        self._db = db\n\n    async def find_by_id(self, user_id: str) -> User | None:\n        \"\"\"Return User if found, None otherwise.\"\"\"\n        ...\n\n    async def find_by_email(self, email: str) -> User | None:\n        ...\n\n    async def save(self, user: User) -> User:\n        \"\"\"Save and return user with generated ID.\"\"\"\n        ...\n```\n\nUse `mypy --strict` or `pyright` in CI to catch type errors early. For existing projects, enable strict mode incrementally using per-module overrides.\n\n### Pattern 2: Use Modern Union Syntax\n\nPython 3.10+ provides cleaner union syntax.\n\n```python\n# Preferred (3.10+)\ndef find_user(user_id: str) -> User | None:\n    ...\n\ndef parse_value(v: str) -> int | float | str:\n    ...\n\n# Older style (still valid, needed for 3.9)\nfrom typing import Optional, Union\n\ndef find_user(user_id: str) -> Optional[User]:\n    ...\n```\n\n### Pattern 3: Type Narrowing with Guards\n\nUse conditionals to narrow types for the type checker.\n\n```python\ndef process_user(user_id: str) -> UserData:\n    user = find_user(user_id)\n\n    if user is None:\n        raise UserNotFoundError(f\"User {user_id} not found\")\n\n    # Type checker knows user is User here, not User | None\n    return UserData(\n        name=user.name,\n        email=user.email,\n    )\n\ndef process_items(items: list[Item | None]) -> list[ProcessedItem]:\n    # Filter and narrow types\n    valid_items = [item for item in items if item is not None]\n    # valid_items is now list[Item]\n    return [process(item) for item in valid_items]\n```\n\n### Pattern 4: Generic Classes\n\nCreate type-safe reusable containers.\n\n```python\nfrom typing import TypeVar, Generic\n\nT = TypeVar(\"T\")\nE = TypeVar(\"E\", bound=Exception)\n\nclass Result(Generic[T, E]):\n    \"\"\"Represents either a success value or an error.\"\"\"\n\n    def __init__(\n        self,\n        value: T | None = None,\n        error: E | None = None,\n    ) -> None:\n        if (value is None) == (error is None):\n            raise ValueError(\"Exactly one of value or error must be set\")\n        self._value = value\n        self._error = error\n\n    @property\n    def is_success(self) -> bool:\n        return self._error is None\n\n    @property\n    def is_failure(self) -> bool:\n        return self._error is not None\n\n    def unwrap(self) -> T:\n        \"\"\"Get value or raise the error.\"\"\"\n        if self._error is not None:\n            raise self._error\n        return self._value  # type: ignore[return-value]\n\n    def unwrap_or(self, default: T) -> T:\n        \"\"\"Get value or return default.\"\"\"\n        if self._error is not None:\n            return default\n        return self._value  # type: ignore[return-value]\n\n# Usage preserves types\ndef parse_config(path: str) -> Result[Config, ConfigError]:\n    try:\n        return Result(value=Config.from_file(path))\n    except ConfigError as e:\n        return Result(error=e)\n\nresult = parse_config(\"config.yaml\")\nif result.is_success:\n    config = result.unwrap()  # Type: Config\n```\n\n## Advanced Patterns\n\n### Pattern 5: Generic Repository\n\nCreate type-safe data access patterns.\n\n```python\nfrom typing import TypeVar, Generic\nfrom abc import ABC, abstractmethod\n\nT = TypeVar(\"T\")\nID = TypeVar(\"ID\")\n\nclass Repository(ABC, Generic[T, ID]):\n    \"\"\"Generic repository interface.\"\"\"\n\n    @abstractmethod\n    async def get(self, id: ID) -> T | None:\n        \"\"\"Get entity by ID.\"\"\"\n        ...\n\n    @abstractmethod\n    async def save(self, entity: T) -> T:\n        \"\"\"Save and return entity.\"\"\"\n        ...\n\n    @abstractmethod\n    async def delete(self, id: ID) -> bool:\n        \"\"\"Delete entity, return True if existed.\"\"\"\n        ...\n\nclass UserRepository(Repository[User, str]):\n    \"\"\"Concrete repository for Users with string IDs.\"\"\"\n\n    async def get(self, id: str) -> User | None:\n        row = await self._db.fetchrow(\n            \"SELECT * FROM users WHERE id = $1\", id\n        )\n        return User(**row) if row else None\n\n    async def save(self, entity: User) -> User:\n        ...\n\n    async def delete(self, id: str) -> bool:\n        ...\n```\n\n### Pattern 6: TypeVar with Bounds\n\nRestrict generic parameters to specific types.\n\n```python\nfrom typing import TypeVar\nfrom pydantic import BaseModel\n\nModelT = TypeVar(\"ModelT\", bound=BaseModel)\n\ndef validate_and_create(model_cls: type[ModelT], data: dict) -> ModelT:\n    \"\"\"Create a validated Pydantic model from dict.\"\"\"\n    return model_cls.model_validate(data)\n\n# Works with any BaseModel subclass\nclass User(BaseModel):\n    name: str\n    email: str\n\nuser = validate_and_create(User, {\"name\": \"Alice\", \"email\": \"a@b.com\"})\n# user is typed as User\n\n# Type error: str is not a BaseModel subclass\nresult = validate_and_create(str, {\"name\": \"Alice\"})  # Error!\n```\n\n### Pattern 7: Protocols for Structural Typing\n\nDefine interfaces without requiring inheritance.\n\n```python\nfrom typing import Protocol, runtime_checkable\n\n@runtime_checkable\nclass Serializable(Protocol):\n    \"\"\"Any class that can be serialized to\u002Ffrom dict.\"\"\"\n\n    def to_dict(self) -> dict:\n        ...\n\n    @classmethod\n    def from_dict(cls, data: dict) -> \"Serializable\":\n        ...\n\n# User satisfies Serializable without inheriting from it\nclass User:\n    def __init__(self, id: str, name: str) -> None:\n        self.id = id\n        self.name = name\n\n    def to_dict(self) -> dict:\n        return {\"id\": self.id, \"name\": self.name}\n\n    @classmethod\n    def from_dict(cls, data: dict) -> \"User\":\n        return cls(id=data[\"id\"], name=data[\"name\"])\n\ndef serialize(obj: Serializable) -> str:\n    \"\"\"Works with any Serializable object.\"\"\"\n    return json.dumps(obj.to_dict())\n\n# Works - User matches the protocol\nserialize(User(\"1\", \"Alice\"))\n\n# Runtime checking with @runtime_checkable\nisinstance(User(\"1\", \"Alice\"), Serializable)  # True\n```\n\n### Pattern 8: Common Protocol Patterns\n\nDefine reusable structural interfaces.\n\n```python\nfrom typing import Protocol\n\nclass Closeable(Protocol):\n    \"\"\"Resource that can be closed.\"\"\"\n    def close(self) -> None: ...\n\nclass AsyncCloseable(Protocol):\n    \"\"\"Async resource that can be closed.\"\"\"\n    async def close(self) -> None: ...\n\nclass Readable(Protocol):\n    \"\"\"Object that can be read from.\"\"\"\n    def read(self, n: int = -1) -> bytes: ...\n\nclass HasId(Protocol):\n    \"\"\"Object with an ID property.\"\"\"\n    @property\n    def id(self) -> str: ...\n\nclass Comparable(Protocol):\n    \"\"\"Object that supports comparison.\"\"\"\n    def __lt__(self, other: \"Comparable\") -> bool: ...\n    def __le__(self, other: \"Comparable\") -> bool: ...\n```\n\n### Pattern 9: Type Aliases\n\nCreate meaningful type names.\n\n**Note:** The `type` statement was introduced in Python 3.10 for simple aliases. Generic type statements require Python 3.12+.\n\n```python\n# Python 3.10+ type statement for simple aliases\ntype UserId = str\ntype UserDict = dict[str, Any]\n\n# Python 3.12+ type statement with generics\ntype Handler[T] = Callable[[Request], T]\ntype AsyncHandler[T] = Callable[[Request], Awaitable[T]]\n\n# Python 3.9-3.11 style (needed for broader compatibility)\nfrom typing import TypeAlias\nfrom collections.abc import Callable, Awaitable\n\nUserId: TypeAlias = str\nHandler: TypeAlias = Callable[[Request], Response]\n\n# Usage\ndef register_handler(path: str, handler: Handler[Response]) -> None:\n    ...\n```\n\n### Pattern 10: Callable Types\n\nType function parameters and callbacks.\n\n```python\nfrom collections.abc import Callable, Awaitable\n\n# Sync callback\nProgressCallback = Callable[[int, int], None]  # (current, total)\n\n# Async callback\nAsyncHandler = Callable[[Request], Awaitable[Response]]\n\n# With named parameters (using Protocol)\nclass OnProgress(Protocol):\n    def __call__(\n        self,\n        current: int,\n        total: int,\n        *,\n        message: str = \"\",\n    ) -> None: ...\n\ndef process_items(\n    items: list[Item],\n    on_progress: ProgressCallback | None = None,\n) -> list[Result]:\n    for i, item in enumerate(items):\n        if on_progress:\n            on_progress(i, len(items))\n        ...\n```\n\n## Configuration\n\n### Strict Mode Checklist\n\nFor `mypy --strict` compliance:\n\n```toml\n# pyproject.toml\n[tool.mypy]\npython_version = \"3.12\"\nstrict = true\nwarn_return_any = true\nwarn_unused_ignores = true\ndisallow_untyped_defs = true\ndisallow_incomplete_defs = true\nno_implicit_optional = true\n```\n\nIncremental adoption goals:\n- All function parameters annotated\n- All return types annotated\n- Class attributes annotated\n- Minimize `Any` usage (acceptable for truly dynamic data)\n- Generic collections use type parameters (`list[str]` not `list`)\n\nFor existing codebases, enable strict mode per-module using `# mypy: strict` or configure per-module overrides in `pyproject.toml`.\n\n## Best Practices Summary\n\n1. **Annotate all public APIs** - Functions, methods, class attributes\n2. **Use `T | None`** - Modern union syntax over `Optional[T]`\n3. **Run strict type checking** - `mypy --strict` in CI\n4. **Use generics** - Preserve type info in reusable code\n5. **Define protocols** - Structural typing for interfaces\n6. **Narrow types** - Use guards to help the type checker\n7. **Bound type vars** - Restrict generics to meaningful types\n8. **Create type aliases** - Meaningful names for complex types\n9. **Minimize `Any`** - Use specific types or generics. `Any` is acceptable for truly dynamic data or when interfacing with untyped third-party code\n10. **Document with types** - Types are enforceable documentation\n","# Python Type Safety\n\nLeverage Python's type system to catch errors at static analysis time. Type annotations serve as enforced documentation that tooling validates automatically.\n\n## When to Use This Skill\n\n- Adding type hints to existing code\n- Creating generic, reusable classes\n- Defining structural interfaces with protocols\n- Configuring mypy or pyright for strict checking\n- Understanding type narrowing and guards\n- Building type-safe APIs and libraries\n\n## Core Concepts\n\n### 1. Type Annotations\n\nDeclare expected types for function parameters, return values, and variables.\n\n### 2. Generics\n\nWrite reusable code that preserves type information across different types.\n\n### 3. Protocols\n\nDefine structural interfaces without inheritance (duck typing with type safety).\n\n### 4. Type Narrowing\n\nUse guards and conditionals to narrow types within code blocks.\n\n## Quick Start\n\n```python\ndef get_user(user_id: str) -> User | None:\n    \"\"\"Return type makes 'might not exist' explicit.\"\"\"\n    ...\n\n# Type checker enforces handling None case\nuser = get_user(\"123\")\nif user is None:\n    raise UserNotFoundError(\"123\")\nprint(user.name)  # Type checker knows user is User here\n```\n\n## Fundamental Patterns\n\n### Pattern 1: Annotate All Public Signatures\n\nEvery public function, method, and class should have type annotations.\n\n```python\ndef get_user(user_id: str) -> User:\n    \"\"\"Retrieve user by ID.\"\"\"\n    ...\n\ndef process_batch(\n    items: list[Item],\n    max_workers: int = 4,\n) -> BatchResult[ProcessedItem]:\n    \"\"\"Process items concurrently.\"\"\"\n    ...\n\nclass UserRepository:\n    def __init__(self, db: Database) -> None:\n        self._db = db\n\n    async def find_by_id(self, user_id: str) -> User | None:\n        \"\"\"Return User if found, None otherwise.\"\"\"\n        ...\n\n    async def find_by_email(self, email: str) -> User | None:\n        ...\n\n    async def save(self, user: User) -> User:\n        \"\"\"Save and return user with generated ID.\"\"\"\n        ...\n```\n\nUse `mypy --strict` or `pyright` in CI to catch type errors early. For existing projects, enable strict mode incrementally using per-module overrides.\n\n### Pattern 2: Use Modern Union Syntax\n\nPython 3.10+ provides cleaner union syntax.\n\n```python\n# Preferred (3.10+)\ndef find_user(user_id: str) -> User | None:\n    ...\n\ndef parse_value(v: str) -> int | float | str:\n    ...\n\n# Older style (still valid, needed for 3.9)\nfrom typing import Optional, Union\n\ndef find_user(user_id: str) -> Optional[User]:\n    ...\n```\n\n### Pattern 3: Type Narrowing with Guards\n\nUse conditionals to narrow types for the type checker.\n\n```python\ndef process_user(user_id: str) -> UserData:\n    user = find_user(user_id)\n\n    if user is None:\n        raise UserNotFoundError(f\"User {user_id} not found\")\n\n    # Type checker knows user is User here, not User | None\n    return UserData(\n        name=user.name,\n        email=user.email,\n    )\n\ndef process_items(items: list[Item | None]) -> list[ProcessedItem]:\n    # Filter and narrow types\n    valid_items = [item for item in items if item is not None]\n    # valid_items is now list[Item]\n    return [process(item) for item in valid_items]\n```\n\n### Pattern 4: Generic Classes\n\nCreate type-safe reusable containers.\n\n```python\nfrom typing import TypeVar, Generic\n\nT = TypeVar(\"T\")\nE = TypeVar(\"E\", bound=Exception)\n\nclass Result(Generic[T, E]):\n    \"\"\"Represents either a success value or an error.\"\"\"\n\n    def __init__(\n        self,\n        value: T | None = None,\n        error: E | None = None,\n    ) -> None:\n        if (value is None) == (error is None):\n            raise ValueError(\"Exactly one of value or error must be set\")\n        self._value = value\n        self._error = error\n\n    @property\n    def is_success(self) -> bool:\n        return self._error is None\n\n    @property\n    def is_failure(self) -> bool:\n        return self._error is not None\n\n    def unwrap(self) -> T:\n        \"\"\"Get value or raise the error.\"\"\"\n        if self._error is not None:\n            raise self._error\n        return self._value  # type: ignore[return-value]\n\n    def unwrap_or(self, default: T) -> T:\n        \"\"\"Get value or return default.\"\"\"\n        if self._error is not None:\n            return default\n        return self._value  # type: ignore[return-value]\n\n# Usage preserves types\ndef parse_config(path: str) -> Result[Config, ConfigError]:\n    try:\n        return Result(value=Config.from_file(path))\n    except ConfigError as e:\n        return Result(error=e)\n\nresult = parse_config(\"config.yaml\")\nif result.is_success:\n    config = result.unwrap()  # Type: Config\n```\n\n## Advanced Patterns\n\n### Pattern 5: Generic Repository\n\nCreate type-safe data access patterns.\n\n```python\nfrom typing import TypeVar, Generic\nfrom abc import ABC, abstractmethod\n\nT = TypeVar(\"T\")\nID = TypeVar(\"ID\")\n\nclass Repository(ABC, Generic[T, ID]):\n    \"\"\"Generic repository interface.\"\"\"\n\n    @abstractmethod\n    async def get(self, id: ID) -> T | None:\n        \"\"\"Get entity by ID.\"\"\"\n        ...\n\n    @abstractmethod\n    async def save(self, entity: T) -> T:\n        \"\"\"Save and return entity.\"\"\"\n        ...\n\n    @abstractmethod\n    async def delete(self, id: ID) -> bool:\n        \"\"\"Delete entity, return True if existed.\"\"\"\n        ...\n\nclass UserRepository(Repository[User, str]):\n    \"\"\"Concrete repository for Users with string IDs.\"\"\"\n\n    async def get(self, id: str) -> User | None:\n        row = await self._db.fetchrow(\n            \"SELECT * FROM users WHERE id = $1\", id\n        )\n        return User(**row) if row else None\n\n    async def save(self, entity: User) -> User:\n        ...\n\n    async def delete(self, id: str) -> bool:\n        ...\n```\n\n### Pattern 6: TypeVar with Bounds\n\nRestrict generic parameters to specific types.\n\n```python\nfrom typing import TypeVar\nfrom pydantic import BaseModel\n\nModelT = TypeVar(\"ModelT\", bound=BaseModel)\n\ndef validate_and_create(model_cls: type[ModelT], data: dict) -> ModelT:\n    \"\"\"Create a validated Pydantic model from dict.\"\"\"\n    return model_cls.model_validate(data)\n\n# Works with any BaseModel subclass\nclass User(BaseModel):\n    name: str\n    email: str\n\nuser = validate_and_create(User, {\"name\": \"Alice\", \"email\": \"a@b.com\"})\n# user is typed as User\n\n# Type error: str is not a BaseModel subclass\nresult = validate_and_create(str, {\"name\": \"Alice\"})  # Error!\n```\n\n### Pattern 7: Protocols for Structural Typing\n\nDefine interfaces without requiring inheritance.\n\n```python\nfrom typing import Protocol, runtime_checkable\n\n@runtime_checkable\nclass Serializable(Protocol):\n    \"\"\"Any class that can be serialized to\u002Ffrom dict.\"\"\"\n\n    def to_dict(self) -> dict:\n        ...\n\n    @classmethod\n    def from_dict(cls, data: dict) -> \"Serializable\":\n        ...\n\n# User satisfies Serializable without inheriting from it\nclass User:\n    def __init__(self, id: str, name: str) -> None:\n        self.id = id\n        self.name = name\n\n    def to_dict(self) -> dict:\n        return {\"id\": self.id, \"name\": self.name}\n\n    @classmethod\n    def from_dict(cls, data: dict) -> \"User\":\n        return cls(id=data[\"id\"], name=data[\"name\"])\n\ndef serialize(obj: Serializable) -> str:\n    \"\"\"Works with any Serializable object.\"\"\"\n    return json.dumps(obj.to_dict())\n\n# Works - User matches the protocol\nserialize(User(\"1\", \"Alice\"))\n\n# Runtime checking with @runtime_checkable\nisinstance(User(\"1\", \"Alice\"), Serializable)  # True\n```\n\n### Pattern 8: Common Protocol Patterns\n\nDefine reusable structural interfaces.\n\n```python\nfrom typing import Protocol\n\nclass Closeable(Protocol):\n    \"\"\"Resource that can be closed.\"\"\"\n    def close(self) -> None: ...\n\nclass AsyncCloseable(Protocol):\n    \"\"\"Async resource that can be closed.\"\"\"\n    async def close(self) -> None: ...\n\nclass Readable(Protocol):\n    \"\"\"Object that can be read from.\"\"\"\n    def read(self, n: int = -1) -> bytes: ...\n\nclass HasId(Protocol):\n    \"\"\"Object with an ID property.\"\"\"\n    @property\n    def id(self) -> str: ...\n\nclass Comparable(Protocol):\n    \"\"\"Object that supports comparison.\"\"\"\n    def __lt__(self, other: \"Comparable\") -> bool: ...\n    def __le__(self, other: \"Comparable\") -> bool: ...\n```\n\n### Pattern 9: Type Aliases\n\nCreate meaningful type names.\n\n**Note:** The `type` statement was introduced in Python 3.10 for simple aliases. Generic type statements require Python 3.12+.\n\n```python\n# Python 3.10+ type statement for simple aliases\ntype UserId = str\ntype UserDict = dict[str, Any]\n\n# Python 3.12+ type statement with generics\ntype Handler[T] = Callable[[Request], T]\ntype AsyncHandler[T] = Callable[[Request], Awaitable[T]]\n\n# Python 3.9-3.11 style (needed for broader compatibility)\nfrom typing import TypeAlias\nfrom collections.abc import Callable, Awaitable\n\nUserId: TypeAlias = str\nHandler: TypeAlias = Callable[[Request], Response]\n\n# Usage\ndef register_handler(path: str, handler: Handler[Response]) -> None:\n    ...\n```\n\n### Pattern 10: Callable Types\n\nType function parameters and callbacks.\n\n```python\nfrom collections.abc import Callable, Awaitable\n\n# Sync callback\nProgressCallback = Callable[[int, int], None]  # (current, total)\n\n# Async callback\nAsyncHandler = Callable[[Request], Awaitable[Response]]\n\n# With named parameters (using Protocol)\nclass OnProgress(Protocol):\n    def __call__(\n        self,\n        current: int,\n        total: int,\n        *,\n        message: str = \"\",\n    ) -> None: ...\n\ndef process_items(\n    items: list[Item],\n    on_progress: ProgressCallback | None = None,\n) -> list[Result]:\n    for i, item in enumerate(items):\n        if on_progress:\n            on_progress(i, len(items))\n        ...\n```\n\n## Configuration\n\n### Strict Mode Checklist\n\nFor `mypy --strict` compliance:\n\n```toml\n# pyproject.toml\n[tool.mypy]\npython_version = \"3.12\"\nstrict = true\nwarn_return_any = true\nwarn_unused_ignores = true\ndisallow_untyped_defs = true\ndisallow_incomplete_defs = true\nno_implicit_optional = true\n```\n\nIncremental adoption goals:\n- All function parameters annotated\n- All return types annotated\n- Class attributes annotated\n- Minimize `Any` usage (acceptable for truly dynamic data)\n- Generic collections use type parameters (`list[str]` not `list`)\n\nFor existing codebases, enable strict mode per-module using `# mypy: strict` or configure per-module overrides in `pyproject.toml`.\n\n## Best Practices Summary\n\n1. **Annotate all public APIs** - Functions, methods, class attributes\n2. **Use `T | None`** - Modern union syntax over `Optional[T]`\n3. **Run strict type checking** - `mypy --strict` in CI\n4. **Use generics** - Preserve type info in reusable code\n5. **Define protocols** - Structural typing for interfaces\n6. **Narrow types** - Use guards to help the type checker\n7. **Bound type vars** - Restrict generics to meaningful types\n8. **Create type aliases** - Meaningful names for complex types\n9. **Minimize `Any`** - Use specific types or generics. `Any` is acceptable for truly dynamic data or when interfacing with untyped third-party code\n10. **Document with types** - Types are enforceable documentation\n",{"name":5,"description":7},"main","87afe6ce96220accf50a345dea46784c8c9f210e","YYC3-Plugin-插件协议\u002FYYC3-Plugin-插件协议-plugins-claude\u002Fpython-development\u002Fskills\u002Fpython-type-safety",0,"https:\u002F\u002Fgithub.com\u002FYYC-Cube\u002FYYC3-Knowledge-Base","https:\u002F\u002Fkb.yyc3.top\u002F","https:\u002F\u002Fgithub.com\u002FYYC-Cube","万象归元于云枢 | 深栈智启新纪元","2026-11-10 10:37:32",{"source":8,"skillName":5,"commands":34,"prompt":44,"zipAvailable":45},[35,38,41],{"tool":36,"command":37},"npx","npx skills add YYC-Cube\u002FYYC3-Knowledge-Base --skill python-type-safety",{"tool":39,"command":40},"bunx","bunx skills add YYC-Cube\u002FYYC3-Knowledge-Base --skill python-type-safety",{"tool":42,"command":43},"pnpm","pnpm dlx skills add YYC-Cube\u002FYYC3-Knowledge-Base --skill python-type-safety","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FYYC-Cube\u002FYYC3-Knowledge-Base\u002Fblob\u002Fmain\u002FYYC3-Plugin-插件协议\u002FYYC3-Plugin-插件协议-plugins-claude\u002Fpython-development\u002Fskills\u002Fpython-type-safety\u002FSKILL.md",true,[],[48,55,62,69,76,83],{"skillNo":49,"name":50,"nameZh":6,"description":51,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":52,"categories":53,"keywords":54,"publishedAt":19},"01M7CTDWHERCXPQCP0K03A86AS","vercel-sandbox","Run agent-browser + Chrome inside Vercel Sandbox microVMs for browser automation from any Vercel-deployed app. Use when the user needs browser automation in a Vercel app (Next.js, SvelteKit, Nuxt, Remix, Astro, etc.), wants to run headless Chrome without binary size limits, needs persistent browser sessions across commands, or wants ephemeral isolated browser environments. Triggers include \"Vercel Sandbox browser\", \"microVM Chrome\", \"agent-browser in sandbox\", \"browser automation on Vercel\", or any task requiring Chrome in a Vercel Sandbox.","https:\u002F\u002Fgithub.com\u002FYYC-Cube\u002FYYC3-Knowledge-Base\u002Fblob\u002Fmain\u002FYYC3-WebSpec-Web标准\u002FYYC3-WebSpec-Web标准-standards\u002Fbrowser-agent\u002Fskills\u002Fvercel-sandbox\u002FSKILL.md",[],[],{"skillNo":56,"name":57,"nameZh":6,"description":58,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":59,"categories":60,"keywords":61,"publishedAt":19},"01M7CTD8D2BNJY54S65M47HEJA","slack","Interact with Slack workspaces using browser automation. Use when the user needs to check unread channels, navigate Slack, send messages, extract data, find information, search conversations, or automate any Slack task. Triggers include \"check my Slack\", \"what channels have unreads\", \"send a message to\", \"search Slack for\", \"extract from Slack\", \"find who said\", or any task requiring programmatic Slack interaction.","https:\u002F\u002Fgithub.com\u002FYYC-Cube\u002FYYC3-Knowledge-Base\u002Fblob\u002Fmain\u002FYYC3-WebSpec-Web标准\u002FYYC3-WebSpec-Web标准-standards\u002Fbrowser-agent\u002Fskills\u002Fslack\u002FSKILL.md",[],[],{"skillNo":63,"name":64,"nameZh":6,"description":65,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":66,"categories":67,"keywords":68,"publishedAt":19},"01M7CTCSSB8ZP3Q58C3YZDZK1W","electron","Automate Electron desktop apps (VS Code, Slack, Discord, Figma, Notion, Spotify, etc.) using agent-browser via Chrome DevTools Protocol. Use when the user needs to interact with an Electron app, automate a desktop app, connect to a running app, control a native app, or test an Electron application. Triggers include \"automate Slack app\", \"control VS Code\", \"interact with Discord app\", \"test this Electron app\", \"connect to desktop app\", or any task requiring automation of a native Electron application.","https:\u002F\u002Fgithub.com\u002FYYC-Cube\u002FYYC3-Knowledge-Base\u002Fblob\u002Fmain\u002FYYC3-WebSpec-Web标准\u002FYYC3-WebSpec-Web标准-standards\u002Fbrowser-agent\u002Fskills\u002Felectron\u002FSKILL.md",[],[],{"skillNo":70,"name":71,"nameZh":6,"description":72,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":73,"categories":74,"keywords":75,"publishedAt":19},"01M7CTCBJY76688V4DCZGWFHGQ","dogfood","Systematically explore and test a web application to find bugs, UX issues, and other problems. Use when asked to \"dogfood\", \"QA\", \"exploratory test\", \"find issues\", \"bug hunt\", \"test this app\u002Fsite\u002Fplatform\", or review the quality of a web application. Produces a structured report with full reproduction evidence -- step-by-step screenshots, repro videos, and detailed repro steps for every issue -- so findings can be handed directly to the responsible teams.","https:\u002F\u002Fgithub.com\u002FYYC-Cube\u002FYYC3-Knowledge-Base\u002Fblob\u002Fmain\u002FYYC3-WebSpec-Web标准\u002FYYC3-WebSpec-Web标准-standards\u002Fbrowser-agent\u002Fskills\u002Fdogfood\u002FSKILL.md",[],[],{"skillNo":77,"name":78,"nameZh":6,"description":79,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":80,"categories":81,"keywords":82,"publishedAt":19},"01M7CTC4H0FFGVEAQR9PA4GA1A","agent-browser","Browser automation CLI for AI agents. Use when the user needs to interact with websites, including navigating pages, filling forms, clicking buttons, taking screenshots, extracting data, testing web apps, or automating any browser task. Triggers include requests to \"open a website\", \"fill out a form\", \"click a button\", \"take a screenshot\", \"scrape data from a page\", \"test this web app\", \"login to a site\", \"automate browser actions\", or any task requiring programmatic web interaction.","https:\u002F\u002Fgithub.com\u002FYYC-Cube\u002FYYC3-Knowledge-Base\u002Fblob\u002Fmain\u002FYYC3-WebSpec-Web标准\u002FYYC3-WebSpec-Web标准-standards\u002Fbrowser-agent\u002Fskills\u002Fagent-browser\u002FSKILL.md",[],[],{"skillNo":84,"name":85,"nameZh":6,"description":86,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":87,"categories":88,"keywords":89,"publishedAt":19},"01M7CTBKVFYBG78FDSABSDJTTQ","shadcn","Manages shadcn components and projects — adding, searching, fixing, debugging, styling, and composing UI, including chat interfaces. Provides project context, component docs, and usage examples. Applies when working with shadcn\u002Fui, component registries, presets, --preset codes, or any project with a components.json file. Also triggers for \"shadcn init\", \"create an app with --preset\", \"switch to --preset\", and for building a design system or applying a DESIGN.md or brand spec to shadcn\u002Fui.","https:\u002F\u002Fgithub.com\u002FYYC-Cube\u002FYYC3-Knowledge-Base\u002Fblob\u002Fmain\u002FYYC3-UI-界面组件\u002FYYC3-UI-界面组件-ui\u002Fskills\u002Fshadcn\u002FSKILL.md",[],[]]