planar 0.5.0__py3-none-any.whl

planar/logging/logger.py

@@ -0,0 +1,114 @@
+from datetime import datetime
+from logging import DEBUG, Logger, getLogger
+from typing import Any, Mapping
+from uuid import UUID
+
+
+def _process_values(values: Mapping[str, Any] | None):
+    if not values:
+        return None
+
+    processed = {}
+    for k, v in values.items():
+        k = f"${k}"  # prefix keys to avoid conflicts with LogRecord keys
+        if isinstance(v, (UUID, datetime)):
+            processed[k] = str(v)
+        else:
+            processed[k] = v
+    return processed
+
+
+# A wrapper around a standard `logging.Logger` instance. The main
+# difference is that its logging methods accept arbitrary **kwargs which are
+# automatically merged with "extra"
+class PlanarLogger:
+    def __init__(self, logger: Logger):
+        self._logger = logger
+
+    def isDebugEnabled(self) -> bool:
+        return self._logger.isEnabledFor(DEBUG)
+
+    def debug(
+        self,
+        msg: object,
+        **kwargs: Any,
+    ) -> None:
+        return self._logger.debug(
+            msg,
+            stacklevel=2,
+            extra=_process_values(kwargs),
+        )
+
+    def info(
+        self,
+        msg: object,
+        **kwargs: Any,
+    ) -> None:
+        return self._logger.info(
+            msg,
+            stacklevel=2,
+            extra=_process_values(kwargs),
+        )
+
+    def warning(
+        self,
+        msg: object,
+        **kwargs: Any,
+    ) -> None:
+        return self._logger.warning(
+            msg,
+            stacklevel=2,
+            extra=_process_values(kwargs),
+        )
+
+    def error(
+        self,
+        msg: object,
+        **kwargs: Any,
+    ) -> None:
+        return self._logger.error(
+            msg,
+            stacklevel=2,
+            extra=_process_values(kwargs),
+        )
+
+    def critical(
+        self,
+        msg: object,
+        **kwargs: Any,
+    ) -> None:
+        return self._logger.critical(
+            msg,
+            stacklevel=2,
+            extra=_process_values(kwargs),
+        )
+
+    def exception(
+        self,
+        msg: object,
+        **kwargs: Any,
+    ) -> None:
+        return self._logger.exception(
+            msg,
+            exc_info=True,
+            stacklevel=2,
+            extra=_process_values(kwargs),
+        )
+
+    def setLevel(self, level: int) -> None:
+        self._logger.setLevel(level)
+
+    @property
+    def handlers(self):
+        return self._logger.handlers
+
+
+def get_logger(name: str) -> PlanarLogger:
+    """
+    Get a logger instance.
+
+    This will be a PlanarLogger instance which supports structured logging
+    by passing keyword arguments to logging methods.
+    """
+    logger = getLogger(name)
+    return PlanarLogger(logger)

planar/logging/otel.py

@@ -0,0 +1,51 @@
+import logging
+from typing import Any
+
+from opentelemetry._logs import set_logger_provider
+from opentelemetry.exporter.otlp.proto.grpc._log_exporter import OTLPLogExporter
+from opentelemetry.sdk._logs import LoggerProvider, LoggingHandler
+from opentelemetry.sdk._logs.export import BatchLogRecordProcessor
+from opentelemetry.sdk.resources import Resource
+from pydantic import HttpUrl
+
+from .attributes import ExtraAttributesFilter
+
+
+def get_otel_collector_handler(
+    otel_collector_endpoint: HttpUrl,
+    resource_attributes: dict[str, Any] | None = None,
+) -> logging.Handler:
+    logger_provider = LoggerProvider(
+        resource=Resource.create(
+            resource_attributes
+            or {
+                "service.name": "planar-app",
+            }
+        ),
+    )
+
+    otlp_exporter = OTLPLogExporter(
+        endpoint=str(otel_collector_endpoint),
+        insecure=otel_collector_endpoint.scheme == "http",
+    )
+    logger_provider.add_log_record_processor(BatchLogRecordProcessor(otlp_exporter))
+
+    set_logger_provider(logger_provider)
+    handler = LoggingHandler(level=logging.NOTSET, logger_provider=logger_provider)
+    handler.addFilter(ExtraAttributesFilter())
+    return handler
+
+
+def setup_otel_logging(
+    otel_collector_endpoint: HttpUrl,
+    resource_attributes: dict[str, Any] | None = None,
+) -> None:
+    """
+    Sets up the OpenTelemetry logging handler and adds it to the root logger.
+
+    Args:
+        otel_collector_endpoint: The endpoint of the OpenTelemetry collector.
+        resource_attributes: A dictionary of resource attributes to add to the logs.
+    """
+    handler = get_otel_collector_handler(otel_collector_endpoint, resource_attributes)
+    logging.getLogger().addHandler(handler)

