simple-module-feature-flags 0.0.1__tar.gz

simple_module_feature_flags-0.0.1/.gitignore

@@ -0,0 +1,59 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+*.egg
+
+# UV
+uv.lock
+
+# Node
+node_modules/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Environment
+.env
+
+# Database
+*.db
+*.sqlite3
+
+# Module-managed runtime state (e.g. uploaded dataset files,
+# default storage_dir for SM_DATASETS_STORAGE_DIR).
+var/
+
+# file_storage filesystem backend default root (override via SM_FILE_STORAGE_FS_ROOT_PATH).
+uploads/
+
+# Vite
+host/static/dist/
+
+# Auto-generated frontend module manifest (regenerated by the host at boot
+# or via `make gen-pages`).
+host/client_app/modules.manifest.json
+host/client_app/modules.generated.ts
+host/client_app/modules.generated.css
+
+# Worktrees
+.worktrees/
+
+# Performance profiles
+.memray/
+.benchmarks/
+
+# OS
+.DS_Store
+Thumbs.db
+
+.playwright-cli/*
+.playwright-mcp/*
+host/client_app/.playwright-cli/*
+.superpowers/

simple_module_feature_flags-0.0.1/LICENSE

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

simple_module_feature_flags-0.0.1/PKG-INFO

@@ -0,0 +1,83 @@
+Metadata-Version: 2.4
+Name: simple_module_feature_flags
+Version: 0.0.1
+Summary: Simple feature-flag module with per-tenant overrides and a consumer API for simple_module
+Project-URL: Homepage, https://github.com/antosubash/simple_module_python
+Project-URL: Repository, https://github.com/antosubash/simple_module_python
+Project-URL: Issues, https://github.com/antosubash/simple_module_python/issues
+Project-URL: Changelog, https://github.com/antosubash/simple_module_python/blob/main/CHANGELOG.md
+Author-email: Anto Subash <antosubash@live.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: feature-flags,multi-tenant,simple-module,toggles
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+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.12
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: simple-module-core==0.0.1
+Requires-Dist: simple-module-db==0.0.1
+Requires-Dist: simple-module-hosting==0.0.1
+Description-Content-Type: text/markdown
+
+# simple_module_feature_flags
+
+Feature flags for [simple_module](https://github.com/antosubash/simple_module_python) apps. Global flags with per-tenant overrides, a tiny consumer API, and no external service to run.
+
+## Install
+
+```bash
+pip install simple_module_feature_flags
+```
+
+## What it provides
+
+- `Flag` and `TenantFlagOverride` SQLModel tables.
+- `is_enabled("flag.name", tenant_id=...)` consumer API.
+- Admin UI at `/feature-flags/admin` — toggle flags, add tenant overrides.
+- Cache layer so checking a flag on every request is cheap.
+
+## Usage
+
+Gate a route:
+
+```python
+from feature_flags import is_enabled   # type: ignore[import-not-found]
+from fastapi import APIRouter, Depends, HTTPException
+
+router = APIRouter()
+
+
+@router.get("/new-feature")
+async def new_feature(tenant_id: int = Depends(current_tenant_id)):
+    if not await is_enabled("orders.new_pricing_engine", tenant_id=tenant_id):
+        raise HTTPException(404)
+    return {"rolled_out": True}
+```
+
+Seed a flag in a migration or admin UI:
+
+```python
+# via migration
+Flag(name="orders.new_pricing_engine", enabled=False)
+```
+
+Tenant override:
+
+```python
+TenantFlagOverride(tenant_id=7, flag_name="orders.new_pricing_engine", enabled=True)
+```
+
+## Depends on
+
+- `simple_module_core`, `simple_module_db`, `simple_module_hosting`
+
+## License
+
+MIT — see [LICENSE](https://github.com/antosubash/simple_module_python/blob/main/LICENSE).

simple_module_feature_flags-0.0.1/README.md

@@ -0,0 +1,55 @@
+# simple_module_feature_flags
+
+Feature flags for [simple_module](https://github.com/antosubash/simple_module_python) apps. Global flags with per-tenant overrides, a tiny consumer API, and no external service to run.
+
+## Install
+
+```bash
+pip install simple_module_feature_flags
+```
+
+## What it provides
+
+- `Flag` and `TenantFlagOverride` SQLModel tables.
+- `is_enabled("flag.name", tenant_id=...)` consumer API.
+- Admin UI at `/feature-flags/admin` — toggle flags, add tenant overrides.
+- Cache layer so checking a flag on every request is cheap.
+
+## Usage
+
+Gate a route:
+
+```python
+from feature_flags import is_enabled   # type: ignore[import-not-found]
+from fastapi import APIRouter, Depends, HTTPException
+
+router = APIRouter()
+
+
+@router.get("/new-feature")
+async def new_feature(tenant_id: int = Depends(current_tenant_id)):
+    if not await is_enabled("orders.new_pricing_engine", tenant_id=tenant_id):
+        raise HTTPException(404)
+    return {"rolled_out": True}
+```
+
+Seed a flag in a migration or admin UI:
+
+```python
+# via migration
+Flag(name="orders.new_pricing_engine", enabled=False)
+```
+
+Tenant override:
+
+```python
+TenantFlagOverride(tenant_id=7, flag_name="orders.new_pricing_engine", enabled=True)
+```
+
+## Depends on
+
+- `simple_module_core`, `simple_module_db`, `simple_module_hosting`
+
+## License
+
+MIT — see [LICENSE](https://github.com/antosubash/simple_module_python/blob/main/LICENSE).

simple_module_feature_flags-0.0.1/feature_flags/__init__.py

@@ -0,0 +1 @@
+"""FeatureFlags module."""

simple_module_feature_flags-0.0.1/feature_flags/constants.py

@@ -0,0 +1,31 @@
+"""Stable identifiers for the feature_flags module."""
+
+PERM_FEATURE_FLAGS_VIEW = "feature_flags.view"
+PERM_FEATURE_FLAGS_MANAGE = "feature_flags.manage"
+
+# Prefix is load-bearing on SQLite, which has no per-module schemas.
+TABLE_OVERRIDE = "feature_flags_override"
+UQ_OVERRIDE_SCOPE_NAME = "uq_feature_flags_override_scope_scope_id_name"
+
+SCOPE_SYSTEM = "system"
+SCOPE_TENANT = "tenant"
+ALL_SCOPES = (SCOPE_SYSTEM, SCOPE_TENANT)
+# Empty string, not NULL: PG treats NULLs as distinct in unique indexes,
+# which would let two "system" rows for the same flag coexist.
+SYSTEM_SCOPE_ID = ""
+
+SCOPE_MAX_LENGTH = 10
+SCOPE_ID_MAX_LENGTH = 64
+
+LOCALE_NAMESPACE = "feature_flags"
+
+MENU_LABEL = "Feature Flags"
+MENU_URL = "/feature_flags"
+MENU_ICON = "flag"
+MENU_ORDER = 45
+
+PAGE_BROWSE = "FeatureFlags/Browse"
+
+API_PREFIX = "/api/feature_flags"
+VIEW_PREFIX = "/feature_flags"
+QP_TENANT_ID = "tenant_id"

simple_module_feature_flags-0.0.1/feature_flags/contracts/__init__.py

@@ -0,0 +1,13 @@
+"""feature_flags contracts — public interface for other modules."""
+
+from feature_flags.contracts.schemas import (
+    FeatureFlagOverrideOut,
+    FeatureFlagView,
+    ToggleRequest,
+)
+
+__all__ = [
+    "FeatureFlagOverrideOut",
+    "FeatureFlagView",
+    "ToggleRequest",
+]

simple_module_feature_flags-0.0.1/feature_flags/contracts/schemas.py

@@ -0,0 +1,47 @@
+"""SQLModel DTOs for the feature_flags module."""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from pydantic import ConfigDict
+from sqlmodel import Field, SQLModel
+
+
+class FeatureFlagOverrideOut(SQLModel):
+    """Stored override row as returned by the service/API."""
+
+    model_config = ConfigDict(from_attributes=True)
+
+    id: int
+    scope: str
+    scope_id: str
+    name: str
+    enabled: bool
+    created_at: datetime | None = None
+    updated_at: datetime | None = None
+
+
+class FeatureFlagView(SQLModel):
+    """A flag as shown in the admin UI for a given scope.
+
+    ``enabled`` is the value an ``is_enabled(name, tenant_id=...)`` call
+    would return for this scope. ``overridden`` reports whether the row
+    that produced ``enabled`` lives at *this* scope (vs. inherited from
+    system or default). ``system_enabled`` exposes the underlying system
+    value when viewing a tenant scope, so the UI can show "inheriting:
+    on/off" next to the toggle.
+    """
+
+    name: str
+    description: str = ""
+    default_enabled: bool
+    enabled: bool
+    overridden: bool
+    system_enabled: bool | None = None
+
+
+class ToggleRequest(SQLModel):
+    """Body for PUT /api/feature_flags/[tenant/{tenant_id}/]{name} — sets an override."""
+
+    enabled: bool = Field(...)

simple_module_feature_flags-0.0.1/feature_flags/deps.py

@@ -0,0 +1,27 @@
+"""FastAPI dependencies for the feature_flags module."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from fastapi import Depends, Request
+from simple_module_core.feature_flags import FeatureFlagRegistry
+from simple_module_db.deps import get_db
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from feature_flags.service import FeatureFlagService
+
+
+async def get_feature_flag_service(
+    db: AsyncSession = Depends(get_db),
+) -> FeatureFlagService:
+    return FeatureFlagService(db)
+
+
+def get_feature_flag_registry(request: Request) -> FeatureFlagRegistry:
+    """Return the process-wide FeatureFlagRegistry owned by the framework."""
+    return request.app.state.sm.feature_flags
+
+
+FeatureFlagServiceDep = Annotated[FeatureFlagService, Depends(get_feature_flag_service)]
+FeatureFlagRegistryDep = Annotated[FeatureFlagRegistry, Depends(get_feature_flag_registry)]

simple_module_feature_flags-0.0.1/feature_flags/endpoints/api.py

@@ -0,0 +1,136 @@
+"""REST API endpoints for feature_flags management."""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends, HTTPException
+from simple_module_core.feature_flags import FeatureFlagRegistry
+from simple_module_hosting.permissions import RequiresPermission
+
+from feature_flags.constants import (
+    PERM_FEATURE_FLAGS_MANAGE,
+    PERM_FEATURE_FLAGS_VIEW,
+    SCOPE_TENANT,
+)
+from feature_flags.contracts.schemas import FeatureFlagView, ToggleRequest
+from feature_flags.deps import FeatureFlagRegistryDep, FeatureFlagServiceDep
+
+router = APIRouter()
+
+
+def _ensure_registered(name: str, registry: FeatureFlagRegistry) -> None:
+    # A typo here would silently persist a dead row that ``list_flags`` filters out.
+    if name not in {f.name for f in registry.all_flags}:
+        raise HTTPException(status_code=404, detail="Feature flag not registered")
+
+
+@router.get(
+    "/",
+    response_model=list[FeatureFlagView],
+    dependencies=[Depends(RequiresPermission(PERM_FEATURE_FLAGS_VIEW))],
+)
+async def list_flags(
+    service: FeatureFlagServiceDep,
+    registry: FeatureFlagRegistryDep,
+) -> list[FeatureFlagView]:
+    return await service.list_flags(registry)
+
+
+@router.get(
+    "/{name}",
+    response_model=FeatureFlagView,
+    dependencies=[Depends(RequiresPermission(PERM_FEATURE_FLAGS_VIEW))],
+)
+async def get_flag(
+    name: str,
+    service: FeatureFlagServiceDep,
+    registry: FeatureFlagRegistryDep,
+) -> FeatureFlagView:
+    view = service.build_view(registry, name)
+    if view is None:
+        raise HTTPException(status_code=404, detail="Feature flag not registered")
+    return view
+
+
+@router.put(
+    "/{name}",
+    response_model=FeatureFlagView,
+    dependencies=[Depends(RequiresPermission(PERM_FEATURE_FLAGS_MANAGE))],
+)
+async def set_override(
+    name: str,
+    body: ToggleRequest,
+    service: FeatureFlagServiceDep,
+    registry: FeatureFlagRegistryDep,
+) -> FeatureFlagView:
+    _ensure_registered(name, registry)
+    await service.set_override(name, body.enabled, registry=registry)
+    view = service.build_view(registry, name)
+    assert view is not None  # _ensure_registered already proved it exists
+    return view
+
+
+@router.delete(
+    "/{name}",
+    status_code=204,
+    dependencies=[Depends(RequiresPermission(PERM_FEATURE_FLAGS_MANAGE))],
+)
+async def clear_override(
+    name: str,
+    service: FeatureFlagServiceDep,
+    registry: FeatureFlagRegistryDep,
+) -> None:
+    cleared = await service.clear_override(name, registry=registry)
+    if not cleared:
+        raise HTTPException(status_code=404, detail="No override set for this flag")
+
+
+@router.get(
+    "/tenant/{tenant_id}",
+    response_model=list[FeatureFlagView],
+    dependencies=[Depends(RequiresPermission(PERM_FEATURE_FLAGS_VIEW))],
+)
+async def list_flags_for_tenant(
+    tenant_id: str,
+    service: FeatureFlagServiceDep,
+    registry: FeatureFlagRegistryDep,
+) -> list[FeatureFlagView]:
+    return await service.list_flags(registry, tenant_id=tenant_id)
+
+
+@router.put(
+    "/tenant/{tenant_id}/{name}",
+    response_model=FeatureFlagView,
+    dependencies=[Depends(RequiresPermission(PERM_FEATURE_FLAGS_MANAGE))],
+)
+async def set_tenant_override(
+    tenant_id: str,
+    name: str,
+    body: ToggleRequest,
+    service: FeatureFlagServiceDep,
+    registry: FeatureFlagRegistryDep,
+) -> FeatureFlagView:
+    _ensure_registered(name, registry)
+    await service.set_override(
+        name, body.enabled, registry=registry, scope=SCOPE_TENANT, scope_id=tenant_id
+    )
+    view = service.build_view(registry, name, tenant_id=tenant_id)
+    assert view is not None  # _ensure_registered already proved it exists
+    return view
+
+
+@router.delete(
+    "/tenant/{tenant_id}/{name}",
+    status_code=204,
+    dependencies=[Depends(RequiresPermission(PERM_FEATURE_FLAGS_MANAGE))],
+)
+async def clear_tenant_override(
+    tenant_id: str,
+    name: str,
+    service: FeatureFlagServiceDep,
+    registry: FeatureFlagRegistryDep,
+) -> None:
+    cleared = await service.clear_override(
+        name, registry=registry, scope=SCOPE_TENANT, scope_id=tenant_id
+    )
+    if not cleared:
+        raise HTTPException(status_code=404, detail="No override set for this flag")

simple_module_feature_flags-0.0.1/feature_flags/endpoints/views.py

@@ -0,0 +1,98 @@
+"""Inertia view endpoints for feature_flags admin UI.
+
+The browse page renders either system-scope or a tenant-scope view of the
+flags. Tenant scope is selected via a ``tenant_id`` query string. The form
+actions for toggling/clearing accept the same ``tenant_id`` query so the
+frontend doesn't need separate routes per scope.
+"""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends, Request
+from inertia import InertiaResponse
+from simple_module_hosting.inertia_deps import InertiaDep
+from simple_module_hosting.permissions import RequiresPermission
+from starlette.responses import RedirectResponse
+
+from feature_flags.constants import (
+    MENU_URL,
+    PAGE_BROWSE,
+    PERM_FEATURE_FLAGS_MANAGE,
+    PERM_FEATURE_FLAGS_VIEW,
+    QP_TENANT_ID,
+    SCOPE_SYSTEM,
+    SCOPE_TENANT,
+    SYSTEM_SCOPE_ID,
+)
+from feature_flags.deps import FeatureFlagRegistryDep, FeatureFlagServiceDep
+
+router = APIRouter()
+
+
+def _redirect_for_tenant(tenant_id: str | None) -> RedirectResponse:
+    target = MENU_URL if not tenant_id else f"{MENU_URL}?{QP_TENANT_ID}={tenant_id}"
+    return RedirectResponse(target, status_code=303)
+
+
+def _scope_args(tenant_id: str | None) -> dict[str, str]:
+    if tenant_id:
+        return {"scope": SCOPE_TENANT, "scope_id": tenant_id}
+    return {"scope": SCOPE_SYSTEM, "scope_id": SYSTEM_SCOPE_ID}
+
+
+@router.get(
+    "/",
+    response_model=None,
+    dependencies=[Depends(RequiresPermission(PERM_FEATURE_FLAGS_VIEW))],
+)
+async def browse(
+    inertia: InertiaDep,
+    service: FeatureFlagServiceDep,
+    registry: FeatureFlagRegistryDep,
+    tenant_id: str | None = None,
+) -> InertiaResponse:
+    flags = await service.list_flags(registry, tenant_id=tenant_id)
+    tenants = await service.list_tenants_with_overrides()
+    return await inertia.render(
+        PAGE_BROWSE,
+        {
+            "flags": [f.model_dump(mode="json") for f in flags],
+            "tenant_id": tenant_id,
+            "tenants": tenants,
+        },
+    )
+
+
+@router.post(
+    "/{name}/toggle",
+    response_model=None,
+    dependencies=[Depends(RequiresPermission(PERM_FEATURE_FLAGS_MANAGE))],
+)
+async def toggle_action(
+    name: str,
+    request: Request,
+    service: FeatureFlagServiceDep,
+    registry: FeatureFlagRegistryDep,
+    tenant_id: str | None = None,
+) -> RedirectResponse:
+    if name not in {f.name for f in registry.all_flags}:
+        return _redirect_for_tenant(tenant_id)
+    body = await request.json()
+    enabled = bool(body.get("enabled", False))
+    await service.set_override(name, enabled, registry=registry, **_scope_args(tenant_id))
+    return _redirect_for_tenant(tenant_id)
+
+
+@router.post(
+    "/{name}/clear",
+    response_model=None,
+    dependencies=[Depends(RequiresPermission(PERM_FEATURE_FLAGS_MANAGE))],
+)
+async def clear_action(
+    name: str,
+    service: FeatureFlagServiceDep,
+    registry: FeatureFlagRegistryDep,
+    tenant_id: str | None = None,
+) -> RedirectResponse:
+    await service.clear_override(name, registry=registry, **_scope_args(tenant_id))
+    return _redirect_for_tenant(tenant_id)

simple_module_feature_flags-0.0.1/feature_flags/locales/en.json

@@ -0,0 +1,40 @@
+{
+  "browse": {
+    "title": "Feature Flags",
+    "description": "Toggle features exposed by installed modules. Overrides persist across restarts.",
+    "empty_title": "No feature flags registered",
+    "empty_description": "Modules declare flags via register_feature_flags(); install one to see it here.",
+    "count_one": "{count} flag",
+    "count_other": "{count} flags",
+    "viewing_system": "Viewing system-level flags. Switch scope to override per tenant.",
+    "viewing_tenant": "Viewing overrides for tenant \"{tenant_id}\". Tenant overrides beat the system value.",
+    "tenant_id_label": "Tenant ID",
+    "tenant_id_placeholder": "e.g. acme",
+    "scope_label": "Scope",
+    "scope_system": "System (all tenants)",
+    "scope_tenant": "Specific tenant",
+    "go": "View",
+    "back_to_system": "Back to system view",
+    "tenants_with_overrides": "Tenants with overrides"
+  },
+  "table": {
+    "name": "Flag",
+    "description": "Description",
+    "default": "Default",
+    "status": "Status",
+    "actions": "Actions",
+    "enabled": "Enabled",
+    "disabled": "Disabled",
+    "overridden": "Override active",
+    "following_default": "Following default",
+    "following_system": "Following system",
+    "system_value": "System: {value}",
+    "clear_override": "Clear override"
+  },
+  "toasts": {
+    "enabled": "\"{name}\" enabled",
+    "disabled": "\"{name}\" disabled",
+    "cleared": "Override cleared for \"{name}\"",
+    "toggle_failed": "Failed to update flag"
+  }
+}

simple_module_feature_flags-0.0.1/feature_flags/models.py

@@ -0,0 +1,42 @@
+"""SQLModel tables for the feature_flags module.
+
+Stores persisted overrides for flags that modules declare via
+``register_feature_flags``. The definition of a flag (name, description,
+default) lives in code; this table only records admin-applied overrides so
+they survive across app restarts.
+
+A row's ``scope`` selects whether the override applies globally
+(``system``, ``scope_id=""``) or to a single tenant (``tenant``,
+``scope_id=<tenant_id>``). Resolution at runtime: tenant > system > default.
+"""
+
+from __future__ import annotations
+
+from simple_module_db.base import create_module_base
+from simple_module_db.mixins import AuditMixin
+from sqlalchemy import UniqueConstraint
+from sqlmodel import Field
+
+from feature_flags.constants import (
+    SCOPE_ID_MAX_LENGTH,
+    SCOPE_MAX_LENGTH,
+    SCOPE_SYSTEM,
+    SYSTEM_SCOPE_ID,
+    TABLE_OVERRIDE,
+    UQ_OVERRIDE_SCOPE_NAME,
+)
+
+Base = create_module_base("feature_flags")
+
+
+class FeatureFlagOverride(Base, AuditMixin, table=True):  # ty: ignore[unsupported-base]
+    """Persisted override for a single feature flag at a given scope."""
+
+    __tablename__ = TABLE_OVERRIDE
+    __table_args__ = (UniqueConstraint("scope", "scope_id", "name", name=UQ_OVERRIDE_SCOPE_NAME),)
+
+    id: int | None = Field(default=None, primary_key=True)
+    scope: str = Field(default=SCOPE_SYSTEM, max_length=SCOPE_MAX_LENGTH, index=True)
+    scope_id: str = Field(default=SYSTEM_SCOPE_ID, max_length=SCOPE_ID_MAX_LENGTH, index=True)
+    name: str = Field(max_length=200, index=True)
+    enabled: bool = Field(default=False)