Initial commit

.dockerignore

@@ -0,0 +1 @@
+.venv

.env.example

@@ -0,0 +1,4 @@
+# Application Settings
+APP_NAME=template-python
+DEBUG=true
+ENV=development

.github/workflows/build.yaml

@@ -0,0 +1,27 @@
+name: Docker Build
+
+on:
+  push:
+    branches:
+      - main
+      - develop
+      - "feature/**"
+      - "hotfix/**"
+    tags:
+      - "v*.*.*"
+  pull_request:
+    branches:
+      - main
+      - develop
+
+jobs:
+  docker:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: pnstack/actions/docker-publish@main
+        with:
+          platforms: linux/amd64,linux/arm64
+          dockerfile: Dockerfile
+          context: .
+          push_enabled: true
+          registry: ghcr.io

.github/workflows/deploy-to-huggingface.yml

@@ -0,0 +1,50 @@
+name: Deploy to Hugging Face
+
+on:
+  push:
+    branches:
+      - main
+      - master
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          lfs: true
+      
+      - name: Setup Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.11'
+          cache: 'pip'
+      
+      - name: Config git
+        run: |
+          git config --global credential.helper store
+          git config --global user.email "actions@github.com"
+          git config --global user.name "github-actions"
+
+      - name: Configure Hugging Face
+        env:
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
+          HF_USERNAME: ${{ secrets.HF_USERNAME }}
+        run: |
+          # Install Hugging Face CLI
+          pip install huggingface-hub
+          # Login to Hugging Face
+          huggingface-cli login --token $HF_TOKEN --add-to-git-credential
+
+      - name: Push to Hugging Face
+        env:
+          HF_USERNAME: ${{ secrets.HF_USERNAME }}
+          SPACE_NAME: ${{ secrets.SPACE_NAME }}
+        run: |
+          # Create repository URL
+          REPO_URL="https://huggingface.co/spaces/$HF_USERNAME/template-python"
+          
+          # Add Hugging Face as a remote and push
+          git remote add space $REPO_URL || git remote set-url space $REPO_URL
+          git push -f space main

.gitignore

@@ -0,0 +1,162 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/

.python-version

@@ -0,0 +1 @@
+3.11

.vscode/settings.json

@@ -0,0 +1,17 @@
+{
+  "python.testing.pytestArgs": ["tests"],
+  "python.testing.unittestEnabled": false,
+  "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
+}

Dockerfile

@@ -0,0 +1,39 @@
+# Use a Python image with uv pre-installed
+FROM ghcr.io/astral-sh/uv:python3.11-bookworm
+
+# Install the project into `/app`
+WORKDIR /app
+
+# Enable bytecode compilation
+ENV UV_COMPILE_BYTECODE=1
+
+# Copy from the cache instead of linking since it's a mounted volume
+ENV UV_LINK_MODE=copy
+
+# Install the project's dependencies using the lockfile and settings
+RUN --mount=type=cache,target=/root/.cache/uv \
+  --mount=type=bind,source=uv.lock,target=uv.lock \
+  --mount=type=bind,source=pyproject.toml,target=pyproject.toml \
+  uv sync --frozen --no-install-project --no-dev
+
+# Then, add the rest of the project source code and install it
+# Installing separately from its dependencies allows optimal layer caching
+ADD . /app
+RUN --mount=type=cache,target=/root/.cache/uv \
+  uv sync --frozen --no-dev
+
+# Place executables in the environment at the front of the path
+ENV PATH="/app/.venv/bin:$PATH"
+
+# Reset the entrypoint, don't invoke `uv`
+ENTRYPOINT []
+
+# Run setup.py
+
+RUN python setup.py
+
+EXPOSE 8080
+# Run the FastAPI application by default
+# Uses `fastapi dev` to enable hot-reloading when the `watch` sync occurs
+# Uses `--host 0.0.0.0` to allow access from outside the container
+CMD ["python", "main.py"]

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-present Your Name or Organization
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

Makefile

@@ -0,0 +1,41 @@
+.PHONY: help install dev-install test format lint type-check clean build run
+
+help:  ## Show this help menu
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}'
+
+install:  ## Install production dependencies
+	uv pip install .
+
+dev-install:  ## Install development dependencies
+	uv pip install -e ".[dev]"
+
+test:  ## Run tests with pytest
+	pytest -v --cov=src --cov-report=term-missing
+
+format:  ## Format code with black and isort
+	black .
+	isort .
+
+lint:  ## Lint code with ruff
+	ruff check .
+
+type-check:  ## Run type checking with mypy
+	mypy src tests
+
+clean:  ## Clean build artifacts
+	rm -rf build/ dist/ *.egg-info/ .coverage .pytest_cache/ .mypy_cache/ .ruff_cache/
+	find . -type d -name __pycache__ -exec rm -rf {} +
+
+build:  ## Build Docker image
+	docker build -t template-python .
+
+run:  ## Run Docker container
+	docker run -it --rm template-python
+
+package:  ## Create requirements.txt
+	uv pip freeze > requirements.txt
+
+setup:  ## Initial project setup
+	uv venv
+	$(MAKE) dev-install
+	cp .env.example .env

