@mytechtoday/augment-extensions 0.1.0 → 0.1.1

package/augment-extensions/coding-standards/python/rules/error-handling.md

@@ -0,0 +1,221 @@
+# Python Error Handling
+
+Proper exception handling patterns for robust Python code.
+
+## Basic Exception Handling
+
+```python
+# Good - Specific exception
+try:
+    result = int(user_input)
+except ValueError as e:
+    print(f"Invalid input: {e}")
+    result = 0
+
+# Bad - Bare except
+try:
+    result = int(user_input)
+except:  # Don't do this
+    result = 0
+```
+
+## Multiple Exceptions
+
+```python
+# Handle different exceptions differently
+try:
+    with open(file_path) as f:
+        data = json.load(f)
+except FileNotFoundError:
+    print(f"File not found: {file_path}")
+    data = {}
+except json.JSONDecodeError as e:
+    print(f"Invalid JSON: {e}")
+    data = {}
+except PermissionError:
+    print(f"Permission denied: {file_path}")
+    data = {}
+
+# Handle multiple exceptions the same way
+try:
+    result = perform_operation()
+except (ValueError, TypeError, KeyError) as e:
+    print(f"Operation failed: {e}")
+    result = None
+```
+
+## Finally and Else
+
+```python
+# Using finally for cleanup
+try:
+    file = open(file_path)
+    data = file.read()
+except FileNotFoundError:
+    print("File not found")
+    data = None
+finally:
+    if 'file' in locals():
+        file.close()
+
+# Using else for success case
+try:
+    result = risky_operation()
+except ValueError:
+    print("Operation failed")
+else:
+    print("Operation succeeded")
+    process_result(result)
+finally:
+    cleanup()
+```
+
+## Context Managers
+
+```python
+# Preferred - Automatic cleanup
+with open(file_path) as f:
+    data = f.read()
+
+# Multiple context managers
+with open(input_file) as f_in, open(output_file, 'w') as f_out:
+    data = f_in.read()
+    f_out.write(process(data))
+
+# Custom context manager
+from contextlib import contextmanager
+
+@contextmanager
+def database_connection(db_url: str):
+    conn = connect(db_url)
+    try:
+        yield conn
+    finally:
+        conn.close()
+
+# Usage
+with database_connection("postgresql://...") as conn:
+    conn.execute("SELECT * FROM users")
+```
+
+## Custom Exceptions
+
+```python
+# Define custom exceptions
+class ValidationError(Exception):
+    """Raised when validation fails"""
+    pass
+
+class AuthenticationError(Exception):
+    """Raised when authentication fails"""
+    def __init__(self, user_id: int, message: str = "Authentication failed"):
+        self.user_id = user_id
+        self.message = message
+        super().__init__(self.message)
+
+# Usage
+def validate_email(email: str) -> None:
+    if '@' not in email:
+        raise ValidationError(f"Invalid email: {email}")
+
+def authenticate_user(user_id: int, password: str) -> User:
+    if not verify_password(user_id, password):
+        raise AuthenticationError(user_id)
+    return get_user(user_id)
+```
+
+## Exception Chaining
+
+```python
+# Preserve original exception
+try:
+    result = process_data(data)
+except ValueError as e:
+    raise ProcessingError("Failed to process data") from e
+
+# Suppress original exception (rare)
+try:
+    result = process_data(data)
+except ValueError:
+    raise ProcessingError("Failed to process data") from None
+```
+
+## Logging Exceptions
+
+```python
+import logging
+
+logger = logging.getLogger(__name__)
+
+# Log exception with traceback
+try:
+    result = risky_operation()
+except Exception as e:
+    logger.exception("Operation failed")  # Includes traceback
+    raise
+
+# Log without traceback
+try:
+    result = risky_operation()
+except ValueError as e:
+    logger.error(f"Invalid value: {e}")
+    result = default_value
+```
+
+## Best Practices
+
+1. **Catch specific exceptions** - Never use bare `except:`
+2. **Use context managers** - Prefer `with` for resource management
+3. **Don't silence exceptions** - Log or handle them properly
+4. **Create custom exceptions** - For domain-specific errors
+5. **Use exception chaining** - Preserve error context with `from`
+6. **Clean up resources** - Use `finally` or context managers
+7. **Fail fast** - Don't catch exceptions you can't handle
+8. **Document exceptions** - Use docstrings to document raised exceptions
+
+## Anti-Patterns to Avoid
+
+```python
+# DON'T: Bare except
+try:
+    do_something()
+except:
+    pass
+
+# DON'T: Catch Exception without re-raising
+try:
+    critical_operation()
+except Exception:
+    print("Error occurred")
+
+# DON'T: Use exceptions for flow control
+try:
+    value = my_dict[key]
+except KeyError:
+    value = default
+
+# DO: Use get() instead
+value = my_dict.get(key, default)
+```
+
+## Exception Hierarchy
+
+```python
+# Create exception hierarchy
+class AppError(Exception):
+    """Base exception for application"""
+    pass
+
+class DatabaseError(AppError):
+    """Database-related errors"""
+    pass
+
+class ConnectionError(DatabaseError):
+    """Database connection errors"""
+    pass
+
+class QueryError(DatabaseError):
+    """Database query errors"""
+    pass
+```
+

