@mytechtoday/augment-extensions 0.2.0 → 0.5.0

package/augment-extensions/coding-standards/python/rules/tooling.md

@@ -0,0 +1,446 @@
+# Python Development Tooling
+
+Essential tools for Python development: Black, mypy, and Ruff.
+
+## Black - Code Formatter
+
+Black is an opinionated code formatter that enforces consistent style.
+
+### Installation
+
+```bash
+pip install black
+```
+
+### Configuration
+
+```toml
+# pyproject.toml
+[tool.black]
+line-length = 88
+target-version = ['py310']
+include = '\.pyi?$'
+extend-exclude = '''
+/(
+  # directories
+  \.eggs
+  | \.git
+  | \.hg
+  | \.mypy_cache
+  | \.tox
+  | \.venv
+  | build
+  | dist
+)/
+'''
+```
+
+### Usage
+
+```bash
+# Format a file
+black myfile.py
+
+# Format a directory
+black src/
+
+# Check without modifying
+black --check src/
+
+# Show diff
+black --diff src/
+```
+
+### Pre-commit Hook
+
+```yaml
+# .pre-commit-config.yaml
+repos:
+  - repo: https://github.com/psf/black
+    rev: 23.12.1
+    hooks:
+      - id: black
+        language_version: python3.10
+```
+
+## mypy - Static Type Checker
+
+mypy performs static type checking based on type hints.
+
+### Installation
+
+```bash
+pip install mypy
+```
+
+### Configuration
+
+```toml
+# pyproject.toml
+[tool.mypy]
+python_version = "3.10"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+disallow_any_unimported = false
+no_implicit_optional = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+warn_no_return = true
+check_untyped_defs = true
+strict_equality = true
+
+# Per-module options
+[[tool.mypy.overrides]]
+module = "tests.*"
+disallow_untyped_defs = false
+```
+
+### Usage
+
+```bash
+# Check a file
+mypy myfile.py
+
+# Check a package
+mypy src/
+
+# Check with specific config
+mypy --config-file mypy.ini src/
+
+# Show error codes
+mypy --show-error-codes src/
+```
+
+### Common Type Checking Patterns
+
+```python
+# Ignore specific line
+result = some_function()  # type: ignore
+
+# Ignore specific error
+result = some_function()  # type: ignore[arg-type]
+
+# Assert type for mypy
+from typing import cast
+value = cast(str, some_value)
+
+# Reveal type (for debugging)
+reveal_type(my_variable)  # mypy will show the inferred type
+```
+
+## Ruff - Fast Python Linter
+
+Ruff is an extremely fast Python linter written in Rust, replacing Flake8, isort, and more.
+
+### Installation
+
+```bash
+pip install ruff
+```
+
+### Configuration
+
+```toml
+# pyproject.toml
+[tool.ruff]
+# Same as Black
+line-length = 88
+indent-width = 4
+
+# Python version
+target-version = "py310"
+
+# Exclude directories
+exclude = [
+    ".bzr",
+    ".direnv",
+    ".eggs",
+    ".git",
+    ".git-rewrite",
+    ".hg",
+    ".mypy_cache",
+    ".nox",
+    ".pants.d",
+    ".pytype",
+    ".ruff_cache",
+    ".svn",
+    ".tox",
+    ".venv",
+    "__pypackages__",
+    "_build",
+    "buck-out",
+    "build",
+    "dist",
+    "node_modules",
+    "venv",
+]
+
+[tool.ruff.lint]
+# Enable rules
+select = [
+    "E",   # pycodestyle errors
+    "W",   # pycodestyle warnings
+    "F",   # pyflakes
+    "I",   # isort
+    "B",   # flake8-bugbear
+    "C4",  # flake8-comprehensions
+    "UP",  # pyupgrade
+    "ARG", # flake8-unused-arguments
+    "SIM", # flake8-simplify
+]
+
+# Ignore specific rules
+ignore = [
+    "E501",  # line too long (handled by Black)
+    "B008",  # do not perform function calls in argument defaults
+]
+
+# Allow fix for all enabled rules
+fixable = ["ALL"]
+unfixable = []
+
+# Allow unused variables when underscore-prefixed
+dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"
+
+[tool.ruff.format]
+# Use Black-compatible formatting
+quote-style = "double"
+indent-style = "space"
+skip-magic-trailing-comma = false
+line-ending = "auto"
+
+[tool.ruff.lint.per-file-ignores]
+# Ignore imports in __init__.py
+"__init__.py" = ["F401"]
+# Ignore unused arguments in tests
+"tests/**/*.py" = ["ARG"]
+```
+
+### Usage
+
+```bash
+# Lint files
+ruff check .
+
+# Lint and auto-fix
+ruff check --fix .
+
+# Format code (alternative to Black)
+ruff format .
+
+# Check specific rules
+ruff check --select E,F .
+
+# Show rule explanations
+ruff rule E501
+```
+
+### Common Ruff Rules
+
+```python
+# E501: Line too long
+# Handled by Black, usually ignored
+
+# F401: Imported but unused
+import os  # ruff: noqa: F401
+
+# F841: Local variable assigned but never used
+result = calculate()  # ruff: noqa: F841
+
+# B006: Mutable default argument
+def process(items=[]):  # Bad
+    pass
+
+def process(items=None):  # Good
+    if items is None:
+        items = []
+
+# C4: Unnecessary comprehension
+# Bad
+list([x for x in items])
+# Good
+list(items)
+
+# UP: Use modern Python syntax
+# Bad (Python 3.9-)
+from typing import List
+def process(items: List[str]) -> None:
+    pass
+
+# Good (Python 3.10+)
+def process(items: list[str]) -> None:
+    pass
+```
+
+## Integrated Workflow
+
+### pyproject.toml Complete Example
+
+```toml
+[tool.black]
+line-length = 88
+target-version = ['py310']
+
+[tool.mypy]
+python_version = "3.10"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+no_implicit_optional = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+check_untyped_defs = true
+strict_equality = true
+
+[tool.ruff]
+line-length = 88
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "W", "F", "I", "B", "C4", "UP", "ARG", "SIM"]
+ignore = ["E501"]
+fixable = ["ALL"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+addopts = [
+    "--strict-markers",
+    "--strict-config",
+    "--cov=src",
+    "--cov-report=term-missing",
+]
+```
+
+### Pre-commit Configuration
+
+```yaml
+# .pre-commit-config.yaml
+repos:
+  - repo: https://github.com/psf/black
+    rev: 23.12.1
+    hooks:
+      - id: black
+        language_version: python3.10
+
+  - repo: https://github.com/charliermarsh/ruff-pre-commit
+    rev: v0.1.9
+    hooks:
+      - id: ruff
+        args: [--fix, --exit-non-zero-on-fix]
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.8.0
+    hooks:
+      - id: mypy
+        additional_dependencies: [types-requests]
+```
+
+### Makefile for Common Tasks
+
+```makefile
+.PHONY: format lint type-check test all
+
+format:
+	black src/ tests/
+	ruff check --fix src/ tests/
+
+lint:
+	ruff check src/ tests/
+
+type-check:
+	mypy src/
+
+test:
+	pytest tests/ --cov=src --cov-report=term-missing
+
+all: format lint type-check test
+```
+
+### CI/CD Integration (GitHub Actions)
+
+```yaml
+# .github/workflows/ci.yml
+name: CI
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.10'
+
+      - name: Install dependencies
+        run: |
+          pip install -e ".[dev]"
+
+      - name: Format check
+        run: black --check src/ tests/
+
+      - name: Lint
+        run: ruff check src/ tests/
+
+      - name: Type check
+        run: mypy src/
+
+      - name: Test
+        run: pytest tests/ --cov=src --cov-report=xml
+
+      - name: Upload coverage
+        uses: codecov/codecov-action@v3
+```
+
+## Best Practices
+
+### DO
+
+✅ Use Black for consistent formatting
+✅ Enable strict mypy settings for new projects
+✅ Use Ruff for fast linting and auto-fixes
+✅ Configure tools in pyproject.toml
+✅ Set up pre-commit hooks
+✅ Run tools in CI/CD pipeline
+✅ Fix warnings incrementally in existing projects
+
+### DON'T
+
+❌ Disable type checking without good reason
+❌ Ignore linter warnings without understanding them
+❌ Use `# type: ignore` excessively
+❌ Skip formatting checks in CI
+❌ Mix different formatting styles
+❌ Commit code without running formatters/linters
+
+## Editor Integration
+
+### VS Code
+
+```json
+// .vscode/settings.json
+{
+  "python.formatting.provider": "black",
+  "python.linting.enabled": true,
+  "python.linting.ruffEnabled": true,
+  "python.linting.mypyEnabled": true,
+  "editor.formatOnSave": true,
+  "editor.codeActionsOnSave": {
+    "source.organizeImports": true
+  }
+}
+```
+
+### PyCharm
+
+- Settings → Tools → Black → Enable "On save"
+- Settings → Tools → External Tools → Add Ruff
+- Settings → Editor → Inspections → Enable mypy
+