planar/modeling/field_helpers.py

@@ -0,0 +1,59 @@
+"""
+Helper functions for field definitions and schema customization.
+"""
+
+from dataclasses import dataclass
+from typing import Annotated, Any, Type
+
+from pydantic import GetJsonSchemaHandler
+from pydantic.json_schema import JsonSchemaValue
+from pydantic_core import core_schema
+
+from planar.modeling.orm import PlanarBaseEntity
+
+
+class JsonSchemaJson:
+    @classmethod
+    def __get_pydantic_json_schema__(
+        cls, core_schema: core_schema.CoreSchema, handler: GetJsonSchemaHandler
+    ) -> JsonSchemaValue:
+        return {"$ref": "https://json-schema.org/draft/2020-12/schema"}
+
+
+JsonSchema = Annotated[dict[str, Any], JsonSchemaJson]
+
+
+@dataclass
+class EntityField:
+    entity: Type[PlanarBaseEntity]
+    description: str | None = None
+    display_field: str | None = None
+    """
+    Create a field that references an entity, with metadata for UI rendering.
+
+    Args:
+        entity: The entity class this field references
+        display_field: Field to display in dropdowns (defaults to best guess)
+        description: Field description
+
+    Use this by annotating a field with:
+    Annotated[str, EntityField(entity=MyEntity)]
+    """
+
+    def __get_pydantic_json_schema__(
+        self, core_schema: core_schema.CoreSchema, handler: GetJsonSchemaHandler
+    ) -> JsonSchemaValue:
+        json_schema = handler(core_schema)
+        json_schema["description"] = self.description
+        display_field = self.display_field
+        if display_field is None:
+            for field_name in ["name", "title", "username", "label", "display_name"]:
+                if hasattr(self.entity, field_name):
+                    display_field = field_name
+                    break
+        json_schema["x-planar-presentation"] = {
+            "inputType": "entity-select",
+            "entity": self.entity.__name__,
+            "displayField": display_field,
+        }
+        return json_schema.copy()

planar/modeling/json_schema_generator.py

@@ -0,0 +1,94 @@
+import inspect
+from typing import Any, Callable, Optional, get_args, get_origin, get_type_hints
+
+from pydantic import create_model
+
+from planar.logging import get_logger
+from planar.modeling.field_helpers import JsonSchema
+
+logger = get_logger(__name__)
+
+
+def generate_json_schema_for_input_parameters(func: Callable[..., Any]) -> JsonSchema:
+    """Generate a Pydantic model from a function's parameters and return it as JSON schema."""
+    logger.debug(
+        "generating input json schema for function", function_name=func.__name__
+    )
+    class_name = "DynamicInputModel"
+
+    sig = inspect.signature(func)
+    type_hints = get_type_hints(func)
+
+    fields = {}
+    for param_name, param in sig.parameters.items():
+        # Skip self/cls for methods
+        if param_name in ("self", "cls") and param.kind == param.POSITIONAL_OR_KEYWORD:
+            continue
+
+        param_type = type_hints.get(param_name, Any)
+
+        is_optional = False
+        if get_origin(param_type) is Optional:
+            param_type = get_args(param_type)[0]
+            is_optional = True
+
+        if param.default is not param.empty:
+            default = param.default
+        elif is_optional:
+            default = None
+        else:
+            default = ...  # Required field with no default
+
+        fields[param_name] = (param_type, default)
+
+    logger.debug(
+        "fields for input model",
+        function_name=func.__name__,
+        fields=list(fields.keys()),
+    )
+    model_class = create_model(class_name, **fields)
+    schema = model_class.model_json_schema()
+    logger.debug(
+        "generated input schema",
+        function_name=func.__name__,
+        title=schema.get("title", class_name),
+    )
+    return schema
+
+
+def generate_json_schema_for_output_parameters(func: Callable[..., Any]) -> JsonSchema:
+    """Generate a Pydantic model from a function's output parameters and return it as JSON schema."""
+    logger.debug(
+        "generating output json schema for function", function_name=func.__name__
+    )
+    class_name = "DynamicOutputModel"
+
+    type_hints = get_type_hints(func)
+    return_type = type_hints.get("return", Any)
+
+    is_optional = False
+    if get_origin(return_type) is Optional:
+        return_type = get_args(return_type)[0]
+        is_optional = True
+
+    if is_optional:
+        default = None
+    else:
+        default = ...  # Required field with no default
+
+    fields = {}
+    fields["output_type"] = (return_type, default)
+
+    logger.debug(
+        "field for output model",
+        function_name=func.__name__,
+        fields=list(fields.keys()),
+    )
+    model_class = create_model(class_name, **fields)
+    schema = model_class.model_json_schema()
+    logger.debug(
+        "generated output schema",
+        function_name=func.__name__,
+        title=schema.get("title", class_name),
+    )
+    return schema

