platzky 1.3.1__py3-none-any.whl → 1.4.1__py3-none-any.whl

platzky/__init__.py

@@ -1,3 +1,9 @@
 from platzky.engine import Engine as Engine
+from platzky.feature_flags import FakeLogin as FakeLogin
+from platzky.feature_flags import FeatureFlag as FeatureFlag
+from platzky.feature_flags import all_flags as all_flags
+from platzky.feature_flags import build_flag_set as build_flag_set
+from platzky.feature_flags import parse_flags as parse_flags
+from platzky.feature_flags_wrapper import FeatureFlagSet as FeatureFlagSet
 from platzky.platzky import create_app_from_config as create_app_from_config
 from platzky.platzky import create_engine as create_engine

platzky/admin/admin.py

@@ -20,7 +20,6 @@ def create_admin_blueprint(
     Returns:
         Configured Flask Blueprint for admin panel
     """
-    # …rest of the function…
     admin = Blueprint(
         "admin",
         __name__,
@@ -49,7 +48,7 @@ def create_admin_blueprint(
         Returns:
             Rendered login page if not authenticated, admin panel if authenticated
         """
-        user = session.get("user", None)
+        user = session.get("user")
 
         if not user:
             return render_template("login.html", login_methods=login_methods)

platzky/blog/blog.py

@@ -31,11 +31,10 @@ def create_blog_blueprint(db: DB, blog_prefix: str, locale_func: Callable[[], st
     Returns:
         Configured Flask Blueprint for blog functionality
     """
-    url_prefix = blog_prefix
     blog = Blueprint(
         "blog",
         __name__,
-        url_prefix=url_prefix,
+        url_prefix=blog_prefix,
         template_folder=f"{dirname(__file__)}/../templates",
     )
 
@@ -159,7 +158,7 @@ def create_blog_blueprint(db: DB, blog_prefix: str, locale_func: Callable[[], st
             Rendered HTML template of the page
         """
         page = _get_content_or_404(db.get_page, page_slug)
-        cover_image_url = page.coverImage.url if page.coverImage.url else None
+        cover_image_url = (page.coverImage.url or None) if page.coverImage else None
         return render_template("page.html", page=page, cover_image=cover_image_url)
 
     @blog.route("/tag/<path:tag>", methods=["GET"])

platzky/config.py

@@ -9,18 +9,14 @@ import typing as t
 import yaml
 from pydantic import BaseModel, ConfigDict, Field, field_validator
 
-from .attachment.constants import BLOCKED_EXTENSIONS, DEFAULT_MAX_ATTACHMENT_SIZE
-from .db.db import DBConfig
-from .db.db_loader import get_db_module
+from platzky.attachment.constants import BLOCKED_EXTENSIONS, DEFAULT_MAX_ATTACHMENT_SIZE
+from platzky.db.db import DBConfig
+from platzky.db.db_loader import get_db_module
+from platzky.feature_flags import build_flag_set
+from platzky.feature_flags_wrapper import FeatureFlagSet
 
 
-class StrictBaseModel(BaseModel):
-    """Base model with immutable (frozen) configuration."""
-
-    model_config = ConfigDict(frozen=True)
-
-
-class LanguageConfig(StrictBaseModel):
+class LanguageConfig(BaseModel):
     """Configuration for a single language.
 
     Attributes:
@@ -30,10 +26,12 @@ class LanguageConfig(StrictBaseModel):
         domain: Optional domain specific to this language
     """
 
-    name: str = Field(alias="name")
-    flag: str = Field(alias="flag")
-    country: str = Field(alias="country")
-    domain: t.Optional[str] = Field(default=None, alias="domain")
+    model_config = ConfigDict(frozen=True)
+
+    name: str
+    flag: str
+    country: str
+    domain: t.Optional[str] = None
 
 
 Languages = dict[str, LanguageConfig]
@@ -64,7 +62,7 @@ def languages_dict(languages: Languages) -> LanguagesMapping:
     }
 
 
-class TelemetryConfig(StrictBaseModel):
+class TelemetryConfig(BaseModel):
     """OpenTelemetry configuration for application tracing.
 
     Attributes:
@@ -79,15 +77,17 @@ class TelemetryConfig(StrictBaseModel):
         instrument_logging: Enable automatic logging instrumentation (default: True)
     """
 
-    enabled: bool = Field(default=False, alias="enabled")
-    endpoint: t.Optional[str] = Field(default=None, alias="endpoint")
-    console_export: bool = Field(default=False, alias="console_export")
-    timeout: int = Field(default=10, alias="timeout", gt=0)
-    deployment_environment: t.Optional[str] = Field(default=None, alias="deployment_environment")
-    service_instance_id: t.Optional[str] = Field(default=None, alias="service_instance_id")
-    flush_on_request: bool = Field(default=True, alias="flush_on_request")
-    flush_timeout_ms: int = Field(default=5000, alias="flush_timeout_ms", gt=0)
-    instrument_logging: bool = Field(default=True, alias="instrument_logging")
+    model_config = ConfigDict(frozen=True)
+
+    enabled: bool = False
+    endpoint: t.Optional[str] = None
+    console_export: bool = False
+    timeout: int = Field(default=10, gt=0)
+    deployment_environment: t.Optional[str] = None
+    service_instance_id: t.Optional[str] = None
+    flush_on_request: bool = True
+    flush_timeout_ms: int = Field(default=5000, gt=0)
+    instrument_logging: bool = True
 
     @field_validator("endpoint")
     @classmethod
@@ -165,7 +165,7 @@ _DEFAULT_ALLOWED_MIME_TYPES: frozenset[str] = frozenset(
 )
 
 
-class AttachmentConfig(StrictBaseModel):
+class AttachmentConfig(BaseModel):
     """Configuration for attachment handling.
 
     Attributes:
@@ -181,6 +181,8 @@ class AttachmentConfig(StrictBaseModel):
             Files without extensions are always blocked when allowed_extensions is set.
     """
 
+    model_config = ConfigDict(frozen=True)
+
     allowed_mime_types: frozenset[str] = Field(default=_DEFAULT_ALLOWED_MIME_TYPES)
     validate_content: bool = Field(default=True)
     allow_unrecognized_content: bool = Field(default=False)
@@ -220,7 +222,7 @@ class AttachmentConfig(StrictBaseModel):
     )
 
 
-class Config(StrictBaseModel):
+class Config(BaseModel):
     """Main application configuration.
 
     Attributes:
@@ -239,6 +241,8 @@ class Config(StrictBaseModel):
         attachment: Attachment handling configuration
     """
 
+    model_config = ConfigDict(frozen=True, arbitrary_types_allowed=True)
+
     app_name: str = Field(alias="APP_NAME")
     secret_key: str = Field(alias="SECRET_KEY")
     db: DBConfig = Field(alias="DB")
@@ -252,10 +256,25 @@ class Config(StrictBaseModel):
     )
     debug: bool = Field(default=False, alias="DEBUG")
     testing: bool = Field(default=False, alias="TESTING")
