platzky 1.0.0__py3-none-any.whl → 1.1.0__py3-none-any.whl

platzky/admin/fake_login.py

@@ -6,7 +6,8 @@ environments as it bypasses proper authentication and authorization controls.
 """
 
 import os
-from typing import Any, Callable
+from collections.abc import Callable
+from typing import Any
 
 from flask import Blueprint, flash, redirect, render_template_string, session, url_for
 from flask_wtf import FlaskForm

platzky/blog/blog.py

@@ -1,10 +1,17 @@
+import logging
+from collections.abc import Callable
 from os.path import dirname
+from typing import Any
 
-from flask import Blueprint, make_response, render_template, request
+from flask import Blueprint, abort, make_response, render_template, request
 from markupsafe import Markup
+from werkzeug.exceptions import HTTPException
+from werkzeug.wrappers import Response
 
 from . import comment_form
 
+logger = logging.getLogger(__name__)
+
 
 def create_blog_blueprint(db, blog_prefix: str, locale_func):
     url_prefix = blog_prefix
@@ -20,27 +27,35 @@ def create_blog_blueprint(db, blog_prefix: str, locale_func):
         return Markup(text)
 
     @blog.errorhandler(404)
-    def page_not_found(e):
+    def page_not_found(_e: HTTPException) -> tuple[str, int]:
+        """Handle 404 Not Found errors in blog routes.
+
+        Args:
+            _e: HTTPException object containing error details (unused)
+
+        Returns:
+            Tuple of rendered 404 template and HTTP 404 status code
+        """
         return render_template("404.html", title="404"), 404
 
     @blog.route("/", methods=["GET"])
-    def all_posts():
+    def all_posts() -> str:
         lang = locale_func()
         posts = db.get_all_posts(lang)
         if not posts:
-            return page_not_found("no posts")
+            abort(404)
         posts_sorted = sorted(posts, reverse=True)
         return render_template("blog.html", posts=posts_sorted)
 
     @blog.route("/feed", methods=["GET"])
-    def get_feed():
+    def get_feed() -> Response:
         lang = locale_func()
         response = make_response(render_template("feed.xml", posts=db.get_all_posts(lang)))
         response.headers["Content-Type"] = "application/xml"
         return response
 
     @blog.route("/<post_slug>", methods=["POST"])
-    def post_comment(post_slug):
+    def post_comment(post_slug: str) -> str:
         comment = request.form.to_dict()
         db.add_comment(
             post_slug=post_slug,
@@ -49,40 +64,47 @@ def create_blog_blueprint(db, blog_prefix: str, locale_func):
         )
         return get_post(post_slug=post_slug)
 
-    @blog.route("/<post_slug>", methods=["GET"])
-    def get_post(post_slug):
+    def _get_content_or_404(
+        getter_func: Callable[[str], Any],
+        slug: str,
+    ) -> Any:
+        """Helper to fetch content from database or abort with 404.
+
+        Args:
+            getter_func: Database getter function (e.g., db.get_post, db.get_page)
+            slug: Content slug to fetch
+
+        Returns:
+            The fetched content object
+
+        Raises:
+            HTTPException: 404 if content not found
+        """
         try:
-            post = db.get_post(post_slug)
-            return render_template(
-                "post.html",
-                post=post,
-                post_slug=post_slug,
-                form=comment_form.CommentForm(),
-                comment_sent=request.args.get("comment_sent"),
-            )
-        except ValueError:
-            return page_not_found(f"no post with slug {post_slug}")
-        except Exception as e:
-            return page_not_found(str(e))
+            return getter_func(slug)
+        except ValueError as e:
+            logger.debug("Content not found for slug '%s': %s", slug, e)
+            abort(404)
+
+    @blog.route("/<post_slug>", methods=["GET"])
+    def get_post(post_slug: str) -> str:
+        post = _get_content_or_404(db.get_post, post_slug)
+        return render_template(
+            "post.html",
+            post=post,
+            post_slug=post_slug,
+            form=comment_form.CommentForm(),
+            comment_sent=request.args.get("comment_sent"),
+        )
 
     @blog.route("/page/<path:page_slug>", methods=["GET"])
-    def get_page(
-        page_slug,
-    ):  # TODO refactor to share code with get_post since they are very similar
-        try:
-            page = db.get_page(page_slug)
-            if cover_image := page.coverImage:
-                cover_image_url = cover_image.url
-            else:
-                cover_image_url = None
-            return render_template("page.html", page=page, cover_image=cover_image_url)
-        except ValueError:
-            return page_not_found("no page with slug {page_slug}")
-        except Exception as e:
-            return page_not_found(str(e))
+    def get_page(page_slug: str) -> str:
+        page = _get_content_or_404(db.get_page, page_slug)
+        cover_image_url = page.coverImage.url if page.coverImage.url else None
+        return render_template("page.html", page=page, cover_image=cover_image_url)
 
     @blog.route("/tag/<path:tag>", methods=["GET"])
-    def get_posts_from_tag(tag):
+    def get_posts_from_tag(tag: str) -> str:
         lang = locale_func()
         posts = db.get_posts_by_tag(tag, lang)
         return render_template("blog.html", posts=posts, subtitle=f" - tag: {tag}")

platzky/config.py

@@ -75,6 +75,7 @@ class TelemetryConfig(StrictBaseModel):
         service_instance_id: Service instance ID (auto-generated if not provided)
         flush_on_request: Flush spans after each request (default: True, may impact latency)
         flush_timeout_ms: Timeout in milliseconds for per-request flush (default: 5000)
+        instrument_logging: Enable automatic logging instrumentation (default: True)
     """
 
     enabled: bool = Field(default=False, alias="enabled")