planar/modeling/mixins/__init__.py

@@ -0,0 +1,10 @@
+from planar.modeling.mixins.auditable import AuditableMixin
+from planar.modeling.mixins.timestamp import TimestampMixin, timestamp_column
+from planar.modeling.mixins.uuid_primary_key import UUIDPrimaryKeyMixin
+
+__all__ = [
+    "TimestampMixin",
+    "timestamp_column",
+    "AuditableMixin",
+    "UUIDPrimaryKeyMixin",
+]

planar/modeling/mixins/auditable.py

@@ -0,0 +1,52 @@
+from sqlalchemy import event
+from sqlalchemy.engine import Connection
+from sqlalchemy.orm import Mapper
+from sqlmodel import Field, SQLModel
+
+from planar.logging import get_logger
+from planar.security.auth_context import get_current_principal
+
+logger = get_logger("orm.AuditableMixin")
+
+SYSTEM_USER = "system"
+
+
+class AuditableMixin(SQLModel, table=False):
+    """
+    Mixin that provides audit trail fields for tracking who created and updated records.
+
+    This standardizes audit trail handling across all models that need to track
+    user actions.
+
+    Attributes:
+        created_by: User who created the record
+        updated_by: User who last updated the record
+    """
+
+    __abstract__ = True
+
+    created_by: str = Field(default=SYSTEM_USER)
+    updated_by: str = Field(default=SYSTEM_USER)
+
+
+@event.listens_for(AuditableMixin, "before_insert", propagate=True)
+def set_auditable_values(
+    mapper: Mapper, connection: Connection, target: AuditableMixin
+) -> None:
+    """Set created_by, updated_by before insert."""
+    principal = get_current_principal()
+    email = principal.user_email if principal else None
+    user_str: str = email or SYSTEM_USER
+    target.created_by = user_str
+    target.updated_by = user_str
+
+
+@event.listens_for(AuditableMixin, "before_update", propagate=True)
+def update_auditable_values(
+    mapper: Mapper, connection: Connection, target: AuditableMixin
+) -> None:
+    """Set updated_by before update."""
+    principal = get_current_principal()
+    email = principal.user_email if principal else None
+    user_str: str = email or SYSTEM_USER
+    target.updated_by = user_str

planar/modeling/mixins/test_auditable.py