README.md

@@ -0,0 +1,122 @@
+---
+title: Python Project Template
+emoji: 🟧
+colorFrom: yellow
+colorTo: purple
+sdk: docker
+tags:
+- Python
+fullwidth: true
+license: mit
+app_port: 8080
+---
+
+# Python Project Template
+
+A modern Python project template with best practices for development, testing, and deployment.
+
+## Features
+
+- Modern Python (3.11+) project structure
+- Development tools configuration (pytest, black, isort, mypy, ruff)
+- Docker support
+- GitHub Actions ready
+- Comprehensive documentation structure
+- Jupyter notebook support
+
+## Project Structure
+
+```
+.
+├── docs/               # Documentation files
+├── notebooks/         # Jupyter notebooks
+├── src/               # Source code
+│   ├── common/        # Common utilities and shared code
+│   ├── modules/       # Feature modules
+│   │   └── api/       # API related code
+│   ├── shared/        # Shared resources
+│   └── utils/         # Utility functions
+└── tests/             # Test files
+```
+
+## Getting Started
+
+### Prerequisites
+
+- Python 3.11 or higher
+- [uv](https://github.com/astral-sh/uv) for dependency management
+
+### Installation
+
+1. Clone the repository:
+```bash
+git clone https://github.com/yourusername/template-python.git
+cd template-python
+```
+
+2. Create a virtual environment and install dependencies:
+```bash
+uv venv
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+uv pip install -e ".[dev]"
+```
+
+3. Copy the environment file and adjust as needed:
+```bash
+cp .env.example .env
+```
+
+### Development
+
+This project uses several development tools:
+
+- **pytest**: Testing framework
+- **black**: Code formatting
+- **isort**: Import sorting
+- **mypy**: Static type checking
+- **ruff**: Fast Python linter
+
+Run tests:
+```bash
+pytest
+```
+
+Format code:
+```bash
+black .
+isort .
+```
+
+Run type checking:
+```bash
+mypy src tests
+```
+
+Run linting:
+```bash
+ruff check .
+```
+
+### Docker
+
+Build the Docker image:
+```bash
+make build
+```
+
+Run the container:
+```bash
+make run
+```
+
+## Contributing
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.

docs/README.md

@@ -0,0 +1,60 @@
+# Project Documentation
+
+Welcome to the documentation for the Python Template Project.
+
+## Table of Contents
+
+1. [Getting Started](getting-started.md)
+2. [Project Structure](project-structure.md)
+3. [Development Guide](development.md)
+4. [API Documentation](api.md)
+5. [Testing Guide](testing.md)
+6. [Deployment Guide](deployment.md)
+
+## Overview
+
+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)
+- [Development Setup](development.md#setup)
+- [Running Tests](testing.md#running-tests)
+- [Docker Guide](deployment.md#docker)
+- [API Reference](api.md#endpoints)
+
+## Contributing
+
+See our [Contributing Guide](CONTRIBUTING.md) for details on how to contribute to this project.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](../LICENSE) file for details.

main.py

@@ -0,0 +1,21 @@
+#!/usr/bin/env python3
+
+import logging
+import os
+from pathlib import Path
+from typing import Dict
+
+
+def main() -> None:
+    """Main application entry point."""
+    try:
+        print("Start app...")
+        import src.modules.api
+
+    except Exception as e:
+        logging.error(f"Application failed to start: {e}", exc_info=True)
+        raise
+
+
+if __name__ == "__main__":
+    main()

notebooks/notes.ipynb

@@ -0,0 +1,91 @@
+{
+ "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import os"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Import the parent directory into the path\n",
+    "import sys\n",
+    "sys.path.append(\"..\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "56277"
+      ]
+     },
+     "execution_count": 3,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "os.getpid()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from src.utils.math import hello"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Hello from math module\n"
+     ]
+    }
+   ],
+   "source": [
+    "hello()"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": ".venv",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.11.7"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}

pyproject.toml

@@ -0,0 +1,39 @@
+[project]
+name = "template-python"
+version = "0.1.0"
+description = "Add your description here"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "fastapi[standard]>=0.115.8",
+    "ipykernel>=6.29.5",
+    "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

setup.py

@@ -0,0 +1 @@
+print("Setup.py")

src/__init__.py

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

src/common/config.py

