overflask 0.1.0__tar.gz

overflask-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 rklaus
+
+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.

overflask-0.1.0/PKG-INFO

@@ -0,0 +1,220 @@
+Metadata-Version: 2.4
+Name: overflask
+Version: 0.1.0
+Summary: Flask scaffolding CLI and runtime library — component architecture, SQLAlchemy, Redis caching, async tasks, and Elasticsearch analytics
+Author: rklaus
+License: MIT License
+        
+        Copyright (c) 2026 rklaus
+        
+        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.
+Project-URL: Homepage, https://gitlab.com/overflask/overflask
+Project-URL: Source, https://gitlab.com/overflask/overflask
+Project-URL: Tracker, https://gitlab.com/overflask/overflask/-/issues
+Keywords: flask,scaffolding,cli,sqlalchemy,redis,elasticsearch,tasks,analytics
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Web Environment
+Classifier: Framework :: Flask
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP :: WSGI :: Application
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.0
+Requires-Dist: flask>=3.0
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: sqlalchemy>=2.0
+Requires-Dist: redis>=5.0
+Requires-Dist: elasticsearch>=8.0
+Requires-Dist: croniter>=3.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-tmp-files>=0.0.2; extra == "dev"
+Requires-Dist: ruff>=0.8; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Dynamic: license-file
+
+# overflask
+
+A CLI tool that scaffolds Flask projects with component-based architecture, and a runtime library that adds SQLAlchemy models, Redis caching, async/recurring tasks, and Elasticsearch analytics on top of Flask.
+
+## Install
+
+```bash
+pip install overflask @ git+https://gitlab.com/hamdarsi/overflask.git
+```
+
+## Create a project
+
+```bash
+overflask create myapp
+```
+
+The CLI prompts for an initial component name and Postgres/Redis connection details, generates the project, pre-fills `.env`, and optionally starts the database containers.
+
+```
+myapp/
+├── manage.py           # project CLI
+├── settings.py         # configuration
+├── requirements.pip    # dependencies
+├── compose.yaml        # Docker Compose
+├── conftest.py         # pytest fixtures
+├── ops/
+│   ├── env.template
+│   ├── migrations/     # Alembic
+│   └── setup-traefik.sh
+├── docs/
+└── components/
+    └── myapp/
+        ├── models.py
+        ├── views.py
+        ├── services.py
+        ├── cli.py
+        ├── tasks.py
+        └── tests.py
+```
+
+## Add a component
+
+```bash
+python manage.py component add auth
+```
+
+Creates `components/auth/` with the same structure and registers it in `settings.COMPONENTS`.
+
+## Runtime library
+
+Generated projects import directly from `overflask`:
+
+### Models
+
+```python
+from overflask import ModelBase
+from sqlalchemy.orm import Mapped, mapped_column
+
+class User(ModelBase):
+    # __tablename__ auto-set to "auth_users"
+    id: Mapped[int] = mapped_column(primary_key=True)
+    email: Mapped[str] = mapped_column(String(255), unique=True)
+```
+
+Table names are derived automatically as `{component}_{plural_snake_case_model_name}`.
+
+### Redis cache
+
+```python
+from overflask import cached
+
+@cached(ttl=300)
+def get_user(user_id: int):
+    ...
+```
+
+Backed by Redis db 15 with stampede prevention via locking.
+
+### Async tasks
+
+```python
+from overflask import async_task
+
+@async_task
+def send_welcome_email(user_id: int, email: str) -> None:
+    ...
+
+# Enqueue immediately or with a delay
+send_welcome_email.queue(user_id=42, email="alice@example.com")
+send_welcome_email.queue(timedelta(minutes=5), user_id=42, email="alice@example.com")
+```
+
+### Recurring tasks
+
+```python
+from overflask import recurring_task
+
+@recurring_task("0 9 * * MON-FRI")
+def daily_report() -> None:
+    ...
+```
+
+Tasks are stored in Elasticsearch and dispatched via Redis. Run the supporting processes:
+
+```bash
+python manage.py tasks scheduler   # polls ES, dispatches due tasks
+python manage.py tasks worker      # executes tasks from Redis queue
+```
+
+### Analytics
+
+```python
+from overflask.analytics import Analytics
+
+Analytics.record("user.registered", area="auth", plan="free")
+Analytics.record("purchase.completed", area="billing", amount=99)
+```
+
+Events are buffered in-process and bulk-flushed to Elasticsearch in the background. Each `area` gets its own monthly index (`myapp_analytics_auth-2026.03`).
+
+## Database migrations
+
+```bash
+python manage.py db migrate -m "add users table"
+python manage.py db upgrade
+python manage.py db downgrade 001
+```
+
+## Testing
+
+```bash
+pytest               # all tests
+pytest -m unit       # unit tests only (no DB)
+pytest -m integration
+pytest -n auto       # parallel
+```
+
+Integration tests run against a real PostgreSQL instance using a cloned template database — fast isolation without `create_all()` per test. Redis is always replaced with fakeredis.
+
+## Deployment
+
+The generated project ships with a Gunicorn config and Traefik integration for HTTPS:
+
+```bash
+bash ops/setup-traefik.sh   # one-time Traefik setup per server
+docker compose up -d
+docker compose exec web python manage.py db upgrade
+```
+
+See `docs/traefik.md` and `docs/gunicorn.md` in the generated project for details.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+ruff check src/ tests/
+ruff format src/ tests/
+```

overflask-0.1.0/README.md

@@ -0,0 +1,159 @@
+# overflask
+
+A CLI tool that scaffolds Flask projects with component-based architecture, and a runtime library that adds SQLAlchemy models, Redis caching, async/recurring tasks, and Elasticsearch analytics on top of Flask.
+
+## Install
+
+```bash
+pip install overflask @ git+https://gitlab.com/hamdarsi/overflask.git
+```
+
+## Create a project
+
+```bash
+overflask create myapp
+```
+
+The CLI prompts for an initial component name and Postgres/Redis connection details, generates the project, pre-fills `.env`, and optionally starts the database containers.
+
+```
+myapp/
+├── manage.py           # project CLI
+├── settings.py         # configuration
+├── requirements.pip    # dependencies
+├── compose.yaml        # Docker Compose
+├── conftest.py         # pytest fixtures
+├── ops/
+│   ├── env.template
+│   ├── migrations/     # Alembic
+│   └── setup-traefik.sh
+├── docs/
+└── components/
+    └── myapp/
+        ├── models.py
+        ├── views.py
+        ├── services.py
+        ├── cli.py
+        ├── tasks.py
+        └── tests.py
+```
+
+## Add a component
+
+```bash
+python manage.py component add auth
+```
+
+Creates `components/auth/` with the same structure and registers it in `settings.COMPONENTS`.
+
+## Runtime library
+
+Generated projects import directly from `overflask`:
+
+### Models
+
+```python
+from overflask import ModelBase
+from sqlalchemy.orm import Mapped, mapped_column
+
+class User(ModelBase):
+    # __tablename__ auto-set to "auth_users"
+    id: Mapped[int] = mapped_column(primary_key=True)
+    email: Mapped[str] = mapped_column(String(255), unique=True)
+```
+
+Table names are derived automatically as `{component}_{plural_snake_case_model_name}`.
+
+### Redis cache
+
+```python
+from overflask import cached
+
+@cached(ttl=300)
+def get_user(user_id: int):
+    ...
+```
+
+Backed by Redis db 15 with stampede prevention via locking.
+
+### Async tasks
+
+```python
+from overflask import async_task
+
+@async_task
+def send_welcome_email(user_id: int, email: str) -> None:
+    ...
+
+# Enqueue immediately or with a delay
+send_welcome_email.queue(user_id=42, email="alice@example.com")
+send_welcome_email.queue(timedelta(minutes=5), user_id=42, email="alice@example.com")
+```
+
+### Recurring tasks
+
+```python
+from overflask import recurring_task
+
+@recurring_task("0 9 * * MON-FRI")
+def daily_report() -> None:
+    ...
+```
+
+Tasks are stored in Elasticsearch and dispatched via Redis. Run the supporting processes:
+
+```bash
+python manage.py tasks scheduler   # polls ES, dispatches due tasks
+python manage.py tasks worker      # executes tasks from Redis queue
+```
+
+### Analytics
+
+```python
+from overflask.analytics import Analytics
+
+Analytics.record("user.registered", area="auth", plan="free")
+Analytics.record("purchase.completed", area="billing", amount=99)
+```
+
+Events are buffered in-process and bulk-flushed to Elasticsearch in the background. Each `area` gets its own monthly index (`myapp_analytics_auth-2026.03`).
+
+## Database migrations
+
+```bash
+python manage.py db migrate -m "add users table"
+python manage.py db upgrade
+python manage.py db downgrade 001
+```
+
+## Testing
+
+```bash
+pytest               # all tests
+pytest -m unit       # unit tests only (no DB)
+pytest -m integration
+pytest -n auto       # parallel
+```
+
+Integration tests run against a real PostgreSQL instance using a cloned template database — fast isolation without `create_all()` per test. Redis is always replaced with fakeredis.
+
+## Deployment
+
+The generated project ships with a Gunicorn config and Traefik integration for HTTPS:
+
+```bash
+bash ops/setup-traefik.sh   # one-time Traefik setup per server
+docker compose up -d
+docker compose exec web python manage.py db upgrade
+```
+
+See `docs/traefik.md` and `docs/gunicorn.md` in the generated project for details.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+ruff check src/ tests/
+ruff format src/ tests/
+```