@@ -0,0 +1,97 @@
+import pytest
+from sqlmodel import Field, SQLModel
+
+from planar.db import PlanarSession, new_session
+from planar.modeling.mixins.auditable import AuditableMixin
+from planar.security.auth_context import (
+    Principal,
+    as_principal,
+    get_current_principal,
+)
+
+TEST_PRINCIPAL = Principal(
+    sub="test_user",
+    iss="test",
+    exp=1000,
+    iat=1000,
+    sid="test",
+    jti="test",
+    org_id="test",
+    org_name="test",
+    user_first_name="test",
+    user_last_name="test",
+    user_email="test@test.com",
+    role="test",
+    permissions=["test"],
+    extra_claims={"test": "test"},
+)
+
+
+class TestAuditableModel(AuditableMixin, SQLModel, table=True):
+    """Test model using AuditableMixin."""
+
+    __test__ = False
+
+    id: int | None = Field(default=None, primary_key=True)
+    name: str = Field()
+
+
+@pytest.fixture
+async def session(mem_db_engine):
+    """Create a database session."""
+
+    async with new_session(mem_db_engine) as session:
+        await (await session.connection()).run_sync(SQLModel.metadata.create_all)
+        yield session
+
+
+def test_auditable_mixin_has_audit_fields():
+    """Test that AuditableMixin provides default audit fields."""
+    model = TestAuditableModel(name="test")
+
+    assert hasattr(model, "created_by")
+    assert hasattr(model, "updated_by")
+    assert model.created_by == "system"
+    assert model.updated_by == "system"
+
+
+async def test_auditable_mixin_sets_values_on_insert(session: PlanarSession):
+    """Test that audit fields are set from SecurityContext on insert."""
+    with as_principal(TEST_PRINCIPAL):
+        model = TestAuditableModel(name="test_insert")
+        session.add(model)
+        await session.commit()
+
+        # Refresh to get the updated values
+        await session.refresh(model)
+
+        assert model.created_by == "test@test.com"
+        assert model.updated_by == "test@test.com"
+
+
+async def test_auditable_mixin_sets_updated_by_on_update(session: PlanarSession):
+    """Test that updated_by is set from SecurityContext on update."""
+    # First insert with initial user
+    with as_principal(TEST_PRINCIPAL):
+        model = TestAuditableModel(name="test_update")
+        session.add(model)
+        await session.commit()
+        await session.refresh(model)
+
+        assert model.created_by == "test@test.com"
+        assert model.updated_by == "test@test.com"
+
+    # Now update with different user
+    updating_principal = TEST_PRINCIPAL.model_copy(
+        update={"user_email": "updating@test.com"}
+    )
+    with as_principal(updating_principal):
+        assert get_current_principal() == updating_principal
+        model.name = "updated_name"
+        session.add(model)
+        await session.commit()
+        await session.refresh(model)
+
+        # created_by should remain the same, updated_by should change
+        assert model.created_by == "test@test.com"
+        assert model.updated_by == "updating@test.com"

planar/modeling/mixins/test_timestamp.py

