zecmf 0.1.0__py3-none-any.whl

zecmf/__init__.py

@@ -0,0 +1,7 @@
+"""ZecMF - A lightweight framework for building microservices in Python with Flask."""
+
+from zecmf.app import create_app
+
+__all__ = [
+    "create_app",
+]

zecmf/api/__init__.py

@@ -0,0 +1,49 @@
+"""API module for Flask-RESTX integration."""
+
+from typing import Any
+
+from flask import Blueprint, Flask
+from flask_restx import Api
+
+
+def init_api(
+    app: Flask,
+) -> Api:
+    """Initialize the API on the Flask app.
+
+    Args:
+        app: The Flask application
+
+    Returns:
+        The configured API instance
+
+    """
+    # Get API configuration from app.config with defaults
+    prefix = app.config.get("API_PREFIX", "/api")
+    title = app.config.get("API_TITLE", "API")
+    version = app.config.get("API_VERSION", "1.0.0")
+    description = app.config.get("API_DESCRIPTION", "...")
+
+    # Create API blueprint with prefix
+    blueprint = Blueprint("api", __name__, url_prefix=prefix)
+
+    # Configure API with provided settings
+    api_config: dict[str, Any] = {
+        "doc": False,
+        "authorizations": {
+            "Bearer": {"type": "apiKey", "in": "header", "name": "Authorization"}
+        },
+        "security": "Bearer",
+        "title": title,
+        "version": version,
+        "description": description,
+    }
+
+    # Create and register API
+    api = Api(blueprint, **api_config)
+    app.register_blueprint(blueprint)
+
+    return api
+
+
+__all__ = ["init_api"]

zecmf/app.py

@@ -0,0 +1,79 @@
+"""Application factory for creating Flask microservice applications with standardized configuration."""
+
+import logging
+import os
+
+from flask import Flask
+from flask_restx import Namespace
+
+from zecmf.api import init_api
+from zecmf.auth import init_jwt
+from zecmf.cli import register_commands
+from zecmf.config import BaseConfig, get_config
+from zecmf.constants import Config as ConfigConstants
+
+logger = logging.getLogger(__name__)
+
+
+def create_app(
+    config_name: str,
+    api_namespaces: list[tuple[Namespace, str]],
+    app_config_module: str = ConfigConstants.APP_CONFIG_MODULE,
+) -> Flask:
+    """Create and configure a Flask microservice application.
+
+    Args:
+        config_name: The name of the configuration to use (development, production, etc).
+        api_namespaces: List of namespaces to register with the API.
+        app_config_module: The module path for the app-specific configuration.
+
+    Returns:
+        A configured Flask application.
+
+    """
+    logger.debug(f"Creating app with config_name: {config_name}")
+
+    if not config_name:
+        logger.warning(
+            "No config_name provided. Trying to load from environment variable."
+        )
+        config_name = os.getenv("FLASK_ENV", "development")
+
+    app_config = _resolve_and_validate_config(config_name, app_config_module)
+    app = _initialize_flask_app(app_config)
+    _setup_auth(app)
+    _setup_api(app, api_namespaces)
+    register_commands(app)
+    return app
+
+
+def _resolve_and_validate_config(
+    config_name: str, app_config_module: str
+) -> BaseConfig:
+    """Resolve and instantiate the configuration class."""
+    config_class = get_config(config_name, app_config_module)
+    logger.debug(f"Resolved config class: {config_class.__name__}")
+    config_instance = config_class()  # Validation on instantiation
+    return config_instance
+
+
+def _initialize_flask_app(app_config: BaseConfig) -> Flask:
+    """Create and configure the Flask app instance."""
+    app = Flask("app")
+    app.config.from_object(app_config)
+    return app
+
+
+def _setup_auth(app: Flask) -> None:
+    """Initialize JWT authentication."""
+    init_jwt(app)
+
+
+def _setup_api(
+    app: Flask,
+    api_namespaces: list[tuple[Namespace, str]],
+) -> None:
+    """Configure API and register namespaces."""
+    api = init_api(app)
+    for namespace, path in api_namespaces:
+        api.add_namespace(namespace, path=path)

zecmf/auth/__init__.py

@@ -0,0 +1,19 @@
+"""Authentication module for micro-framework."""
+
+from zecmf.auth.decorators import (
+    public_endpoint,
+    require_admin_role,
+    require_agent_role,
+    require_role,
+    require_user_role,
+)
+from zecmf.auth.jwt import init_jwt
+
+__all__ = [
+    "init_jwt",
+    "public_endpoint",
+    "require_admin_role",
+    "require_agent_role",
+    "require_role",
+    "require_user_role",
+]

zecmf/auth/decorators.py