@@ -0,0 +1,81 @@
+"""Common configuration utilities."""
+
+import json
+import os
+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
+        """
+        return cls(
+            app_name=os.getenv("APP_NAME", "template-python"),
+            environment=os.getenv("ENV", "development"),
+            debug=os.getenv("DEBUG", "false").lower() == "true",
+            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
+    """
+    # Check common configuration locations
+    locations = [
+        Path("config"),  # Project config directory
+        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"

src/modules/api/__init__.py

@@ -0,0 +1,3 @@
+"""API module initialization."""
+print("API module loaded.")
+import src.modules.api.index

src/modules/api/app.py

@@ -0,0 +1,39 @@
+"""FastAPI application factory."""
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+from .routes import v1_router
+
+
+def create_app() -> FastAPI:
+    """Create and configure the FastAPI application."""
+    app = FastAPI()
+
+    # Add CORS middleware
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=["*"],
+        allow_credentials=True,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+
+    # Include routers
+    app.include_router(v1_router)
+
+    @app.on_event("startup")
+    async def startup_event():
+        """Run startup events."""
+        pass
+
+    @app.on_event("shutdown")
+    async def shutdown_event():
+        """Run shutdown events."""
+        pass
+
+    return app
+
+
+# Create default app instance
+app = create_app()

src/modules/api/index.py

@@ -0,0 +1,21 @@
+import uvicorn
+from .app import app as api_app
+import logging
+
+
+def main():
+    """Main application entry point."""
+    try:
+        print("Start api...")
+        uvicorn.run(
+            api_app,
+            host="0.0.0.0",
+            port=8080,
+            reload=False,
+        )
+    except Exception as e:
+        logging.error(f"Application failed to start: {e}", exc_info=True)
+        raise
+
+
+main()

src/modules/api/routes/__init__.py

@@ -0,0 +1,5 @@
+"""API routes package."""
+
+from .v1 import router as v1_router
+
+__all__ = ["v1_router"]

src/modules/api/routes/v1.py

@@ -0,0 +1,26 @@
+"""API v1 route handlers."""
+
+from fastapi import APIRouter
+from typing import Dict, List
+
+
+# Create v1 router
+router = APIRouter(prefix='/v1', tags=['v1'])
+
+@router.get("/hello")
+async def hello_world() -> Dict[str, str]:
+    """Hello world endpoint."""
+    return {"message": "Hello, World!"}
+
+@router.get("/health")
+async def health_check() -> Dict[str, str]:
+    """Health check endpoint."""
+    return {"status": "healthy"}
+
+@router.get("/metrics")
+async def metrics() -> Dict[str, int]:
+    """Application metrics endpoint."""
+    return {
+        "total_routes": len(router.routes),
+        "api_version": 1
+    }

src/shared/utils/validation.py

@@ -0,0 +1,54 @@
+"""Shared validation utilities."""
+
+import re
+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}$"
+)
+
+
+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]]:
+    """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

src/utils/__init__.py

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

src/utils/math.py

@@ -0,0 +1,56 @@
+"""Mathematical utility functions."""
+
+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]

tests/__init__.py

@@ -0,0 +1,4 @@
+"""
+Test package.
+Contains all test cases for the application.
+"""

tests/test_math.py

@@ -0,0 +1,56 @@
+"""Tests for mathematical utility functions."""
+
+import pytest
+from src.utils.math import calculate_mean, calculate_median
+
+def test_calculate_mean():
+    """Test the calculate_mean function with various inputs."""
+    # Test with integers
+    assert calculate_mean([1, 2, 3, 4, 5]) == 3.0
+    
+    # Test with floats
+    assert calculate_mean([1.5, 2.5, 3.5]) == 2.5
+    
+    # Test with mixed numbers
+    assert calculate_mean([1, 2.5, 3]) == 2.1666666666666665
+
+def test_calculate_mean_errors():
+    """Test error handling in calculate_mean function."""
+    # Test empty list
+    with pytest.raises(ValueError) as exc:
+        calculate_mean([])
+    assert str(exc.value) == "Cannot calculate mean of empty list"
+    
+    # Test invalid input types
+    with pytest.raises(TypeError) as exc:
+        calculate_mean([1, "2", 3])
+    assert str(exc.value) == "All elements must be numbers"
+
+def test_calculate_median():
+    """Test the calculate_median function with various inputs."""
+    # Test odd number of integers
+    assert calculate_median([1, 2, 3, 4, 5]) == 3.0
+    
+    # Test even number of integers
+    assert calculate_median([1, 2, 3, 4]) == 2.5
+    
+    # Test unsorted list
+    assert calculate_median([5, 2, 1, 4, 3]) == 3.0
+    
+    # Test with floats
+    assert calculate_median([1.5, 2.5, 3.5]) == 2.5
+    
+    # Test with mixed numbers
+    assert calculate_median([1, 2.5, 3]) == 2.5
+
+def test_calculate_median_errors():
+    """Test error handling in calculate_median function."""
+    # Test empty list
+    with pytest.raises(ValueError) as exc:
+        calculate_median([])
+    assert str(exc.value) == "Cannot calculate median of empty list"
+    
+    # Test invalid input types
+    with pytest.raises(TypeError) as exc:
+        calculate_median([1, "2", 3])
+    assert str(exc.value) == "All elements must be numbers"