feat: improved the Claude Kit as a plugin

2026-06-10 20:24:57 +03:00 · 2026-04-19 14:09:14 +07:00
parent 3103a8da1b
commit d1a6d2a2bc
186 changed files with 771 additions and 1691 deletions
@@ -0,0 +1,697 @@
+# Languages — Python Patterns
+
+
+# Python
+
+## When to Use
+
+- Working with Python files (.py)
+- Writing Python scripts or applications
+- Using Python frameworks (Django, FastAPI, Flask)
+- Data processing and automation
+
+## When NOT to Use
+
+- JavaScript or TypeScript-only projects with no Python components
+- Non-Python environments where another language skill is more appropriate
+
+---
+
+## Core Patterns
+
+### 1. Type Hints
+
+Use type hints on all public functions and module-level variables. Python 3.10+ syntax is preferred (use `X | Y` instead of `Union[X, Y]`).
+
+#### Basic Types
+
+```python
+from typing import Any
+
+def greet(name: str) -> str:
+    return f"Hello, {name}"
+
+def process(count: int, factor: float = 1.0) -> float:
+    return count * factor
+
+def is_valid(data: bytes | None) -> bool:
+    return data is not None and len(data) > 0
+```
+
+#### Optional and Union
+
+```python
+# Python 3.10+ syntax (preferred)
+def find_user(user_id: int) -> User | None:
+    ...
+
+# Pre-3.10 fallback
+from typing import Optional, Union
+
+def find_user(user_id: int) -> Optional[User]:
+    ...
+
+def parse_input(value: Union[str, int]) -> str:
+    return str(value)
+```
+
+#### Generic Collections
+
+```python
+# Python 3.9+ built-in generics (preferred)
+def process_items(items: list[str]) -> dict[str, int]:
+    return {item: len(item) for item in items}
+
+def merge_configs(base: dict[str, Any], overrides: dict[str, Any]) -> dict[str, Any]:
+    return {**base, **overrides}
+
+# Nested generics
+def group_by_key(pairs: list[tuple[str, int]]) -> dict[str, list[int]]:
+    result: dict[str, list[int]] = {}
+    for key, value in pairs:
+        result.setdefault(key, []).append(value)
+    return result
+```
+
+#### Protocol for Structural Subtyping
+
+```python
+from typing import Protocol, runtime_checkable
+
+@runtime_checkable
+class Renderable(Protocol):
+    def render(self) -> str: ...
+
+class HtmlWidget:
+    def render(self) -> str:
+        return "<div>widget</div>"
+
+def display(item: Renderable) -> None:
+    print(item.render())
+
+# HtmlWidget satisfies Renderable without inheriting from it
+display(HtmlWidget())  # works
+```
+
+#### TypeVar for Generic Functions
+
+```python
+from typing import TypeVar, Sequence
+
+T = TypeVar("T")
+
+def first(items: Sequence[T]) -> T:
+    return items[0]
+
+# Bounded TypeVar
+Numeric = TypeVar("Numeric", int, float)
+
+def clamp(value: Numeric, low: Numeric, high: Numeric) -> Numeric:
+    return max(low, min(high, value))
+```
+
+#### @overload for Multiple Signatures
+
+```python
+from typing import overload
+
+@overload
+def parse(raw: str) -> dict[str, Any]: ...
+@overload
+def parse(raw: bytes) -> dict[str, Any]: ...
+@overload
+def parse(raw: str, as_list: bool) -> list[Any]: ...
+
+def parse(raw: str | bytes, as_list: bool = False) -> dict[str, Any] | list[Any]:
+    data = raw if isinstance(raw, str) else raw.decode()
+    parsed = json.loads(data)
+    return list(parsed) if as_list else parsed
+```
+
+#### TypeAlias and TypeGuard
+
+```python
+from typing import TypeAlias, TypeGuard
+
+# TypeAlias for complex types
+JsonValue: TypeAlias = str | int | float | bool | None | list["JsonValue"] | dict[str, "JsonValue"]
+Headers: TypeAlias = dict[str, str]
+
+# TypeGuard for narrowing
+def is_string_list(val: list[Any]) -> TypeGuard[list[str]]:
+    return all(isinstance(item, str) for item in val)
+
+def process(items: list[Any]) -> None:
+    if is_string_list(items):
+        # items is now list[str] inside this branch
+        print(", ".join(items))
+```
+
+---
+
+### 2. Dataclasses & Pydantic
+
+#### @dataclass with Options
+
+```python
+from dataclasses import dataclass, field
+from datetime import datetime
+
+@dataclass
+class User:
+    id: int
+    email: str
+    name: str
+    created_at: datetime = field(default_factory=datetime.now)
+    tags: list[str] = field(default_factory=list)
+
+    def __post_init__(self):
+        self.email = self.email.strip().lower()
+```
+
+#### Frozen and Slots
+
+```python
+@dataclass(frozen=True, slots=True)
+class Coordinate:
+    """Immutable, memory-efficient value object."""
+    x: float
+    y: float
+
+    @property
+    def magnitude(self) -> float:
+        return (self.x ** 2 + self.y ** 2) ** 0.5
+```
+
+#### Pydantic BaseModel
+
+```python
+from pydantic import BaseModel, EmailStr, Field, field_validator, computed_field, model_validator
+
+class UserCreate(BaseModel):
+    model_config = {"str_strip_whitespace": True, "frozen": False}
+
+    email: EmailStr
+    name: str = Field(min_length=1, max_length=100)
+    password: str = Field(min_length=8)
+    age: int = Field(ge=0, le=150)
+
+    @field_validator("name")
+    @classmethod
+    def name_must_not_be_blank(cls, v: str) -> str:
+        if not v.strip():
+            raise ValueError("Name must not be blank")
+        return v.title()
+
+    @computed_field
+    @property
+    def display_name(self) -> str:
+        return f"{self.name} <{self.email}>"
+
+    @model_validator(mode="after")
+    def check_consistency(self) -> "UserCreate":
+        if "admin" in self.name.lower() and self.age < 18:
+            raise ValueError("Admins must be 18+")
+        return self
+```
+
+---
+
+### 3. Async Patterns
+
+#### Basic async/await
+
+```python
+import asyncio
+import aiohttp
+
+async def fetch_json(url: str) -> dict:
+    async with aiohttp.ClientSession() as session:
+        async with session.get(url) as response:
+            response.raise_for_status()
+            return await response.json()
+```
+
+#### asyncio.gather for Parallel Work
+
+```python
+async def fetch_all(urls: list[str]) -> list[dict]:
+    return await asyncio.gather(*[fetch_json(url) for url in urls])
+```
+
+#### asyncio.TaskGroup (Python 3.11+)
+
+```python
+async def fetch_all_safe(urls: list[str]) -> list[dict]:
+    results: list[dict] = []
+    async with asyncio.TaskGroup() as tg:
+        for url in urls:
+            tg.create_task(fetch_and_append(url, results))
+    return results
+
+async def fetch_and_append(url: str, results: list[dict]) -> None:
+    data = await fetch_json(url)
+    results.append(data)
+```
+
+#### Async Generators
+
+```python
+async def paginate(url: str) -> AsyncIterator[dict]:
+    page = 1
+    while True:
+        data = await fetch_json(f"{url}?page={page}")
+        if not data["items"]:
+            break
+        for item in data["items"]:
+            yield item
+        page += 1
+
+# Usage
+async for item in paginate("/api/users"):
+    process(item)
+```
+
+#### Async Context Managers
+
+```python
+from contextlib import asynccontextmanager
+
+@asynccontextmanager
+async def db_transaction(pool):
+    conn = await pool.acquire()
+    tx = await conn.begin()
+    try:
+        yield conn
+        await tx.commit()
+    except Exception:
+        await tx.rollback()
+        raise
+    finally:
+        await pool.release(conn)
+```
+
+#### Semaphores for Concurrency Limiting
+
+```python
+async def fetch_with_limit(urls: list[str], max_concurrent: int = 10) -> list[dict]:
+    semaphore = asyncio.Semaphore(max_concurrent)
+
+    async def limited_fetch(url: str) -> dict:
+        async with semaphore:
+            return await fetch_json(url)
+
+    return await asyncio.gather(*[limited_fetch(url) for url in urls])
+```
+
+---
+
+### 4. Decorators
+
+#### Function Decorator with functools.wraps
+
+```python
+import functools
+import time
+
+def timing(func):
+    @functools.wraps(func)
+    def wrapper(*args, **kwargs):
+        start = time.perf_counter()
+        result = func(*args, **kwargs)
+        elapsed = time.perf_counter() - start
+        print(f"{func.__name__} took {elapsed:.4f}s")
+        return result
+    return wrapper
+
+@timing
+def slow_operation():
+    time.sleep(1)
+```
+
+#### Decorator with Arguments
+
+```python
+def retry(max_attempts: int = 3, delay: float = 1.0):
+    def decorator(func):
+        @functools.wraps(func)
+        async def wrapper(*args, **kwargs):
+            last_error: Exception | None = None
+            for attempt in range(max_attempts):
+                try:
+                    return await func(*args, **kwargs)
+                except Exception as e:
+                    last_error = e
+                    if attempt < max_attempts - 1:
+                        await asyncio.sleep(delay * (2 ** attempt))
+            raise last_error
+        return wrapper
+    return decorator
+
+@retry(max_attempts=5, delay=0.5)
+async def unreliable_call(url: str) -> dict:
+    return await fetch_json(url)
+```
+
+#### Class Decorator
+
+```python
+def singleton(cls):
+    instances: dict[type, Any] = {}
+
+    @functools.wraps(cls)
+    def get_instance(*args, **kwargs):
+        if cls not in instances:
+            instances[cls] = cls(*args, **kwargs)
+        return instances[cls]
+
+    return get_instance
+
+@singleton
+class AppConfig:
+    def __init__(self):
+        self.settings = load_settings()
+```
+
+#### Caching Decorator
+
+```python
+from functools import lru_cache, cache
+
+@lru_cache(maxsize=256)
+def fibonacci(n: int) -> int:
+    if n < 2:
+        return n
+    return fibonacci(n - 1) + fibonacci(n - 2)
+
+# Python 3.9+ unbounded cache
+@cache
+def load_config(path: str) -> dict:
+    with open(path) as f:
+        return json.load(f)
+```
+
+---
+
+### 5. Context Managers
+
+#### Basic @contextmanager
+
+```python
+from contextlib import contextmanager
+
+@contextmanager
+def managed_connection(dsn: str):
+    conn = connect(dsn)
+    try:
+        yield conn
+    finally:
+        conn.close()
+
+with managed_connection("postgres://...") as conn:
+    conn.execute("SELECT 1")
+```
+
+#### Temporary File Context Manager
+
+```python
+import tempfile
+import os
+
+@contextmanager
+def temp_directory():
+    dirpath = tempfile.mkdtemp()
+    try:
+        yield dirpath
+    finally:
+        shutil.rmtree(dirpath)
+
+with temp_directory() as tmpdir:
+    filepath = os.path.join(tmpdir, "data.json")
+    write_json(filepath, data)
+```
+
+#### Lock Context Manager
+
+```python
+import threading
+
+@contextmanager
+def timed_lock(lock: threading.Lock, timeout: float = 5.0):
+    acquired = lock.acquire(timeout=timeout)
+    if not acquired:
+        raise TimeoutError("Could not acquire lock")
+    try:
+        yield
+    finally:
+        lock.release()
+```
+
+#### Async Context Manager
+
+```python
+from contextlib import asynccontextmanager
+
+@asynccontextmanager
+async def http_session():
+    session = aiohttp.ClientSession()
+    try:
+        yield session
+    finally:
+        await session.close()
+```
+
+---
+
+### 6. Pattern Matching
+
+#### Basic match/case
+
+```python
+def handle_command(command: str) -> str:
+    match command.split():
+        case ["quit"]:
+            return "Goodbye"
+        case ["hello", name]:
+            return f"Hello, {name}"
+        case ["add", *items]:
+            return f"Adding {len(items)} items"
+        case _:
+            return "Unknown command"
+```
+
+#### Structural Patterns
+
+```python
+def process_event(event: dict) -> None:
+    match event:
+        case {"type": "click", "x": int(x), "y": int(y)}:
+            handle_click(x, y)
+        case {"type": "keypress", "key": str(key)} if len(key) == 1:
+            handle_keypress(key)
+        case {"type": "resize", "width": w, "height": h}:
+            handle_resize(w, h)
+```
+
+#### Guard Clauses and OR Patterns
+
+```python
+def classify_status(code: int) -> str:
+    match code:
+        case 200 | 201 | 204:
+            return "success"
+        case code if 300 <= code < 400:
+            return "redirect"
+        case 401 | 403:
+            return "auth_error"
+        case code if 400 <= code < 500:
+            return "client_error"
+        case code if 500 <= code < 600:
+            return "server_error"
+        case _:
+            return "unknown"
+```
+
+---
+
+### 7. Error Handling
+
+#### Custom Exception Hierarchies
+
+```python
+class AppError(Exception):
+    """Base exception for the application."""
+    def __init__(self, message: str, code: str | None = None):
+        super().__init__(message)
+        self.code = code
+
+class NotFoundError(AppError):
+    """Resource was not found."""
+    def __init__(self, resource: str, resource_id: str):
+        super().__init__(f"{resource} {resource_id} not found", code="NOT_FOUND")
+        self.resource = resource
+        self.resource_id = resource_id
+
+class ValidationError(AppError):
+    """Input validation failed."""
+    def __init__(self, errors: list[str]):
+        super().__init__(f"Validation failed: {'; '.join(errors)}", code="VALIDATION")
+        self.errors = errors
+```
+
+#### ExceptionGroup (Python 3.11+)
+
+```python
+async def process_batch(items: list[dict]) -> list[dict]:
+    results = []
+    errors = []
+    for item in items:
+        try:
+            results.append(await process(item))
+        except Exception as e:
+            errors.append(e)
+    if errors:
+        raise ExceptionGroup("Batch processing errors", errors)
+    return results
+
+# Handling with except*
+try:
+    await process_batch(items)
+except* ValueError as eg:
+    print(f"Validation errors: {len(eg.exceptions)}")
+except* ConnectionError as eg:
+    print(f"Connection errors: {len(eg.exceptions)}")
+```
+
+#### Exception Chaining
+
+```python
+def load_config(path: str) -> dict:
+    try:
+        with open(path) as f:
+            return json.load(f)
+    except FileNotFoundError as e:
+        raise AppError(f"Config file missing: {path}") from e
+    except json.JSONDecodeError as e:
+        raise AppError(f"Invalid JSON in {path}") from e
+```
+
+#### contextlib.suppress
+
+```python
+from contextlib import suppress
+
+# Instead of try/except/pass
+with suppress(FileNotFoundError):
+    os.remove("temp_file.txt")
+
+# Instead of:
+# try:
+#     os.remove("temp_file.txt")
+# except FileNotFoundError:
+#     pass
+```
+
+---
+
+## Best Practices
+
+1. **Use type hints on all public functions** -- they serve as documentation, enable IDE autocompletion, and allow static analysis with mypy or pyright.
+
+2. **Prefer dataclasses or Pydantic for structured data** -- avoid passing raw dicts around. Use `@dataclass` for internal data, Pydantic `BaseModel` for external boundaries (API input/output, config files).
+
+3. **Use context managers for resource management** -- database connections, file handles, locks, and temporary resources should always be wrapped in `with` statements to guarantee cleanup.
+
+4. **Prefer `asyncio.TaskGroup` over bare `gather`** -- TaskGroup (3.11+) provides proper error handling by cancelling sibling tasks when one fails, avoiding orphaned coroutines.
+
+5. **Follow PEP 8 and use a formatter** -- use `ruff format` or `black` for consistent formatting, and `ruff check` for linting. Configure in `pyproject.toml`.
+
+6. **Write small, composable functions** -- each function should do one thing. Prefer returning values over mutating state. Limit functions to ~20 lines when practical.
+
+7. **Use `__all__` in public modules** -- explicitly declare the public API of a module to prevent accidental imports of internal helpers.
+
+8. **Use `pathlib.Path` over `os.path`** -- pathlib provides a cleaner, object-oriented API for file system operations and works cross-platform.
+
+---
+
+## Common Pitfalls
+
+1. **Mutable default arguments** -- default values are shared across calls. Use `None` and initialize inside the function body.
+   ```python
+   # BAD
+   def add_item(item: str, items: list[str] = []) -> list[str]: ...
+
+   # GOOD
+   def add_item(item: str, items: list[str] | None = None) -> list[str]:
+       if items is None:
+           items = []
+       items.append(item)
+       return items
+   ```
+
+2. **Blocking calls inside async functions** -- calling `time.sleep()`, `requests.get()`, or CPU-heavy code in an async function blocks the entire event loop. Use `asyncio.to_thread()` or `asyncio.sleep()`.
+   ```python
+   # BAD
+   async def fetch():
+       return requests.get(url)  # blocks event loop
+
+   # GOOD
+   async def fetch():
+       return await asyncio.to_thread(requests.get, url)
+   ```
+
+3. **Catching bare `Exception`** -- always be specific about which exceptions you catch. Bare `except:` or `except Exception:` hides bugs.
+   ```python
+   # BAD
+   try:
+       result = compute()
+   except Exception:
+       pass
+
+   # GOOD
+   try:
+       result = compute()
+   except (ValueError, TypeError) as e:
+       logger.warning("Computation failed: %s", e)
+       result = default_value
+   ```
+
+4. **Using `is` for value comparison** -- `is` checks identity, not equality. Only use `is` for `None`, `True`, `False`, and sentinel objects.
+   ```python
+   # BAD
+   if x is 42: ...
+
+   # GOOD
+   if x == 42: ...
+   if x is None: ...
+   ```
+
+5. **Forgetting to close resources** -- file handles, database connections, and HTTP sessions leak if not closed. Always use context managers.
+   ```python
+   # BAD
+   f = open("data.txt")
+   data = f.read()
+
+   # GOOD
+   with open("data.txt") as f:
+       data = f.read()
+   ```
+
+6. **Circular imports** -- restructure code to avoid circular dependencies. Move shared types into a separate module, use `TYPE_CHECKING` for type-only imports, or use lazy imports.
+   ```python
+   from __future__ import annotations
+   from typing import TYPE_CHECKING
+
+   if TYPE_CHECKING:
+       from myapp.models import User  # only imported during type checking
+   ```
+
+---
+
+## Related Skills
+
+- `typescript` -- TypeScript language patterns for polyglot projects
+- `fastapi` -- FastAPI web framework built on Python
+- `django` -- Django web framework for Python
+- `pytest` -- Python testing with pytest
+- `error-handling` -- Python error handling and exception hierarchies