overflask-0.1.0/pyproject.toml

@@ -0,0 +1,107 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "overflask"
+version = "0.1.0"
+description = "Flask scaffolding CLI and runtime library — component architecture, SQLAlchemy, Redis caching, async tasks, and Elasticsearch analytics"
+readme = "README.md"
+license = { file = "LICENSE" }
+authors = [{ name = "rklaus" }]
+requires-python = ">=3.10"
+keywords = ["flask", "scaffolding", "cli", "sqlalchemy", "redis", "elasticsearch", "tasks", "analytics"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Web Environment",
+    "Framework :: Flask",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Internet :: WWW/HTTP :: WSGI :: Application",
+    "Topic :: Software Development :: Code Generators",
+    "Topic :: Software Development :: Libraries :: Application Frameworks",
+]
+
+dependencies = [
+    "click>=8.0",
+    "flask>=3.0",
+    "python-dotenv>=1.0",
+    "sqlalchemy>=2.0",
+    "redis>=5.0",
+    "elasticsearch>=8.0",
+    "croniter>=3.0",
+]
+
+[project.urls]
+Homepage = "https://gitlab.com/overflask/overflask"
+Source = "https://gitlab.com/overflask/overflask"
+Tracker = "https://gitlab.com/overflask/overflask/-/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-tmp-files>=0.0.2",
+    "ruff>=0.8",
+    "build>=1.0",
+    "twine>=5.0",
+]
+
+[project.scripts]
+overflask = "overflask.cli.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+overflask = ["templates/**/*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = [
+    "fixture_file: load JSON fixture files into db_session",
+]
+
+[tool.pyright]
+extraPaths = ["src"]
+exclude = ["build", "dist", "*.egg-info"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+
+[tool.ruff.lint]
+select = [
+    "E",     # pycodestyle errors
+    "W",     # pycodestyle warnings
+    "F",     # pyflakes
+    "I",     # isort (import sorting)
+    "N",     # pep8-naming
+    "UP",    # pyupgrade
+    "B",     # flake8-bugbear
+    "C4",    # flake8-comprehensions
+    "SIM",   # flake8-simplify
+]
+
+ignore = [
+    "TC001",   # Move application imports to TYPE_CHECKING
+    "TC003",   # Move standard library imports to TYPE_CHECKING
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = [
+    "N806",    # Non-lowercase variables
+    "F841",    # Unused variables (test fixtures)
+    "SIM117",  # Nested with statements
+    "B023",    # Function uses loop variable
+    "F401",    # Unused imports
+    "E402",    # Module import not at top
+]
+
+[tool.ruff.format]
+quote-style = "single"
+docstring-code-format = true

overflask-0.1.0/setup.cfg

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

overflask-0.1.0/src/overflask/__init__.py

@@ -0,0 +1,23 @@
+"""overflask - A CLI tool to scaffold Flask projects with component-based architecture."""
+
+from overflask.analytics.analytics import Analytics
+from overflask.core.app import OverFlask
+from overflask.core.config import Config
+from overflask.db.model_base import ModelBase
+from overflask.redis.cache import CachePopulationTimeoutError, cached
+from overflask.redis.redis import get_redis
+from overflask.tasks.tasks import async_task, delete, recurring_task
+
+__version__ = '0.1.0'
+__all__ = [
+    'Analytics',
+    'CachePopulationTimeoutError',
+    'Config',
+    'ModelBase',
+    'OverFlask',
+    'async_task',
+    'cached',
+    'delete',
+    'get_redis',
+    'recurring_task',
+]

overflask-0.1.0/src/overflask/analytics/__init__.py

@@ -0,0 +1 @@
+"""Analytics package for overflask."""

overflask-0.1.0/src/overflask/analytics/analytics.py

@@ -0,0 +1,72 @@
+"""Analytics static class for recording events."""
+
+import re
+from datetime import datetime, timezone
+from typing import Any
+
+from flask import g, request
+
+from overflask.analytics.events import AnalyticsEvents
+from overflask.analytics.flusher import AnalyticsFlusher
+from overflask.core.config import Config
+
+
+def _normalize_area(area: str) -> str:
+    """Lowercase and replace non-alphanumeric characters with underscores."""
+    return re.sub(r"[^a-z0-9]+", "_", area.lower()).strip("_")
+
+
+class Analytics:
+    """Record analytics events. Thread-safe; buffered in-process."""
+
+    @staticmethod
+    def record(event: str, *, area: str, **data: Any) -> None:
+        """Record an analytics event.
+
+        Args:
+            event: Event name (e.g. "user.registered").
+            area: Required domain/component label (e.g. "auth"). Determines the ES index.
+            **data: Arbitrary key-value pairs stored under ``data`` in the event envelope.
+        """
+        doc = Analytics._build_doc(event, area, data)
+        AnalyticsEvents.queue(doc)
+        AnalyticsFlusher.ensure()
+
+    @staticmethod
+    def _build_doc(event: str, area: str, data: dict) -> dict:
+        """Build the full event envelope with optional request context enrichment."""
+        doc: dict[str, Any] = {
+            "event": event,
+            "timestamp": datetime.now(tz=timezone.utc).isoformat(),
+            "project": Config.project_name(),
+            "environment": Config.analytics_environment(),
+            "area": _normalize_area(area),
+            "data": data,
+        }
+
+        # Auto-enrich with Flask request context if available.
+        try:
+            ctx: dict[str, str] = {
+                "http_method": request.method,
+                "http_path": request.path,
+            }
+            request_id = getattr(g, "request_id", None) or request.headers.get("X-Request-ID")
+            if request_id:
+                ctx["request_id"] = request_id
+            user_id = getattr(g, "user_id", None)
+            if user_id is not None:
+                ctx["user_id"] = str(user_id)
+            doc["context"] = ctx
+        except RuntimeError:
+            # No Flask request context — omit context entirely.
+            pass
+
+        return doc
+
+    @staticmethod
+    def flush_now() -> int:
+        """Drain the buffer and bulk-write to ES immediately.
+
+        Returns the number of events flushed.
+        """
+        return AnalyticsFlusher.flush_now()

overflask-0.1.0/src/overflask/analytics/commands.py

@@ -0,0 +1,30 @@
+"""Click commands for the analytics system."""
+
+import click
+from flask import Flask
+
+from overflask.analytics.es_index_templates import AnalyticsEsIndexTemplates
+from overflask.analytics.purge import AnalyticsPurge
+
+
+@click.group()
+def analytics():
+    """Analytics management commands."""
+
+
+@analytics.command("provision")
+@click.pass_obj
+def provision_cmd(app: Flask) -> None:
+    """Create or update the Elasticsearch index template for analytics indices."""
+    with app.app_context():
+        AnalyticsEsIndexTemplates.ensure()
+        click.echo("Analytics ES index template provisioned.")
+
+
+@analytics.command("purge")
+@click.pass_obj
+def purge_cmd(app: Flask) -> None:
+    """Delete analytics indices older than the configured retention period."""
+    with app.app_context():
+        AnalyticsPurge.purge_old()
+        click.echo("Analytics purge complete.")

overflask-0.1.0/src/overflask/analytics/es_index_templates.py

@@ -0,0 +1,51 @@
+"""Elasticsearch index templates and naming helpers for the analytics system."""
+
+from datetime import datetime
+
+from overflask.core.config import Config
+from overflask.es.elastic import get_es_client
+
+
+class AnalyticsEsIndexTemplates:
+    """Manages ES index templates and index naming for the analytics system."""
+
+    @staticmethod
+    def analytics_index(project: str, area: str, dt: datetime) -> str:
+        """Return the monthly analytics index name for the given project, area, and datetime."""
+        return f"{project}_analytics_{area}-{dt:%Y.%m}"
+
+    @staticmethod
+    def ensure() -> None:
+        """Create or update the ES index template for all analytics index patterns.
+
+        Idempotent — safe to call on every scheduler and worker startup.
+        """
+        es = get_es_client()
+        project = Config.project_name()
+
+        properties = {
+            "event": {"type": "keyword"},
+            "timestamp": {"type": "date"},
+            "project": {"type": "keyword"},
+            "environment": {"type": "keyword"},
+            "area": {"type": "keyword"},
+            "context": {
+                "type": "object",
+                "properties": {
+                    "request_id": {"type": "keyword"},
+                    "http_method": {"type": "keyword"},
+                    "http_path": {"type": "keyword"},
+                    "user_id": {"type": "keyword"},
+                },
+            },
+            "data": {
+                "type": "object",
+                "dynamic": True,
+            },
+        }
+
+        es.indices.put_index_template(
+            name=f"{project}-analytics",
+            index_patterns=[f"{project}_analytics_*-*"],
+            template={"mappings": {"properties": properties}},
+        )