platzky 0.4.3__tar.gz → 1.0.1__tar.gz

platzky-1.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Platzky Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

{platzky-0.4.3 → platzky-1.0.1}/PKG-INFO

@@ -1,8 +1,9 @@
 Metadata-Version: 2.4
 Name: platzky
-Version: 0.4.3
+Version: 1.0.1
 Summary: Not only blog engine
 License: MIT
+License-File: LICENSE
 Requires-Python: >=3.10,<4.0
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
@@ -11,6 +12,8 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
+Provides-Extra: docs
+Provides-Extra: telemetry
 Requires-Dist: Flask (==3.0.3)
 Requires-Dist: Flask-Babel (>=4.0.0,<5.0.0)
 Requires-Dist: Flask-Minify (>=0.42,<0.43)
@@ -21,9 +24,18 @@ Requires-Dist: deprecation (>=2.1.0,<3.0.0)
 Requires-Dist: google-cloud-storage (>=2.5.0,<3.0.0)
 Requires-Dist: gql (>=3.4.0,<4.0.0)
 Requires-Dist: humanize (>=4.9.0,<5.0.0)
+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)
 Requires-Dist: pymongo (>=4.7.0,<5.0.0)
+Requires-Dist: sphinx (>=8.0.0,<9.0.0) ; extra == "docs"
+Requires-Dist: sphinx-rtd-theme (>=3.0.0,<4.0.0) ; extra == "docs"
+Requires-Dist: tomli (>=2.0.0,<3.0.0) ; extra == "docs"
 Description-Content-Type: text/markdown
 
 ![Github Actions](https://github.com/platzky/platzky/actions/workflows/tests.yml/badge.svg?event=push&branch=main)

platzky-1.0.1/platzky/config.py

@@ -0,0 +1,209 @@
+"""Configuration module for Platzky application.
+
+This module defines all configuration models and parsing logic for the application.
+"""
+
+import sys
+import typing as t
+
+import yaml
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from .db.db import DBConfig
+from .db.db_loader import get_db_module
+
+
+class StrictBaseModel(BaseModel):
+    """Base model with immutable (frozen) configuration."""
+
+    model_config = ConfigDict(frozen=True)
+
+
+class LanguageConfig(StrictBaseModel):
+    """Configuration for a single language.
+
+    Attributes:
+        name: Display name of the language
+        flag: Flag icon code (country code)
+        country: Country code
+        domain: Optional domain specific to this language
+    """
+
+    name: str = Field(alias="name")
+    flag: str = Field(alias="flag")
+    country: str = Field(alias="country")
+    domain: t.Optional[str] = Field(default=None, alias="domain")
+
+
+Languages = dict[str, LanguageConfig]
+LanguagesMapping = t.Mapping[str, t.Mapping[str, str]]
+
+# Validation error messages
+_INVALID_ENDPOINT_FORMAT_MSG = (
+    "Invalid endpoint: '{}'. Must be host:port or [http|https]://host[:port]"
+)
+_INVALID_ENDPOINT_SCHEME_MSG = "Invalid endpoint scheme: '{}'. Must be http or https"
+_MISSING_HOSTNAME_MSG = "Invalid endpoint: '{}'. Missing hostname"
+
+
+def languages_dict(languages: Languages) -> LanguagesMapping:
+    """Convert Languages configuration to a mapping dictionary.
+
+    Excludes None values to align with type signature.
+
+    Args:
+        languages: Dictionary of language configurations
+
+    Returns:
+        Mapping of language codes to their configuration dictionaries (excludes None values)
+    """
+    return {
+        name: {k: v for k, v in lang.model_dump().items() if v is not None}
+        for name, lang in languages.items()
+    }
+
+
+class TelemetryConfig(StrictBaseModel):
+    """OpenTelemetry configuration for application tracing.
+
+    Attributes:
+        enabled: Enable or disable telemetry tracing
+        endpoint: OTLP gRPC endpoint (e.g., localhost:4317 or http://localhost:4317)
+        console_export: Export traces to console for debugging
+        timeout: Timeout in seconds for exporter (default: 10)
+        deployment_environment: Deployment environment (e.g., production, staging, dev)
+        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")
+    endpoint: t.Optional[str] = Field(default=None, alias="endpoint")
+    console_export: bool = Field(default=False, alias="console_export")
+    timeout: int = Field(default=10, alias="timeout", gt=0)
+    deployment_environment: t.Optional[str] = Field(default=None, alias="deployment_environment")
+    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
+    def validate_endpoint(cls, v: t.Optional[str]) -> t.Optional[str]:
+        """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.
+        """
+        if v is None:
+            return v
+
+        from urllib.parse import urlparse
+
+        # Check if it has a scheme (contains ://)
+        if "://" not in v:
+            # Must be host:port format - validate it has a colon
+            if ":" in v and not v.startswith("/"):
+                return v
+            raise ValueError(_INVALID_ENDPOINT_FORMAT_MSG.format(v))
+
+        # Parse URL with scheme
+        parsed = urlparse(v)
+
+        # Validate scheme (only http/https per OTLP spec, grpc is NOT supported)
+        if parsed.scheme not in ("http", "https"):
+            raise ValueError(_INVALID_ENDPOINT_SCHEME_MSG.format(parsed.scheme))
+
+        # Validate hostname exists
+        if not parsed.hostname:
+            raise ValueError(_MISSING_HOSTNAME_MSG.format(v))
+
+        return v
+
+
+class Config(StrictBaseModel):
+    """Main application configuration.
+
+    Attributes:
+        app_name: Application name
+        secret_key: Flask secret key for sessions
+        db: Database configuration
+        use_www: Redirect non-www to www URLs
+        seo_prefix: URL prefix for SEO routes
+        blog_prefix: URL prefix for blog routes
+        languages: Supported languages configuration
+        domain_to_lang: Domain to language mapping
+        translation_directories: Additional translation directories
+        debug: Enable debug mode
+        testing: Enable testing mode
+        feature_flags: Feature flag configuration
+        telemetry: OpenTelemetry configuration
+    """
+
+    app_name: str = Field(alias="APP_NAME")
+    secret_key: str = Field(alias="SECRET_KEY")
+    db: DBConfig = Field(alias="DB")
+    use_www: bool = Field(default=True, alias="USE_WWW")
+    seo_prefix: str = Field(default="/", alias="SEO_PREFIX")
+    blog_prefix: str = Field(default="/", alias="BLOG_PREFIX")
+    languages: Languages = Field(default_factory=dict, alias="LANGUAGES")
+    domain_to_lang: dict[str, str] = Field(default_factory=dict, alias="DOMAIN_TO_LANG")
+    translation_directories: list[str] = Field(
+        default_factory=list,
+        alias="TRANSLATION_DIRECTORIES",
+    )
+    debug: bool = Field(default=False, alias="DEBUG")
+    testing: bool = Field(default=False, alias="TESTING")
+    feature_flags: t.Optional[dict[str, bool]] = Field(default=None, alias="FEATURE_FLAGS")
+    telemetry: TelemetryConfig = Field(default_factory=TelemetryConfig, alias="TELEMETRY")
+
+    @classmethod
+    def model_validate(
+        cls,
+        obj: t.Any,
+        *,
+        strict: bool | None = None,
+        from_attributes: bool | None = None,
+        context: dict[str, t.Any] | None = None,
+    ) -> "Config":
+        """Validate and construct Config from dictionary.
+
+        Args:
+            obj: Configuration dictionary
+            strict: Enable strict validation
+            from_attributes: Populate from object attributes
+            context: Additional validation context
+
+        Returns:
+            Validated Config instance
+        """
+        db_cfg_type = get_db_module(obj["DB"]["TYPE"]).db_config_type()
+        obj["DB"] = db_cfg_type.model_validate(obj["DB"])
+        return super().model_validate(
+            obj, strict=strict, from_attributes=from_attributes, context=context
+        )
+
+    @classmethod
+    def parse_yaml(cls, path: str) -> "Config":
+        """Parse configuration from YAML file.
+
+        Args:
+            path: Path to YAML configuration file
+
+        Returns:
+            Validated Config instance
+
+        Raises:
+            SystemExit: If config file is not found
+        """
+        try:
+            with open(path, "r") as f:
+                return cls.model_validate(yaml.safe_load(f))
+        except FileNotFoundError:
+            print(f"Config file not found: {path}", file=sys.stderr)
+            raise SystemExit(1)

{platzky-0.4.3 → platzky-1.0.1}/platzky/engine.py

@@ -19,6 +19,7 @@ class Engine(Flask):
         self.dynamic_body = ""
         self.dynamic_head = ""
         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")
         config.translation_directories.append(locale_dir)

{platzky-0.4.3 → platzky-1.0.1}/platzky/platzky.py

@@ -17,6 +17,12 @@ from platzky.plugin.plugin_loader import plugify
 from platzky.seo import seo
 from platzky.www_handler import redirect_nonwww_to_www, redirect_www_to_nonwww
 
+_MISSING_OTEL_MSG = (
+    "OpenTelemetry is not installed. Install with: "
+    "poetry add opentelemetry-api opentelemetry-sdk "
+    "opentelemetry-instrumentation-flask opentelemetry-exporter-otlp-proto-grpc"
+)
+
 
 def create_engine(config: Config, db) -> Engine:
     app = Engine(config, db, __name__)
@@ -85,6 +91,20 @@ def create_app_from_config(config: Config) -> Engine:
     db = get_db(config.db)
     engine = create_engine(config, db)
 
+    # Setup telemetry (optional feature)
+    if config.telemetry.enabled:
+        try:
+            from platzky.telemetry import setup_telemetry
+
+            setup_telemetry(engine, config.telemetry)
+        except ImportError as e:
+            raise ImportError(_MISSING_OTEL_MSG) from e
+        except ValueError as e:
+            raise ValueError(
+                f"Telemetry configuration error: {e}. "
+                "Check your telemetry settings in the configuration file."
+            ) from e
+
     admin_blueprint = admin.create_admin_blueprint(
         login_methods=engine.login_methods, cms_modules=engine.cms_modules
     )

platzky-1.0.1/platzky/telemetry.py

@@ -0,0 +1,132 @@
+import atexit
+import socket
+import uuid
+from typing import TYPE_CHECKING, Optional
+
+from platzky.config import TelemetryConfig
+
+if TYPE_CHECKING:
+    from opentelemetry.trace import Tracer
+
+    from platzky.engine import Engine
+
+# Error messages
+_MISSING_EXPORTERS_MSG = (
+    "Telemetry is enabled but no exporters are configured. "
+    "Set endpoint or console_export=True to export traces."
+)
+
+
+def setup_telemetry(app: "Engine", telemetry_config: TelemetryConfig) -> Optional["Tracer"]:
+    """Setup OpenTelemetry tracing for Flask application.
+
+    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)
+        telemetry_config: Telemetry configuration specifying endpoint and export options
+
+    Returns:
+        OpenTelemetry tracer instance if enabled, None otherwise
+
+    Raises:
+        ImportError: If OpenTelemetry packages are not installed when telemetry is enabled
+        ValueError: If telemetry is enabled but no exporters are configured
+    """
+    if not telemetry_config.enabled:
+        return None
+
+    # Reject telemetry enabled without exporters (creates overhead without benefit)
+    if not telemetry_config.endpoint and not telemetry_config.console_export:
+        raise ValueError(_MISSING_EXPORTERS_MSG)
+
+    # If already instrumented, return tracer without rebuilding provider/exporters
+    if app.telemetry_instrumented:
+        from opentelemetry import trace
+
+        return trace.get_tracer(__name__)
+
+    # Import OpenTelemetry modules (will raise ImportError if not installed)
+    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 (
+        BatchSpanProcessor,
+        ConsoleSpanExporter,
+        SimpleSpanProcessor,
+    )
+    from opentelemetry.semconv.resource import ResourceAttributes
+
+    # Build resource attributes
+    service_name = app.config.get("APP_NAME", "platzky")
+    resource_attrs: dict[str, str] = {
+        ResourceAttributes.SERVICE_NAME: service_name,
+    }
+
+    # Auto-detect service version from package metadata
+    from importlib.metadata import PackageNotFoundError
+    from importlib.metadata import version as get_version
+
+    try:
+        resource_attrs[ResourceAttributes.SERVICE_VERSION] = get_version("platzky")
+    except PackageNotFoundError:
+        pass  # Version not available
+
+    if telemetry_config.deployment_environment:
+        resource_attrs[ResourceAttributes.DEPLOYMENT_ENVIRONMENT] = (
+            telemetry_config.deployment_environment
+        )
+
+    # Add instance ID (user-provided or auto-generated)
+    if telemetry_config.service_instance_id:
+        resource_attrs[ResourceAttributes.SERVICE_INSTANCE_ID] = (
+            telemetry_config.service_instance_id
+        )
+    else:
+        # Generate unique instance ID: hostname + short UUID
+        hostname = socket.gethostname()
+        instance_uuid = str(uuid.uuid4())[:8]
+        resource_attrs[ResourceAttributes.SERVICE_INSTANCE_ID] = f"{hostname}-{instance_uuid}"
+
+    resource = Resource.create(resource_attrs)
+    provider = TracerProvider(resource=resource)
+
+    # Configure exporter based on endpoint
+    if telemetry_config.endpoint:
+        exporter = OTLPSpanExporter(
+            endpoint=telemetry_config.endpoint, timeout=telemetry_config.timeout
+        )
+        provider.add_span_processor(BatchSpanProcessor(exporter))
+
+    # Optional console export
+    if telemetry_config.console_export:
+        provider.add_span_processor(SimpleSpanProcessor(ConsoleSpanExporter()))
+
+    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)
+    if telemetry_config.flush_on_request:
+
+        @app.teardown_appcontext
+        def flush_telemetry(_exc: Optional[BaseException] = None) -> None:
+            """Flush pending spans after request completion."""
+            provider.force_flush(timeout_millis=telemetry_config.flush_timeout_ms)
+
+    # Shutdown provider once at process exit
+    atexit.register(provider.shutdown)
+
+    return trace.get_tracer(__name__)

{platzky-0.4.3 → platzky-1.0.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "platzky"
-version = "0.4.3"
+version = "1.0.1"
 description = "Not only blog engine"
 authors = []
 license = "MIT"
@@ -21,6 +21,30 @@ pydantic = "^2.7.1"
 deprecation = "^2.1.0"
 pygithub = "^2.6.1"
 pymongo = "^4.7.0"
+sphinx = {version = "^8.0.0", optional = true}
+sphinx-rtd-theme = {version = "^3.0.0", optional = true}
+tomli = {version = "^2.0.0", optional = true}
+myst-parser = {version = "^4.0.0", optional = true}
+opentelemetry-api = {version = "^1.27.0", optional = true}
+opentelemetry-sdk = {version = "^1.27.0", optional = true}
+opentelemetry-instrumentation-flask = {version = "^0.48b0", optional = true}
+opentelemetry-instrumentation-logging = {version = "^0.48b0", optional = true}
+opentelemetry-exporter-otlp-proto-grpc = {version = "^1.27.0", optional = true}
+
+[tool.poetry.extras]
+docs = [
+    "sphinx",
+    "sphinx-rtd-theme",
+    "myst-parser",
+    "tomli"
+]
+telemetry = [
+    "opentelemetry-api",
+    "opentelemetry-sdk",
+    "opentelemetry-instrumentation-flask",
+    "opentelemetry-instrumentation-logging",
+    "opentelemetry-exporter-otlp-proto-grpc"
+]
 
 [tool.poetry.group.dev.dependencies]
 pytest = "^8.2.1"
@@ -32,6 +56,12 @@ ruff = "^0.4.4"
 pyright = "^1.1.364"
 beautifulsoup4 = "^4.12.3"
 python-semantic-release = "^9.8.0"
+interrogate = "^1.7.0"
+opentelemetry-api = "^1.27.0"
+opentelemetry-sdk = "^1.27.0"
+opentelemetry-instrumentation-flask = "^0.48b0"
+opentelemetry-instrumentation-logging = "^0.48b0"
+opentelemetry-exporter-otlp-proto-grpc = "^1.27.0"
 
 [build-system]
 requires = ["poetry-core"]
@@ -48,6 +78,8 @@ exclude_lines = [
     "@abstractmethod",
     "@abc.abstractmethod"
 ]
+fail_under = 70
+show_missing = true
 
 [tool.pyright]
 pythonVersion = "3.10"
@@ -113,3 +145,12 @@ type = "github"
 
 [tool.semantic_release.remote.token]
 env = "GH_TOKEN"
+
+[tool.interrogate]
+fail-under = 20
+ignore-init-method = true
+ignore-init-module = true
+ignore-magic = true
+ignore-private = true
+ignore-semiprivate = false
+exclude = ["tests", "docs"]

platzky-0.4.3/platzky/config.py

@@ -1,69 +0,0 @@
-import sys
-import typing as t
-
-import yaml
-from pydantic import BaseModel, ConfigDict, Field
-
-from .db.db import DBConfig
-from .db.db_loader import get_db_module
-
-
-class StrictBaseModel(BaseModel):
-    model_config = ConfigDict(frozen=True)
-
-
-class LanguageConfig(StrictBaseModel):
-    name: str = Field(alias="name")
-    flag: str = Field(alias="flag")
-    country: str = Field(alias="country")
-    domain: t.Optional[str] = Field(default=None, alias="domain")
-
-
-Languages = dict[str, LanguageConfig]
-LanguagesMapping = t.Mapping[str, t.Mapping[str, str]]
-
-
-def languages_dict(languages: Languages) -> LanguagesMapping:
-    return {name: lang.model_dump() for name, lang in languages.items()}
-
-
-class Config(StrictBaseModel):
-    app_name: str = Field(alias="APP_NAME")
-    secret_key: str = Field(alias="SECRET_KEY")
-    db: DBConfig = Field(alias="DB")
-    use_www: bool = Field(default=True, alias="USE_WWW")
-    seo_prefix: str = Field(default="/", alias="SEO_PREFIX")
-    blog_prefix: str = Field(default="/", alias="BLOG_PREFIX")
-    languages: Languages = Field(default_factory=dict, alias="LANGUAGES")
-    domain_to_lang: dict[str, str] = Field(default_factory=dict, alias="DOMAIN_TO_LANG")
-    translation_directories: list[str] = Field(
-        default_factory=list,
-        alias="TRANSLATION_DIRECTORIES",
-    )
-    debug: bool = Field(default=False, alias="DEBUG")
-    testing: bool = Field(default=False, alias="TESTING")
-    feature_flags: t.Optional[dict[str, bool]] = Field(default_factory=dict, alias="FEATURE_FLAGS")
-
-    @classmethod
-    def model_validate(
-        cls,
-        obj: t.Any,
-        *,
-        strict: bool | None = None,
-        from_attributes: bool | None = None,
-        context: dict[str, t.Any] | None = None,
-    ) -> "Config":
-        db_cfg_type = get_db_module(obj["DB"]["TYPE"]).db_config_type()
-        obj["DB"] = db_cfg_type.model_validate(obj["DB"])
-        return super().model_validate(
-            obj, strict=strict, from_attributes=from_attributes, context=context
-        )
-
-    @classmethod
-    def parse_yaml(cls, path: str) -> "Config":
-        try:
-            with open(path, "r") as f:
-                return cls.model_validate(yaml.safe_load(f))
-        except FileNotFoundError:
-            print(f"Config file not found: {path}", file=sys.stderr)
-            raise SystemExit(1)