@@ -85,6 +86,7 @@ class TelemetryConfig(StrictBaseModel):
     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")
 
     @field_validator("endpoint")
     @classmethod

platzky/db/db.py

@@ -1,6 +1,7 @@
 from abc import ABC, abstractmethod
+from collections.abc import Callable
 from functools import partial
-from typing import Any, Callable
+from typing import Any
 
 from pydantic import BaseModel, Field
 

platzky/db/json_db.py

@@ -1,5 +1,5 @@
 import datetime
-from typing import Any, Dict
+from typing import Any
 
 from pydantic import Field
 
@@ -12,7 +12,7 @@ def db_config_type():
 
 
 class JsonDbConfig(DBConfig):
-    data: Dict[str, Any] = Field(alias="DATA")
+    data: dict[str, Any] = Field(alias="DATA")
 
 
 def get_db(config):
@@ -30,9 +30,9 @@ def db_from_config(config: JsonDbConfig):
 
 
 class Json(DB):
-    def __init__(self, data: Dict[str, Any]):
+    def __init__(self, data: dict[str, Any]):
         super().__init__()
-        self.data: Dict[str, Any] = data
+        self.data: dict[str, Any] = data
         self.module_name = "json_db"
         self.db_name = "JsonDb"
 
@@ -62,7 +62,10 @@ class Json(DB):
         list_of_pages = (
             page for page in self._get_site_content().get("pages") if page["slug"] == slug
         )
-        page = Post.model_validate(next(list_of_pages))
+        wanted_page = next(list_of_pages, None)
+        if wanted_page is None:
+            raise ValueError(f"Page with slug {slug} not found")
+        page = Post.model_validate(wanted_page)
         return page
 
     def get_menu_items_in_lang(self, lang) -> list[MenuItem]:
@@ -101,10 +104,15 @@ class Json(DB):
         return self._get_site_content().get("secondary_color", "navy")
 
     def add_comment(self, author_name, comment, post_slug):
+        # Store dates in UTC with timezone info for consistency with MongoDB backend
+        # This ensures accurate time delta calculations regardless of server timezone
+        # Legacy dates without timezone info are still supported for backward compatibility
+        now_utc = datetime.datetime.now(datetime.timezone.utc).isoformat(timespec="seconds")
+
         comment = {
             "author": str(author_name),
             "comment": str(comment),
-            "date": datetime.datetime.now().strftime("%Y-%m-%dT%H:%M:%S"),
+            "date": now_utc,
         }
 
         post_index = next(

platzky/engine.py

@@ -1,6 +1,7 @@
 import os
+from collections.abc import Callable
 from concurrent.futures import ThreadPoolExecutor, TimeoutError
-from typing import Any, Callable, Dict, List, Tuple
+from typing import Any
 
 from flask import Blueprint, Flask, jsonify, make_response, request, session
 from flask_babel import Babel
@@ -18,7 +19,7 @@ class Engine(Flask):
         self.login_methods = []
         self.dynamic_body = ""
         self.dynamic_head = ""
-        self.health_checks: List[Tuple[str, Callable[[], None]]] = []
+        self.health_checks: list[tuple[str, Callable[[], None]]] = []
         self.telemetry_instrumented: bool = False
         directory = os.path.dirname(os.path.realpath(__file__))
         locale_dir = os.path.join(directory, "locale")
@@ -31,7 +32,7 @@ class Engine(Flask):
         )
         self._register_default_health_endpoints()
 
-        self.cms_modules: List[CmsModule] = []
+        self.cms_modules: list[CmsModule] = []
         # TODO add plugins as CMS Module - all plugins should be visible from
         # admin page at least as configuration
 
@@ -94,7 +95,7 @@ class Engine(Flask):
         @health_bp.route("/health/readiness")
         def readiness():
             """Readiness check - can the app serve traffic?"""
-            health_status: Dict[str, Any] = {"status": "ready", "checks": {}}
+            health_status: dict[str, Any] = {"status": "ready", "checks": {}}
             status_code = 200
 
             executor = ThreadPoolExecutor(max_workers=1)

platzky/models.py

@@ -1,7 +1,87 @@
 import datetime
+import warnings
+from typing import Annotated
 
 import humanize