-    feature_flags: t.Optional[dict[str, bool]] = Field(default=None, alias="FEATURE_FLAGS")
+    feature_flags: FeatureFlagSet = Field(
+        default_factory=build_flag_set,
+        alias="FEATURE_FLAGS",
+    )
     telemetry: TelemetryConfig = Field(default_factory=TelemetryConfig, alias="TELEMETRY")
     attachment: AttachmentConfig = Field(default_factory=AttachmentConfig, alias="ATTACHMENT")
 
+    @field_validator("feature_flags", mode="before")
+    @classmethod
+    def validate_feature_flags(cls, v: FeatureFlagSet | dict[str, bool] | None) -> FeatureFlagSet:
+        """Coerce dict or None into a FeatureFlagSet."""
+        if isinstance(v, FeatureFlagSet):
+            return v
+        if isinstance(v, dict):
+            return build_flag_set(v)
+        if v is None:
+            return build_flag_set()
+        return v
+
     @classmethod
     def model_validate(
         cls,
@@ -267,6 +286,9 @@ class Config(StrictBaseModel):
     ) -> "Config":
         """Validate and construct Config from dictionary.
 
+        Parses the raw FEATURE_FLAGS dict into a frozenset of enabled
+        FeatureFlag types via ``parse_flags()``.
+
         Args:
             obj: Configuration dictionary
             strict: Enable strict validation
@@ -276,8 +298,14 @@ class Config(StrictBaseModel):
         Returns:
             Validated Config instance
         """
-        db_cfg_type = get_db_module(obj["DB"]["TYPE"]).db_config_type()
-        obj["DB"] = db_cfg_type.model_validate(obj["DB"])
+        try:
+            db_section = obj["DB"]
+            db_type = db_section["TYPE"]
+        except KeyError as e:
+            raise ValueError(f"Missing required config key: {e}. DB.TYPE is required.") from e
+        db_cfg_type = get_db_module(db_type).db_config_type()
+        obj["DB"] = db_cfg_type.model_validate(db_section)
+
         return super().model_validate(
             obj, strict=strict, from_attributes=from_attributes, context=context
         )

platzky/db/github_json_db.py

@@ -52,13 +52,7 @@ def get_db(config: dict[str, Any]) -> "GithubJsonDb":
     Returns:
         Configured GitHub JSON database instance
     """
-    github_json_db_config = GithubJsonDbConfig.model_validate(config)
-    return GithubJsonDb(
-        github_json_db_config.github_token,
-        github_json_db_config.repo_name,
-        github_json_db_config.branch_name,
-        github_json_db_config.path_to_file,
-    )
+    return db_from_config(GithubJsonDbConfig.model_validate(config))
 
 
 class GithubJsonDb(JsonDB):

platzky/db/google_json_db.py

@@ -50,8 +50,7 @@ def get_db(config: dict[str, Any]) -> "GoogleJsonDb":
     Returns:
         Configured Google Cloud Storage JSON database instance
     """
-    google_json_db_config = GoogleJsonDbConfig.model_validate(config)
-    return GoogleJsonDb(google_json_db_config.bucket_name, google_json_db_config.source_blob_name)
+    return db_from_config(GoogleJsonDbConfig.model_validate(config))
 
 
 def get_blob(bucket_name: str, source_blob_name: str) -> "Blob":

platzky/db/graph_ql_db.py

@@ -29,18 +29,6 @@ class GraphQlDbConfig(DBConfig):
     token: str = Field(alias="CMS_TOKEN")
 
 
-def get_db(config: GraphQlDbConfig) -> "GraphQL":
-    """Get a GraphQL database instance from configuration.
-
-    Args:
-        config: GraphQL database configuration
-
-    Returns:
-        Configured GraphQL database instance
-    """
-    return GraphQL(config.endpoint, config.token)
-
-
 def db_from_config(config: GraphQlDbConfig) -> "GraphQL":
     """Create a GraphQL database instance from configuration.
 
@@ -53,6 +41,10 @@ def db_from_config(config: GraphQlDbConfig) -> "GraphQL":
     return GraphQL(config.endpoint, config.token)
 
 
+# Legacy alias retained for backward compatibility
+get_db = db_from_config
+
+
 def _standardize_comment(
     comment: dict[str, Any],
 ) -> dict[str, Any]:

platzky/db/json_db.py

@@ -33,8 +33,7 @@ def get_db(config: dict[str, Any]) -> "Json":
     Returns:
         Configured JSON database instance
     """
-    json_db_config = JsonDbConfig.model_validate(config)
-    return Json(json_db_config.data)
+    return db_from_config(JsonDbConfig.model_validate(config))
 
 
 def db_from_config(config: JsonDbConfig) -> "Json":
@@ -129,12 +128,10 @@ class Json(DB):
         pages = self._get_site_content().get("pages")
         if pages is None:
             raise ValueError("Pages data is missing")
