[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6CD30N0A01RYFGY5XQWXAF4":3,"skill-same:01M6CD30N0A01RYFGY5XQWXAF4":66},{"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":34,"linkOnly":35,"markdownContent":36,"markdownBody":37,"frontMatter":38,"refName":40,"commitSha":41,"skillDirectory":42,"forksCount":43,"repositoryHtmlUrl":44,"repositoryHomepageUrl":6,"ownerHtmlUrl":45,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":46,"install":47,"resources":59},"01M6CD30N0A01RYFGY5XQWXAF4","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.","cercova-studios\u002F10x-swe","cercova-studios","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F217108198?v=4","01M6CCYGHXTH80N3BXRW6KESTE","Cercova Studios","01M6CCYGPADH5MJDR0VNNR775C",1,"MIT","https:\u002F\u002Fgithub.com\u002Fcercova-studios\u002F10x-swe\u002Fblob\u002Fmain\u002Fplugins\u002F10x-swe\u002Fskills\u002Fpython-type-safety\u002FSKILL.md",[],[19,20,21,22,23,24,25,26,27,28,29,30,31,32,33],"Type Safety","python","Safety","python type safety","type","protocols","use","annotations","generic","structural","implementing","when","with","mypy","pyright","2026-11-10 10:12:30",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.\ndisable-model-invocation: true\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,"disable-model-invocation":39},true,"main","224d7699a283a75bd3f75d4d8b03b15aca0ae309","plugins\u002F10x-swe\u002Fskills\u002Fpython-type-safety",0,"https:\u002F\u002Fgithub.com\u002Fcercova-studios\u002F10x-swe","https:\u002F\u002Fgithub.com\u002Fcercova-studios","2026-11-12 07:39:44",{"source":8,"skillName":5,"commands":48,"prompt":58,"zipAvailable":39},[49,52,55],{"tool":50,"command":51},"npx","npx skills add cercova-studios\u002F10x-swe --skill python-type-safety",{"tool":53,"command":54},"bunx","bunx skills add cercova-studios\u002F10x-swe --skill python-type-safety",{"tool":56,"command":57},"pnpm","pnpm dlx skills add cercova-studios\u002F10x-swe --skill python-type-safety","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fcercova-studios\u002F10x-swe\u002Fblob\u002Fmain\u002Fplugins\u002F10x-swe\u002Fskills\u002Fpython-type-safety\u002FSKILL.md",[60],{"path":61,"resourceType":62,"resourceTypeDesc":63,"sizeBytes":64,"sourceHtmlUrl":65},"agents\u002Fopenai.yaml","REFERENCE","参考文档",43,"https:\u002F\u002Fgithub.com\u002Fcercova-studios\u002F10x-swe\u002Fblob\u002Fmain\u002Fplugins\u002F10x-swe\u002Fskills\u002Fpython-type-safety\u002Fagents\u002Fopenai.yaml",[67,107,142,162,181,193],{"skillNo":68,"name":69,"nameZh":6,"description":70,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":71,"licenseFileUrl":72,"sourceHtmlUrl":73,"categories":74,"keywords":80,"publishedAt":34},"01M6CD3T6EQ9N5KPNXCM6ABHVA","turnstile-spin","Set up Cloudflare Turnstile end-to-end in a project. Scan the codebase, create the widget via the Cloudflare API, embed it where user requests need bot verification (form submissions, SPA actions, API endpoints, download links, comment or vote submissions, etc.), wire canonical server-side siteverify in the customer's existing backend, validate, and persist the skill. Load this when a user asks to add Turnstile, set up CAPTCHA, protect a form or endpoint from bots, or fix a Turnstile integration. Uses Cloudflare's documented Turnstile contract.","Apache-2.0","https:\u002F\u002Fgithub.com\u002Fcercova-studios\u002F10x-swe\u002Fblob\u002Fmain\u002Fplugins\u002F10x-swe\u002Fskills\u002Fturnstile-spin\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fcercova-studios\u002F10x-swe\u002Fblob\u002Fmain\u002Fplugins\u002F10x-swe\u002Fskills\u002Fturnstile-spin\u002FSKILL.md",[75],{"categoryNo":76,"categoryName":77,"taxonomyType":78,"taxonomyTypeDesc":79},"01JBSEEDCAT000000000000010","后端与接口","SCENARIO","使用场景",[81,82,83,84,85,86,87,88,89,90,91,92,93,94,95,96,97,98,99,100,101,102,103,104,105,106,30],"turnstile spin","SET","nextjs","actions","up","fix","cloudflare","bot","api","permissions","create","astro","server","verification","plugin","endpoints","customer","backend","sveltekit","integration","app","bots","spa","project","end","SWE",{"skillNo":108,"name":109,"nameZh":6,"description":110,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":71,"licenseFileUrl":111,"sourceHtmlUrl":112,"categories":113,"keywords":125,"publishedAt":34},"01M6CD0BJYRNV610HYYPX933RE","frontend-design","Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.","https:\u002F\u002Fgithub.com\u002Fcercova-studios\u002F10x-swe\u002Fblob\u002Fmain\u002Fplugins\u002F10x-swe\u002Fskills\u002Ffrontend-design\u002FLICENSE.txt","https:\u002F\u002Fgithub.com\u002Fcercova-studios\u002F10x-swe\u002Fblob\u002Fmain\u002Fplugins\u002F10x-swe\u002Fskills\u002Ffrontend-design\u002FSKILL.md",[114,117,120],{"categoryNo":115,"categoryName":116,"taxonomyType":78,"taxonomyTypeDesc":79},"01JBSEEDCAT000000000000009","前端开发",{"categoryNo":118,"categoryName":119,"taxonomyType":78,"taxonomyTypeDesc":79},"01JBSEEDCAT000000000000015","视觉设计",{"categoryNo":121,"categoryName":122,"taxonomyType":123,"taxonomyTypeDesc":124},"01JBSEEDCAT000000000000032","设计师","PROFESSION","适用职业",[126,127,128,91,129,130,131,132,133,134,25,135,136,137,27,138,139,30,31,140,141],"frontend design","frontend","design","web","quality","applications","creative","web components","Production","code","components","user","aesthetics","pages","high","build",{"skillNo":143,"name":144,"nameZh":6,"description":145,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":146,"categories":147,"keywords":148,"publishedAt":34},"01M6CD4QX8C4DST98AY21HEYCM","source-insights","Prepare inspected source evidence, preserve exact citations, and publish reviewed insights into an explicit local library.","https:\u002F\u002Fgithub.com\u002Fcercova-studios\u002F10x-swe\u002Fblob\u002Fmain\u002Fplugins\u002Fknowledge\u002Fskills\u002Fsource-insights\u002FSKILL.md",[],[149,150,151,152,153,154,155,156,157,158,159,160,161],"source insights","insights","source","publish","Citations","evidence","library","workflows","prepare","session","global","local","preserve",{"skillNo":163,"name":164,"nameZh":6,"description":165,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":166,"categories":167,"keywords":171,"publishedAt":34},"01M6CD4N1HVNC1EXPEBZT7YS31","skill-graph","Discover skills and workflows through independent lexical search, relationship paths and a terminal graph.","https:\u002F\u002Fgithub.com\u002Fcercova-studios\u002F10x-swe\u002Fblob\u002Fmain\u002Fplugins\u002Fknowledge\u002Fskills\u002Fskill-graph\u002FSKILL.md",[168],{"categoryNo":169,"categoryName":170,"taxonomyType":78,"taxonomyTypeDesc":79},"01JBSEEDCAT000000000000023","Skill与智能体开发",[172,173,95,156,174,175,176,159,177,178,179,106,180],"graph","skill graph","terminal","10x","search","discover skills","discover","paths","relationship",{"skillNo":182,"name":183,"nameZh":6,"description":184,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":185,"categories":186,"keywords":187,"publishedAt":34},"01M6CD4HQKXNZ57YEGD8QVK6Z6","session-search","Recall public session turns with exact provenance, bounded excerpts and independent piped exports.","https:\u002F\u002Fgithub.com\u002Fcercova-studios\u002F10x-swe\u002Fblob\u002Fmain\u002Fplugins\u002Fknowledge\u002Fskills\u002Fsession-search\u002FSKILL.md",[],[176,158,188,189,156,190,191,159,31,150,151,192],"session search","public","provenance","recall","bounded",{"skillNo":194,"name":195,"nameZh":6,"description":196,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":197,"categories":198,"keywords":205,"publishedAt":34},"01M6CD4ET7DVNBYPDAMAYMSK2T","newsletter","Produce a private local AI newsletter from bounded public research, with cited deep dives, HTML\u002FMarkdown output, Dagu scheduling and seven-day retention.","https:\u002F\u002Fgithub.com\u002Fcercova-studios\u002F10x-swe\u002Fblob\u002Fmain\u002Fplugins\u002Fknowledge\u002Fskills\u002Fnewsletter\u002FSKILL.md",[199,202],{"categoryNo":200,"categoryName":201,"taxonomyType":78,"taxonomyTypeDesc":79},"01JBSEEDCAT000000000000005","邮件与沟通",{"categoryNo":203,"categoryName":204,"taxonomyType":78,"taxonomyTypeDesc":79},"01JBSEEDCAT000000000000021","资料检索与研究",[195,206,207,208,209,189,156,210,211,212,213,159,31,214,215,160,192,216],"local ai","dagu","produce","research","markdown","scheduling","html","daily","deep","retention","output"]