feat: enhance development setup with Black and Ruff configuration, update README, and remove unused loader module

.vscode/settings.json

@@ -1,5 +1,17 @@
 {
   "python.testing.pytestArgs": ["tests"],
   "python.testing.unittestEnabled": false,
-  "python.testing.pytestEnabled": true
+  "python.testing.pytestEnabled": true,
+  "[python]": {
+    "editor.formatOnSave": true,
+    "editor.defaultFormatter": "ms-python.black-formatter",
+    "editor.codeActionsOnSave": {
+      "source.organizeImports": "explicit",
+      "source.fixAll": "explicit"
+    }
+  },
+  "editor.formatOnSave": true,
+  "python.analysis.typeCheckingMode": "basic",
+  "ruff.organizeImports": true,
+  "ruff.fixAll": true
 }

docs/README.md

@@ -17,11 +17,32 @@ This template provides a foundation for Python projects with:
 
 - Modern Python project structure
 - Development tooling configuration
+  - Black for code formatting
+  - Ruff for linting and import sorting
+  - Type checking support
 - Testing framework setup
 - Docker support
 - Documentation templates
 - CI/CD examples
 
+## Development Setup
+
+### Code Quality Tools
+
+This project uses modern Python code quality tools:
+
+- **Black**: Code formatter that enforces a consistent style
+- **Ruff**: Fast Python linter and import sorter
+  - Enforces PEP 8 style guide
+  - Sorts imports automatically
+  - Checks for common errors and anti-patterns
+  - Type checking enforcement
+
+VSCode is configured to automatically:
+- Format code on save using Black
+- Run Ruff for linting and import sorting
+- Provide type checking feedback
+
 ## Quick Links
 
 - [Installation Guide](getting-started.md#installation)

main.py

@@ -6,10 +6,6 @@ from pathlib import Path
 from typing import Dict
 
 
-
-
-
-
 def main() -> None:
     """Main application entry point."""
     try:
@@ -22,4 +18,4 @@ def main() -> None:
 
 
 if __name__ == "__main__":
-    main()
+    main()

pyproject.toml

@@ -10,3 +10,30 @@ dependencies = [
     "numpy>=2.2.3",
     "pytest>=8.3.4",
 ]
+
+[tool.black]
+line-length = 88
+target-version = ["py311"]
+include = '\.pyi?$'
+
+[tool.ruff]
+line-length = 88
+target-version = "py311"
+select = [
+    "E",  # pycodestyle errors
+    "W",  # pycodestyle warnings
+    "F",  # pyflakes
+    "I",  # isort
+    "C",  # flake8-comprehensions
+    "B",  # flake8-bugbear
+]
+ignore = []
+
+[tool.ruff.per-file-ignores]
+"__init__.py" = ["F401"]
+
+[tool.ruff.isort]
+known-first-party = ["src"]
+
+[tool.ruff.mccabe]
+max-complexity = 10

src/__init__.py

@@ -1,4 +1,4 @@
 """
 Main application package.
 This is the root package of the application.
-"""
+"""

src/common/config.py

@@ -6,18 +6,20 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import Any, Optional
 
+
 @dataclass
 class AppConfig:
     """Application configuration."""
+
     app_name: str
     environment: str
     debug: bool
     log_level: str
-    
+
     @classmethod
     def from_env(cls) -> "AppConfig":
         """Create configuration from environment variables.
-        
+
         Returns:
             AppConfig: Application configuration instance
         """
@@ -28,35 +30,39 @@ class AppConfig:
             log_level=os.getenv("LOG_LEVEL", "INFO"),
         )
 
+
 def load_json_config(path: Path) -> dict[str, Any]:
     """Load configuration from JSON file.
-    
+
     Args:
         path: Path to JSON configuration file
-        
+
     Returns:
         dict[str, Any]: Configuration dictionary
-        
+
     Raises:
         FileNotFoundError: If configuration file doesn't exist
         json.JSONDecodeError: If configuration file is invalid JSON
     """
     if not path.exists():
         raise FileNotFoundError(f"Configuration file not found: {path}")
-    
+
     with path.open() as f:
         return json.load(f)
 
+
 class ConfigurationError(Exception):
     """Base class for configuration errors."""
+
     pass
 
+
 def get_config_path(config_name: str) -> Path:
     """Get configuration file path.
-    
+
     Args:
         config_name: Name of the configuration file
-        
+
     Returns:
         Path: Path to configuration file
     """
@@ -66,10 +72,10 @@ def get_config_path(config_name: str) -> Path:
         Path("~/.config/template-python"),  # User config directory
         Path("/etc/template-python"),  # System config directory
     ]
-    
+
     for location in locations:
         path = location.expanduser() / f"{config_name}.json"
         if path.exists():
             return path
-    
-    return locations[0].expanduser() / f"{config_name}.json"
+
+    return locations[0].expanduser() / f"{config_name}.json"

src/shared/utils/validation.py

@@ -5,43 +5,50 @@ from typing import Any, Optional, Pattern
 
 # Common validation patterns
 EMAIL_PATTERN: Pattern = re.compile(r"^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$")
-UUID_PATTERN: Pattern = re.compile(r"^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$")
+UUID_PATTERN: Pattern = re.compile(
+    r"^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+)
+
 
 def validate_email(email: str) -> bool:
     """Validate email format.
-    
+
     Args:
         email: Email address to validate
-        
+
     Returns:
         bool: True if email format is valid, False otherwise
     """
     return bool(EMAIL_PATTERN.match(email))
 
+
 def validate_uuid(uuid: str) -> bool:
     """Validate UUID format.
-    
+
     Args:
         uuid: UUID string to validate
-        
+
     Returns:
         bool: True if UUID format is valid, False otherwise
     """
     return bool(UUID_PATTERN.match(uuid.lower()))
 
-def validate_required_fields(data: dict[str, Any], required_fields: list[str]) -> tuple[bool, Optional[str]]:
+
+def validate_required_fields(
+    data: dict[str, Any], required_fields: list[str]
+) -> tuple[bool, Optional[str]]:
     """Validate required fields in a dictionary.
-    
+
     Args:
         data: Dictionary containing data to validate
         required_fields: List of required field names
-        
+
     Returns:
         tuple[bool, Optional[str]]: (is_valid, error_message)
     """
     missing_fields = [field for field in required_fields if field not in data]
-    
+
     if missing_fields:
         return False, f"Missing required fields: {', '.join(missing_fields)}"
-    
-    return True, None
+
+    return True, None

src/utils/loader.py

@@ -1,65 +0,0 @@
-"""Module loader utilities."""
-
-import logging
-import uvicorn
-from typing import Any, Optional
-
-from src.modules.api.app import app as api_app
-from src.modules.api.core.config import settings
-
-logger = logging.getLogger(__name__)
-
-class ModuleLoader:
-    """Utility class for loading and running modules."""
-    
-    @staticmethod
-    def load_api(
-        host: str = "0.0.0.0",
-        port: int = 8000,
-        reload: bool = False,
-        **kwargs: Any
-    ) -> None:
-        """Load and run the API module.
-        
-        Args:
-            host: Host to bind the server to
-            port: Port to bind the server to
-            reload: Enable auto-reload for development
-            **kwargs: Additional uvicorn configuration
-        """
-        logger.info(f"Starting API server on {host}:{port}")
-        logger.debug(f"API Settings: {settings.dict()}")
-        
-        config = uvicorn.Config(
-            api_app,
-            host=host,
-            port=port,
-            reload=reload,
-            log_level="debug" if settings.debug else "info",
-            **kwargs
-        )
-        
-        server = uvicorn.Server(config)
-        server.run()
-
-    @classmethod
-    def load_module(
-        cls,
-        module_name: str,
-        **kwargs: Any
-    ) -> Optional[Any]:
-        """Generic module loader.
-        
-        Args:
-            module_name: Name of the module to load
-            **kwargs: Module-specific configuration
-            
-        Returns:
-            Optional[Any]: Module instance if applicable
-        """
-        if module_name == "api":
-            cls.load_api(**kwargs)
-            return api_app
-        else:
-            logger.error(f"Unknown module: {module_name}")
-            return None

src/utils/math.py

@@ -4,51 +4,53 @@ from typing import List, Union
 
 Number = Union[int, float]
 
+
 def calculate_mean(numbers: List[Number]) -> float:
     """Calculate the arithmetic mean of a list of numbers.
-    
+
     Args:
         numbers: A list of integers or floating point numbers
-        
+
     Returns:
         float: The arithmetic mean of the input numbers
-        
+
     Raises:
         ValueError: If the input list is empty
         TypeError: If any element is not a number
     """
     if not numbers:
         raise ValueError("Cannot calculate mean of empty list")
-    
+
     if not all(isinstance(x, (int, float)) for x in numbers):
         raise TypeError("All elements must be numbers")
-    
+
     return sum(numbers) / len(numbers)
 
+
 def calculate_median(numbers: List[Number]) -> float:
     """Calculate the median value from a list of numbers.
-    
+
     Args:
         numbers: A list of integers or floating point numbers
-        
+
     Returns:
         float: The median value of the input numbers
-        
+
     Raises:
         ValueError: If the input list is empty
         TypeError: If any element is not a number
     """
     if not numbers:
         raise ValueError("Cannot calculate median of empty list")
-    
+
     if not all(isinstance(x, (int, float)) for x in numbers):
         raise TypeError("All elements must be numbers")
-    
+
     sorted_numbers = sorted(numbers)
     length = len(sorted_numbers)
-    
+
     if length % 2 == 0:
         mid = length // 2
         return (sorted_numbers[mid - 1] + sorted_numbers[mid]) / 2
     else:
-        return sorted_numbers[length // 2]
+        return sorted_numbers[length // 2]