@@ -0,0 +1,79 @@
+"""Authentication decorators for role-based access control."""
+
+from collections.abc import Callable
+from functools import wraps
+from typing import Any, TypeVar, cast
+
+from flask import g
+from werkzeug.exceptions import Forbidden
+
+# Type variable for generic functions
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+class DecoratorFactory:
+    """Factory to create decorators only when needed in a request context."""
+
+    @staticmethod
+    def require_role(role: str) -> Callable[[F], F]:
+        """Create a decorator to require a specific role."""
+
+        def decorator(f: F) -> F:
+            @wraps(f)
+            def wrapper(*args: object, **kwargs: object) -> object:
+                # Check if user has the required role
+                if not hasattr(g, "user_roles") or role not in g.user_roles:
+                    raise Forbidden(f"Requires role: {role}")
+
+                return f(*args, **kwargs)
+
+            return cast("F", wrapper)
+
+        return decorator
+
+    @staticmethod
+    def public_endpoint() -> Callable[[F], F]:
+        """Create a decorator to mark an endpoint as public.
+
+        This decorator can be applied to:
+        - Regular Flask routes (function-based views)
+        - Specific HTTP methods in Flask-RESTX Resources (apply to method)
+
+        Note: For Flask-RESTX Resource classes, do not apply this decorator directly to
+        the class. Instead, apply it to individual methods.
+        """
+
+        def decorator(f: F) -> F:
+            # Mark the original function as public
+            f.is_public = True  # type: ignore
+
+            @wraps(f)
+            def wrapper(*args: object, **kwargs: object) -> object:
+                return f(*args, **kwargs)
+
+            # Mark the wrapper function as public
+            wrapper.is_public = True  # type: ignore
+
+            return cast("F", wrapper)
+
+        return decorator
+
+
+# Create decorator factory instance
+decorator_factory = DecoratorFactory()
+
+
+def require_role(role: str) -> Callable[[F], F]:
+    """Require a specific role for an endpoint."""
+    return decorator_factory.require_role(role)
+
+
+def public_endpoint() -> Callable[[F], F]:
+    """Mark an endpoint as public, exempt from authentication requirements."""
+    return decorator_factory.public_endpoint()
+
+
+# Pre-defined role decorators for convenience
+require_admin_role = require_role("admin")
+require_user_role = require_role("user")
+require_agent_role = require_role("agent")

zecmf/auth/jwt.py

@@ -0,0 +1,86 @@
+"""JWT authentication module for micro-framework."""
+
+from collections.abc import Callable
+from typing import Any, TypeVar
+
+from flask import Flask, Response, current_app, g, request
+from flask_jwt_extended import (
+    JWTManager,
+    get_jwt,
+    get_jwt_identity,
+    verify_jwt_in_request,
+)
+from werkzeug.exceptions import Unauthorized
+
+# Type variable for generic functions
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+jwt = JWTManager()
+
+
+def _check_public_endpoint(endpoint_func: Callable[..., Any]) -> bool:
+    """Check if an endpoint is marked as public."""
+    # Check if it's a class-based view (like Flask-RESTX resources)
+    if hasattr(endpoint_func, "view_class"):
+        view_class = endpoint_func.view_class
+
+        # Check class for the is_public attribute
+        if hasattr(view_class, "is_public") and view_class.is_public:
+            return True
+
+        # Check the specific method for the is_public attribute
+        method = request.method.lower()
+        if hasattr(view_class, method):
+            handler = getattr(view_class, method)
+            if hasattr(handler, "is_public") and handler.is_public:
+                return True
+
+    # For regular function-based views
+    elif hasattr(endpoint_func, "is_public") and endpoint_func.is_public:
+        return True
+
+    return False
+
+
+def _authenticate_request() -> None:
+    """Authenticate the current request using JWT."""
+    try:
+        verify_jwt_in_request()
+
+        # Get JWT claims
+        claims = get_jwt()
+        user_roles = claims.get("roles", [])
+
+        # Store user info in flask g object for use in the request
+        g.user_id = get_jwt_identity()
+        g.user_roles = user_roles
+    except Exception as err:
+        raise Unauthorized("Authentication required") from err
+
+
+def init_jwt(app: Flask) -> None:
+    """Initialize JWT manager with the Flask app."""
+    jwt.init_app(app)
+
+    # Register before_request handler to enforce authentication by default
+    @app.before_request
+    def enforce_authentication() -> Response | None:
+        """Enforce authentication for each request unless marked as public."""
+        # Skip OPTIONS requests for CORS support
+        if request.method == "OPTIONS":
+            return None
+
+        # Allow access to swagger.json only in debug mode
+        if app.debug and request.path.endswith("/swagger.json"):
+            return None
+
+        # Check if the endpoint is public
+        if request.endpoint is not None:
+            endpoint_func = current_app.view_functions.get(request.endpoint)
+            if endpoint_func is not None and _check_public_endpoint(endpoint_func):
+                return None
+
+        # If we're here, authentication is required
+        _authenticate_request()
+        return None

zecmf/cli/__init__.py

@@ -0,0 +1,5 @@
+"""Command-line interface module for Flask applications."""
+
+from zecmf.cli.commands import register_commands
+
+__all__ = ["register_commands"]

zecmf/cli/commands.py

