API Reference

This part of the documentation covers all the interfaces of Platzky.

Engine

Flask application engine with notification support.

class platzky.engine.Engine(config, db, import_name)[source]

Flask subclass composing database, plugins, notifications, and health checks.

Parameters:
__init__(config, db, import_name)[source]

Initialize the Engine.

Parameters:

  • config (Config) – Application configuration.

  • db (DB) – Database instance.

  • import_name (str) – Name of the application module.

Return type:

None

get_plugins(plugin_type)[source]

Return all registered plugins of the given capability type.

Parameters:

plugin_type (type)

Return type:

list[Any]

get_plugin_infos()[source]

Return PluginInfo metadata for all loaded plugins.

Return type:

list[Any]

notify(message, topic='general', attachments=(), receiver='')[source]

Send a notification to all registered notifiers.

Parameters:

  • message (str) – The notification message text.

  • topic (Literal['security', 'content', 'general']) – Notification topic for routing (default "general").

  • attachments (Sequence[AttachmentProtocol]) – Attachments to include; empty sequence if none.

  • receiver (str) – Target recipient identifier; empty string means broadcast.

Return type:

None

add_notifier(notifier)[source]

Register a simple notifier (message only).

Deprecated: implement NotifierPluginBase instead.

Deprecated since version 1.5.0: This will be removed in 2.0.0. Use NotifierPluginBase subclass instead.

Parameters:

notifier (Notifier)

Return type:

None

add_notifier_with_attachments(notifier)[source]

Register a notifier that supports attachments.

Deprecated: implement NotifierPluginBase instead.

Deprecated since version 1.5.0: This will be removed in 2.0.0. Use NotifierPluginBase subclass instead.

Parameters:

notifier (NotifierWithAttachments)

Return type:

None

transform_content(content, content_type)[source]

Apply all registered content-filter plugins for the given content type.

Checks plugin’s declared accepted_content_types first, then the engine-enforced allowlist set via set_content_transformer_allowlist. Transformers chain their output, so a failing transformer aborts the chain rather than silently passing through partial output to the next stage.

Parameters:

  • content (str)

  • content_type (Literal['post', 'page', 'comment'])

Return type:

str

set_content_transformer_allowlist(plugin, allowed_types)[source]

Register engine-enforced content-type allowlist for a content-transformer plugin.

Empty frozenset blocks all content types. Plugin absent from the allowlist is also blocked. Called by the plugin loader; not intended to be called from plugin code.

Parameters:

  • plugin (ContentTransformerPluginBase)

  • allowed_types (frozenset[Literal['post', 'page', 'comment']])

Return type:

None

register_plugin_capabilities(instance, plugin_name)[source]

Register a plugin instance under all matching capability keys.

Each recognised capability base class becomes a key in self.plugins so the engine can look up e.g. all NotifierPluginBase plugins without knowing concrete types. Plugins that don’t match any capability are stored under PluginBase.

Parameters:

  • instance (PluginBase)

  • plugin_name (str)

Return type:

None

register_plugin_locale(plugin_instance, plugin_name)[source]

Register plugin’s locale directory with Babel if it exists.

Parameters:

  • plugin_instance (PluginBase)

  • plugin_name (str)

Return type:

None

load_plugin(plugin_class, plugin_config, plugin_name, allowed_topics=frozenset({}), allowed_content_types=frozenset({}))[source]

Instantiate and register a class-based plugin. Returns the (possibly replaced) engine.

Parameters:

  • plugin_class (type[PluginBase]) – The plugin class to instantiate.

  • plugin_config (dict[str, Any]) – Configuration dict passed to the plugin constructor.

  • plugin_name (str) – Human-readable name used in log messages.

  • allowed_topics (frozenset[Literal['security', 'content', 'general']]) – Topic allowlist for notifier plugins. Empty frozenset blocks all topics; a non-empty frozenset restricts to those topics.

  • allowed_content_types (frozenset[Literal['post', 'page', 'comment']]) – Content-type allowlist for transformer plugins. Empty frozenset blocks all types; a non-empty frozenset restricts.

Returns:

The (possibly replaced) engine after loading the plugin.

Return type:

Engine

set_notifier_allowlist(plugin, allowed_topics)[source]

Register engine-enforced topic allowlist for a notifier.

Empty frozenset blocks all topics. Plugin absent from the allowlist is also blocked. Called by the plugin loader; not accessible to plugin code.

Parameters:

  • plugin (NotifierPluginBase)

  • allowed_topics (frozenset[Literal['security', 'content', 'general']])

Return type:

None

add_cms_module(module)[source]

Add a CMS module to the modules list.

Parameters:

module (CmsModule)

Return type:

None

add_login_method(login_method)[source]

Register a login method callable.

Parameters:

login_method (Callable[[], str])

Return type:

None

add_dynamic_body(body)[source]

Append HTML to the dynamic body section rendered in templates.

Parameters:

body (str)

Return type:

None

add_dynamic_head(head)[source]

Append HTML to the dynamic head section rendered in templates.

Parameters:

head (str)

Return type:

None

get_locale()[source]

Return the current locale based on session or browser preferences.

Return type:

str

is_enabled(flag)[source]

Check whether a feature flag is enabled.

This is the primary API for flag checks.

Parameters:

flag (FeatureFlag) – A FeatureFlag instance.

Returns:

True if the flag is enabled.

Return type:

bool

add_health_check(name, check_function)[source]

Register a health check function.

Parameters:
Return type:

None

Configuration

Configuration module for Platzky application.

This module defines all configuration models and parsing logic for the application.

class platzky.config.LanguageConfig(*, name, flag, country, domain=None)[source]

Configuration for a single language.

Parameters:
name

Display name of the language

Type:

str

flag

Flag icon code (country code)

Type:

str

country

Country code

Type:

str

domain

Optional domain specific to this language

Type:

str | None

model_config: ClassVar[ConfigDict] = {'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str
flag: str
country: str
domain: str | None
platzky.config.languages_dict(languages)[source]

Convert Languages configuration to a mapping dictionary.

Excludes None values to align with type signature.

Parameters:

languages (dict[str, LanguageConfig]) – Dictionary of language configurations

Returns:

Mapping of language codes to their configuration dictionaries (excludes None values)

Return type:

Mapping[str, Mapping[str, str]]

class platzky.config.TelemetryConfig(*, enabled=False, endpoint=None, console_export=False, timeout=10, deployment_environment=None, service_instance_id=None, flush_on_request=True, flush_timeout_ms=5000, instrument_logging=True)[source]

OpenTelemetry configuration for application tracing.

Parameters:

  • enabled (bool)

  • endpoint (str | None)

  • console_export (bool)

  • timeout (int)

  • deployment_environment (str | None)

  • service_instance_id (str | None)

  • flush_on_request (bool)

  • flush_timeout_ms (int)

  • instrument_logging (bool)

enabled

Enable or disable telemetry tracing

Type:

bool

endpoint

OTLP gRPC endpoint (e.g., localhost:4317 or http://localhost:4317)

Type:

str | None

console_export

Export traces to console for debugging

Type:

bool

timeout

Timeout in seconds for exporter (default: 10)

Type:

int

deployment_environment

Deployment environment (e.g., production, staging, dev)

Type:

str | None

service_instance_id

Service instance ID (auto-generated if not provided)

Type:

str | None

flush_on_request

Flush spans after each request (default: True, may impact latency)

Type:

bool

flush_timeout_ms

Timeout in milliseconds for per-request flush (default: 5000)

Type:

int

instrument_logging

Enable automatic logging instrumentation (default: True)

Type:

bool

model_config: ClassVar[ConfigDict] = {'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

enabled: bool
endpoint: str | None
console_export: bool
timeout: int
deployment_environment: str | None
service_instance_id: str | None
flush_on_request: bool
flush_timeout_ms: int
instrument_logging: bool
classmethod validate_endpoint(v)[source]

Validate endpoint URL format.

Accepts OTLP/gRPC spec-compliant formats: - host:port (e.g., localhost:4317) - http://host[:port] - https://host[:port]

Note: grpc:// scheme is NOT supported per OTLP spec and will be rejected.

Parameters:

v (str | None)

Return type:

str | None

class platzky.config.AttachmentConfig(*, allowed_mime_types=frozenset({'application/gzip', 'application/msword', 'application/pdf', 'application/vnd.ms-excel', 'application/vnd.ms-powerpoint', 'application/vnd.openxmlformats-officedocument.presentationml.presentation', 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet', 'application/vnd.openxmlformats-officedocument.wordprocessingml.document', 'application/x-tar', 'application/zip', 'audio/mpeg', 'audio/ogg', 'audio/wav', 'image/bmp', 'image/gif', 'image/jpeg', 'image/png', 'image/tiff', 'image/webp', 'video/mp4', 'video/ogg', 'video/webm'}), validate_content=True, allow_unrecognized_content=False, max_size=10485760, blocked_extensions=frozenset({'app', 'appimage', 'bash', 'bat', 'class', 'cmd', 'com', 'cpl', 'csh', 'deb', 'dll', 'dmg', 'exe', 'gadget', 'hta', 'inf', 'jar', 'js', 'jse', 'ksh', 'lnk', 'msc', 'msi', 'php', 'php3', 'php4', 'php5', 'phtml', 'pif', 'pkg', 'pl', 'ps1', 'psd1', 'psm1', 'py', 'pyc', 'pyo', 'pyw', 'rb', 'reg', 'rpm', 'scf', 'scr', 'sh', 'url', 'vbe', 'vbs', 'war', 'ws', 'wsc', 'wsf', 'wsh', 'zsh'}), allowed_extensions=frozenset({'bmp', 'doc', 'docx', 'gif', 'gz', 'jpeg', 'jpg', 'mp3', 'mp4', 'ogg', 'pdf', 'png', 'ppt', 'pptx', 'tar', 'tiff', 'wav', 'webm', 'webp', 'xls', 'xlsx', 'zip'}))[source]

Configuration for attachment handling.

Parameters:
allowed_mime_types

MIME types allowed for attachments.

Type:

frozenset[str]

validate_content

Whether to validate content matches declared MIME type.

Type:

bool

allow_unrecognized_content

If True, allow content that cannot be identified.

Type:

bool

max_size

Maximum attachment size in bytes (default: 10MB).

Type:

int

blocked_extensions

File extensions that are PERMANENTLY blocked (executable and script formats). These cannot be overridden via allowed_extensions.

Type:

frozenset[str]

allowed_extensions

File extensions to allow. Defaults to common safe formats (images, documents, archives, audio/video). Set to None to block all. Note: blocked_extensions takes precedence over allowed_extensions. Files without extensions are always blocked when allowed_extensions is set.

Type:

frozenset[str] | None

model_config: ClassVar[ConfigDict] = {'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

allowed_mime_types: frozenset[str]
validate_content: bool
allow_unrecognized_content: bool
max_size: int
blocked_extensions: frozenset[str]
allowed_extensions: frozenset[str] | None
class platzky.config.Config(*, APP_NAME, SECRET_KEY, DB, USE_WWW=True, SEO_PREFIX='/', BLOG_PREFIX='/', LANGUAGES=<factory>, TRANSLATION_DIRECTORIES=<factory>, DEBUG=False, TESTING=False, FEATURE_FLAGS=<factory>, TELEMETRY=<factory>, ATTACHMENT=<factory>)[source]

Main application configuration.

Parameters:
app_name

Application name

Type:

str

secret_key

Flask secret key for sessions

Type:

str

db

Database configuration

Type:

platzky.db.db.DBConfig

use_www

Redirect non-www to www URLs

Type:

bool

seo_prefix

URL prefix for SEO routes

Type:

str

blog_prefix

URL prefix for blog routes

Type:

str

languages

Supported languages configuration

Type:

dict[str, platzky.config.LanguageConfig]

translation_directories

Additional translation directories

Type:

list[str]

debug

Enable debug mode

Type:

bool

testing

Enable testing mode

Type:

bool

feature_flags

Feature flag configuration

Type:

platzky.feature_flags_wrapper.FeatureFlagSet

telemetry

OpenTelemetry configuration

Type:

platzky.config.TelemetryConfig

attachment

Attachment handling configuration

Type:

platzky.config.AttachmentConfig

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

app_name: str
secret_key: str
db: DBConfig
use_www: bool
seo_prefix: str
blog_prefix: str
languages: dict[str, LanguageConfig]
translation_directories: list[str]
debug: bool
testing: bool
feature_flags: FeatureFlagSet
telemetry: TelemetryConfig
attachment: AttachmentConfig
classmethod validate_feature_flags(v)[source]

Coerce dict or None into a FeatureFlagSet.

Parameters:

v (FeatureFlagSet | dict[str, bool] | None)

Return type:

FeatureFlagSet

classmethod model_validate(obj, *, strict=None, from_attributes=None, context=None, by_alias=None, by_name=None, extra=None)[source]

Validate and construct Config from dictionary.

Parses the raw FEATURE_FLAGS dict into a FeatureFlagSet.

Parameters:

  • obj (dict[str, Any]) – Configuration dictionary

  • strict (bool | None) – Enable strict validation

  • from_attributes (bool | None) – Populate from object attributes

  • context (dict[str, Any] | None) – Additional validation context

  • by_alias (bool | None) – Whether to use field aliases

  • by_name (bool | None) – Whether to use field names

  • extra (Literal['allow', 'ignore', 'forbid'] | None) – Extra fields handling

Returns:

Validated Config instance

Return type:

Config

classmethod parse_yaml(path)[source]

Parse configuration from YAML file.

Parameters:

path (str) – Path to YAML configuration file

Returns:

Validated Config instance

Raises:

SystemExit – If config file is not found

Return type:

Config

Database

Abstract base classes for database implementations.

class platzky.db.db.DB[source]

Abstract base class for all database implementations.

db_name: str = 'DB'
module_name: str = 'db'
config_type: type
extend(function_name, function)[source]

Add a function to the DB object. The function must take the DB object as first parameter.

Parameters: function_name (str): The name of the function to add. function (Callable): The function to add to the DB object.

Parameters:
Return type:

None

abstract get_app_description(lang)[source]

Retrieve the application description for a specific language.

Parameters:

lang (str) – Language code (e.g., ‘en’, ‘pl’)

Return type:

str

abstract get_all_posts(lang)[source]

Retrieve all posts for a specific language.

Parameters:

lang (str) – Language code (e.g., ‘en’, ‘pl’)

Return type:

list[Post]

abstract get_menu_items_in_lang(lang)[source]

Retrieve menu items for a specific language.

Parameters:

lang (str) – Language code (e.g., ‘en’, ‘pl’)

Return type:

list[MenuItem]

abstract get_post(slug)[source]

Retrieve a single post by its slug.

Parameters:

slug (str) – URL-friendly identifier for the post

Return type:

Post

abstract get_page(slug)[source]

Retrieve a page by its slug.

Parameters:

slug (str) – URL-friendly identifier for the page

Return type:

Post

abstract get_posts_by_tag(tag, lang)[source]

Retrieve posts filtered by tag and language.

Parameters:

  • tag (str) – Tag name to filter by

  • lang (str) – Language code (e.g., ‘en’, ‘pl’)

Return type:

list[Post]

abstract add_comment(author_name, comment, post_slug)[source]

Add a new comment to a post.

Parameters:

  • author_name (str) – Name of the comment author

  • comment (str) – Comment text content

  • post_slug (str) – URL-friendly identifier of the post

Return type:

None

abstract get_logo_url()[source]

Retrieve the URL of the application logo.

Return type:

str

abstract get_favicon_url()[source]

Retrieve the URL of the application favicon.

Return type:

str

abstract get_primary_color()[source]

Retrieve the primary color for the application theme.

Return type:

str

abstract get_secondary_color()[source]

Retrieve the secondary color for the application theme.

Return type:

str

abstract get_plugins_data()[source]

Retrieve configuration data for all plugins.

Return type:

list[PluginConfigBase]

abstract get_font()[source]

Get the font configuration for the application.

Return type:

str

abstract health_check()[source]

Perform a health check on the database.

Should raise an exception if the database is not healthy. This should be a lightweight operation suitable for health checks.

Return type:

None

class platzky.db.db.DBConfig(*, TYPE)[source]

Base configuration class for database connections.

Parameters:

TYPE (str)

type: str
model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

Models

Pydantic models for blog posts, pages, comments, and CMS modules.

class platzky.models.CmsModule(*, name, description, template, slug)[source]

Represents a CMS module with basic metadata.

Parameters:
name: str
description: str
template: str
slug: str
model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class platzky.models.CmsModuleGroup(*, name, description, template, slug, modules=[])[source]

Represents a group of CMS modules, inheriting module properties.

Parameters:
modules: list[CmsModule]
model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class platzky.models.Image(*, url='', alternateText='')[source]

Represents an image with URL and alternate text.

Parameters:

  • url (str)

  • alternateText (str)

url

URL path to the image resource

Type:

str

alternateText

Descriptive text for accessibility and SEO

Type:

str

url: str
alternateText: str
model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class platzky.models.MenuItem(*, name, url)[source]

Represents a navigation menu item.

Parameters:
name

Display name of the menu item

Type:

str

url

Target URL for the menu item link

Type:

str

name: str
url: str
model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class platzky.models.Comment(*, author, comment, date)[source]

Represents a user comment on a blog post or page.

Parameters:

  • author (str)

  • comment (str)

  • date (Annotated[datetime, BeforeValidator(func=~platzky.models._parse_date_string, json_schema_input_type=PydanticUndefined)])

author

Name of the comment author

Type:

str

comment

The comment text content

Type:

str

date

Datetime when the comment was posted (timezone-aware recommended)

Type:

datetime.datetime

author: str
comment: str
date: Annotated[datetime, BeforeValidator(func=_parse_date_string, json_schema_input_type=PydanticUndefined)]
property time_delta: str

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”)

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class platzky.models.Post(*, author, slug, title, contentInMarkdown, excerpt, coverImage=<factory>, language='en', comments=<factory>, tags=<factory>, date=None)[source]

Represents a blog post with metadata, content, and comments.

Parameters:
author

Name of the post author

Type:

str

slug

URL-friendly unique identifier for the post

Type:

str

title

Post title

Type:

str

contentInMarkdown

Post content in Markdown format

Type:

str

excerpt

Short summary or preview of the post

Type:

str

coverImage

Cover image for the post

Type:

platzky.models.Image

language

Language code for the post content (defaults to ‘en’)

Type:

str

comments

Optional list of comments on this post

Type:

list[platzky.models.Comment]

tags

Optional list of tags for categorization

Type:

list[str]

date

Optional datetime when the post was published (timezone-aware recommended)

Type:

datetime.datetime | None

author: str
slug: str
title: str
contentInMarkdown: str
excerpt: str
coverImage: Image
language: str
comments: list[Comment]
tags: list[str]
date: Annotated[datetime, BeforeValidator(func=_parse_date_string, json_schema_input_type=PydanticUndefined)] | None
model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

platzky.models.Page

alias of Post

class platzky.models.Color(*, r=0, g=0, b=0, a=255)[source]

Represents an RGBA color value.

Parameters:
r

Red component (0-255)

Type:

int

g

Green component (0-255)

Type:

int

b

Blue component (0-255)

Type:

int

a

Alpha/transparency component (0-255, where 255 is fully opaque)

Type:

int

r: int
g: int
b: int
a: int
model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].