-        list_of_pages = (page for page in pages if page["slug"] == slug)
-        wanted_page = next(list_of_pages, None)
+        wanted_page = next((page for page in pages if page["slug"] == slug), None)
         if wanted_page is None:
             raise ValueError(f"Page with slug {slug} not found")
-        page = Page.model_validate(wanted_page)
-        return page
+        return Page.model_validate(wanted_page)
 
     def get_menu_items_in_lang(self, lang: str) -> list[MenuItem]:
         """Retrieve menu items for a specific language.
@@ -146,10 +143,8 @@ class Json(DB):
             List of MenuItem objects
         """
         menu_items_raw = self._get_site_content().get("menu_items", {})
-        items_in_lang = menu_items_raw.get(lang, {})
-
-        menu_items_list = [MenuItem.model_validate(x) for x in items_in_lang]
-        return menu_items_list
+        items_in_lang = menu_items_raw.get(lang, [])
+        return [MenuItem.model_validate(x) for x in items_in_lang]
 
     def get_posts_by_tag(self, tag: str, lang: str) -> list[Post]:
         """Retrieve posts filtered by tag and language.
@@ -236,12 +231,11 @@ class Json(DB):
             "date": now_utc,
         }
 
-        post_index = next(
-            i
-            for i in range(len(self._get_site_content()["posts"]))
-            if self._get_site_content()["posts"][i]["slug"] == post_slug
-        )
-        self._get_site_content()["posts"][post_index]["comments"].append(comment_data)
+        posts = self._get_site_content()["posts"]
+        post = next((p for p in posts if p["slug"] == post_slug), None)
+        if post is None:
+            raise ValueError(f"Post with slug {post_slug} not found")
+        post["comments"].append(comment_data)
 
     def get_plugins_data(self) -> list[dict[str, Any]]:
         """Retrieve configuration data for all plugins.

platzky/db/json_file_db.py

@@ -33,8 +33,7 @@ def get_db(config: dict[str, Any]) -> "JsonFile":
     Returns:
         Configured JSON file database instance
     """
-    json_file_db_config = JsonFileDbConfig.model_validate(config)
-    return JsonFile(json_file_db_config.path)
+    return db_from_config(JsonFileDbConfig.model_validate(config))
 
 
 def db_from_config(config: JsonFileDbConfig) -> "JsonFile":

platzky/db/mongodb_db.py

@@ -37,8 +37,7 @@ def get_db(config: dict[str, Any]) -> "MongoDB":
     Returns:
         Configured MongoDB database instance
     """
-    mongodb_config = MongoDbConfig.model_validate(config)
-    return MongoDB(mongodb_config.connection_string, mongodb_config.database_name)
+    return db_from_config(MongoDbConfig.model_validate(config))
 
 
 def db_from_config(config: MongoDbConfig) -> "MongoDB":
@@ -78,6 +77,10 @@ class MongoDB(DB):
         self.menu_items: Collection[Any] = self.db.menu_items
         self.plugins: Collection[Any] = self.db.plugins
 
+    def _get_site_config(self) -> dict[str, Any] | None:
+        """Retrieve the site configuration document."""
+        return self.site_content.find_one({"_id": "config"})
+
     def get_app_description(self, lang: str) -> str:
         """Retrieve the application description for a specific language.
 
@@ -87,9 +90,9 @@ class MongoDB(DB):
         Returns:
             Application description text or empty string if not found
         """
-        site_content = self.site_content.find_one({"_id": "config"})
-        if site_content and "app_description" in site_content:
-            return site_content["app_description"].get(lang, "")
+        site_config = self._get_site_config()
+        if site_config and "app_description" in site_config:
+            return site_config["app_description"].get(lang, "")
         return ""
 
     def get_all_posts(self, lang: str) -> list[Post]:
@@ -193,10 +196,8 @@ class MongoDB(DB):
         Returns:
             Logo image URL or empty string if not found
         """
-        site_content = self.site_content.find_one({"_id": "config"})
-        if site_content:
-            return site_content.get("logo_url", "")
-        return ""
+        site_config = self._get_site_config()
+        return site_config.get("logo_url", "") if site_config else ""
 
     def get_favicon_url(self) -> str:
         """Retrieve the URL of the application favicon.
@@ -204,10 +205,8 @@ class MongoDB(DB):
         Returns:
             Favicon URL or empty string if not found
         """
-        site_content = self.site_content.find_one({"_id": "config"})
-        if site_content:
-            return site_content.get("favicon_url", "")
-        return ""
+        site_config = self._get_site_config()
+        return site_config.get("favicon_url", "") if site_config else ""
 
     def get_primary_color(self) -> str:
         """Retrieve the primary color for the application theme.
@@ -215,10 +214,8 @@ class MongoDB(DB):
         Returns:
             Primary color value, defaults to 'white'
         """
-        site_content = self.site_content.find_one({"_id": "config"})
-        if site_content:
-            return site_content.get("primary_color", "white")
-        return "white"
+        site_config = self._get_site_config()
+        return site_config.get("primary_color", "white") if site_config else "white"
 
     def get_secondary_color(self) -> str:
         """Retrieve the secondary color for the application theme.
@@ -226,10 +223,8 @@ class MongoDB(DB):
         Returns:
             Secondary color value, defaults to 'navy'
         """
-        site_content = self.site_content.find_one({"_id": "config"})
-        if site_content:
-            return site_content.get("secondary_color", "navy")
-        return "navy"
+        site_config = self._get_site_config()
+        return site_config.get("secondary_color", "navy") if site_config else "navy"
 
     def get_plugins_data(self) -> list[dict[str, Any]]:
         """Retrieve configuration data for all plugins.
@@ -248,10 +243,8 @@ class MongoDB(DB):
         Returns:
             Font name or empty string if not configured
         """
-        site_content = self.site_content.find_one({"_id": "config"})
-        if site_content:
-            return site_content.get("font", "")
-        return ""
+        site_config = self._get_site_config()
+        return site_config.get("font", "") if site_config else ""
 
     def health_check(self) -> None:
         """Perform a health check on the MongoDB database.

