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

platzky/admin/admin.py

@@ -1,14 +1,24 @@
+"""Blueprint for admin panel functionality."""
+
+from collections.abc import Callable
 from os.path import dirname
 
 from flask import Blueprint, render_template, session
 
+from platzky.models import CmsModule
+
 
-def create_admin_blueprint(login_methods, cms_modules):
+def create_admin_blueprint(
+    login_methods: list[Callable[[], str]], cms_modules: list[CmsModule]
+) -> Blueprint:
     """Create admin blueprint with dynamic module routes.
 
     Args:
         login_methods: Available login methods
         cms_modules: List of CMS modules to register routes for
+
+    Returns:
+        Configured Flask Blueprint for admin panel
     """
     # …rest of the function…
     admin = Blueprint(
@@ -21,12 +31,24 @@ def create_admin_blueprint(login_methods, cms_modules):
     for module in cms_modules:
 
         @admin.route(f"/module/{module.slug}", methods=["GET"])
-        def module_route(module=module):
+        def module_route(module: CmsModule = module) -> str:
+            """Render a CMS module page.
 
+            Args:
+                module: CMS module object containing template and configuration
+
+            Returns:
+                Rendered HTML template for the module
+            """
             return render_template(module.template, module=module)
 
     @admin.route("/", methods=["GET"])
-    def admin_panel_home():
+    def admin_panel_home() -> str:
+        """Display admin panel home or login page.
+
+        Returns:
+            Rendered login page if not authenticated, admin panel if authenticated
+        """
         user = session.get("user", None)
 
         if not user:

platzky/admin/fake_login.py

@@ -6,11 +6,12 @@ environments as it bypasses proper authentication and authorization controls.
 """
 
 import os
-from typing import Any, Callable
+from collections.abc import Callable
 
 from flask import Blueprint, flash, redirect, render_template_string, session, url_for
 from flask_wtf import FlaskForm
 from markupsafe import Markup
+from werkzeug.wrappers import Response
 
 ROLE_ADMIN = "admin"
 ROLE_NONADMIN = "nonadmin"
@@ -89,7 +90,7 @@ def setup_fake_login_routes(admin_blueprint: Blueprint) -> Blueprint:
         )
 
     @admin_blueprint.route("/fake-login/<role>", methods=["POST"])
-    def handle_fake_login(role: str) -> Any:
+    def handle_fake_login(role: str) -> Response:
         form = FakeLoginForm()
         if form.validate_on_submit() and role in VALID_ROLES:
             if role == ROLE_ADMIN:

platzky/blog/blog.py

@@ -1,12 +1,36 @@
+"""Blueprint for blog functionality including posts, pages, and comments."""
+
+import logging
+from collections.abc import Callable
 from os.path import dirname
+from typing import TypeVar
 
-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 platzky.db.db import DB
+from platzky.models import Page, Post
 
 from . import comment_form
 
+ContentType = TypeVar("ContentType", Post, Page)
+
+logger = logging.getLogger(__name__)
+
 
-def create_blog_blueprint(db, blog_prefix: str, locale_func):
+def create_blog_blueprint(db: DB, blog_prefix: str, locale_func: Callable[[], str]) -> Blueprint:
+    """Create and configure the blog blueprint with all routes and handlers.
+
+    Args:
+        db: Database instance for accessing blog content
+        blog_prefix: URL prefix for blog routes
+        locale_func: Function that returns the current locale/language code
+
+    Returns:
+        Configured Flask Blueprint for blog functionality
+    """
     url_prefix = blog_prefix
     blog = Blueprint(
         "blog",
@@ -16,31 +40,65 @@ def create_blog_blueprint(db, blog_prefix: str, locale_func):
     )
 
     @blog.app_template_filter()
-    def markdown(text):
+    def markdown(text: str) -> Markup:
+        """Template filter to render markdown text as safe HTML.
+
+        Args:
+            text: Markdown text to be rendered
+
+        Returns:
+            Markup object containing safe HTML
+        """
         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:
+        """Display all blog posts for the current language.
+
+        Returns:
+            Rendered HTML template with all blog posts
+        """
         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:
+        """Generate RSS/Atom feed for blog posts.
+
+        Returns:
+            XML response containing the RSS/Atom feed
+        """
         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:
+        """Handle comment submission for a blog post.
+
+        Args:
+            post_slug: URL slug of the blog post
+
+        Returns:
+            Rendered HTML template of the blog post with new comment
+        """
         comment = request.form.to_dict()
         db.add_comment(
             post_slug=post_slug,
@@ -49,40 +107,71 @@ 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], ContentType],
+        slug: str,
+    ) -> ContentType:
+        """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:
+        """Display a single blog post with comments.
+
+        Args:
+            post_slug: URL slug of the blog post
+
+        Returns:
+            Rendered HTML template of the blog post
+        """
+        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:
+        """Display a static page.
+
+        Args:
+            page_slug: URL slug of the page
+
+        Returns:
+            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
+        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:
+        """Display all blog posts with a specific tag.
+
+        Args:
+            tag: Tag name to filter posts by
+
+        Returns:
+            Rendered HTML template with filtered blog posts
+        """
         lang = locale_func()
         posts = db.get_posts_by_tag(tag, lang)
         return render_template("blog.html", posts=posts, subtitle=f" - tag: {tag}")

platzky/blog/comment_form.py

@@ -1,3 +1,5 @@
+"""Form for blog post comments."""
+
 from flask_babel import lazy_gettext
 from flask_wtf import FlaskForm
 from wtforms import StringField, SubmitField
@@ -6,6 +8,14 @@ from wtforms.widgets import TextArea
 
 
 class CommentForm(FlaskForm):
+    """Form for submitting comments on blog posts.
+
+    Attributes:
+        author_name: Required text field for the commenter's name.
+        comment: Required text area for the comment content.
+        submit: Submit button to post the comment.
+    """
+
     author_name = StringField(str(lazy_gettext("Name")), validators=[DataRequired()])
     comment = StringField(
         str(lazy_gettext("Type comment here")),

platzky/config.py

@@ -165,7 +165,7 @@ class Config(StrictBaseModel):
     @classmethod
     def model_validate(
         cls,
-        obj: t.Any,
+        obj: dict[str, t.Any],
         *,
         strict: bool | None = None,
         from_attributes: bool | None = None,

platzky/db/db.py

@@ -1,6 +1,9 @@
+"""Abstract base classes for database implementations."""
+
 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
 
@@ -8,6 +11,8 @@ from platzky.models import MenuItem, Page, Post
 
 
 class DB(ABC):
+    """Abstract base class for all database implementations."""
+
     db_name: str = "DB"
     module_name: str = "db"
     config_type: type
@@ -45,55 +50,99 @@ class DB(ABC):
             raise ValueError(f"Failed to extend DB with function {function_name}: {e}")
 
     @abstractmethod
-    def get_app_description(self, lang) -> str:
+    def get_app_description(self, lang: str) -> str:
+        """Retrieve the application description for a specific language.
+
+        Args:
+            lang: Language code (e.g., 'en', 'pl')
+        """
         pass
 
     @abstractmethod
-    def get_all_posts(self, lang) -> list[Post]:
+    def get_all_posts(self, lang: str) -> list[Post]:
+        """Retrieve all posts for a specific language.
+
+        Args:
+            lang: Language code (e.g., 'en', 'pl')
+        """
         pass
 
     @abstractmethod
-    def get_menu_items_in_lang(self, lang) -> list[MenuItem]:
+    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')
+        """
         pass
 
     @abstractmethod
-    def get_post(self, slug) -> Post:
+    def get_post(self, slug: str) -> Post:
+        """Retrieve a single post by its slug.
+
+        Args:
+            slug: URL-friendly identifier for the post
+        """
         pass
 
     @abstractmethod
-    def get_page(self, slug) -> Page:
+    def get_page(self, slug: str) -> Page:
+        """Retrieve a page by its slug.
+
+        Args:
+            slug: URL-friendly identifier for the page
+        """
         pass
 
     @abstractmethod
-    def get_posts_by_tag(self, tag, lang) -> 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')
+        """
         pass
 
     @abstractmethod
-    def add_comment(self, author_name, comment, post_slug) -> None:
+    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
+        """
         pass
 
     @abstractmethod
-    def get_logo_url(self) -> str:  # TODO provide alternative text along with the URL of logo
+    def get_logo_url(self) -> str:  # TODO: Provide alternative text along with the URL of logo
+        """Retrieve the URL of the application logo."""
         pass
 
     @abstractmethod
     def get_favicon_url(self) -> str:
+        """Retrieve the URL of the application favicon."""
         pass
 
     @abstractmethod
     def get_primary_color(self) -> str:
+        """Retrieve the primary color for the application theme."""
         pass
 
     @abstractmethod
     def get_secondary_color(self) -> str:
+        """Retrieve the secondary color for the application theme."""
         pass
 
     @abstractmethod
-    def get_plugins_data(self) -> list[Any]:
+    def get_plugins_data(self) -> list[dict[str, Any]]:
+        """Retrieve configuration data for all plugins."""
         pass
 
     @abstractmethod
     def get_font(self) -> str:
+        """Get the font configuration for the application."""
         pass
 
     @abstractmethod
@@ -107,4 +156,6 @@ class DB(ABC):
 
 
 class DBConfig(BaseModel):
+    """Base configuration class for database connections."""
+
     type: str = Field(alias="TYPE")

platzky/db/db_loader.py

@@ -1,16 +1,19 @@
 import importlib.util
 import os
 import sys
+import types
 from os.path import abspath, dirname
 
+from platzky.db.db import DB, DBConfig
 
-def get_db(db_config):
+
+def get_db(db_config: DBConfig) -> DB:
     db_name = db_config.type
     db = get_db_module(db_name)
     return db.db_from_config(db_config)
 
 
-def get_db_module(db_type):
+def get_db_module(db_type: str) -> types.ModuleType:
     """
     Load db module from db_type
     This function is used to load db module dynamically as it is specified in config file.

platzky/db/github_json_db.py

@@ -1,4 +1,7 @@
+"""GitHub-based JSON database implementation."""
+
 import json
+from typing import Any
 
 import requests
 from github import Github
@@ -8,24 +11,47 @@ from platzky.db.db import DBConfig
 from platzky.db.json_db import Json as JsonDB
 
 
-def db_config_type():
+def db_config_type() -> type["GithubJsonDbConfig"]:
+    """Return the configuration class for GitHub JSON database.
+
+    Returns:
+        GithubJsonDbConfig class
+    """
     return GithubJsonDbConfig
 
 
 class GithubJsonDbConfig(DBConfig):
+    """Configuration for GitHub JSON database connection."""
+
     github_token: str = Field(alias="GITHUB_TOKEN")
     repo_name: str = Field(alias="REPO_NAME")
     path_to_file: str = Field(alias="PATH_TO_FILE")
     branch_name: str = Field(alias="BRANCH_NAME", default="main")
 
 
-def db_from_config(config: GithubJsonDbConfig):
+def db_from_config(config: GithubJsonDbConfig) -> "GithubJsonDb":
+    """Create a GitHub JSON database instance from configuration.
+
+    Args:
+        config: GitHub JSON database configuration
+
+    Returns:
+        Configured GitHub JSON database instance
+    """
     return GithubJsonDb(
         config.github_token, config.repo_name, config.branch_name, config.path_to_file
     )
 
 
-def get_db(config):
+def get_db(config: dict[str, Any]) -> "GithubJsonDb":
+    """Get a GitHub JSON database instance from raw configuration.
+
+    Args:
+        config: Raw configuration dictionary
+
+    Returns:
+        Configured GitHub JSON database instance
+    """
     github_json_db_config = GithubJsonDbConfig.model_validate(config)
     return GithubJsonDb(
         github_json_db_config.github_token,
@@ -36,7 +62,19 @@ def get_db(config):
 
 
 class GithubJsonDb(JsonDB):
-    def __init__(self, github_token: str, repo_name: str, branch_name: str, path_to_file: str):
+    """JSON database stored in a GitHub repository."""
+
+    def __init__(
+        self, github_token: str, repo_name: str, branch_name: str, path_to_file: str
+    ) -> None:
+        """Initialize GitHub JSON database connection.
+
+        Args:
+            github_token: GitHub personal access token
+            repo_name: Full repository name (e.g., 'owner/repo')
+            branch_name: Branch name to read from
+            path_to_file: Path to the JSON file within the repository
+        """
         self.branch_name = branch_name
         self.repo = Github(github_token).get_repo(repo_name)
         self.file_path = path_to_file

platzky/db/google_json_db.py

@@ -1,4 +1,7 @@
+"""Google Cloud Storage-based JSON database implementation."""
+
 import json
+from typing import TYPE_CHECKING, Any
 
 from google.cloud.storage import Client
 from pydantic import Field
@@ -6,38 +9,91 @@ from pydantic import Field
 from platzky.db.db import DBConfig
 from platzky.db.json_db import Json
 
+if TYPE_CHECKING:
+    from google.cloud.storage import Blob
+
 
-def db_config_type():
+def db_config_type() -> type["GoogleJsonDbConfig"]:
+    """Return the configuration class for Google Cloud Storage JSON database.
+
+    Returns:
+        GoogleJsonDbConfig class
+    """
     return GoogleJsonDbConfig
 
 
 class GoogleJsonDbConfig(DBConfig):
+    """Configuration for Google Cloud Storage JSON database connection."""
+
     bucket_name: str = Field(alias="BUCKET_NAME")
     source_blob_name: str = Field(alias="SOURCE_BLOB_NAME")
 
 
-def db_from_config(config: GoogleJsonDbConfig):
+def db_from_config(config: GoogleJsonDbConfig) -> "GoogleJsonDb":
+    """Create a Google Cloud Storage JSON database instance from configuration.
+
+    Args:
+        config: Google Cloud Storage JSON database configuration
+
+    Returns:
+        Configured Google Cloud Storage JSON database instance
+    """
     return GoogleJsonDb(config.bucket_name, config.source_blob_name)
 
 
-def get_db(config):
+def get_db(config: dict[str, Any]) -> "GoogleJsonDb":
+    """Get a Google Cloud Storage JSON database instance from raw configuration.
+
+    Args:
+        config: Raw configuration dictionary
+
+    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)
 
 
-def get_blob(bucket_name, source_blob_name):
+def get_blob(bucket_name: str, source_blob_name: str) -> "Blob":
+    """Retrieve a blob from Google Cloud Storage.
+
+    Args:
+        bucket_name: Name of the GCS bucket
+        source_blob_name: Name of the blob/file in the bucket
+
+    Returns:
+        GCS Blob object
+    """
     storage_client = Client()
     bucket = storage_client.bucket(bucket_name)
     return bucket.blob(source_blob_name)
 
 
-def get_data(blob):
-    raw_data = blob.download_as_text(client=None)
+def get_data(blob: "Blob") -> dict[str, Any]:
+    """Download and parse JSON data from a blob.
+
+    Args:
+        blob: GCS Blob object to download from
+
+    Returns:
+        Parsed JSON data as dictionary
+    """
+    raw_data = (
+        blob.download_as_text()
+    )  # pyright: ignore[reportCallIssue] - Incomplete type stubs for google.cloud.storage Blob
     return json.loads(raw_data)
 
 
 class GoogleJsonDb(Json):
-    def __init__(self, bucket_name, source_blob_name):
+    """JSON database stored in Google Cloud Storage."""
+
+    def __init__(self, bucket_name: str, source_blob_name: str) -> None:
+        """Initialize Google Cloud Storage JSON database connection.
+
+        Args:
+            bucket_name: Name of the GCS bucket
+            source_blob_name: Name of the blob/file in the bucket
+        """
         self.bucket_name = bucket_name
         self.source_blob_name = source_blob_name