-from pydantic import BaseModel
+from pydantic import BaseModel, BeforeValidator, Field
+
+
+def _parse_date_string(v: str | datetime.datetime) -> datetime.datetime:
+    """Parse date string to datetime for backward compatibility.
+
+    Handles string dates in various ISO 8601 formats for backward compatibility.
+    Emits deprecation warning when parsing strings.
+
+    In version 2.0.0, only datetime objects will be accepted.
+
+    Args:
+        v: Either a datetime object or an ISO 8601 date string
+
+    Returns:
+        Timezone-aware datetime object
+
+    Raises:
+        ValueError: If the date string cannot be parsed
+    """
+    if isinstance(v, datetime.datetime):
+        # If already a datetime object, ensure it's timezone-aware
+        if v.tzinfo is None:
+            # Naive datetime - make timezone-aware using UTC
+            return v.replace(tzinfo=datetime.timezone.utc)
+        return v
+
+    # v must be a string (based on type annotation)
+    # Emit deprecation warning for string dates
+    warnings.warn(
+        f"Passing date as string ('{v}') is deprecated. "
+        "Please use datetime objects instead. "
+        "String support will be removed in version 2.0.0.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+
+    # Check for timezone in the original string (before any manipulation)
+    # Check for: +HH:MM, -HH:MM, or Z suffix
+    time_part = v.split("T")[-1] if "T" in v else ""
+    has_timezone = (
+        v.endswith("Z")
+        or "+" in time_part
+        or ("-" in time_part and ":" in time_part.split("-")[-1])
+    )
+
+    # Normalize 'Z' suffix to '+00:00' for fromisoformat
+    normalized = v.replace("Z", "+00:00") if v.endswith("Z") else v
+
+    if has_timezone:
+        # Parse timezone-aware datetime (handles microseconds automatically)
+        return datetime.datetime.fromisoformat(normalized)
+    else:
+        # Legacy format: naive datetime - make timezone-aware using UTC
+        warnings.warn(
+            f"Naive datetime '{v}' interpreted as UTC. "
+            "Explicitly specify timezone in future versions for clarity.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        try:
+            parsed = datetime.datetime.fromisoformat(normalized)
+            return parsed.replace(tzinfo=datetime.timezone.utc)
+        except ValueError:
+            # Fallback: date-only format
+            parsed_date = datetime.date.fromisoformat(normalized)
+            return datetime.datetime.combine(
+                parsed_date, datetime.time.min, tzinfo=datetime.timezone.utc
+            )
+
+
+# Type alias for datetime fields that accept strings for backward compatibility
+# Input: str | datetime.datetime
+# Output (after validation): datetime.datetime
+DateTimeField = Annotated[
+    datetime.datetime,
+    BeforeValidator(_parse_date_string),
+    # This allows str at the type-checker level while ensuring datetime after validation
+]
 
 
 class CmsModule(BaseModel):
@@ -21,28 +101,73 @@ class CmsModuleGroup(CmsModule):
 
 
 class Image(BaseModel):
+    """Represents an image with URL and alternate text.
+
+    Attributes:
+        url: URL path to the image resource
+        alternateText: Descriptive text for accessibility and SEO
+    """
+
     url: str = ""
     alternateText: str = ""
 
 
 class MenuItem(BaseModel):
+    """Represents a navigation menu item.
+
+    Attributes:
+        name: Display name of the menu item
+        url: Target URL for the menu item link
+    """
+
     name: str
     url: str
 
 
 class Comment(BaseModel):
+    """Represents a user comment on a blog post or page.
+
+    Attributes:
+        author: Name of the comment author
+        comment: The comment text content
+        date: Datetime when the comment was posted (timezone-aware recommended)
+    """
+
     author: str
     comment: str
-    date: str  # TODO change its type to datetime
+    date: DateTimeField
 
     @property
     def time_delta(self) -> str:
-        now = datetime.datetime.now()
-        date = datetime.datetime.strptime(self.date.split(".")[0], "%Y-%m-%dT%H:%M:%S")
-        return humanize.naturaltime(now - date)
+        """Calculate human-readable time since the comment was posted.
+
+        Uses timezone-aware datetimes to ensure accurate time delta calculations.
+
+        Returns:
+            Human-friendly time description (e.g., "2 hours ago", "3 days ago")
+        """
+        # self.date is already a datetime object (parsed by field_validator)
+        # Always use timezone-aware datetime for consistency
+        now = datetime.datetime.now(datetime.timezone.utc)
+        return humanize.naturaltime(now - self.date)
 
 
 class Post(BaseModel):
+    """Represents a blog post with metadata, content, and comments.
+
+    Attributes:
+        author: Name of the post author
+        slug: URL-friendly unique identifier for the post
+        title: Post title
+        contentInMarkdown: Post content in Markdown format
+        comments: List of comments on this post
+        excerpt: Short summary or preview of the post
+        tags: List of tags for categorization
+        language: Language code for the post content
+        coverImage: Cover image for the post
+        date: Datetime when the post was published (timezone-aware recommended)
+    """
+
     author: str
     slug: str
     title: str
@@ -52,30 +177,41 @@ class Post(BaseModel):
     tags: list[str]
     language: str
     coverImage: Image
-    date: str
+    date: DateTimeField
+
+    def __lt__(self, other: object) -> bool:
+        """Compare posts by date for sorting.
+
+        Uses datetime comparison to ensure robust and correct ordering.
+
+        Args:
+            other: Another Post instance to compare against
 
-    def __lt__(self, other):
+        Returns:
+            True if this post's date is earlier than the other post's date,
+            or NotImplemented if comparing with a non-Post object
+        """
         if isinstance(other, Post):
             return self.date < other.date
-        raise NotImplementedError("Posts can only be compared with other posts")
+        return NotImplemented
 
 
-Page = Post
+Page = Post  # Page is an alias for Post (static pages use the same structure)
 
 
 class Color(BaseModel):
-    def __init__(self, r: int = 0, g: int = 0, b: int = 0, a: int = 255):
-        if not (0 <= r <= 255):
-            raise ValueError("r must be between 0 and 255")
-        if not (0 <= g <= 255):
-            raise ValueError("g must be between 0 and 255")
-        if not (0 <= b <= 255):
-            raise ValueError("b must be between 0 and 255")
-        if not (0 <= a <= 255):
-            raise ValueError("a must be between 0 and 255")
-        super().__init__(r=r, g=g, b=b, a=a)
-
-    r: int
-    g: int
-    b: int
-    a: int
+    """Represents an RGBA color value.
+
+    Attributes:
+        r: Red component (0-255)
+        g: Green component (0-255)
+        b: Blue component (0-255)
+        a: Alpha/transparency component (0-255, where 255 is fully opaque)
+    """
+
+    r: int = Field(default=0, ge=0, le=255, description="Red component (0-255)")
+    g: int = Field(default=0, ge=0, le=255, description="Green component (0-255)")
+    b: int = Field(default=0, ge=0, le=255, description="Blue component (0-255)")
+    a: int = Field(
+        default=255, ge=0, le=255, description="Alpha component (0-255, where 255 is fully opaque)"
+    )

platzky/platzky.py

@@ -4,6 +4,8 @@ import urllib.parse
 from flask import redirect, render_template, request, session
 from flask_minify import Minify
 from flask_wtf import CSRFProtect
+from werkzeug.exceptions import HTTPException
+from werkzeug.wrappers import Response
 
 from platzky.admin import admin
 from platzky.blog import blog
@@ -11,6 +13,7 @@ from platzky.config import (
     Config,
     languages_dict,
 )
+from platzky.db.db import DB
 from platzky.db.db_loader import get_db
 from platzky.engine import Engine
 from platzky.plugin.plugin_loader import plugify
@@ -24,38 +27,131 @@ _MISSING_OTEL_MSG = (
 )
 
 
-def create_engine(config: Config, db) -> Engine:
+def _url_encode(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 urllib.parse.quote(x, safe="")
+
+
+def _get_language_domain(config: Config, lang: str) -> t.Optional[str]:
+    """Get the domain associated with a language.
+
+    Args:
+        config: Application configuration
+        lang: Language code to look up
+
+    Returns:
+        Domain string if language has a dedicated domain, None otherwise
+    """
+    lang_cfg = config.languages.get(lang)
+    if lang_cfg is None:
+        return None
+    return lang_cfg.domain
+
+
+def _get_safe_redirect_url(referrer: t.Optional[str], current_host: str) -> str:
+    """Get a safe redirect URL by validating the referrer.
+
+    Prevents open redirect vulnerabilities by only allowing same-host redirects.
+
+    Args:
+        referrer: The HTTP referrer header value
+        current_host: The current request host
+
+    Returns:
+        The referrer URL if safe, otherwise "/"
+    """
+    if not referrer:
+        return "/"
+
+    referrer_parsed = urllib.parse.urlparse(referrer)
+    # Only redirect to referrer if it's from the same host
+    if referrer_parsed.netloc == current_host:
+        return referrer
+    return "/"
+
+
+def create_engine(config: Config, db: DB) -> Engine:
+    """Create and configure a Platzky Engine instance.
+
+    Sets up the core application with database connection, request handlers,
+    route definitions, and context processors for template rendering.
+
+    Args:
+        config: Application configuration object
+        db: Database instance for data persistence
+
+    Returns:
+        Configured Engine instance with plugins loaded
+    """
     app = Engine(config, db, __name__)
 
     @app.before_request
-    def handle_www_redirection():
+    def handle_www_redirection() -> t.Optional[Response]:
+        """Handle WWW subdomain redirection based on configuration.
+
+        Redirects requests to/from www subdomain based on config.use_www setting.
+
+        Returns:
+            Redirect response if redirection is needed, None otherwise
+        """
         if config.use_www:
             return redirect_nonwww_to_www()
-        else:
-            return redirect_www_to_nonwww()
-
-    def get_langs_domain(lang: str) -> t.Optional[str]:
-        lang_cfg = config.languages.get(lang)
-        if lang_cfg is None:
-            return None
-        return lang_cfg.domain
+        return redirect_www_to_nonwww()
 
     @app.route("/lang/<string:lang>", methods=["GET"])
-    def change_language(lang):
-        if new_domain := get_langs_domain(lang):
-            return redirect("http://" + new_domain, code=301)
-        else:
-            session["language"] = lang
-            return redirect(request.referrer)
+    def change_language(lang: str) -> Response | tuple[str, int]:
+        """Change the user's language preference.
+
+        If the language has a dedicated domain, redirects to that domain.
+        Otherwise, sets the language in the session and returns to the referrer.
+
+        Args:
+            lang: Language code to switch to
+
+        Returns:
+            Redirect response to the language domain or referrer page, or 404 if invalid
+        """
+        # Only allow configured languages
+        if lang not in config.languages:
+            return render_template("404.html", title="404"), 404
+
+        if new_domain := _get_language_domain(config, lang):
+            return redirect(f"{request.scheme}://{new_domain}", code=302)
+
+        session["language"] = lang
+        redirect_url = _get_safe_redirect_url(request.referrer, request.host)
+        return redirect(redirect_url)
 
     def url_link(x: str) -> str:
-        return urllib.parse.quote(x, safe="")
+        """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():
+    def utils() -> dict[str, t.Any]:
+        """Provide utility variables and functions to all templates.
+
+        Returns:
+            Dictionary of template context variables including app metadata,
+            language settings, styling configuration, and helper functions
+        """
         locale = app.get_locale()
-        flag = lang.flag if (lang := config.languages.get(locale)) is not None else ""
-        country = lang.country if (lang := config.languages.get(locale)) is not None else ""
+        lang = config.languages.get(locale)
+        flag = lang.flag if lang is not None else ""
+        country = lang.country if lang is not None else ""
         return {
             "app_name": config.app_name,
             "app_description": app.db.get_app_description(locale) or config.app_name,
@@ -73,21 +169,55 @@ def create_engine(config: Config, db) -> Engine:
         }
 
     @app.context_processor
-    def dynamic_body():
+    def dynamic_body() -> dict[str, str]:
+        """Provide dynamic body content to all templates.
+
+        Returns:
+            Dictionary with dynamic_body content for injection into page body
+        """
         return {"dynamic_body": app.dynamic_body}
 
     @app.context_processor
-    def dynamic_head():
+    def dynamic_head() -> dict[str, str]:
+        """Provide dynamic head content to all templates.
+
+        Returns:
+            Dictionary with dynamic_head content for injection into page head
+        """
         return {"dynamic_head": app.dynamic_head}
 
     @app.errorhandler(404)
-    def page_not_found(e):
+    def page_not_found(_e: HTTPException) -> tuple[str, int]:
+        """Handle 404 Not Found errors.
+
+        Args:
+            _e: HTTPException object containing error details (unused)
+
+        Returns:
+            Tuple of rendered 404 template and HTTP 404 status code
+        """
         return render_template("404.html", title="404"), 404
 
     return plugify(app)
 
 
 def create_app_from_config(config: Config) -> Engine:
+    """Create a fully configured Platzky application from a Config object.
+
+    Initializes the database, creates the engine, sets up telemetry (if enabled),
+    registers blueprints (admin, blog, SEO), and configures minification and CSRF
+    protection.
+
+    Args:
+        config: Application configuration object
+
+    Returns:
+        Fully configured Engine instance ready to serve requests
+
+    Raises:
+        ImportError: If telemetry is enabled but OpenTelemetry packages are not installed
+        ValueError: If telemetry configuration is invalid
+    """
     db = get_db(config.db)
     engine = create_engine(config, db)
 
@@ -133,5 +263,21 @@ def create_app_from_config(config: Config) -> Engine:
 
 
 def create_app(config_path: str) -> Engine:
+    """Create a Platzky application from a YAML configuration file.
+
+    Convenience function that loads configuration from a YAML file and
+    creates the application.
+
+    Args:
+        config_path: Path to the YAML configuration file
+
+    Returns:
+        Fully configured Engine instance ready to serve requests
+
+    Raises:
+        FileNotFoundError: If the configuration file doesn't exist
+        yaml.YAMLError: If the configuration file contains invalid YAML
+        ValidationError: If the configuration doesn't match the expected schema
+    """
     config = Config.parse_yaml(config_path)
     return create_app_from_config(config)

platzky/plugin/plugin.py

@@ -1,6 +1,9 @@
+import inspect
 import logging
+import os
+import types
 from abc import ABC, abstractmethod
-from typing import Any, Dict, Generic, Type, TypeVar
+from typing import Any, Generic, Optional, TypeVar
 
 from pydantic import BaseModel, ConfigDict
 
@@ -39,17 +42,50 @@ class PluginBase(Generic[T], ABC):
     Plugin developers must extend this class to implement their plugins.
     """
 
+    @staticmethod
+    def get_locale_dir_from_module(plugin_module: types.ModuleType) -> Optional[str]:
+        """Get plugin locale directory from a module.
+
+        Encapsulates the knowledge of how plugins organize their locale directories.
+
+        Args:
+            plugin_module: The plugin module
+
+        Returns:
+            Path to the locale directory if it exists, None otherwise
+        """
+        if not hasattr(plugin_module, "__file__") or plugin_module.__file__ is None:
+            return None
+
+        # Use realpath to resolve symlinks and get canonical path
+        plugin_dir = os.path.dirname(os.path.realpath(plugin_module.__file__))
+        locale_dir = os.path.join(plugin_dir, "locale")
+
+        return locale_dir if os.path.isdir(locale_dir) else None
+
     @classmethod
-    def get_config_model(cls) -> Type[PluginBaseConfig]:
+    def get_config_model(cls) -> type[PluginBaseConfig]:
         return PluginBaseConfig
 
-    def __init__(self, config: Dict[str, Any]):
+    def __init__(self, config: dict[str, Any]) -> None:
         try:
             config_class = self.get_config_model()
             self.config = config_class.model_validate(config)
         except Exception as e:
             raise ConfigPluginError(f"Invalid configuration: {e}") from e
 
+    def get_locale_dir(self) -> Optional[str]:
+        """Get this plugin's locale directory.
+
+        Returns:
+            Path to the locale directory if it exists, None otherwise
+        """
+        module = inspect.getmodule(self.__class__)
+        if module is None:
+            return None
+
+        return self.get_locale_dir_from_module(module)
+
     @abstractmethod
     def process(self, app: PlatzkyEngine) -> PlatzkyEngine:
         """Process the plugin with the given app.

platzky/plugin/plugin_loader.py

@@ -1,6 +1,7 @@
 import importlib.util
 import inspect
 import logging
+import os
 from typing import Any, Optional, Type
 
 import deprecation
@@ -49,24 +50,114 @@ def _is_class_plugin(plugin_module: Any) -> Optional[Type[PluginBase[Any]]]:
 
 
 @deprecation.deprecated(
-    deprecated_in="0.3.1",
-    removed_in="0.4.0",
-    current_version=None,  # You should replace this with the current version
-    details="Legacy plugin style using the entrypoint process() function is deprecated. "
-    "Please migrate to the PluginBase interface.",
+    deprecated_in="1.2.0",
+    removed_in="2.0.0",
+    current_version="1.2.0",
+    details=(
+        "Legacy plugin style using the entrypoint process() function is deprecated. "
+        "Migrate to PluginBase to support plugin translations and other features. "
+        "See: https://platzky.readthedocs.io/en/latest/plugins.html"
+    ),
 )
-def _process_legacy_plugin(plugin_module, app, plugin_config, plugin_name):
-    """Process a legacy plugin using the entrypoint approach."""
+def _process_legacy_plugin(
+    plugin_module: Any, app: Engine, plugin_config: dict[str, Any], plugin_name: str
+) -> Engine:
+    """Process a legacy plugin using the entrypoint approach.
+
+    DEPRECATED: This function will be removed in version 2.0.0.
+    Please migrate your plugin to extend PluginBase.
+
+    Args:
+        plugin_module: The plugin module
+        app: The Platzky Engine instance
+        plugin_config: Plugin configuration dictionary
+        plugin_name: Name of the plugin
+
+    Returns:
+        Platzky Engine with processed plugin
+    """
     app = plugin_module.process(app, plugin_config)
-    logger.info(f"Processed legacy plugin: {plugin_name}")
+    logger.warning(
+        "Plugin '%s' uses deprecated legacy interface. "
+        "This will be removed in version 2.0.0. "
+        "Migrate to PluginBase: https://platzky.readthedocs.io/",
+        plugin_name,
+    )
     return app
 
 
+def _is_safe_locale_dir(locale_dir: str, plugin_instance: PluginBase[Any]) -> bool:
+    """Validate that a locale directory is safe to use.
+
+    Prevents malicious plugins from exposing arbitrary filesystem paths
+    by ensuring the locale directory is within the plugin's module directory.
+
+    Args:
+        locale_dir: Path to the locale directory
+        plugin_instance: The plugin instance
+
+    Returns:
+        True if the locale directory is safe to use, False otherwise
+    """
+    if not os.path.isdir(locale_dir):
+        return False
+
+    module = inspect.getmodule(plugin_instance.__class__)
+    if module is None or not hasattr(module, "__file__") or module.__file__ is None:
+        return False
+
+    normalized_path = os.path.normpath(locale_dir)
+    if ".." in normalized_path.split(os.sep):
+        logger.warning("Rejected locale path with .. components: %s", locale_dir)
+        return False
+
+    # Get canonical paths (resolve symlinks)
+    locale_path = os.path.realpath(locale_dir)
+    module_path = os.path.realpath(os.path.dirname(module.__file__))
+
+    if not locale_path.startswith(module_path + os.sep):
+        if locale_path != module_path:
+            return False
+
+    return True
+
+
+def _register_plugin_locale(
+    app: Engine, plugin_instance: PluginBase[Any], plugin_name: str
+) -> None:
+    """Register plugin's locale directory with Babel if it exists.
+
+    Args:
+        app: The Platzky Engine instance
+        plugin_instance: The plugin instance
+        plugin_name: Name of the plugin for logging
+    """
+    locale_dir = plugin_instance.get_locale_dir()
+    if locale_dir is None:
+        return
+
+    # Validate that the locale directory is safe to use
+    if not _is_safe_locale_dir(locale_dir, plugin_instance):
+        logger.warning(
+            "Skipping locale directory for plugin %s: path validation failed: %s",
+            plugin_name,
+            locale_dir,
+        )
+        return
+
+    babel_config = app.extensions.get("babel")
+    if babel_config and locale_dir not in babel_config.translation_directories:
+        babel_config.translation_directories.append(locale_dir)
+        logger.info("Registered locale directory for plugin %s: %s", plugin_name, locale_dir)
+
+
 def plugify(app: Engine) -> Engine:
     """Load plugins and run their entrypoints.
 
     Supports both class-based plugins (PluginBase) and legacy entrypoint plugins.
 
+    Legacy plugin support is deprecated and will be removed in version 2.0.0.
+
     Args:
         app: Platzky Engine instance
 
@@ -91,8 +182,9 @@ def plugify(app: Engine) -> Engine:
             if plugin_class:
                 # Handle new class-based plugins
                 plugin_instance = plugin_class(plugin_config)
+                _register_plugin_locale(app, plugin_instance, plugin_name)
                 app = plugin_instance.process(app)
-                logger.info(f"Processed class-based plugin: {plugin_name}")
+                logger.info("Processed class-based plugin: %s", plugin_name)
             elif hasattr(plugin_module, "process"):
                 # Handle legacy entrypoint plugins with deprecation warning
                 app = _process_legacy_plugin(plugin_module, app, plugin_config, plugin_name)
@@ -102,8 +194,11 @@ def plugify(app: Engine) -> Engine:
                     f"or provide a process() function"
                 )
 
+        except PluginError:
+            # Re-raise PluginError directly to avoid redundant wrapping
+            raise
         except Exception as e:
-            logger.error(f"Error processing plugin {plugin_name}: {e}")
+            logger.exception("Error processing plugin %s", plugin_name)
             raise PluginError(f"Error processing plugin {plugin_name}: {e}") from e
 
     return app

platzky/seo/seo.py

@@ -27,7 +27,7 @@ def create_seo_blueprint(db, config: dict[str, t.Any], locale_func: t.Callable[[
             lang
         ):  # TODO add get_list_of_posts for faster getting just list of it
             slug = post.slug
-            datet = post.date.split("T")[0]
+            datet = post.date.date().isoformat()
             url = {"loc": f"{host_base}{blog_prefix}/{slug}", "lastmod": datet}
             dynamic_urls.append(url)
         return dynamic_urls

platzky/telemetry.py

@@ -22,6 +22,7 @@ def setup_telemetry(app: "Engine", telemetry_config: TelemetryConfig) -> Optiona
 
     Configures and initializes OpenTelemetry tracing with OTLP and/or console exporters.
     Automatically instruments Flask to capture HTTP requests and trace information.
+    Optionally instruments logging to add trace context to log records.
 
     Args:
         app: Engine instance (Flask-based application)
@@ -51,6 +52,7 @@ def setup_telemetry(app: "Engine", telemetry_config: TelemetryConfig) -> Optiona
     from opentelemetry import trace
     from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
     from opentelemetry.instrumentation.flask import FlaskInstrumentor
+    from opentelemetry.instrumentation.logging import LoggingInstrumentor
     from opentelemetry.sdk.resources import Resource
     from opentelemetry.sdk.trace import TracerProvider
     from opentelemetry.sdk.trace.export import (
@@ -107,6 +109,13 @@ def setup_telemetry(app: "Engine", telemetry_config: TelemetryConfig) -> Optiona
 
     trace.set_tracer_provider(provider)
     FlaskInstrumentor().instrument_app(app)
+
+    # Instrument logging to add trace context to log records
+    # Note: set_logging_format=False to avoid modifying existing log formats
+    # Users can access trace context in their custom formatters via log record attributes
+    if telemetry_config.instrument_logging:
+        LoggingInstrumentor().instrument(set_logging_format=False)
+
     app.telemetry_instrumented = True
 
     # Optionally flush spans after each request (may impact latency)

{platzky-1.0.0.dist-info → platzky-1.1.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: platzky
-Version: 1.0.0
+Version: 1.1.0
 Summary: Not only blog engine
 License: MIT
 License-File: LICENSE
@@ -28,6 +28,7 @@ Requires-Dist: myst-parser (>=4.0.0,<5.0.0) ; extra == "docs"
 Requires-Dist: opentelemetry-api (>=1.27.0,<2.0.0) ; extra == "telemetry"
 Requires-Dist: opentelemetry-exporter-otlp-proto-grpc (>=1.27.0,<2.0.0) ; extra == "telemetry"
 Requires-Dist: opentelemetry-instrumentation-flask (>=0.48b0,<0.49) ; extra == "telemetry"
+Requires-Dist: opentelemetry-instrumentation-logging (>=0.48b0,<0.49) ; extra == "telemetry"
 Requires-Dist: opentelemetry-sdk (>=1.27.0,<2.0.0) ; extra == "telemetry"
 Requires-Dist: pydantic (>=2.7.1,<3.0.0)
 Requires-Dist: pygithub (>=2.6.1,<3.0.0)

{platzky-1.0.0.dist-info → platzky-1.1.0.dist-info}/RECORD

@@ -1,34 +1,34 @@
 platzky/__init__.py,sha256=IhL91rSWxIIJQNfVsqJ1d4yY5D2WyWcefo4Xv2aX_lo,180
 platzky/admin/admin.py,sha256=PlwAXaR_YaM07knB88D33vNe6vCpJXOfuxpCaGnHQlY,1028
-platzky/admin/fake_login.py,sha256=tGsdofPyI3P65pol_3Nbj5075xjA_CU090brnBVNjxg,3480
+platzky/admin/fake_login.py,sha256=YkWS-WD5hb-ClVMPO4vJA4Lt2teT9_xkTXQXzubwMdA,3507
 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
 platzky/blog/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-platzky/blog/blog.py,sha256=L9IYWxnLo1v1h_wLF-0HyG1Y4RSGg7maEMnYxhTgG5Y,2971
+platzky/blog/blog.py,sha256=YMbLLxza_bhL5wIoqklzhko4Ov9vXLibPHbv8XK1ueA,3600
 platzky/blog/comment_form.py,sha256=4lkNJ_S_2DZmJBbz-NPDqahvy2Zz5AGNH2spFeGIop4,513
-platzky/config.py,sha256=N5cQjV8Jh_fETw9jXE-UOcC-bSlC3l_04yMMtRwXKXw,7365
+platzky/config.py,sha256=NFnW-cjieWgER-uRko1Hbuh6cyGKCFQcq6ihDNSyjQk,7529
 platzky/db/README.md,sha256=IO-LoDsd4dLBZenaz423EZjvEOQu_8m2OC0G7du170w,1753
 platzky/db/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-platzky/db/db.py,sha256=0h5rGCBO_N1wBqJRl5EoiW_bFDpNIvmNwuA0hJi89jw,3060
+platzky/db/db.py,sha256=-rwNDBPV_2fswIyQeecahjLSLkt5n0BYGnTUxGzGTio,3087
 platzky/db/db_loader.py,sha256=CuEiXxhIa4bFMm0vi7ugzm7j3WycilGRKCU6smgIImE,905
 platzky/db/github_json_db.py,sha256=G1GBIomeKOCeG05pA4qccaFntiGzkgyEMQJz_FQlvNY,2185
 platzky/db/google_json_db.py,sha256=rS__UEK7ed71htTg066_vzpg0etTlpke6YkcrAQ3Fgk,1325
 platzky/db/graph_ql_db.py,sha256=af6yy1R27YO8N9zJWU7VgU7optRgpdk_1ZUtab_1eT4,8967
-platzky/db/json_db.py,sha256=NUBPy4jt-y37TYq4SCGaSgief3MbBWL_Efw8Bxp8Jo0,4046
+platzky/db/json_db.py,sha256=URsUykJc1-f5J3Uk64KeKki9Fdok_Be-XqmuhmAfJXE,4488
 platzky/db/json_file_db.py,sha256=tPo92n5zG7vGpunn5vl66zISHBziQdxBttitvc5hPug,1030
 platzky/db/mongodb_db.py,sha256=28KO8XmTEiqE7FcNBzw_pfxOy6Vo-T7qsHdUlh59QX0,5174
-platzky/engine.py,sha256=0bxKzfK83ic-VNlKcDut_84_u5EmY2baU5JcJsleUoM,5461
+platzky/engine.py,sha256=hSkatp5EC8yKjY_mXkvbVrBnlabvlmcygle_OMzBc_o,5469
 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=DZZgKW2Q3fY2GMdikFUmAgpsRqT5VKAOwP6RmEsmO2M,1871
-platzky/platzky.py,sha256=8mTqdYqRKONv2oGvQF5Y0fuOomH7ZFYvXtxc7ZohBLE,4585
-platzky/plugin/plugin.py,sha256=tV8aobIzMDJe1frKUAi4kLbrTAIS0FWE3oYpktSo6Ug,1633
-platzky/plugin/plugin_loader.py,sha256=MeQ8LNbrOomwXgc1ISHuyhjZd2mzYKen70eDShWs-Co,3497
-platzky/seo/seo.py,sha256=N_MmAA4KJZmmrDUh0hYNtD8ycOwpNKow4gVSAv8V3N4,2631
+platzky/models.py,sha256=Z372NhIhZcJ92DLPlOq44gTu8XqVcw05SOeJ1BaU7zE,6767
+platzky/platzky.py,sha256=1LKYq8pLm1QBlOcEPhugxWi8W0vuWqjjINIFK8b2Kow,9319
+platzky/plugin/plugin.py,sha256=KZb6VEph__lx9xrv5Ay4h4XkFFYbodV5OimaG6B9IDc,2812
+platzky/plugin/plugin_loader.py,sha256=1bhFQbOu_OKJr4ayth9-x4HMHi8eP96EO1ZQwQ57x0o,6657
+platzky/seo/seo.py,sha256=pw7yrhZFQwWR6Ec7_j45JwQAkwAYBGBiQ4NKIB97bHY,2636
 platzky/static/blog.css,sha256=TrppzgQbj4UtuTufDCdblyNTVAqgIbhD66Cziyv_xnY,7893
 platzky/static/styles.css,sha256=U5ddGIK-VcGRJZ3BdOpMp0pR__k6rNEMsuQXkP4tFQ0,686
-platzky/telemetry.py,sha256=NQuueK-uwZDdnpWaOTFSMvzRWWg6Yu4jPOMPYdMidNY,4524
+platzky/telemetry.py,sha256=iXYvEt0Uw5Hx8lAxyr45dpQ_SiE2NxmJkoSx-JSRJyM,5011
 platzky/templates/404.html,sha256=EheoLSWylOscLH8FmcMA4c6Jw14i5HkSvE_GXzGIrUo,78
 platzky/templates/base.html,sha256=clvWlVOxNLqSQxBpPao3qnKKzkU2q48Apf1WbHJgYfE,4003
 platzky/templates/blog.html,sha256=aPl-DzLX85bHv7tN8UjlABR086PUJ9IGlGbIBioFHGA,1281
@@ -41,7 +41,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.0.0.dist-info/METADATA,sha256=NSQ3OIyrJ4NQsdu3QRIo-c4jQQ9mM0HoqwmQK2EPvKc,2463
-platzky-1.0.0.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
-platzky-1.0.0.dist-info/licenses/LICENSE,sha256=wCdfk-qEosi6BDwiBulMfKMi0hxp1UXV0DdjLrRm788,1077
-platzky-1.0.0.dist-info/RECORD,,
+platzky-1.1.0.dist-info/METADATA,sha256=gunNzvqEk_vWisK0fPkYaS4D625Pn89HV8QQeezaIc8,2556
+platzky-1.1.0.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
+platzky-1.1.0.dist-info/licenses/LICENSE,sha256=wCdfk-qEosi6BDwiBulMfKMi0hxp1UXV0DdjLrRm788,1077
+platzky-1.1.0.dist-info/RECORD,,