platzky/debug/__init__.py

@@ -0,0 +1,9 @@
+"""Debug and development utilities.
+
+This package contains tools that should only be used in development
+or testing environments, never in production.
+"""
+
+from platzky.debug.blueprint import DebugBlueprint, DebugBlueprintProductionError
+
+__all__ = ["DebugBlueprint", "DebugBlueprintProductionError"]

platzky/debug/blueprint.py

@@ -0,0 +1,51 @@
+"""Debug-only Platzky blueprint."""
+
+import os
+from typing import Any
+
+from flask import Blueprint
+from flask.sansio.app import App
+from typing_extensions import override
+
+_FLASK_DEBUG_TRUTHY = {"1", "true", "yes"}
+
+
+def _is_flask_debug_env() -> bool:
+    """Check if FLASK_DEBUG environment variable indicates debug mode.
+
+    Flask CLI sets this env var before calling the app factory, so it
+    reflects ``--debug`` even though ``app.config["DEBUG"]`` may not yet.
+    """
+    return os.environ.get("FLASK_DEBUG", "").lower() in _FLASK_DEBUG_TRUTHY
+
+
+class DebugBlueprintProductionError(RuntimeError):
+    """Raised when a DebugBlueprint is registered on a production app."""
+
+    def __init__(self, blueprint_name: str) -> None:
+        super().__init__(
+            f"SECURITY ERROR: Cannot register DebugBlueprint '{blueprint_name}' in production. "
+            f"DEBUG and TESTING are both False. "
+            f"Set DEBUG: true or TESTING: true in your config, "
+            f"or use flask --debug."
+        )
+
+
+class DebugBlueprint(Blueprint):
+    """A Blueprint that can only be registered on apps in debug/testing mode.
+
+    Raises DebugBlueprintProductionError during registration if the app is not
+    in debug or testing mode. This provides a structural guarantee that debug-only
+    routes cannot be accidentally enabled in production.
+
+    Checks ``app.config["DEBUG"]``, ``app.config["TESTING"]``, and the
+    ``FLASK_DEBUG`` environment variable (set by ``flask --debug`` before
+    the app factory is called).
+    """
+
+    @override
+    def register(self, app: App, options: dict[str, Any]) -> None:
+        """Register the blueprint, but only if app is in debug/testing mode."""
+        if not (app.config.get("DEBUG") or app.config.get("TESTING") or _is_flask_debug_env()):
+            raise DebugBlueprintProductionError(self.name)
+        super().register(app, options)

platzky/{admin → debug}/fake_login.py

@@ -5,14 +5,15 @@ WARNING: This module provides fake login functionality and should NEVER be used
 environments as it bypasses proper authentication and authorization controls.
 """
 
-import os
 from collections.abc import Callable
 
-from flask import Blueprint, flash, redirect, render_template_string, session, url_for
+from flask import flash, redirect, render_template_string, session, url_for
 from flask_wtf import FlaskForm
 from markupsafe import Markup
 from werkzeug.wrappers import Response
 
+from platzky.debug.blueprint import DebugBlueprint
+
 ROLE_ADMIN = "admin"
 ROLE_NONADMIN = "nonadmin"
 VALID_ROLES = [ROLE_ADMIN, ROLE_NONADMIN]
@@ -33,8 +34,8 @@ def get_fake_login_html() -> Callable[[], str]:
     """Return a callable that generates HTML for fake login buttons."""
 
     def generate_html() -> str:
-        admin_url = url_for("admin.handle_fake_login", role="admin")
-        nonadmin_url = url_for("admin.handle_fake_login", role="nonadmin")
+        admin_url = url_for("fake_login.handle_fake_login", role="admin")
+        nonadmin_url = url_for("fake_login.handle_fake_login", role="nonadmin")
 
         # Create a form instance to get the CSRF token
         form = FakeLoginForm()
@@ -72,24 +73,18 @@ def get_fake_login_html() -> Callable[[], str]:
     return generate_html
 
 
-def setup_fake_login_routes(admin_blueprint: Blueprint) -> Blueprint:
-    """Add fake login routes to the provided admin_blueprint."""
+def create_fake_login_blueprint() -> DebugBlueprint:
+    """Create a DebugBlueprint with fake login routes.
 
-    env = os.environ
-    is_testing = "PYTEST_CURRENT_TEST" in env.keys() or env.get("FLASK_DEBUG") in (
-        "1",
-        "true",
-        "True",
-        True,
-    )
+    The returned blueprint will raise RuntimeError if registered on an app
+    that is not in debug or testing mode.
 
-    if not is_testing:
-        raise RuntimeError(
-            "SECURITY ERROR: Fake login routes are enabled outside of a testing environment! "
-            "This functionality must only be used during development or testing."
-        )
+    Returns:
+        DebugBlueprint with fake login routes at /admin/fake-login/<role>.
+    """
+    bp = DebugBlueprint("fake_login", __name__, url_prefix="/admin")
 
-    @admin_blueprint.route("/fake-login/<role>", methods=["POST"])
+    @bp.route("/fake-login/<role>", methods=["POST"])
     def handle_fake_login(role: str) -> Response:
         form = FakeLoginForm()
         if form.validate_on_submit() and role in VALID_ROLES:
@@ -102,4 +97,4 @@ def setup_fake_login_routes(admin_blueprint: Blueprint) -> Blueprint:
         flash(f"Invalid role: {role}. Must be one of: {', '.join(VALID_ROLES)}", "error")
         return redirect(url_for("admin.admin_panel_home"))
 
-    return admin_blueprint
+    return bp

platzky/engine.py

@@ -13,6 +13,7 @@ from flask_babel import Babel
 from platzky.attachment import AttachmentProtocol, create_attachment_class
 from platzky.config import Config
 from platzky.db.db import DB
+from platzky.feature_flags import FeatureFlag
 from platzky.models import CmsModule
 from platzky.notifier import Notifier, NotifierWithAttachments
 
@@ -35,6 +36,7 @@ class Engine(Flask):
         """
         super().__init__(import_name)
         self.config.from_mapping(config.model_dump(by_alias=True))
