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

platzky/db/graph_ql_db.py

@@ -1,5 +1,8 @@
-# TODO rename file, extract it to another library, remove qgl and aiohttp from dependencies
+"""GraphQL-based database implementation for CMS integration."""
 
+# TODO: Rename file, extract to another library, remove gql and aiohttp from dependencies
+
+from typing import Any
 
 from gql import Client, gql
 from gql.transport.aiohttp import AIOHTTPTransport
@@ -7,29 +10,60 @@ from gql.transport.exceptions import TransportQueryError
 from pydantic import Field
 
 from platzky.db.db import DB, DBConfig
-from platzky.models import Post
+from platzky.models import MenuItem, Page, Post
+
 
+def db_config_type() -> type["GraphQlDbConfig"]:
+    """Return the configuration class for GraphQL database.
 
-def db_config_type():
+    Returns:
+        GraphQlDbConfig class
+    """
     return GraphQlDbConfig
 
 
 class GraphQlDbConfig(DBConfig):
+    """Configuration for GraphQL database connection."""
+
     endpoint: str = Field(alias="CMS_ENDPOINT")
     token: str = Field(alias="CMS_TOKEN")
 
 
-def get_db(config: GraphQlDbConfig):
+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):
+def db_from_config(config: GraphQlDbConfig) -> "GraphQL":
+    """Create a GraphQL database instance from configuration.
+
+    Args:
+        config: GraphQL database configuration
+
+    Returns:
+        Configured GraphQL database instance
+    """
     return GraphQL(config.endpoint, config.token)
 
 
