platzky 0.4.3__py3-none-any.whl → 1.0.0__py3-none-any.whl

platzky/config.py

@@ -1,18 +1,34 @@
+"""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
+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")
@@ -22,12 +38,111 @@ class LanguageConfig(StrictBaseModel):
 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:
-    return {name: lang.model_dump() for name, lang in languages.items()}
+    """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)
+    """
+
+    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)
+
+    @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")
@@ -42,7 +157,8 @@ class Config(StrictBaseModel):
     )
     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")
+    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(
@@ -53,6 +169,17 @@ class Config(StrictBaseModel):
         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(
@@ -61,6 +188,17 @@ class Config(StrictBaseModel):
 
     @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))

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/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/telemetry.py

@@ -0,0 +1,123 @@
+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.
+
+    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.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)
+    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.dist-info → platzky-1.0.0.dist-info}/METADATA

@@ -1,8 +1,9 @@
 Metadata-Version: 2.4
 Name: platzky
-Version: 0.4.3
+Version: 1.0.0
 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,17 @@ 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-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-0.4.3.dist-info → platzky-1.0.0.dist-info}/RECORD

@@ -7,7 +7,7 @@ platzky/admin/templates/module.html,sha256=WuQZxKQDD4INl-QF2uiKHf9Fmf2h7cEW9RLe1
 platzky/blog/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 platzky/blog/blog.py,sha256=L9IYWxnLo1v1h_wLF-0HyG1Y4RSGg7maEMnYxhTgG5Y,2971
 platzky/blog/comment_form.py,sha256=4lkNJ_S_2DZmJBbz-NPDqahvy2Zz5AGNH2spFeGIop4,513
-platzky/config.py,sha256=M3gmZI9yI-ThgmTA4RKsAPcnJwJjcWhXipYzq3hO-Hk,2346
+platzky/config.py,sha256=N5cQjV8Jh_fETw9jXE-UOcC-bSlC3l_04yMMtRwXKXw,7365
 platzky/db/README.md,sha256=IO-LoDsd4dLBZenaz423EZjvEOQu_8m2OC0G7du170w,1753
 platzky/db/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 platzky/db/db.py,sha256=0h5rGCBO_N1wBqJRl5EoiW_bFDpNIvmNwuA0hJi89jw,3060
@@ -18,16 +18,17 @@ platzky/db/graph_ql_db.py,sha256=af6yy1R27YO8N9zJWU7VgU7optRgpdk_1ZUtab_1eT4,896
 platzky/db/json_db.py,sha256=NUBPy4jt-y37TYq4SCGaSgief3MbBWL_Efw8Bxp8Jo0,4046
 platzky/db/json_file_db.py,sha256=tPo92n5zG7vGpunn5vl66zISHBziQdxBttitvc5hPug,1030
 platzky/db/mongodb_db.py,sha256=28KO8XmTEiqE7FcNBzw_pfxOy6Vo-T7qsHdUlh59QX0,5174
-platzky/engine.py,sha256=Kv242PsB8lVz_FCYdGogd8o5zGmn5Msev3B3lfYRUXA,5411
+platzky/engine.py,sha256=0bxKzfK83ic-VNlKcDut_84_u5EmY2baU5JcJsleUoM,5461
 platzky/locale/en/LC_MESSAGES/messages.po,sha256=WaZGlFAegKRq7CSz69dWKic-mKvQFhVvssvExxNmGaU,1400
 platzky/locale/pl/LC_MESSAGES/messages.po,sha256=sUPxMKDeEOoZ5UIg94rGxZD06YVWiAMWIby2XE51Hrc,1624
 platzky/models.py,sha256=DZZgKW2Q3fY2GMdikFUmAgpsRqT5VKAOwP6RmEsmO2M,1871
-platzky/platzky.py,sha256=oWI-R2lZzpmmqrRqhswssZO1Z14R8fAdRFJCbyRTyeY,3868
+platzky/platzky.py,sha256=8mTqdYqRKONv2oGvQF5Y0fuOomH7ZFYvXtxc7ZohBLE,4585
 platzky/plugin/plugin.py,sha256=tV8aobIzMDJe1frKUAi4kLbrTAIS0FWE3oYpktSo6Ug,1633
 platzky/plugin/plugin_loader.py,sha256=MeQ8LNbrOomwXgc1ISHuyhjZd2mzYKen70eDShWs-Co,3497
 platzky/seo/seo.py,sha256=N_MmAA4KJZmmrDUh0hYNtD8ycOwpNKow4gVSAv8V3N4,2631
 platzky/static/blog.css,sha256=TrppzgQbj4UtuTufDCdblyNTVAqgIbhD66Cziyv_xnY,7893
 platzky/static/styles.css,sha256=U5ddGIK-VcGRJZ3BdOpMp0pR__k6rNEMsuQXkP4tFQ0,686
+platzky/telemetry.py,sha256=NQuueK-uwZDdnpWaOTFSMvzRWWg6Yu4jPOMPYdMidNY,4524
 platzky/templates/404.html,sha256=EheoLSWylOscLH8FmcMA4c6Jw14i5HkSvE_GXzGIrUo,78
 platzky/templates/base.html,sha256=clvWlVOxNLqSQxBpPao3qnKKzkU2q48Apf1WbHJgYfE,4003
 platzky/templates/blog.html,sha256=aPl-DzLX85bHv7tN8UjlABR086PUJ9IGlGbIBioFHGA,1281
@@ -40,6 +41,7 @@ platzky/templates/post.html,sha256=GSgjIZsOQKtNx3cEbquSjZ5L4whPnG6MzRyoq9k4B8Q,1
 platzky/templates/robots.txt,sha256=2_j2tiYtYJnzZUrANiX9pvBxyw5Dp27fR_co18BPEJ0,116
 platzky/templates/sitemap.xml,sha256=iIJZ91_B5ZuNLCHsRtsGKZlBAXojOTP8kffqKLacgvs,578
 platzky/www_handler.py,sha256=pF6Rmvem1sdVqHD7z3RLrDuG-CwAqfGCti50_NPsB2w,725
-platzky-0.4.3.dist-info/METADATA,sha256=RMfCt6cM7vEEWaS_lmahJZ9kNyy53c41_gmu064X6tU,1818
-platzky-0.4.3.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
-platzky-0.4.3.dist-info/RECORD,,
+platzky-1.0.0.dist-info/METADATA,sha256=NSQ3OIyrJ4NQsdu3QRIo-c4jQQ9mM0HoqwmQK2EPvKc,2463
+platzky-1.0.0.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
+platzky-1.0.0.dist-info/licenses/LICENSE,sha256=wCdfk-qEosi6BDwiBulMfKMi0hxp1UXV0DdjLrRm788,1077
+platzky-1.0.0.dist-info/RECORD,,

platzky-1.0.0.dist-info/licenses/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.