+        self.config["FEATURE_FLAGS"] = config.feature_flags
         self.db = db
         self.Attachment: type[AttachmentProtocol] = create_attachment_class(config.attachment)
         self.notifiers: list[Notifier] = []
@@ -87,7 +89,7 @@ class Engine(Flask):
         """
         self.notifiers_with_attachments.append(notifier)
 
-    def add_cms_module(self, module: CmsModule):
+    def add_cms_module(self, module: CmsModule) -> None:
         """Add a CMS module to the modules list."""
         self.cms_modules.append(module)
 
@@ -95,11 +97,11 @@ class Engine(Flask):
     def add_login_method(self, login_method: Callable[[], str]) -> None:
         self.login_methods.append(login_method)
 
-    def add_dynamic_body(self, body: str):
+    def add_dynamic_body(self, body: str) -> None:
         self.dynamic_body += body
 
-    def add_dynamic_head(self, body: str):
-        self.dynamic_head += body
+    def add_dynamic_head(self, head: str) -> None:
+        self.dynamic_head += head
 
     def get_locale(self) -> str:
         languages = self.config.get("LANGUAGES", {}).keys()
@@ -113,6 +115,19 @@ class Engine(Flask):
         session["language"] = lang
         return lang
 
+    def is_enabled(self, flag: FeatureFlag) -> bool:
+        """Check whether a feature flag is enabled.
+
+        This is the primary API for flag checks.
+
+        Args:
+            flag: A FeatureFlag instance.
+
+        Returns:
+            True if the flag is enabled.
+        """
+        return flag in self.config["FEATURE_FLAGS"]
+
     def add_health_check(self, name: str, check_function: Callable[[], None]) -> None:
         """Register a health check function"""
         if not callable(check_function):

platzky/feature_flags.py

@@ -0,0 +1,141 @@
+"""Feature flags system with instance-based registration.
+
+Flags are created as instances of ``FeatureFlag``. Each instance is
+automatically registered and discovered via ``all_flags()``. The primary
+API is ``engine.is_enabled(flag_instance)``.
+
+Example::
+
+    CategoriesHelp = FeatureFlag(alias="CATEGORIES_HELP")
+
+    # Usage
+    app.is_enabled(CategoriesHelp)  # True/False
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from platzky.feature_flags_wrapper import FeatureFlagSet
+
+_registry: set[FeatureFlag] = set()
+
+
+class FeatureFlag:
+    """A feature flag.
+
+    Identity is based solely on ``alias``: two flags with the same alias
+    are considered equal regardless of ``default`` or ``description``.
+    Aliases are expected to be unique across the application.
+
+    Args:
+        alias: The YAML/dict key for this flag.
+        default: Whether the flag is enabled by default.
+        description: Human-readable description.
+
+    Example::
+
+        FakeLogin = FeatureFlag(
+            alias="FAKE_LOGIN",
+            default=False,
+            description="Enable fake login. Never in production.",
+        )
+    """
+
+    __slots__ = ("alias", "default", "description", "production_warning")
+
+    def __init__(
+        self,
+        *,
+        alias: str,
+        default: bool = False,
+        description: str = "",
+        production_warning: bool = False,
+        register: bool = True,
+    ) -> None:
+        if not alias:
+            raise ValueError("FeatureFlag requires a non-empty 'alias'")
+        self.alias = alias
+        self.default = default
+        self.description = description
+        self.production_warning = production_warning
+        if register:
+            _registry.add(self)
+
+    def __repr__(self) -> str:
+        return f"FeatureFlag(alias={self.alias!r})"
+
+    def __hash__(self) -> int:
+        return hash(self.alias)
+
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, FeatureFlag):
+            return self.alias == other.alias
+        return NotImplemented
+
+
+FakeLogin = FeatureFlag(
+    alias="FAKE_LOGIN",
+    default=False,
+    description="Enable fake login for development. WARNING: Never enable in production.",
+    production_warning=True,
+)
+
+
+def all_flags() -> frozenset[FeatureFlag]:
+    """Return all registered feature flags.
+
+    Note: The returned frozenset has no guaranteed iteration order.
+    Use ``sorted(all_flags(), key=lambda f: f.alias)`` when
+    deterministic ordering is needed (e.g., documentation generation).
+    """
+    return frozenset(_registry)
+
+
+def unregister(flag: FeatureFlag) -> None:
+    """Remove a flag from the registry."""
+    _registry.discard(flag)
+
+
+def clear_registry() -> None:
+    """Remove all flags from the registry. Intended for test isolation."""
+    _registry.clear()
+
+
+def parse_flags(
+    raw_data: dict[str, bool] | None = None,
+) -> frozenset[FeatureFlag]:
+    """Build a frozenset of *enabled* flags from raw config data.
+
+    Uses ``all_flags()`` for discovery. Unknown keys in *raw_data* are
+    silently ignored.
+
+    Args:
+        raw_data: Dict of flag alias -> value from config / YAML.
+
+    Returns:
+        A frozenset containing the enabled FeatureFlag instances.
+    """
+    if raw_data is None:
+        raw_data = {}
+
+    return frozenset(flag for flag in all_flags() if raw_data.get(flag.alias, flag.default))
+
+
+def build_flag_set(raw_data: dict[str, bool] | None = None) -> FeatureFlagSet:
+    """Build a FeatureFlagSet from raw config data.
+
+    Preserves ALL keys (including unregistered ones) for backward
+    compatibility with consumers that use dict-like access.
+    """
+    from platzky.feature_flags_wrapper import FeatureFlagSet
+
+    if raw_data is None:
+        raw_data = {}
+
+    enabled_flags = frozenset(
+        flag for flag in all_flags() if raw_data.get(flag.alias, flag.default)
+    )
+
+    return FeatureFlagSet(enabled_flags, raw_data)