package/augment-extensions/coding-standards/python/rules/type-hints.md

@@ -1,12 +1,10 @@
 # Python Type Hints
 
-Use type hints extensively for better code quality and IDE support.
+Use type hints extensively for better code quality and IDE support. Follow PEP 484, PEP 585, and PEP 604 for modern Python 3.10+ syntax.
 
 ## Basic Type Hints
 
 ```python
-from typing import List, Dict, Set, Tuple, Optional, Union
-
 # Function parameters and return types
 def greet(name: str) -> str:
     return f"Hello, {name}"
@@ -14,71 +12,100 @@ def greet(name: str) -> str:
 def add_numbers(a: int, b: int) -> int:
     return a + b
 
-def get_user_age(user_id: int) -> Optional[int]:
+def get_user_age(user_id: int) -> int | None:
     """Returns age or None if user not found"""
     pass
 ```
 
-## Collection Types
+## Modern Collection Types (Python 3.10+, PEP 585)
 
-```python
-from typing import List, Dict, Set, Tuple
+Use built-in collection types instead of importing from `typing`.
 
-# Lists
-def process_items(items: List[str]) -> List[int]:
+```python
+# Lists - Use list[T] instead of List[T]
+def process_items(items: list[str]) -> list[int]:
     return [len(item) for item in items]
 