package/augment-extensions/coding-standards/python/rules/naming-conventions.md

@@ -0,0 +1,172 @@
+# Python Naming Conventions
+
+Follow PEP 8 naming conventions strictly.
+
+## Module Names
+
+- Use lowercase with underscores: `my_module.py`
+- Keep names short and descriptive
+- Avoid single-letter names except for common abbreviations
+
+```python
+# Good
+user_authentication.py
+data_processor.py
+api_client.py
+
+# Bad
+UserAuthentication.py
+dataProcessor.py
+ua.py
+```
+
+## Class Names
+
+- Use CapWords (PascalCase)
+- Use nouns or noun phrases
+- Avoid abbreviations unless widely known
+
+```python
+# Good
+class UserAccount:
+    pass
+
+class HTTPClient:
+    pass
+
+class DataProcessor:
+    pass
+
+# Bad
+class user_account:
+    pass
+
+class Http_Client:
+    pass
+
+class DP:
+    pass
+```
+
+## Function and Method Names
+
+- Use lowercase with underscores (snake_case)
+- Use verbs or verb phrases
+- Be descriptive and clear
+
+```python
+# Good
+def calculate_total_price():
+    pass
+
+def get_user_by_id(user_id: int):
+    pass
+
+def is_valid_email(email: str) -> bool:
+    pass
+
+# Bad
+def CalcPrice():
+    pass
+
+def getUserById(userId):
+    pass
+
+def valid(e):
+    pass
+```
+
+## Variable Names
+
+- Use lowercase with underscores
+- Be descriptive
+- Avoid single letters except in loops or comprehensions
+
+```python
+# Good
+user_count = 10
+total_price = 99.99
+is_authenticated = True
+
+# Bad
+userCount = 10
+tp = 99.99
+x = True
+```
+
+## Constants
+
+- Use UPPERCASE with underscores
+- Define at module level
+
+```python
+# Good
+MAX_CONNECTIONS = 100
+DEFAULT_TIMEOUT = 30
+API_BASE_URL = "https://api.example.com"
+
+# Bad
+maxConnections = 100
+default_timeout = 30
+apiBaseUrl = "https://api.example.com"
+```
+
+## Private Members
+
+- Use single leading underscore for internal use
+- Use double leading underscore for name mangling (rare)
+
+```python
+class MyClass:
+    def __init__(self):
+        self._internal_value = 0  # Internal use
+        self.__private_value = 0  # Name mangling (rare)
+    
+    def _internal_method(self):
+        """Internal method, not part of public API"""
+        pass
+    
+    def public_method(self):
+        """Public API method"""
+        pass
+```
+
+## Special Methods
+
+- Use double underscores on both sides (dunder methods)
+- Only for Python special methods
+
+```python
+class MyClass:
+    def __init__(self):
+        pass
+    
+    def __str__(self):
+        return "MyClass instance"
+    
+    def __repr__(self):
+        return "MyClass()"
+```
+
+## Type Variable Names
+
+- Use CapWords for type variables
+- Use descriptive names or single capital letters
+
+```python
+from typing import TypeVar
+
+T = TypeVar('T')
+UserType = TypeVar('UserType')
+KeyType = TypeVar('KeyType')
+ValueType = TypeVar('ValueType')
+```
+
+## Best Practices
+
+1. **Consistency**: Follow the same naming pattern throughout the codebase
+2. **Clarity**: Prefer clarity over brevity
+3. **Context**: Use context to avoid redundant names
+4. **Avoid**: Hungarian notation, type prefixes
+5. **Use**: Meaningful names that convey intent
+

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