platzky/feature_flags_wrapper.py

@@ -0,0 +1,93 @@
+"""Backward-compatible wrapper for feature flags.
+
+.. deprecated:: 1.4.0
+    Dict-like access is deprecated. Use typed FeatureFlag instances
+    with engine.is_enabled(flag) instead.
+"""
+
+import warnings
+
+import deprecation
+
+from platzky.feature_flags import FeatureFlag
+
+_MIGRATION_MSG = (
+    "Dict-like access to feature flags is deprecated. "
+    "Define a FeatureFlag instance and use engine.is_enabled(flag) instead. "
+    "See: https://platzky.readthedocs.io/en/latest/config.html#feature-flags"
+)
+
+_DEPRECATION_WARNING = deprecation.DeprecatedWarning(
+    "feature_flags dict access",
+    "1.4.0",
+    "2.0.0",
+    _MIGRATION_MSG,
+)
+
+
+def _warn_dict_access() -> None:
+    warnings.warn(_DEPRECATION_WARNING, stacklevel=3)
+
+
+class FeatureFlagSet(dict[str, bool]):
+    """Backward-compatible feature flag collection (dict subclass).
+
+    .. deprecated:: 1.4.0
+        Dict-like access (.get, .KEY, [key]) is deprecated.
+        Migrate to typed FeatureFlag + engine.is_enabled().
+
+    Dual-mode container:
+    - ``FeatureFlag in flag_set`` -- typed membership (engine.is_enabled). Intended API.
+    - ``flag_set.get("KEY")`` -- deprecated dict access via dict inheritance.
+    - ``flag_set.KEY`` -- deprecated Jinja2 attribute access.
+    """
+
+    _enabled_flags: frozenset[FeatureFlag]
+
+    def __init__(
+        self,
+        enabled_flags: frozenset[FeatureFlag],
+        raw_data: dict[str, bool],
+    ) -> None:
+        super().__init__(raw_data)
+        # Use object.__setattr__ to bypass __getattr__ override
+        object.__setattr__(self, "_enabled_flags", enabled_flags)
+
+    def __getitem__(self, key: str) -> bool:
+        """Dict bracket access with deprecation warning."""
+        _warn_dict_access()
+        return super().__getitem__(key)
+
+    def get(self, key: str, default: bool | None = None) -> bool | None:  # type: ignore[override]
+        """Dict .get() access with deprecation warning."""
+        _warn_dict_access()
+        return super().get(key, default)
+
+    def _raise_immutable(self, *_args: object, **_kwargs: object) -> None:
+        raise TypeError("FeatureFlagSet is immutable")
+
+    __setitem__ = _raise_immutable
+    __delitem__ = _raise_immutable
+    pop = _raise_immutable  # type: ignore[assignment]
+    update = _raise_immutable
+    clear = _raise_immutable
+    setdefault = _raise_immutable  # type: ignore[assignment]
+    __ior__ = _raise_immutable  # type: ignore[assignment]
+
+    def __contains__(self, item: object) -> bool:
+        """Support both FeatureFlag membership and string key lookup."""
+        if isinstance(item, FeatureFlag):
+            return item in self._enabled_flags
+        return super().__contains__(item)
+
+    def __getattr__(self, name: str) -> bool:
+        """Jinja2 dot-notation access: ``{{ feature_flags.SOME_FLAG }}``."""
+        try:
+            return self[name]
+        except KeyError:
+            raise AttributeError(f"'{type(self).__name__}' has no attribute {name!r}") from None
+
+    @property
+    def enabled_flags(self) -> frozenset[FeatureFlag]:
+        """The set of enabled typed FeatureFlag instances."""
+        return self._enabled_flags

platzky/platzky.py