-# Dictionaries
-def get_user_data() -> Dict[str, str]:
+# Dictionaries - Use dict[K, V] instead of Dict[K, V]
+def get_user_data() -> dict[str, str]:
     return {"name": "John", "email": "john@example.com"}
 
-# Sets
-def get_unique_ids() -> Set[int]:
+# Sets - Use set[T] instead of Set[T]
+def get_unique_ids() -> set[int]:
     return {1, 2, 3, 4, 5}
 
-# Tuples
-def get_coordinates() -> Tuple[float, float]:
+# Tuples - Use tuple[T, ...] instead of Tuple[T, ...]
+def get_coordinates() -> tuple[float, float]:
     return (10.5, 20.3)
+
+# Variable-length tuples
+def get_values() -> tuple[int, ...]:
+    return (1, 2, 3, 4, 5)
 ```
 
-## Optional and Union Types
+## Union Types (Python 3.10+, PEP 604)
 
-```python
-from typing import Optional, Union
+Use `X | Y` syntax instead of `Union[X, Y]`.
 
-# Optional (value or None)
-def find_user(user_id: int) -> Optional[User]:
+```python
+# Union with None (replaces Optional[T])
+def find_user(user_id: int) -> User | None:
     """Returns User or None if not found"""
     pass
 
-# Union (multiple possible types)
-def process_value(value: Union[int, str]) -> str:
+# Union of multiple types
+def process_value(value: int | str) -> str:
     return str(value)
 
 # Multiple optional parameters
 def create_user(
     name: str,
     email: str,
-    age: Optional[int] = None,
-    phone: Optional[str] = None
+    age: int | None = None,
+    phone: str | None = None
 ) -> User:
     pass
+
+# Complex unions
+def parse_config(value: str | int | float | bool) -> dict[str, str | int]:
+    pass
+```
+
+## Legacy Syntax (Python 3.9 and earlier)
+
+For compatibility with older Python versions, use `typing` module imports.
+
+```python
+from typing import Optional, Union, List, Dict, Set, Tuple
+
+# Optional (value or None)
+def find_user(user_id: int) -> Optional[User]:
+    pass
+
+# Union (multiple possible types)
+def process_value(value: Union[int, str]) -> str:
+    return str(value)
+
+# Collections
+def process_items(items: List[str]) -> List[int]:
+    return [len(item) for item in items]
 ```
 
 ## Generic Types
 
 ```python
-from typing import TypeVar, Generic, List
+from typing import TypeVar, Generic
 
 T = TypeVar('T')
 
+# Modern syntax (Python 3.10+)
 class Stack(Generic[T]):
     def __init__(self) -> None:
-        self._items: List[T] = []
-    
+        self._items: list[T] = []
+
     def push(self, item: T) -> None:
         self._items.append(item)
-    
+
     def pop(self) -> T:
         return self._items.pop()
 
@@ -90,13 +117,13 @@ str_stack: Stack[str] = Stack()
 ## Callable Types
 
 ```python