@@ -0,0 +1,178 @@
+"""Common CLI commands for Flask applications."""
+
+import importlib
+import os
+
+import click
+from flask import Flask, current_app, has_app_context
+from flask.cli import with_appcontext
+from flask_migrate import init, migrate, upgrade
+from sqlalchemy import inspect, text
+from sqlalchemy.exc import ProgrammingError
+
+from zecmf.extensions.database import db
+from zecmf.migrations import setup_migrations
+
+
+def setup_db_impl() -> None:
+    """Implement database setup logic."""
+    click.echo("Setting up database...")
+
+    # Get database connection
+    inspector = inspect(db.engine)
+
+    # Check if tables already exist
+    existing_tables = inspector.get_table_names()
+
+    # Check if migrations directory exists
+    app_root = current_app.root_path
+    migrations_dir = os.path.join(os.path.dirname(app_root), "migrations")
+    migrations_dir_exists = os.path.exists(migrations_dir)
+    migrations_versions_dir = os.path.join(migrations_dir, "versions")
+    has_migration_versions = (
+        os.path.exists(migrations_versions_dir)
+        and len(os.listdir(migrations_versions_dir)) > 0
+    )
+
+    # Initialize migrations directory if it doesn't exist
+    if not migrations_dir_exists:
+        click.echo("Initializing migrations directory...")
+        init()
+        # Create initial migration if needed
+        if not existing_tables:
+            click.echo("Creating initial migration...")
+            migrate(message="Initial migration")
+
+    # Try to apply migrations
+    try:
+        click.echo("Applying migrations...")
+        upgrade()
+        click.echo("Migrations applied successfully!")
+    except ProgrammingError as e:
+        click.echo(f"Migration error: {e!s}")
+
+        # If migrations exist but failed, and we have no tables, create tables directly
+        if has_migration_versions and not existing_tables:
+            click.echo("Falling back to direct table creation...")
+            db.create_all()
+            click.echo("Tables created directly.")
+        else:
+            click.echo(
+                "Could not apply migrations. Please check your database configuration."
+            )
+            raise
+
+    click.echo("Database setup complete!")
+
+
+def health_check_impl() -> None:
+    """Implement health check logic."""
+    click.echo("Checking application health...")
+
+    # Check database connection
+    try:
+        # Use text() to wrap SQL string for proper typing
+        db.session.execute(text("SELECT 1"))
+        click.echo("Database connection: OK")
+    except Exception as e:
+        click.echo(f"Database connection: FAILED ({e!s})")
+        return
+
+    click.echo("All systems operational!")
+
+
+def init_migrations_impl(models_module: list[str]) -> None:
+    """Implement migrations initialization logic.
+
+    Args:
+        models_module: Modules containing models to import (e.g., app.models.user)
+
+    """
+    # Determine base directory for migrations (app root if available, else cwd)
+    if has_app_context():
+        base_dir = os.path.dirname(current_app.root_path)
+    else:
+        base_dir = os.path.dirname(os.getcwd())
+    migrations_dir = os.path.join(base_dir, "migrations")
+
+    # Generate import statements
+    model_imports = []
+    for module_name in models_module:
+        try:
+            module = importlib.import_module(module_name)
+            # Get model classes from the module
+            for attr_name in dir(module):
+                if attr_name.startswith("_"):
+                    continue
+                attr = getattr(module, attr_name)
+                if hasattr(attr, "__tablename__"):
+                    model_imports.append(f"from {module_name} import {attr_name}")
+        except ImportError:
+            click.echo(f"Warning: Could not import module {module_name}")
+
+    # Add import statements for the models
+    click.echo(f"Setting up migrations in {migrations_dir}")
+    setup_migrations(
+        destination_dir=migrations_dir,
+        models_import_statements=model_imports if model_imports else None,
+    )
+    click.echo("Migrations directory initialized successfully.")
+    click.echo("\nNext steps:")
+    click.echo("1. Review the generated files")
+    click.echo("2. Run 'flask db init' to initialize Alembic")
+    click.echo(
+        "3. Run 'flask db migrate -m \"Initial migration\"' to create your first migration"
+    )
+    click.echo("4. Run 'flask db upgrade' to apply the migration")
+
+
+@click.command("setup-db")
+@with_appcontext
+def setup_db() -> None:
+    """Set up database migrations and apply them.
+
+    This command:
+    1. Initializes the migrations directory if it doesn't exist
+    2. Applies all existing migrations to a fresh database
+    3. Creates tables directly if migration fails
+    """
+    setup_db_impl()
+
+
+@click.command("health-check")
+@with_appcontext
+def health_check() -> None:
+    """Check the health of the application and its dependencies."""
+    health_check_impl()
+
+
+@click.command("init-migrations")
+@click.option(
+    "--models-module",
+    "-m",
+    multiple=True,
+    help="Modules containing models to import (format: app.models.user)",
+)
+def init_migrations(models_module: list[str]) -> None:
+    """Initialize migrations directory with templates from the framework.
+
+    This creates a migrations directory with the standard Alembic files,
+    configured to work with the application's models.
+
+    Args:
+        models_module: Modules containing models to import (e.g., app.models.user)
+
+    """
+    init_migrations_impl(models_module)
+
+
+def register_commands(app: Flask) -> None:
+    """Register custom Flask CLI commands.
+
+    Args:
+        app: The Flask application.
+
+    """
+    app.cli.add_command(setup_db)
+    app.cli.add_command(health_check)
+    app.cli.add_command(init_migrations)

zecmf/config/__init__.py