@@ -0,0 +1,134 @@
+import asyncio
+from datetime import timedelta
+
+from sqlalchemy.ext.asyncio import AsyncEngine
+from sqlmodel import select
+
+from planar.db import new_session
+from planar.modeling.mixins import TimestampMixin
+from planar.modeling.orm.planar_base_entity import PlanarBaseEntity
+from planar.utils import utc_now
+
+
+class TimestampTestModel(TimestampMixin, PlanarBaseEntity, table=True):
+    """Test model that uses the TimestampMixin."""
+
+    name: str
+    value: int = 0
+
+
+async def test_timestamp_fields_set_on_creation(tmp_db_engine: AsyncEngine):
+    """Test that created_at and updated_at are set when a model is created."""
+    # Record time before the operation
+    before_creation = utc_now()
+
+    # Create and insert model
+    model_id = None
+    async with new_session(tmp_db_engine) as session:
+        model = TimestampTestModel(name="test_item", value=42)
+        session.add(model)
+        await session.commit()
+        model_id = model.id
+
+    # Record time after the operation
+    after_creation = utc_now()
+
+    # Fetch model to verify timestamps
+    async with new_session(tmp_db_engine) as session:
+        created_model = (
+            await session.exec(
+                select(TimestampTestModel).where(TimestampTestModel.id == model_id)
+            )
+        ).one()
+
+    # Verify created_at is set and within the expected time range
+    # and that it equals updated_at
+    assert created_model.created_at is not None
+    assert before_creation <= created_model.created_at <= after_creation
+    assert created_model.created_at == created_model.updated_at
+
+
+async def test_updated_at_reflects_changes(tmp_db_engine: AsyncEngine):
+    """Test that updated_at is updated when a model is modified."""
+    # Create and insert model
+    model_id = None
+    async with new_session(tmp_db_engine) as session:
+        model = TimestampTestModel(name="test_item", value=42)
+        session.add(model)
+        await session.commit()
+        model_id = model.id
+
+        # Get initial created_at and updated_at values
+        initial_model = (
+            await session.exec(
+                select(TimestampTestModel).where(TimestampTestModel.id == model_id)
+            )
+        ).one()
+        await session.commit()
+        initial_created_at = initial_model.created_at
+        initial_updated_at = initial_model.updated_at
+
+    # Wait a moment to ensure timestamp will be different
+    await asyncio.sleep(0.01)
+
+    # Record time before update
+    before_update = utc_now()
+
+    # Update the model
+    async with new_session(tmp_db_engine) as session:
+        model_to_update = (
+            await session.exec(
+                select(TimestampTestModel).where(TimestampTestModel.id == model_id)
+            )
+        ).one()
+        model_to_update.value = 99
+        await session.commit()
+
+    # Record time after update
+    after_update = utc_now()
+
+    # Verify the timestamps
+    async with new_session(tmp_db_engine) as session:
+        updated_model = (
+            await session.exec(
+                select(TimestampTestModel).where(TimestampTestModel.id == model_id)
+            )
+        ).one()
+        await session.commit()
+
+        # created_at should not change
+        assert updated_model.created_at == initial_created_at
+
+        # updated_at should be newer than before
+        assert updated_model.updated_at is not None
+        assert initial_updated_at is not None
+        assert updated_model.updated_at > initial_updated_at
+        assert before_update <= updated_model.updated_at <= after_update
+
+
+async def test_timestamp_init_with_explicit_values():
+    """Test initializing a model with explicit timestamp values."""
+    # Create a specific timestamp
+    now = utc_now()
+    past = now - timedelta(days=1)
+
+    # Initialize model with explicit timestamps
+    model = TimestampTestModel(
+        name="test_explicit_timestamps",
+        value=200,
+        created_at=past,
+        updated_at=now,
+    )
+
+    # Verify timestamps match what we provided
+    assert model.created_at == past
+    assert model.updated_at == now
+
+    # Initialize model with only created_at
+    model2 = TimestampTestModel(
+        name="test_partial_timestamps", value=300, created_at=past
+    )
+
+    # Verify updated_at equals created_at when only created_at is provided
+    assert model2.created_at == past
+    assert model2.updated_at == past

planar/modeling/mixins/test_uuid_primary_key.py

@@ -0,0 +1,52 @@
+from uuid import UUID
+
+from sqlmodel import Field
+
+from planar.db import PlanarSession
+from planar.modeling.mixins.uuid_primary_key import UUIDPrimaryKeyMixin
+from planar.modeling.orm.planar_base_entity import PlanarBaseEntity
+
+
+class UUIDModelTest(PlanarBaseEntity, UUIDPrimaryKeyMixin, table=True):
+    """Test model using UUIDPrimaryKeyMixin."""
+
+    name: str = Field()
+
+
+def test_uuid_primary_key_mixin_creates_uuid_id():
+    """Test that UUIDPrimaryKeyMixin provides a UUID id field."""
+    model = UUIDModelTest(name="test")
+
+    assert hasattr(model, "id")
+    assert isinstance(model.id, UUID)
+    assert model.id is not None
+
+
+def test_uuid_primary_key_mixin_allows_custom_id():
+    """Test that a custom UUID can be provided."""
+    custom_uuid = UUID("12345678-1234-5678-1234-123456789abc")
+    model = UUIDModelTest(id=custom_uuid, name="test")
+
+    assert model.id == custom_uuid
+
+
+async def test_uuid_primary_key_mixin_is_primary_key(session: PlanarSession):
+    """Test that the id field works as a primary key."""
+    model1 = UUIDModelTest(name="test1")
+    model2 = UUIDModelTest(name="test2")
+
+    session.add(model1)
+    session.add(model2)
+    await session.commit()
+
+    # Both should have different IDs
+    assert model1.id != model2.id
+
+    # Both should be retrievable by their IDs
+    retrieved1 = await session.get(UUIDModelTest, model1.id)
+    retrieved2 = await session.get(UUIDModelTest, model2.id)
+
+    assert retrieved1 is not None
+    assert retrieved1.name == "test1"
+    assert retrieved2 is not None
+    assert retrieved2.name == "test2"