-from typing import Callable
+from collections.abc import Callable
 
-# Function that takes a callback
+# Function that takes a callback (modern syntax)
 def process_data(
-    data: List[int],
+    data: list[int],
     callback: Callable[[int], str]
-) -> List[str]:
+) -> list[str]:
     return [callback(item) for item in data]
 
 # Function that returns a function
@@ -109,22 +136,22 @@ def create_multiplier(factor: int) -> Callable[[int], int]:
 ## Class Type Hints
 
 ```python
-from typing import ClassVar, List
+from typing import ClassVar
 from dataclasses import dataclass
 
 class User:
     # Class variable
     user_count: ClassVar[int] = 0
-    
+
     def __init__(self, name: str, age: int) -> None:
         self.name: str = name
         self.age: int = age
         User.user_count += 1
-    
-    def get_info(self) -> Dict[str, Union[str, int]]:
+
+    def get_info(self) -> dict[str, str | int]:
         return {"name": self.name, "age": self.age}
 
-# Using dataclasses
+# Using dataclasses (recommended)
 @dataclass
 class Product:
     name: str
@@ -157,32 +184,70 @@ class Shape(ABC):
 ## Type Aliases
 
 ```python
-from typing import List, Dict, Tuple
-
+# Modern syntax (Python 3.10+)
 # Simple aliases
 UserId = int
 UserName = str
-Coordinates = Tuple[float, float]
+Coordinates = tuple[float, float]
 
 # Complex aliases
-UserData = Dict[str, Union[str, int, List[str]]]
-Matrix = List[List[float]]
+UserData = dict[str, str | int | list[str]]
+Matrix = list[list[float]]
 
 def get_user(user_id: UserId) -> UserName:
     pass
 
 def process_matrix(matrix: Matrix) -> Matrix:
     pass
+
+# Type alias with TypeAlias annotation (Python 3.10+)
+from typing import TypeAlias
+
+Vector: TypeAlias = list[float]
+ConnectionOptions: TypeAlias = dict[str, str | int | bool]
+```
+
+## Mypy Type Checking (PEP 484)
+
+Configure mypy for strict type checking.
+
+```ini
+# mypy.ini or setup.cfg
+[mypy]
+python_version = 3.10
+warn_return_any = True
+warn_unused_configs = True
+disallow_untyped_defs = True
+disallow_any_unimported = True
+no_implicit_optional = True
+warn_redundant_casts = True
+warn_unused_ignores = True
+warn_no_return = True
+check_untyped_defs = True
+strict_equality = True
+```
+
+```python
+# Run mypy
+# $ mypy myproject/
+
+# Ignore specific lines
+result = legacy_function()  # type: ignore
+
+# Ignore specific error codes
+result = legacy_function()  # type: ignore[no-untyped-call]
 ```
 
 ## Best Practices
 
-1. **Always use type hints** for function parameters and return values
-2. **Use Optional** instead of Union[X, None]
-3. **Use specific types** instead of Any when possible
-4. **Use TypeVar** for generic functions and classes
-5. **Use Protocol** for duck typing
-6. **Run mypy** or pyright for type checking
-7. **Use dataclasses** for simple data containers
-8. **Document complex types** with comments
+1. **Use modern syntax** - Prefer `list[str]` over `List[str]` (Python 3.10+)
+2. **Use union operator** - Prefer `str | None` over `Optional[str]` (Python 3.10+)
+3. **Always use type hints** - For all function parameters and return values
+4. **Use specific types** - Avoid `Any` when possible
+5. **Use TypeVar** - For generic functions and classes
+6. **Use Protocol** - For duck typing and structural subtyping
+7. **Run mypy** - Use mypy or pyright for static type checking
+8. **Use dataclasses** - For simple data containers with type hints
+9. **Document complex types** - Add comments for complex type annotations
+10. **Follow PEP 484, 585, 604** - Stay current with Python typing standards