@@ -16,6 +16,7 @@ from platzky.config import (
 from platzky.db.db import DB
 from platzky.db.db_loader import get_db
 from platzky.engine import Engine
+from platzky.feature_flags import FakeLogin
 from platzky.plugin.plugin_loader import plugify
 from platzky.seo import seo
 from platzky.www_handler import redirect_nonwww_to_www, redirect_www_to_nonwww
@@ -129,17 +130,6 @@ def create_engine(config: Config, db: DB) -> Engine:
         redirect_url = _get_safe_redirect_url(request.referrer, request.host)
         return redirect(redirect_url)
 
-    def url_link(x: str) -> str:
-        """URL-encode a string for safe use in URLs.
-
-        Args:
-            x: String to encode
-
-        Returns:
-            URL-encoded string with all characters except safe ones escaped
-        """
-        return _url_encode(x)
-
     @app.context_processor
     def utils() -> dict[str, t.Any]:
         """Provide utility variables and functions to all templates.
@@ -150,8 +140,8 @@ def create_engine(config: Config, db: DB) -> Engine:
         """
         locale = app.get_locale()
         lang = config.languages.get(locale)
-        flag = lang.flag if lang is not None else ""
-        country = lang.country if lang is not None else ""
+        flag = lang.flag if lang else ""
+        country = lang.country if lang else ""
         return {
             "app_name": config.app_name,
             "app_description": app.db.get_app_description(locale) or config.app_name,
@@ -159,7 +149,7 @@ def create_engine(config: Config, db: DB) -> Engine:
             "current_flag": flag,
             "current_lang_country": country,
             "current_language": locale,
-            "url_link": url_link,
+            "url_link": _url_encode,
             "menu_items": app.db.get_menu_items_in_lang(locale),
             "logo_url": app.db.get_logo_url(),
             "favicon_url": app.db.get_favicon_url(),
@@ -239,11 +229,14 @@ def create_app_from_config(config: Config) -> Engine:
         login_methods=engine.login_methods, cms_modules=engine.cms_modules
     )
 
-    if config.feature_flags and config.feature_flags.get("FAKE_LOGIN", False):
-        from platzky.admin.fake_login import get_fake_login_html, setup_fake_login_routes
+    # Two-layer defense: is_enabled() gates the feature flag, and
+    # DebugBlueprint.register() independently blocks registration
+    # unless the app is in debug or testing mode.
+    if engine.is_enabled(FakeLogin):
+        from platzky.debug.fake_login import create_fake_login_blueprint, get_fake_login_html
 
         engine.login_methods.append(get_fake_login_html())
-        admin_blueprint = setup_fake_login_routes(admin_blueprint)
+        engine.register_blueprint(create_fake_login_blueprint())
 
     blog_blueprint = blog.create_blog_blueprint(
         db=engine.db,

platzky/seo/seo.py

@@ -77,16 +77,15 @@ def create_seo_blueprint(
         """
         lang = locale_func()
 
-        global url
         host_components = urllib.parse.urlparse(request.host_url)
         host_base = host_components.scheme + "://" + host_components.netloc
 
         # Static routes with static content
-        static_urls = []
-        for rule in current_app.url_map.iter_rules():
-            if rule.methods is not None and "GET" in rule.methods and len(rule.arguments) == 0:
-                url = {"loc": f"{host_base}{rule!s}"}
-                static_urls.append(url)
+        static_urls = [
+            {"loc": f"{host_base}{rule!s}"}
+            for rule in current_app.url_map.iter_rules()
+            if rule.methods is not None and "GET" in rule.methods and len(rule.arguments) == 0
+        ]
 
         dynamic_urls = get_blog_entries(host_base, lang, db, config["BLOG_PREFIX"])
 

{platzky-1.3.1.dist-info → platzky-1.4.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: platzky
-Version: 1.3.1
+Version: 1.4.1
 Summary: Not only blog engine
 License: MIT
 License-File: LICENSE

{platzky-1.3.1.dist-info → platzky-1.4.1.dist-info}/RECORD

@@ -1,6 +1,5 @@
-platzky/__init__.py,sha256=IhL91rSWxIIJQNfVsqJ1d4yY5D2WyWcefo4Xv2aX_lo,180
-platzky/admin/admin.py,sha256=QhuxGtUjfX-xeDd_xmSChoeD5Z1UMu1jTGtUck-9jJU,1699
-platzky/admin/fake_login.py,sha256=Z_4M4PLQ73qL-sKh05CmDx_nFy8S30PdsNfPPDeFSmE,3528
+platzky/__init__.py,sha256=jn2Ua0ZpKBI3Fb5tFYcRm3kEaR0SytlNBh6guUtO2jg,558
+platzky/admin/admin.py,sha256=_4Q1nId_QGrbSMaAZzl7ziquza3syQxXlBYYXjD_4XM,1660
 platzky/admin/templates/admin.html,sha256=zgjROhSezayZqnNFezvVa0MEfgmXLvOM8HRRaZemkQw,688
 platzky/admin/templates/login.html,sha256=oBNuv130iMTwXrtRnDUDcGIGvu0O2VsIbjQxw-Tjd7Y,380
 platzky/admin/templates/module.html,sha256=WuQZxKQDD4INl-QF2uiKHf9Fmf2h7cEW9RLe1nWKC8k,175
@@ -9,28 +8,33 @@ platzky/attachment/constants.py,sha256=9WB8w_sKxsq2DM5hfz2ShRI-nUT2E5v9tfBWIOgrq
 platzky/attachment/core.py,sha256=-jrelChnHEeowg5d4-41fY6slFfqnv3fEqiI_sMPFd8,9656
 platzky/attachment/mime_validation.py,sha256=VO272nF7K_Mx_Zefuw-10M-Tapj0ZxX197syh8yy0oQ,2874
 platzky/blog/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-platzky/blog/blog.py,sha256=n3bsZ1GpVCmvxCFMiF7QUDb_PHbmBiTu0GDu3r_Su24,5490
+platzky/blog/blog.py,sha256=UaAS7QpcEsMswMrdAcyoSyuDX1NNQX05ll8D7MKSR3w,5468
 platzky/blog/comment_form.py,sha256=yOuXvX9PZLc6qQLIWZWLFcbwFQD4a849X82PlXKUzdk,805
-platzky/config.py,sha256=37g5Pzvr_Op6mWhsR4XixyGL38iNaUUTU4-H2o8kgNU,11054
+platzky/config.py,sha256=vldHCB6C_Y9NllkacSJ0-jd3vo3eIw9sG6eDpGQpyOU,11589
 platzky/db/README.md,sha256=IO-LoDsd4dLBZenaz423EZjvEOQu_8m2OC0G7du170w,1753
 platzky/db/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 platzky/db/db.py,sha256=gi5uxvY8Ww8O4y2rxaH1Zj_12Yno8SbILvIaWnQPbYQ,4778
 platzky/db/db_loader.py,sha256=YgR16K5Mj5pN0vWYVQxTD4Z6ihG5fZyjbUUCS8LNqJs,999
-platzky/db/github_json_db.py,sha256=0z-aCz7Pm6Al--SbIHx4T_FyzwfwQcZDqBduTCOE5_A,3314
-platzky/db/google_json_db.py,sha256=RnvirGFo5a41vkd1iD-M4-HwHlWDZ19EqpF0vIer_Xo,3049
-platzky/db/graph_ql_db.py,sha256=a8LGPJKoNpmTkJ6Bb89eg6m6Q9GFetp5z8A0xuemuSk,14504
-platzky/db/json_db.py,sha256=pANXJZzVPAO890TRy3IvzHjpCaeDgNNgNOR5Uhkk2h4,8078
-platzky/db/json_file_db.py,sha256=Tl6b67p4hNViXSAjujXZ9vtVHN61QhrzJUgOuvngyMI,2232
-platzky/db/mongodb_db.py,sha256=nq07j0NldK014qRL1mF-cvBXQF1LKKTTeWxaZdyzjAs,8595
-platzky/engine.py,sha256=ZMeZEmqpWO9lXQEITqF1O4JsMjCw3zxvJsRJGsVHmFY,6934
+platzky/db/github_json_db.py,sha256=xCh4F569X2sH5WvOVUzH3Nsk0UTXnzVJoxUs5UYbQcs,3110
+platzky/db/google_json_db.py,sha256=e8xh0YxCpVgbWmGshva2CtbLpGukgrz5D2l0vNHEVks,2949
+platzky/db/graph_ql_db.py,sha256=YU61lcJjkJ3kSyVuCQIet1kgX3gbaeNf7Jo0nODBVsI,14295
+platzky/db/json_db.py,sha256=5l2AGw06J57X-BxDaCo5O8ze9uIrBKg7x7JWHe0hecc,7931
+platzky/db/json_file_db.py,sha256=r5LMg-e0bTuu68ayrkZQ93fgIoPpc4RSfwQ48LNieTA,2187
+platzky/db/mongodb_db.py,sha256=vK-fuZUd4LH0AaZjCHDk7YL89_0qmTCginbVL4Rv87A,8427
+platzky/debug/__init__.py,sha256=5VUFjOOJzuXTuCgzQRe9aNjXHoCJSVUerR3RLKCTZC0,301
+platzky/debug/blueprint.py,sha256=_rtrtrOOsj4Pz8AKE_5kLFVedEtipAyN42j-pBVZqnM,1893
+platzky/debug/fake_login.py,sha256=3AmS11Kb4h5gDwWjUY26iDMif0b0x69S97veotnXUp4,3390
+platzky/engine.py,sha256=JeyRS-A0R0fK2BLude_Y4U8G3d-7nRUkuu4OeX86sRI,7400
+platzky/feature_flags.py,sha256=BD-DcPDYfYr2xuMrc61qyw5s6QQBqI1ro_H3-h3vWeo,3947
+platzky/feature_flags_wrapper.py,sha256=NqBoix90VODiILEkO6esRMRKsKZQVHgOa3VUWV3PPmU,3138
 platzky/locale/en/LC_MESSAGES/messages.po,sha256=WaZGlFAegKRq7CSz69dWKic-mKvQFhVvssvExxNmGaU,1400
 platzky/locale/pl/LC_MESSAGES/messages.po,sha256=sUPxMKDeEOoZ5UIg94rGxZD06YVWiAMWIby2XE51Hrc,1624
 platzky/models.py,sha256=Ws5ZSWf5EhcpFxl3Yeze2pQiesjnjAA_haBJ90bN6lk,7435
 platzky/notifier.py,sha256=fh6_sdeD9TRFPkBjnuSz9jH6UKoSDkaqqGfZD1dmVZc,1214
-platzky/platzky.py,sha256=1LKYq8pLm1QBlOcEPhugxWi8W0vuWqjjINIFK8b2Kow,9319
+platzky/platzky.py,sha256=cQ9X-eczMs0Bhcve0432nDC8_H5UvXCgk5dJLQLqcDo,9214
 platzky/plugin/plugin.py,sha256=KZb6VEph__lx9xrv5Ay4h4XkFFYbodV5OimaG6B9IDc,2812
 platzky/plugin/plugin_loader.py,sha256=eKG6zodUCkiRLxJ2ZX9zdN4-ZrZ9EwssoY1SDtThaFo,6707
-platzky/seo/seo.py,sha256=cguipDKHYBd0J4M8q8t5QNk3bmUIavXp9V3Ugv0UouU,3854
+platzky/seo/seo.py,sha256=9ZSvT7zepHFmmrOSsCvaiSiO0B25E7bdgrm1Ctby5fE,3796
 platzky/static/blog.css,sha256=TrppzgQbj4UtuTufDCdblyNTVAqgIbhD66Cziyv_xnY,7893
 platzky/static/styles.css,sha256=wLUug7kd3S3aXylkq6eDKiGEeHD7CfP0RsDBZnahlhc,3184
 platzky/telemetry.py,sha256=iXYvEt0Uw5Hx8lAxyr45dpQ_SiE2NxmJkoSx-JSRJyM,5011
@@ -46,7 +50,7 @@ platzky/templates/post.html,sha256=GSgjIZsOQKtNx3cEbquSjZ5L4whPnG6MzRyoq9k4B8Q,1
 platzky/templates/robots.txt,sha256=2_j2tiYtYJnzZUrANiX9pvBxyw5Dp27fR_co18BPEJ0,116
 platzky/templates/sitemap.xml,sha256=iIJZ91_B5ZuNLCHsRtsGKZlBAXojOTP8kffqKLacgvs,578
 platzky/www_handler.py,sha256=pF6Rmvem1sdVqHD7z3RLrDuG-CwAqfGCti50_NPsB2w,725
-platzky-1.3.1.dist-info/METADATA,sha256=svMs71SYvCkV0TopZmIve1BEgkA-zgzr-YO4MsX0QYw,2595
-platzky-1.3.1.dist-info/WHEEL,sha256=3ny-bZhpXrU6vSQ1UPG34FoxZBp3lVcvK0LkgUz6VLk,88
-platzky-1.3.1.dist-info/licenses/LICENSE,sha256=wCdfk-qEosi6BDwiBulMfKMi0hxp1UXV0DdjLrRm788,1077
-platzky-1.3.1.dist-info/RECORD,,
+platzky-1.4.1.dist-info/METADATA,sha256=7sZy3c0h0DRh_uEVwK1t_hqrV8XLaWarDbpLj2SA4xM,2595
+platzky-1.4.1.dist-info/WHEEL,sha256=3ny-bZhpXrU6vSQ1UPG34FoxZBp3lVcvK0LkgUz6VLk,88
+platzky-1.4.1.dist-info/licenses/LICENSE,sha256=wCdfk-qEosi6BDwiBulMfKMi0hxp1UXV0DdjLrRm788,1077
+platzky-1.4.1.dist-info/RECORD,,