-def _standarize_comment(
-    comment,
-):
+def _standardize_comment(
+    comment: dict[str, Any],
+) -> dict[str, Any]:
+    """Standardize comment data structure from GraphQL response.
+
+    Args:
+        comment: Raw comment data from GraphQL response
+
+    Returns:
+        Standardized comment dictionary
+    """
     return {
         "author": comment["author"],
         "comment": comment["comment"],
@@ -37,14 +71,22 @@ def _standarize_comment(
     }
 
 
-def _standarize_post(post):
+def _standardize_post(post: dict[str, Any]) -> dict[str, Any]:
+    """Standardize post data structure from GraphQL response.
+
+    Args:
+        post: Raw post data from GraphQL response
+
+    Returns:
+        Standardized post dictionary
+    """
     return {
         "author": post["author"]["name"],
         "slug": post["slug"],
         "title": post["title"],
         "excerpt": post["excerpt"],
         "contentInMarkdown": post["contentInRichText"]["html"],
-        "comments": [_standarize_comment(comment) for comment in post["comments"]],
+        "comments": [_standardize_comment(comment) for comment in post["comments"]],
         "tags": post["tags"],
         "language": post["language"],
         "coverImage": {
@@ -54,8 +96,72 @@ def _standarize_post(post):
     }
 
 
+def _standardize_page(page: dict[str, Any]) -> dict[str, Any]:
+    """Standardize page data structure from GraphQL response.
+
+    Pages have fewer required fields than posts in the GraphQL schema.
+    This function provides sensible defaults for missing Post fields.
+
+    Args:
+        page: Raw page data from GraphQL response
+
+    Returns:
+        Standardized page dictionary compatible with Page model
+    """
+    return {
+        "author": page.get("author", ""),
+        "slug": page.get("slug", ""),
+        "title": page["title"],
+        "excerpt": page.get("excerpt", ""),
+        "contentInMarkdown": page["contentInMarkdown"],
+        "comments": [],
+        "tags": page.get("tags", []),
+        "language": page.get("language", "en"),
+        "coverImage": {
+            "url": page.get("coverImage", {}).get("url", ""),
+        },
+        "date": page.get("date", "1970-01-01"),
+    }
+
+
+def _standardize_post_by_tag(post: dict[str, Any]) -> dict[str, Any]:
+    """Standardize post data from get_posts_by_tag GraphQL response.
+
+    Posts returned by tag query have fewer fields than full posts.
+    This function provides sensible defaults for missing Post fields.
+
+    Args:
+        post: Raw post data from GraphQL get_posts_by_tag response
+
+    Returns:
+        Standardized post dictionary compatible with Post model
+    """
+    return {
+        "author": post.get("author", ""),
+        "slug": post["slug"],
+        "title": post["title"],
+        "excerpt": post["excerpt"],
+        "contentInMarkdown": post.get("contentInMarkdown", ""),
+        "comments": [],
+        "tags": post["tags"],
+        "language": post.get("language", "en"),
+        "coverImage": {
+            "url": post["coverImage"]["image"]["url"],
+        },
+        "date": post["date"],
+    }
+
+
 class GraphQL(DB):
-    def __init__(self, endpoint, token):
+    """GraphQL database implementation for CMS integration."""
+
+    def __init__(self, endpoint: str, token: str) -> None:
+        """Initialize GraphQL database connection.
+
+        Args:
+            endpoint: GraphQL API endpoint URL
+            token: Authentication token for the API
+        """
         self.module_name = "graph_ql_db"
         self.db_name = "GraphQLDb"
         full_token = "bearer " + token
@@ -63,7 +169,15 @@ class GraphQL(DB):
         self.client = Client(transport=transport)
         super().__init__()
 
-    def get_all_posts(self, lang):
+    def get_all_posts(self, lang: str) -> list[Post]:
+        """Retrieve all published posts for a specific language.
+
+        Args:
+            lang: Language code (e.g., 'en', 'pl')
+
+        Returns:
+            List of Post objects
+        """
         all_posts = gql(
             """
             query MyQuery($lang: Lang!) {
@@ -98,9 +212,17 @@ class GraphQL(DB):
         )
         raw_ql_posts = self.client.execute(all_posts, variable_values={"lang": lang})["posts"]
 
-        return [Post.model_validate(_standarize_post(post)) for post in raw_ql_posts]
+        return [Post.model_validate(_standardize_post(post)) for post in raw_ql_posts]
+
+    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')
 
-    def get_menu_items_in_lang(self, lang):
+        Returns:
+            List of MenuItem objects
+        """
         menu_items = []
         try:
             menu_items_with_lang = gql(
@@ -132,9 +254,17 @@ class GraphQL(DB):
             )
             menu_items = self.client.execute(menu_items_without_lang)
 
-        return menu_items["menuItems"]
+        return [MenuItem.model_validate(item) for item in menu_items["menuItems"]]
+
+    def get_post(self, slug: str) -> Post:
+        """Retrieve a single post by its slug.
 
-    def get_post(self, slug):
+        Args:
+            slug: URL-friendly identifier for the post
+
+        Returns:
+            Post object
+        """
         post = gql(
             """
             query MyQuery($slug: String!) {
@@ -169,14 +299,23 @@ class GraphQL(DB):
         )
 
         post_raw = self.client.execute(post, variable_values={"slug": slug})["post"]
-        return Post.model_validate(_standarize_post(post_raw))
+        return Post.model_validate(_standardize_post(post_raw))
 
-    # TODO Cleanup page logic of internationalization (now it depends on translation of slugs)
-    def get_page(self, slug):
-        post = gql(
+    # TODO: Cleanup page logic of internationalization (now it depends on translation of slugs)
+    def get_page(self, slug: str) -> Page:
+        """Retrieve a page by its slug.
+
+        Args:
+            slug: URL-friendly identifier for the page
+
+        Returns:
+            Page object
+        """
+        page_query = gql(
             """
             query MyQuery ($slug: String!){
               page(where: {slug: $slug}, stage: PUBLISHED) {
+                slug
                 title
                 contentInMarkdown
                 coverImage
@@ -187,9 +326,19 @@ class GraphQL(DB):
             }
             """
         )
-        return self.client.execute(post, variable_values={"slug": slug})["page"]
+        page_raw = self.client.execute(page_query, variable_values={"slug": slug})["page"]
+        return Page.model_validate(_standardize_page(page_raw))
+
+    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')
 
-    def get_posts_by_tag(self, tag, lang):
+        Returns:
+            List of Post objects
+        """
         post = gql(
             """
             query MyQuery ($tag: String!, $lang: Lang!){
@@ -209,9 +358,17 @@ class GraphQL(DB):
             }
             """
         )
-        return self.client.execute(post, variable_values={"tag": tag, "lang": lang})["posts"]
+        raw_posts = self.client.execute(post, variable_values={"tag": tag, "lang": lang})["posts"]
+        return [Post.model_validate(_standardize_post_by_tag(p)) for p in raw_posts]
+
+    def add_comment(self, author_name: str, comment: str, post_slug: str) -> None:
+        """Add a new comment to a post.
 
-    def add_comment(self, author_name, comment, post_slug):
+        Args:
+            author_name: Name of the comment author
+            comment: Comment text content
+            post_slug: URL-friendly identifier of the post
+        """
         add_comment = gql(
             """
             mutation MyMutation($author: String!, $comment: String!, $slug: String!) {
@@ -236,10 +393,20 @@ class GraphQL(DB):
             },
         )
 
-    def get_font(self):
-        return str("")
+    def get_font(self) -> str:
+        """Get the font configuration for the application.
+
+        Returns:
+            Empty string (not implemented in GraphQL backend)
+        """
+        return ""
+
+    def get_logo_url(self) -> str:
+        """Retrieve the URL of the application logo.
 
-    def get_logo_url(self):
+        Returns:
+            Logo image URL or empty string if not found
+        """
         logo = gql(
             """
             query myquery {
@@ -259,7 +426,15 @@ class GraphQL(DB):
         except IndexError:
             return ""
 
-    def get_app_description(self, lang):
+    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
+        """
         description_query = gql(
             """
             query myquery($lang: Lang!) {
@@ -272,9 +447,14 @@ class GraphQL(DB):
 
         return self.client.execute(description_query, variable_values={"lang": lang})[
             "applicationSetups"
-        ][0].get("applicationDescription", None)
+        ][0].get("applicationDescription", "")
 
-    def get_favicon_url(self):
+    def get_favicon_url(self) -> str:
+        """Retrieve the URL of the application favicon.
+
+        Returns:
+            Favicon URL
+        """
         favicon = gql(
             """
             query myquery {
@@ -295,7 +475,12 @@ class GraphQL(DB):
     def get_secondary_color(self) -> str:
         return "navy"  # Default color as string
 
-    def get_plugins_data(self):
+    def get_plugins_data(self) -> list[dict[str, Any]]:
+        """Retrieve configuration data for all plugins.
+
+        Returns:
+            List of plugin configuration dictionaries
+        """
         plugins_data = gql(
             """
             query MyQuery {

platzky/db/json_db.py

@@ -1,46 +1,92 @@
+"""In-memory JSON database implementation."""
+
 import datetime
-from typing import Any, Dict
+from typing import Any
 
 from pydantic import Field
 
 from platzky.db.db import DB, DBConfig
-from platzky.models import MenuItem, Post
+from platzky.models import MenuItem, Page, Post
+
 
+def db_config_type() -> type["JsonDbConfig"]:
+    """Return the configuration class for JSON database.
 
-def db_config_type():
+    Returns:
+        JsonDbConfig class
+    """
     return JsonDbConfig
 
 
 class JsonDbConfig(DBConfig):
-    data: Dict[str, Any] = Field(alias="DATA")
+    """Configuration for in-memory JSON database."""
+
+    data: dict[str, Any] = Field(alias="DATA")
+
 
+def get_db(config: dict[str, Any]) -> "Json":
+    """Get a JSON database instance from raw configuration.
 
-def get_db(config):
+    Args:
+        config: Raw configuration dictionary
+
+    Returns:
+        Configured JSON database instance
+    """
     json_db_config = JsonDbConfig.model_validate(config)
     return Json(json_db_config.data)
 
 
-def db_from_config(config: JsonDbConfig):
-    return Json(config.data)
+def db_from_config(config: JsonDbConfig) -> "Json":
+    """Create a JSON database instance from configuration.
 
+    Args:
+        config: JSON database configuration
 
-# TODO make all language specific methods to be available without language
-# this will allow to have a default language and if there is one language
-# there will be no need to pass it to the method or in db
+    Returns:
+        Configured JSON database instance
+    """
+    return Json(config.data)
 
 
+# TODO: Make all language-specific methods available without language parameter.
+# This will allow a default language and if there is one language,
+# there will be no need to pass it to the method or in db.
 class Json(DB):
-    def __init__(self, data: Dict[str, Any]):
+    """In-memory JSON database implementation."""
+
+    def __init__(self, data: dict[str, Any]):
+        """Initialize JSON database with data dictionary.
+
+        Args:
+            data: Dictionary containing all database content
+        """
         super().__init__()
-        self.data: Dict[str, Any] = data
+        self.data: dict[str, Any] = data
         self.module_name = "json_db"
         self.db_name = "JsonDb"
 
-    def get_app_description(self, lang):
+    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
+        """
         description = self._get_site_content().get("app_description", {})
-        return description.get(lang, None)
+        return description.get(lang, "")
+
+    def get_all_posts(self, lang: str) -> list[Post]:
+        """Retrieve all posts for a specific language.
 
-    def get_all_posts(self, lang):
+        Args:
+            lang: Language code (e.g., 'en', 'pl')
+
+        Returns:
+            List of Post objects
+        """
         return [
             Post.model_validate(post)
             for post in self._get_site_content().get("posts", ())
@@ -48,7 +94,17 @@ class Json(DB):
         ]
 
     def get_post(self, slug: str) -> Post:
-        """Returns a post matching the given slug."""
+        """Returns a post matching the given slug.
+
+        Args:
+            slug: URL-friendly identifier for the post
+
+        Returns:
+            Post object
+
+        Raises:
+            ValueError: If posts data is missing or post not found
+        """
         all_posts = self._get_site_content().get("posts")
         if all_posts is None:
             raise ValueError("Posts data is missing")
@@ -57,54 +113,127 @@ class Json(DB):
             raise ValueError(f"Post with slug {slug} not found")
         return Post.model_validate(wanted_post)
 
-    # TODO: add test for non-existing page
-    def get_page(self, slug):
-        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))
+    # TODO: Add test for non-existing page
+    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 pages data is missing or page not found
+        """
+        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)
+        if wanted_page is None:
+            raise ValueError(f"Page with slug {slug} not found")
+        page = Page.model_validate(wanted_page)
         return page
 
-    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')
+
+        Returns:
+            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
 
-    def get_posts_by_tag(self, tag, lang):
-        return (
-            post
+    def get_posts_by_tag(self, tag: str, lang: str) -> list[Post]:
+        """Retrieve posts filtered by tag and language.
+
+        Returns a list of posts, unlike generators which can only be iterated once.
+        """
+        return [
+            Post.model_validate(post)
             for post in self._get_site_content()["posts"]
             if tag in post["tags"] and post["language"] == lang
-        )
+        ]
 
-    def _get_site_content(self):
+    def _get_site_content(self) -> dict[str, Any]:
+        """Get the site content dictionary from data.
+
+        Returns:
+            Site content dictionary
+
+        Raises:
+            ValueError: If site content is not found
+        """
         content = self.data.get("site_content")
         if content is None:
-            raise Exception("Content should not be None")
+            raise ValueError("Content should not be None")
         return content
 
-    def get_logo_url(self):
+    def get_logo_url(self) -> str:
+        """Retrieve the URL of the application logo.
+
+        Returns:
+            Logo image URL or empty string if not found
+        """
         return self._get_site_content().get("logo_url", "")
 
-    def get_favicon_url(self):
+    def get_favicon_url(self) -> str:
+        """Retrieve the URL of the application favicon.
+
+        Returns:
+            Favicon URL or empty string if not found
+        """
         return self._get_site_content().get("favicon_url", "")
 
     def get_font(self) -> str:
+        """Get the font configuration for the application.
+
+        Returns:
+            Font name or empty string if not configured
+        """
         return self._get_site_content().get("font", "")
 
-    def get_primary_color(self):
+    def get_primary_color(self) -> str:
+        """Retrieve the primary color for the application theme.
+
+        Returns:
+            Primary color value, defaults to 'white'
+        """
         return self._get_site_content().get("primary_color", "white")
 
-    def get_secondary_color(self):
+    def get_secondary_color(self) -> str:
+        """Retrieve the secondary color for the application theme.
+
+        Returns:
+            Secondary color value, defaults to 'navy'
+        """
         return self._get_site_content().get("secondary_color", "navy")
 
-    def add_comment(self, author_name, comment, post_slug):
-        comment = {
+    def add_comment(self, author_name: str, comment: str, post_slug: str) -> None:
+        """Add a new comment to a post.
+
+        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.
+
+        Args:
+            author_name: Name of the comment author
+            comment: Comment text content
+            post_slug: URL-friendly identifier of the post
+        """
+        now_utc = datetime.datetime.now(datetime.timezone.utc).isoformat(timespec="seconds")
+
+        comment_data = {
             "author": str(author_name),
             "comment": str(comment),
-            "date": datetime.datetime.now().strftime("%Y-%m-%dT%H:%M:%S"),
+            "date": now_utc,
         }
 
         post_index = next(
@@ -112,9 +241,14 @@ class Json(DB):
             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)
+        self._get_site_content()["posts"][post_index]["comments"].append(comment_data)
+
+    def get_plugins_data(self) -> list[dict[str, Any]]:
+        """Retrieve configuration data for all plugins.
 
-    def get_plugins_data(self):
+        Returns:
+            List of plugin configuration dictionaries
+        """
         return self.data.get("plugins", [])
 
     def health_check(self) -> None: