platzky 1.0.1__py3-none-any.whl → 1.2.0__py3-none-any.whl

platzky/db/json_file_db.py

@@ -1,4 +1,7 @@
+"""Local file-based JSON database implementation."""
+
 import json
+from typing import Any
 
 from pydantic import Field
 
@@ -6,25 +9,55 @@ from platzky.db.db import DBConfig
 from platzky.db.json_db import Json
 
 
-def db_config_type():
+def db_config_type() -> type["JsonFileDbConfig"]:
+    """Return the configuration class for JSON file database.
+
+    Returns:
+        JsonFileDbConfig class
+    """
     return JsonFileDbConfig
 
 
 class JsonFileDbConfig(DBConfig):
+    """Configuration for JSON file database."""
+
     path: str = Field(alias="PATH")
 
 
-def get_db(config):
+def get_db(config: dict[str, Any]) -> "JsonFile":
+    """Get a JSON file database instance from raw configuration.
+
+    Args:
+        config: Raw configuration dictionary
+
+    Returns:
+        Configured JSON file database instance
+    """
     json_file_db_config = JsonFileDbConfig.model_validate(config)
     return JsonFile(json_file_db_config.path)
 
 
-def db_from_config(config: JsonFileDbConfig):
+def db_from_config(config: JsonFileDbConfig) -> "JsonFile":
+    """Create a JSON file database instance from configuration.
+
+    Args:
+        config: JSON file database configuration
+
+    Returns:
+        Configured JSON file database instance
+    """
     return JsonFile(config.path)
 
 
 class JsonFile(Json):
-    def __init__(self, path: str):
+    """JSON database stored in a local file with read/write support."""
+
+    def __init__(self, path: str) -> None:
+        """Initialize JSON file database from a local file path.
+
+        Args:
+            path: Absolute or relative path to the JSON file
+        """
         self.data_file_path = path
         with open(self.data_file_path) as json_file:
             data = json.load(json_file)
@@ -32,10 +65,17 @@ class JsonFile(Json):
         self.module_name = "json_file_db"
         self.db_name = "JsonFileDb"
 
-    def __save_file(self):
+    def __save_file(self) -> None:
         with open(self.data_file_path, "w") as json_file:
             json.dump(self.data, json_file)
 
-    def add_comment(self, author_name, comment, post_slug):
+    def add_comment(self, author_name: str, comment: str, post_slug: str) -> None:
+        """Add a comment to a blog post and persist to file.
+
+        Args:
+            author_name: Name of the comment author
+            comment: Comment text content
+            post_slug: URL-friendly identifier of the post
+        """
         super().add_comment(author_name, comment, post_slug)
         self.__save_file()

platzky/db/mongodb_db.py

@@ -1,3 +1,5 @@
+"""MongoDB database implementation."""
+
 import datetime
 from typing import Any
 
@@ -10,26 +12,57 @@ from platzky.db.db import DB, DBConfig
 from platzky.models import MenuItem, Page, Post
 
 
-def db_config_type():
+def db_config_type() -> type["MongoDbConfig"]:
+    """Return the configuration class for MongoDB database.
+
+    Returns:
+        MongoDbConfig class
+    """
     return MongoDbConfig
 
 
 class MongoDbConfig(DBConfig):
+    """Configuration for MongoDB database connection."""
+
     connection_string: str = Field(alias="CONNECTION_STRING")
     database_name: str = Field(alias="DATABASE_NAME")
 
 
-def get_db(config):
+def get_db(config: dict[str, Any]) -> "MongoDB":
+    """Get a MongoDB database instance from raw configuration.
+
+    Args:
+        config: Raw configuration dictionary
+
+    Returns:
+        Configured MongoDB database instance
+    """
     mongodb_config = MongoDbConfig.model_validate(config)
     return MongoDB(mongodb_config.connection_string, mongodb_config.database_name)
 
 
-def db_from_config(config: MongoDbConfig):
+def db_from_config(config: MongoDbConfig) -> "MongoDB":
+    """Create a MongoDB database instance from configuration.
+
+    Args:
+        config: MongoDB database configuration
+
+    Returns:
+        Configured MongoDB database instance
+    """
     return MongoDB(config.connection_string, config.database_name)
 
 
 class MongoDB(DB):
+    """MongoDB database implementation with connection pooling."""
+
     def __init__(self, connection_string: str, database_name: str):
+        """Initialize MongoDB database connection.
+
+        Args:
+            connection_string: MongoDB connection URI
+            database_name: Name of the database to use
+        """
         super().__init__()
         self.connection_string = connection_string
         self.database_name = database_name
@@ -46,38 +79,103 @@ class MongoDB(DB):
         self.plugins: Collection[Any] = self.db.plugins
 
     def get_app_description(self, lang: str) -> str:
+        """Retrieve the application description for a specific language.
+
+        Args:
+            lang: Language code (e.g., 'en', 'pl')
+
+        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, "")
         return ""
 
     def get_all_posts(self, lang: str) -> list[Post]:
+        """Retrieve all posts for a specific language.
+
+        Args:
+            lang: Language code (e.g., 'en', 'pl')
+
+        Returns:
+            List of Post objects
+        """
         posts_cursor = self.posts.find({"language": lang})
         return [Post.model_validate(post) for post in posts_cursor]
 
     def get_menu_items_in_lang(self, lang: str) -> list[MenuItem]:
+        """Retrieve menu items for a specific language.
+
+        Args:
+            lang: Language code (e.g., 'en', 'pl')
+
+        Returns:
+            List of MenuItem objects
+        """
         menu_items_doc = self.menu_items.find_one({"_id": lang})
         if menu_items_doc and "items" in menu_items_doc:
             return [MenuItem.model_validate(item) for item in menu_items_doc["items"]]
         return []
 
     def get_post(self, slug: str) -> Post:
+        """Retrieve a single post by its slug.
+
+        Args:
+            slug: URL-friendly identifier for the post
+
+        Returns:
+            Post object
+
+        Raises:
+            ValueError: If post not found
+        """
         post_doc = self.posts.find_one({"slug": slug})
         if post_doc is None:
             raise ValueError(f"Post with slug {slug} not found")
         return Post.model_validate(post_doc)
 
     def get_page(self, slug: str) -> Page:
+        """Retrieve a page by its slug.
+
+        Args:
+            slug: URL-friendly identifier for the page
+
+        Returns:
+            Page object
+
+        Raises:
+            ValueError: If page not found
+        """
         page_doc = self.pages.find_one({"slug": slug})
         if page_doc is None:
             raise ValueError(f"Page with slug {slug} not found")
         return Page.model_validate(page_doc)
 
-    def get_posts_by_tag(self, tag: str, lang: str) -> Any:
+    def get_posts_by_tag(self, tag: str, lang: str) -> list[Post]:
+        """Retrieve posts filtered by tag and language.
+
+        Args:
+            tag: Tag name to filter by
+            lang: Language code (e.g., 'en', 'pl')
+
+        Returns:
+            List of Post objects matching the tag and language
+        """
         posts_cursor = self.posts.find({"tags": tag, "language": lang})
-        return posts_cursor
+        return [Post.model_validate(post) for post in posts_cursor]
 
     def add_comment(self, author_name: str, comment: str, post_slug: str) -> None:
+        """Add a new comment to a post.
+
+        Args:
+            author_name: Name of the comment author
+            comment: Comment text content
+            post_slug: URL-friendly identifier of the post
+
+        Raises:
+            ValueError: If post not found
+        """
         now_utc = datetime.datetime.now(datetime.timezone.utc).isoformat(timespec="seconds")
         comment_doc = {
             "author": str(author_name),
@@ -90,36 +188,66 @@ class MongoDB(DB):
             raise ValueError(f"Post with slug {post_slug} not found")
 
     def get_logo_url(self) -> str:
+        """Retrieve the URL of the application logo.
+
+        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 ""
 
     def get_favicon_url(self) -> str:
+        """Retrieve the URL of the application favicon.
+
+        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 ""
 
     def get_primary_color(self) -> str:
+        """Retrieve the primary color for the application theme.
+
+        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"
 
     def get_secondary_color(self) -> str:
+        """Retrieve the secondary color for the application theme.
+
+        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"
 
-    def get_plugins_data(self) -> list[Any]:
+    def get_plugins_data(self) -> list[dict[str, Any]]:
+        """Retrieve configuration data for all plugins.
+
+        Returns:
+            List of plugin configuration dictionaries
+        """
         plugins_doc = self.plugins.find_one({"_id": "config"})
         if plugins_doc and "data" in plugins_doc:
             return plugins_doc["data"]
         return []
 
     def get_font(self) -> str:
+        """Get the font configuration for the application.
+
+        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", "")

platzky/engine.py

@@ -1,16 +1,18 @@
 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
 
 from platzky.config import Config
+from platzky.db.db import DB
 from platzky.models import CmsModule
 
 
 class Engine(Flask):
-    def __init__(self, config: Config, db, import_name):
+    def __init__(self, config: Config, db: DB, import_name: str) -> None:
         super().__init__(import_name)
         self.config.from_mapping(config.model_dump(by_alias=True))
         self.db = db
@@ -18,7 +20,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 +33,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
 
@@ -39,7 +41,7 @@ class Engine(Flask):
         for notifier in self.notifiers:
             notifier(message)
 
-    def add_notifier(self, notifier):
+    def add_notifier(self, notifier: Callable[[str], None]) -> None:
         self.notifiers.append(notifier)
 
     def add_cms_module(self, module: CmsModule):
@@ -47,7 +49,7 @@ class Engine(Flask):
         self.cms_modules.append(module)
 
     # TODO login_method should be interface
-    def add_login_method(self, login_method):
+    def add_login_method(self, login_method: Callable[[], str]) -> None:
         self.login_methods.append(login_method)
 
     def add_dynamic_body(self, body: str):
@@ -94,7 +96,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)"
+    )