@@ -0,0 +1,60 @@
+"""Configuration module for micro-framework."""
+
+import importlib
+import logging
+
+from zecmf.config.base import (
+    BaseConfig,
+    BaseDevelopmentConfig,
+    BaseProductionConfig,
+    BaseTestingConfig,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def get_config(config_name: str, app_config_module: str) -> type[BaseConfig]:
+    """Get the configuration class by name, with optional app-specific overrides.
+
+    This function allows application-specific configurations to extend the
+    framework's base configurations. It will look for a class with the same name
+    as the requested config_name in the app config module and return it if found.
+
+    Args:
+        config_name: The name of the configuration to get ("development", "testing", etc.).
+        app_config_module: The module path for the app-specific configuration.
+
+    Returns:
+        The appropriate configuration class, with app overrides if available.
+
+    """
+    try:
+        app_config = importlib.import_module(app_config_module)
+        app_config_class_name = f"{config_name.capitalize()}Config"
+        if not hasattr(app_config, app_config_class_name):
+            raise AttributeError(
+                f"Config class {app_config_class_name} not found in {app_config_module}."
+            )
+
+        app_config_class = getattr(app_config, app_config_class_name)
+        if not issubclass(app_config_class, BaseConfig):
+            raise TypeError(
+                f"App config class {app_config_class_name} is not a subclass of BaseConfig."
+            )
+
+    except ImportError as e:
+        raise ImportError(
+            f"Failed to import app config module '{app_config_module}': {e}"
+        ) from e
+    else:
+        logger.debug(f"Using app config class: {app_config_class.__name__}")
+        return app_config_class
+
+
+__all__ = [
+    "BaseConfig",
+    "BaseDevelopmentConfig",
+    "BaseProductionConfig",
+    "BaseTestingConfig",
+    "get_config",
+]

zecmf/config/base.py

@@ -0,0 +1,184 @@
+"""Base configuration classes for the application."""
+
+import logging
+import os
+from pathlib import Path
+from typing import Any, ClassVar
+
+logger = logging.getLogger(__name__)
+
+
+class BaseConfig:
+    """Base configuration class with shared settings for all applications.
+
+    This contains all common settings that are shared across all applications.
+    Applications should only need to define app-specific settings or override
+    settings that differ from these defaults.
+    """
+
+    # Flask settings
+    SECRET_KEY: str | None = os.getenv(
+        "SECRET_KEY"
+    )  # Required in production, default in dev/test
+    DEBUG: bool = False
+    TESTING: bool = False
+
+    # Database settings
+    SQLALCHEMY_DATABASE_URI: str | None = os.getenv("DATABASE_URI")
+    SQLALCHEMY_TRACK_MODIFICATIONS: bool = False
+    SQLALCHEMY_ENGINE_OPTIONS: ClassVar[dict[str, Any]] = {
+        "pool_recycle": 3600,
+        "pool_pre_ping": True,
+    }
+
+    # API settings
+    API_TITLE: str = "API"
+    API_VERSION: str = "1.0"
+    API_DESCRIPTION: str = "REST API Service"
+    API_PREFIX: str = "/api/v1"
+    API_VERSION_HEADER: bool = True
+
+    # File upload settings
+    MAX_CONTENT_LENGTH: int = 1024 * 1024  # 1MB
+
+    # JWT settings - supporting both public key (RS256) and secret key (HS256) methods
+    JWT_PUBLIC_KEY: str | None = os.getenv("JWT_PUBLIC_KEY")
+    JWT_PUBLIC_KEY_PATH: str | None = os.getenv("JWT_PUBLIC_KEY_PATH")
+    JWT_SECRET_KEY: str | None = os.getenv("JWT_SECRET_KEY")
+    JWT_ALGORITHM: str = "RS256"
+    JWT_TOKEN_LOCATION: ClassVar[list[str]] = ["headers"]
+    JWT_HEADER_NAME: str = "Authorization"
+    JWT_HEADER_TYPE: str = "Bearer"
+    JWT_ACCESS_TOKEN_EXPIRES: int = 30 * 60  # seconds
+    JWT_REFRESH_TOKEN_EXPIRES: int = 30 * 24 * 60 * 60  # seconds
+
+    def __init__(self) -> None:
+        """Initialize configuration with validation.
+
+        This validates the configuration based on the selected algorithm:
+        - For RS256: requires either JWT_PUBLIC_KEY or JWT_PUBLIC_KEY_PATH
+        - For HS256: requires JWT_SECRET_KEY
+        """
+        # Skip validation for testing
+        if getattr(self, "SKIP_VALIDATION", False):
+            return
+
+        # If SECRET_KEY can be None when DEBUG is True, but is required in production
+        if not self.DEBUG and not self.SECRET_KEY:
+            raise ValueError("SECRET_KEY must be set in production environments.")
+
+        # For RS256 (asymmetric) authentication
+        if self.JWT_ALGORITHM == "RS256":
+            self._validate_rs256_config()
+        # For HS256 (symmetric) authentication
+        elif self.JWT_ALGORITHM == "HS256":
+            self._validate_hs256_config()
+
+    def _validate_rs256_config(self) -> None:
+        """Validate RS256 configuration settings."""
+        if self.JWT_PUBLIC_KEY and self.JWT_PUBLIC_KEY_PATH:
+            raise ValueError(
+                "Both JWT_PUBLIC_KEY and JWT_PUBLIC_KEY_PATH are set. "
+                "Please provide only one of them."
+            )
+        # Allow no keys for development but not production
+        elif not self.JWT_PUBLIC_KEY and not self.JWT_PUBLIC_KEY_PATH:
+            if not self.DEBUG:
+                raise ValueError(
+                    "Either JWT_PUBLIC_KEY or JWT_PUBLIC_KEY_PATH must be set "
+                    "in production when using RS256."
+                )
+            else:
+                # Fall back to HS256 in development when no RS256 keys available
+                logger.warning(
+                    "No RS256 keys available. Falling back to HS256 in development."
+                )
+                self.JWT_ALGORITHM = "HS256"
+                if not self.JWT_SECRET_KEY:
+                    self.JWT_SECRET_KEY = self.SECRET_KEY
+        elif self.JWT_PUBLIC_KEY_PATH and not self.JWT_PUBLIC_KEY:
+            path = Path(self.JWT_PUBLIC_KEY_PATH)
+            if path.exists():
+                with open(path, encoding="utf-8") as f:
+                    self.JWT_PUBLIC_KEY = f.read()
+            elif not self.DEBUG:
+                raise ValueError(f"JWT_PUBLIC_KEY_PATH '{path}' does not exist.")
+            else:
+                # Fall back to HS256 in development when file not found
+                logger.warning(
+                    f"JWT_PUBLIC_KEY_PATH '{path}' not found. Falling back to HS256 in development."
+                )
+                self.JWT_ALGORITHM = "HS256"
+                if not self.JWT_SECRET_KEY:
+                    self.JWT_SECRET_KEY = self.SECRET_KEY
+
+    def _validate_hs256_config(self) -> None:
+        """Validate HS256 configuration settings."""
+        # Use SECRET_KEY as fallback for JWT_SECRET_KEY if not set
+        if not self.JWT_SECRET_KEY and self.SECRET_KEY:
+            self.JWT_SECRET_KEY = self.SECRET_KEY
+        elif not self.JWT_SECRET_KEY and not self.DEBUG:
+            raise ValueError(
+                "JWT_SECRET_KEY must be set in production when using HS256 algorithm."
+            )
+
+
+class BaseDevelopmentConfig(BaseConfig):
+    """Development configuration for local development environments.
+
+    Provides defaults that make development easier with minimal setup.
+    """
+
+    # Enable debugging features
+    DEBUG: bool = True
+
+    # Default database is SQLite for easy development
+    SQLALCHEMY_DATABASE_URI: str = os.getenv("DATABASE_URI", "sqlite:///dev.sqlite3")
+
+    # Default secret key for development (DO NOT use in production)
+    SECRET_KEY: str = os.getenv("SECRET_KEY", "dev-key-not-for-production")
+
+
+class BaseProductionConfig(BaseConfig):
+    """Production configuration for deployment.
+
+    Prioritizes security and requires proper environment configuration.
+    """
+
+    # Disable debugging features in production
+    DEBUG: bool = False
+    TESTING: bool = False
+
+    # These need to be explicitly set from environment in production
+    # SECRET_KEY = os.getenv("SECRET_KEY")  # This is intentionally not set to force proper configuration
+    # SQLALCHEMY_DATABASE_URI = os.getenv("DATABASE_URI")  # This is intentionally not set to force proper configuration
+
+
+class BaseTestingConfig(BaseConfig):
+    """Testing configuration for unit and integration tests.
+
+    Provides fast, isolated test environment with in-memory database.
+    """
+
+    # Enable testing features
+    TESTING: bool = True
+    DEBUG: bool = False
+
+    # Use in-memory SQLite for speed
+    # Match the BaseConfig type for compatibility
+    SQLALCHEMY_DATABASE_URI: str | None = "sqlite:///:memory:"
+
+    # Fixed secret key for test reproducibility
+    # Match the BaseConfig type for compatibility
+    SECRET_KEY: str | None = "testing-secret-key"
+
+    # HS256 is easier for testing
+    JWT_ALGORITHM: str = "HS256"
+    # Match the BaseConfig type for compatibility
+    JWT_SECRET_KEY: str | None = "testing-secret-key"
+
+    # Skip validation in tests
+    SKIP_VALIDATION: bool = True
+
+    # Shortened token expiration for faster testing
+    JWT_ACCESS_TOKEN_EXPIRES: int = 60  # 1 minute

zecmf/constants.py

@@ -0,0 +1,39 @@
+"""Constants shared across microservices."""
+
+
+# HTTP Status Codes
+class HTTPStatus:
+    """HTTP status codes for API responses."""
+
+    # Success
+    OK = 200
+    CREATED = 201
+    ACCEPTED = 202
+    NO_CONTENT = 204
+
+    # Client Errors
+    BAD_REQUEST = 400
+    UNAUTHORIZED = 401
+    PAYMENT_REQUIRED = 402
+    FORBIDDEN = 403
+    NOT_FOUND = 404
+    METHOD_NOT_ALLOWED = 405
+    CONFLICT = 409
+    GONE = 410
+    UNPROCESSABLE_ENTITY = 422
+    TOO_MANY_REQUESTS = 429
+
+    # Server Errors
+    INTERNAL_SERVER_ERROR = 500
+    NOT_IMPLEMENTED = 501
+    BAD_GATEWAY = 502
+    SERVICE_UNAVAILABLE = 503
+    GATEWAY_TIMEOUT = 504
+
+
+# Common configuration constants
+class Config:
+    """Configuration constants used across services."""
+
+    # App config module path
+    APP_CONFIG_MODULE = "app.config"

zecmf/extensions/__init__.py

@@ -0,0 +1 @@
+"""Extensions package for Flask application."""

zecmf/extensions/database.py

@@ -0,0 +1,22 @@
+"""Database extension module.
+
+Sets up SQLAlchemy and Flask-Migrate for database operations.
+"""
+
+from flask import Flask
+from flask_migrate import Migrate
+from flask_sqlalchemy import SQLAlchemy
+
+db = SQLAlchemy()
+migrate = Migrate()
+
+
+def init_app(app: Flask) -> None:
+    """Initialize the database extension.
+
+    Args:
+        app: The Flask application.
+
+    """
+    db.init_app(app)
+    migrate.init_app(app, db)

zecmf/extensions/queue.py

@@ -0,0 +1,37 @@
+"""Queue extension module.
+
+Sets up Celery for asynchronous task processing with Flask integration.
+"""
+
+from celery import Celery, Task
+from flask import Flask
+
+celery = Celery()
+
+
+def init_app(app: Flask) -> None:
+    """Initialize Celery with the Flask app."""
+    # Get configuration from app config with defaults
+    broker_url = app.config.get("CELERY_BROKER_URL", "memory://")
+    result_backend = app.config.get("CELERY_RESULT_BACKEND", "cache")
+
+    celery.conf.update(
+        broker_url=broker_url,
+        result_backend=result_backend,
+        task_serializer="json",
+        accept_content=["json"],
+        result_serializer="json",
+        task_track_started=True,
+        task_time_limit=1800,  # 30 minutes
+        worker_max_tasks_per_child=100,
+        broker_connection_retry_on_startup=True,
+    )
+
+    class ContextTask(Task):
+        def __call__(self, *args: object, **kwargs: object) -> object:
+            with app.app_context():
+                return self.run(*args, **kwargs)
+
+    # Set ContextTask as the default task base class
+    celery.conf.update(task_default_queue="default")
+    celery.conf.task_cls = ContextTask

zecmf/migrations/README.template

@@ -0,0 +1,3 @@
+Generic single-database configuration with Alembic.
+
+This directory contains database migration scripts using Alembic.

zecmf/migrations/__init__.py

@@ -0,0 +1,74 @@
+"""Migrations initialization module for microservices."""
+
+import os
+from importlib import resources
+
+
+def _copy_template_file(src_path: str, dest_path: str) -> None:
+    """Copy a template file from src_path to dest_path."""
+    with (
+        open(src_path, encoding="utf-8") as src_file,
+        open(dest_path, "w", encoding="utf-8") as dest_file,
+    ):
+        dest_file.write(src_file.read())
+
+
+def _copy_and_customize_env_py(
+    src_path: str, dest_path: str, models_import_statements: list[str] | None
+) -> None:
+    """Copy env.py template and insert model imports if provided."""
+    with open(src_path, encoding="utf-8") as src_file:
+        env_template = src_file.read()
+    if models_import_statements:
+        model_imports = "\n".join(models_import_statements)
+        env_template = env_template.replace(
+            "# <IMPORT_MODELS_PLACEHOLDER>", model_imports
+        )
+    else:
+        env_template = env_template.replace("# <IMPORT_MODELS_PLACEHOLDER>", "")
+    with open(dest_path, "w", encoding="utf-8") as dest_file:
+        dest_file.write(env_template)
+
+
+def _ensure_migration_dirs(destination_dir: str) -> None:
+    """Ensure the migrations and versions directories exist."""
+    os.makedirs(destination_dir, exist_ok=True)
+    versions_dir = os.path.join(destination_dir, "versions")
+    os.makedirs(versions_dir, exist_ok=True)
+
+
+def setup_migrations(
+    destination_dir: str, models_import_statements: list[str] | None = None
+) -> None:
+    """Set up the migrations directory for a microservice.
+
+    This function creates the basic structure for Alembic migrations
+    by copying template files from the zecmf package.
+
+    Args:
+        destination_dir: The directory where migrations will be set up
+        models_import_statements: Optional list of import statements for models
+            to be included in the env.py file
+
+    """
+    _ensure_migration_dirs(destination_dir)
+    package_path = resources.files("zecmf.migrations")
+    package_path_str = str(package_path)
+
+    _copy_template_file(
+        os.path.join(package_path_str, "alembic.ini.template"),
+        os.path.join(destination_dir, "alembic.ini"),
+    )
+    _copy_template_file(
+        os.path.join(package_path_str, "script.py.mako"),
+        os.path.join(destination_dir, "script.py.mako"),
+    )
+    _copy_template_file(
+        os.path.join(package_path_str, "README.template"),
+        os.path.join(destination_dir, "README"),
+    )
+    _copy_and_customize_env_py(
+        os.path.join(package_path_str, "env.py.template"),
+        os.path.join(destination_dir, "env.py"),
+        models_import_statements,
+    )

zecmf/migrations/alembic.ini.template

@@ -0,0 +1,74 @@
+# A generic, single database configuration.
+
+[alembic]
+# path to migration scripts
+script_location = migrations
+
+# template used to generate migration files
+# file_template = %%(rev)s_%%(slug)s
+
+# timezone to use when rendering the date
+# within the migration file as well as the filename.
+# string value is passed to dateutil.tz.gettz()
+# leave blank for localtime
+# timezone =
+
+# max length of characters to apply to the
+# "slug" field
+# truncate_slug_length = 40
+
+# set to 'true' to run the environment during
+# the 'revision' command, regardless of autogenerate
+# revision_environment = false
+
+# set to 'true' to allow .pyc and .pyo files without
+# a source .py file to be detected as revisions in the
+# versions/ directory
+# sourceless = false
+
+# version location specification; this defaults
+# to alembic/versions.  When using multiple version
+# directories, initial revisions must be specified with --version-path
+# version_locations = %(here)s/bar %(here)s/bat alembic/versions
+
+# the output encoding used when revision files
+# are written from script.py.mako
+# output_encoding = utf-8
+
+sqlalchemy.url = driver://user:pass@localhost/dbname
+
+
+# Logging configuration
+[loggers]
+keys = root,sqlalchemy,alembic
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = WARN
+handlers = console
+qualname =
+
+[logger_sqlalchemy]
+level = WARN
+handlers =
+qualname = sqlalchemy.engine
+
+[logger_alembic]
+level = INFO
+handlers =
+qualname = alembic
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(levelname)-5.5s [%(name)s] %(message)s
+datefmt = %H:%M:%S

zecmf/migrations/env.py.template

@@ -0,0 +1,97 @@
+"""Alembic environment configuration for database migrations."""
+
+from logging.config import fileConfig
+
+from alembic import context
+from flask import current_app
+
+# this is the Alembic Config object, which provides
+# access to the values within the .ini file in use.
+config = context.config
+
+# Interpret the config file for Python logging.
+# This line sets up loggers basically.
+fileConfig(config.config_file_name)
+
+# add your model's MetaData object here
+# for 'autogenerate' support
+from zecmf.extensions.database import db
+
+target_metadata = db.metadata
+
+# Import all models to ensure they're registered with SQLAlchemy
+# The actual import statements will be populated by the setup process
+# <IMPORT_MODELS_PLACEHOLDER>
+
+# other values from the config, defined by the needs of env.py,
+# can be acquired:
+# my_important_option = config.get_main_option("my_important_option")
+# ... etc.
+
+
+def get_url() -> str:
+    """Get database URL from Flask app config."""
+    return current_app.config.get("SQLALCHEMY_DATABASE_URI")
+
+
+def run_migrations_offline() -> None:
+    """Run migrations in 'offline' mode.
+
+    This configures the context with just a URL
+    and not an Engine, though an Engine is acceptable
+    here as well.  By skipping the Engine creation
+    we don't even need a DBAPI to be available.
+
+    Calls to context.execute() here emit the given string to the
+    script output.
+
+    """
+    url = get_url()
+    context.configure(
+        url=url,
+        target_metadata=target_metadata,
+        literal_binds=True,
+        dialect_opts={"paramstyle": "named"},
+    )
+
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def run_migrations_online() -> None:
+    """Run migrations in 'online' mode.
+
+    In this scenario we need to create an Engine
+    and associate a connection with the context.
+
+    """
+
+    # this callback is used to prevent an auto-migration from being generated
+    # when there are no changes to the schema
+    # reference: http://alembic.zzzcomputing.com/en/latest/cookbook.html
+    def process_revision_directives(
+        context_: object, revision: object, directives: list
+    ) -> None:
+        if getattr(config.cmd_opts, "autogenerate", False):
+            script = directives[0]
+            if script.upgrade_ops.is_empty():
+                directives[:] = []
+
+    from zecmf.extensions.database import db
+    connectable = db.engine
+
+    with connectable.connect() as connection:
+        context.configure(
+            connection=connection,
+            target_metadata=target_metadata,
+            process_revision_directives=process_revision_directives,
+        )
+
+        with context.begin_transaction():
+            context.run_migrations()
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    run_migrations_online()

zecmf/migrations/script.py.mako

@@ -0,0 +1,24 @@
+"""${message}
+
+Revision ID: ${up_revision}
+Revises: ${down_revision | comma,n}
+Create Date: ${create_date}
+
+"""
+from alembic import op
+import sqlalchemy as sa
+${imports if imports else ""}
+
+# revision identifiers, used by Alembic.
+revision = ${repr(up_revision)}
+down_revision = ${repr(down_revision)}
+branch_labels = ${repr(branch_labels)}
+depends_on = ${repr(depends_on)}
+
+
+def upgrade():
+    ${upgrades if upgrades else "pass"}
+
+
+def downgrade():
+    ${downgrades if downgrades else "pass"}

zecmf/testing/__init__.py

@@ -0,0 +1,3 @@
+"""Testing utilities for micro-framework applications."""
+
+from zecmf.testing.constants import *  # noqa

zecmf/testing/config.py

@@ -0,0 +1,9 @@
+"""Used by ZecMF-internal tests as app_config_module."""
+
+from zecmf.config.base import BaseTestingConfig
+
+
+class TestingConfig(BaseTestingConfig):
+    """Testing configuration for unit and integration tests."""
+
+    pass

zecmf/testing/constants.py

@@ -0,0 +1,16 @@
+"""Constants for testing."""
+
+from zecmf.constants import HTTPStatus
+
+# Re-export HTTP status codes for convenience in tests
+HTTP_OK = HTTPStatus.OK
+HTTP_CREATED = HTTPStatus.CREATED
+HTTP_ACCEPTED = HTTPStatus.ACCEPTED
+HTTP_NO_CONTENT = HTTPStatus.NO_CONTENT
+HTTP_BAD_REQUEST = HTTPStatus.BAD_REQUEST
+HTTP_UNAUTHORIZED = HTTPStatus.UNAUTHORIZED
+HTTP_FORBIDDEN = HTTPStatus.FORBIDDEN
+HTTP_NOT_FOUND = HTTPStatus.NOT_FOUND
+HTTP_CONFLICT = HTTPStatus.CONFLICT
+HTTP_UNPROCESSABLE_ENTITY = HTTPStatus.UNPROCESSABLE_ENTITY
+HTTP_INTERNAL_SERVER_ERROR = HTTPStatus.INTERNAL_SERVER_ERROR

zecmf-0.1.0.dist-info/METADATA

@@ -0,0 +1,43 @@
+Metadata-Version: 2.4
+Name: zecmf
+Version: 0.1.0
+Summary: A framework for building microservices in Python
+Author-email: Hendrik Buchwald <hb@zecure.org>
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: flask==3.1.1
+Requires-Dist: flask-restx==1.3.0
+Requires-Dist: jsonschema==4.17.3
+Requires-Dist: flask-sqlalchemy==3.1.1
+Requires-Dist: flask-migrate==4.1.0
+Requires-Dist: flask-jwt-extended==4.7.1
+Requires-Dist: werkzeug==3.1.3
+Requires-Dist: sqlalchemy==2.0.41
+Requires-Dist: click==8.2.0
+Requires-Dist: celery==5.5.2
+Provides-Extra: dev
+Requires-Dist: pytest==8.3.5; extra == "dev"
+Requires-Dist: pytest-cov==6.1.1; extra == "dev"
+Requires-Dist: ruff==0.11.10; extra == "dev"
+Requires-Dist: mypy==1.15.0; extra == "dev"
+Requires-Dist: types-Flask-Migrate==4.1.0.20250112; extra == "dev"
+
+# Zecure Microservices Framework (ZecMF)
+
+A lightweight framework for building microservices in Python with Flask.
+
+## Features
+
+- **Application Factory**: Streamlined Flask application initialization
+- **JWT Authentication**: Built-in JWT authentication with both RS256 and HS256 support
+- **API Setup**: Simplified REST API initialization with Flask-RESTX
+- **Database**: SQLAlchemy and Alembic integration
+- **CLI Commands**: Common CLI commands for microservice management
+- **Configuration**: Hierarchical configuration system with framework defaults and app-specific overrides
+
+## Installation
+
+```bash
+pip install zecmf
+```

zecmf-0.1.0.dist-info/RECORD

@@ -0,0 +1,26 @@
+zecmf/__init__.py,sha256=d2vk_Z5YhJRa3-1MgSHPbMeuFiWPFHRRnZeoyE5Yd4U,154
+zecmf/app.py,sha256=iX4h1qJ1BSMeRsOqI7JeFtUGf4ORcA361VMWH4zBF-w,2392
+zecmf/constants.py,sha256=Mz4mO1uf--POUxZGD9YmAB7FiObjZi7NKytrQkSRpVY,802
+zecmf/api/__init__.py,sha256=IEskBWccYpE4dz4_lAY5QMHv3tN62fi4LitT9IpIrbI,1189
+zecmf/auth/__init__.py,sha256=vtob-F64LWHkCVJenTZUsovmQXNyqnBWXlKQt5aVq1Q,385
+zecmf/auth/decorators.py,sha256=WZGjs-zxmnCwXpupJbOtBeeAoUJxUIqc66cjjoYg6vs,2443
+zecmf/auth/jwt.py,sha256=RGEjiioHtDPlTg9aMXm1obiRIZ5uJL98dLJpWBOIV9c,2763
+zecmf/cli/__init__.py,sha256=qmJkv898McOFTGZ04oX68pK6OGAR4gkVxsYghU9_2ig,143
+zecmf/cli/commands.py,sha256=GJmoGcOpADEvajqgHHhwLWbwQ3Qu0h7koL1jHt_u9EQ,5735
+zecmf/config/__init__.py,sha256=fH27K8pLzAQ5Owe1j-f203p60GGy6ClYkxdkfDlbzwo,1936
+zecmf/config/base.py,sha256=SQBza11KRBYGFo1KTWPmJ1WU1EKGOnb6V2nhXeShX38,6940
+zecmf/extensions/__init__.py,sha256=4XJ7BIhRI_xXDZH-VH4nqgYgo2GZWhUayXOGMOsqg5U,48
+zecmf/extensions/database.py,sha256=ZQxcRRpLyhSo41wkE1PoJmjvB_E87RZafZUxVZR_LX0,420
+zecmf/extensions/queue.py,sha256=_Xk3oh_jC8CL0SGCUN7ExmvzFqNZ2nM6MAXuLZ0-TOE,1152
+zecmf/migrations/README.template,sha256=rHo53QkNpXmN-V8qdmg4-jQ3_ZgGVr86IAGVk4szxfE,118
+zecmf/migrations/__init__.py,sha256=WyaU-o0KinnbOTGp61x-fxI7pr_LKGVRvko9iPNbpPg,2628
+zecmf/migrations/alembic.ini.template,sha256=PgPI8bQQJ-wzmsU8blYSvenGwi2H0s6KXgHoEl-8DUY,1650
+zecmf/migrations/env.py.template,sha256=zqRo_IROKTT-PEhsimGdlzNWK96itAN575U7PlQdS0k,2810
+zecmf/migrations/script.py.mako,sha256=LiqCKQAJ2Wbqo1HT-HsFMsDtqPF8kWX7Yudz0AXGEQ4,493
+zecmf/testing/__init__.py,sha256=4EASYNTYXwDxKZkSkgRkVUun3Kvybk6p5QVw9DMWfTQ,105
+zecmf/testing/config.py,sha256=W878tu0HdGNo4ZlmjXVsoyxSHyNwoYsqweWNl2r508I,222
+zecmf/testing/constants.py,sha256=ecltZHKmlNlvSrmq0v2bQxaj5v7_kM7Ko6DMOn2iHvw,579
+zecmf-0.1.0.dist-info/METADATA,sha256=XzQc6OFB5hThipCUVCHz84gHcxifNN-nvKFa_wkJskU,1505
+zecmf-0.1.0.dist-info/WHEEL,sha256=zaaOINJESkSfm_4HQVc5ssNzHCPXhJm0kEUakpsEHaU,91
+zecmf-0.1.0.dist-info/top_level.txt,sha256=xFSLpzOVc-oDRAr-bijDqsE5Cbm_Y7hn8kGDPN3b32A,6
+zecmf-0.1.0.dist-info/RECORD,,

zecmf-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.8.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

zecmf-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+zecmf