zecmf 0.1.0__tar.gz

zecmf-0.1.0/MANIFEST.in

@@ -0,0 +1 @@
+recursive-include src/zecmf/migrations *.template *.mako

zecmf-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,18 @@
+# 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/pyproject.toml

@@ -0,0 +1,161 @@
+[build-system]
+requires = ["setuptools>=80.8", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "zecmf"
+version = "0.1.0"
+description = "A framework for building microservices in Python"
+authors = [
+    {name = "Hendrik Buchwald", email = "hb@zecure.org"},
+]
+readme = "README.md"
+requires-python = ">=3.12"
+classifiers = [
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+    "flask==3.1.1",
+    "flask-restx==1.3.0",
+    "jsonschema==4.17.3",       # https://github.com/python-restx/flask-restx/issues/553#issuecomment-1639837981
+    "flask-sqlalchemy==3.1.1",
+    "flask-migrate==4.1.0",
+    "flask-jwt-extended==4.7.1",
+    "werkzeug==3.1.3",
+    "sqlalchemy==2.0.41",
+    "click==8.2.0",
+    "celery==5.5.2",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest==8.3.5",
+    "pytest-cov==6.1.1",
+    "ruff==0.11.10",
+    "mypy==1.15.0",
+    "types-Flask-Migrate==4.1.0.20250112",
+]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.ruff]
+line-length = 88
+indent-width = 4
+
+[tool.ruff.lint]
+preview = true
+unfixable = []
+select = [
+    "E",   # pycodestyle errors
+    "F",   # pyflakes
+    "I",   # isort
+    "UP",  # pyupgrade
+    "C",   # flake8-comprehensions
+    "B",   # flake8-bugbear
+    "W",   # pycodestyle warnings
+    "D",   # pydocstyle
+    "N",   # flake8-naming
+    "COM", # flake8-commas
+    "S",   # flake8-bandit
+    "BLE", # flake8-blind-except
+    "A",   # flake8-builtins
+    "PT",  # flake8-pytest-style
+    "SIM", # flake8-simplify
+    "TD",  # flake8-todos
+    "PD",  # pandas-vet
+    "PL",  # pylint
+    "NPY", # numpy
+    "RUF", # ruff-specific rules
+    "ANN", # flake8-annotations
+    "TCH", # flake8-type-checking
+    "TRY", # flake8-try-except-raise
+]
+ignore = [
+    "COM812",  # Missing trailing comma
+    "D203",    # One blank line before class docstring
+    "D211",    # No blank lines before class docstring
+    "D213",    # Multi-line docstring summary should start at the second line
+    "S105",    # Possible hardcoded password
+    "S106",    # Possible hardcoded password
+    "PLR6301", # Method could be a function - common in API endpoints
+    "E501",    # Line too long
+    "TRY003",  # Avoid specifying long messages outside exception class
+    "PLR0913", # Too many arguments in function definition
+    "PLR0917", # Too many positional arguments
+    "S110",    # try-except-pass detected, consider logging the exception
+    "BLE001",  # Do not catch blind exception
+    "PLR0904", # Too many public methods
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*.py" = [
+    "ANN001",   # Missing type annotation for function argument
+    "ANN101",   # Missing type annotation for self in method
+    "ANN201",   # Missing return type annotation for public function
+    "ANN204",   # Missing return type annotation for special method
+    "S101",     # Use of assert detected
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["zecmf"]
+section-order = [
+    "future",
+    "standard-library",
+    "third-party",
+    "first-party",
+    "local-folder"
+]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+skip-magic-trailing-comma = false
+line-ending = "auto"
+
+[tool.mypy]
+exclude = "build/"
+
+# Module resolution settings
+namespace_packages = true
+implicit_reexport = true
+follow_imports = "silent"
+
+# Type checking strictness
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+disallow_untyped_calls = false
+check_untyped_defs = true
+disallow_untyped_decorators = false
+disallow_subclassing_any = false
+disallow_any_unimported = false
+disallow_any_generics = false
+
+# Error reporting settings
+no_implicit_optional = true
+strict_optional = true
+warn_redundant_casts = true
+warn_no_return = true
+warn_return_any = false  # Don't warn about returning Any
+warn_unused_ignores = false  # Allow necessary type ignores
+
+[[tool.mypy.overrides]]
+module = "celery.*"
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = "flask_restx.*"
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = "test_*.py"
+python_classes = ["Test*"]
+markers = [
+    "no_test: marks classes that should not be collected as tests"
+]
+addopts = "--import-mode=importlib"

zecmf-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

zecmf-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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"]