@@ -0,0 +1,188 @@
+# Python Type Hints
+
+Use type hints extensively for better code quality and IDE support.
+
+## 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}"
+
+def add_numbers(a: int, b: int) -> int:
+    return a + b
+
+def get_user_age(user_id: int) -> Optional[int]:
+    """Returns age or None if user not found"""
+    pass
+```
+
+## Collection Types
+
+```python
+from typing import List, Dict, Set, Tuple
+
+# Lists
+def process_items(items: List[str]) -> List[int]:
+    return [len(item) for item in items]
+
+# Dictionaries
+def get_user_data() -> Dict[str, str]:
+    return {"name": "John", "email": "john@example.com"}
+
+# Sets
+def get_unique_ids() -> Set[int]:
+    return {1, 2, 3, 4, 5}
+
+# Tuples
+def get_coordinates() -> Tuple[float, float]:
+    return (10.5, 20.3)
+```
+
+## Optional and Union Types
+
+```python
+from typing import Optional, Union
+
+# Optional (value or None)
+def find_user(user_id: int) -> Optional[User]:
+    """Returns User or None if not found"""
+    pass
+
+# Union (multiple possible types)
+def process_value(value: Union[int, str]) -> str:
+    return str(value)
+
+# Multiple optional parameters
+def create_user(
+    name: str,
+    email: str,
+    age: Optional[int] = None,
+    phone: Optional[str] = None
+) -> User:
+    pass
+```
+
+## Generic Types
+
+```python
+from typing import TypeVar, Generic, List
+
+T = TypeVar('T')
+
+class Stack(Generic[T]):
+    def __init__(self) -> None:
+        self._items: List[T] = []
+    
+    def push(self, item: T) -> None:
+        self._items.append(item)
+    
+    def pop(self) -> T:
+        return self._items.pop()
+
+# Usage
+int_stack: Stack[int] = Stack()
+str_stack: Stack[str] = Stack()
+```
+
+## Callable Types
+
+```python
+from typing import Callable
+
+# Function that takes a callback
+def process_data(
+    data: List[int],
+    callback: Callable[[int], str]
+) -> List[str]:
+    return [callback(item) for item in data]
+
+# Function that returns a function
+def create_multiplier(factor: int) -> Callable[[int], int]:
+    def multiply(x: int) -> int:
+        return x * factor
+    return multiply
+```
+
+## Class Type Hints
+
+```python
+from typing import ClassVar, List
+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]]:
+        return {"name": self.name, "age": self.age}
+
+# Using dataclasses
+@dataclass
+class Product:
+    name: str
+    price: float
+    quantity: int = 0
+```
+
+## Protocol and Abstract Types
+
+```python
+from typing import Protocol
+from abc import ABC, abstractmethod
+
+# Protocol (structural subtyping)
+class Drawable(Protocol):
+    def draw(self) -> None:
+        ...
+
+# Abstract base class
+class Shape(ABC):
+    @abstractmethod
+    def area(self) -> float:
+        pass
+    
+    @abstractmethod
+    def perimeter(self) -> float:
+        pass
+```
+
+## Type Aliases
+
+```python
+from typing import List, Dict, Tuple
+
+# Simple aliases
+UserId = int
+UserName = str
+Coordinates = Tuple[float, float]
+
+# Complex aliases
+UserData = Dict[str, Union[str, int, List[str]]]
+Matrix = List[List[float]]
+
+def get_user(user_id: UserId) -> UserName:
+    pass
+
+def process_matrix(matrix: Matrix) -> Matrix:
+    pass
+```
+
+## 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
+

package/augment-extensions/coding-standards/react/README.md

@@ -0,0 +1,45 @@
+# React Patterns
+
+Modern React patterns and best practices for building scalable applications.
+
+## Overview
+
+This module provides comprehensive guidelines for React development including component patterns, hooks usage, state management, and TypeScript integration.
+
+## Key Benefits
+
+- **Modern Patterns**: React 18+ features and patterns
+- **Type Safety**: TypeScript integration best practices
+- **Performance**: Optimization techniques and patterns
+- **Maintainability**: Clean, testable component architecture
+
+## Installation
+
+```bash
+augx link coding-standards/react
+```
+
+## Contents
+
+### Rules
+
+- **component-patterns.md** - Component design patterns
+- **hooks-best-practices.md** - React Hooks usage
+- **state-management.md** - State management patterns
+- **typescript-react.md** - TypeScript with React
+- **performance.md** - Performance optimization
+
+### Examples
+
+- **component-examples.md** - Component pattern examples
+- **hooks-examples.md** - Custom hooks examples
+- **state-examples.md** - State management examples
+
+## Character Count
+
+~32,000 characters
+
+## Version
+
+1.0.0
+

package/augment-extensions/coding-standards/react/module.json

@@ -0,0 +1,27 @@
+{
+  "name": "react-patterns",
+  "version": "1.0.0",
+  "displayName": "React Patterns",
+  "description": "Modern React patterns including component design, hooks, and state management best practices",
+  "type": "coding-standards",
+  "author": "Augment Extensions",
+  "license": "MIT",
+  "augment": {
+    "characterCount": 32000,
+    "priority": "medium",
+    "category": "coding-standards"
+  },
+  "installation": {
+    "required": false,
+    "dependencies": []
+  },
+  "tags": [
+    "react",
+    "hooks",
+    "components",
+    "state-management",
+    "typescript",
+    "best-practices"
+  ]
+}
+