julee.util.validation
=====================

.. py:module:: julee.util.validation

.. autoapi-nested-parse::

   Validation utilities for type checking and debugging serialization issues.

   This module provides utilities for validating runtime types against expected
   types, with special focus on debugging common serialization issues in
   Temporal workflows where Pydantic models get deserialized as dictionaries.



Submodules
----------

.. toctree::
   :maxdepth: 1

   /autoapi/julee/util/validation/repository/index
   /autoapi/julee/util/validation/type_guards/index


Exceptions
----------

.. autoapisummary::

   julee.util.validation.RepositoryValidationError
   julee.util.validation.TypeValidationError


Functions
---------

.. autoapisummary::

   julee.util.validation.ensure_repository_protocol
   julee.util.validation.guard_check
   julee.util.validation.validate_parameter_types
   julee.util.validation.validate_repository_protocol
   julee.util.validation.validate_type


Package Contents
----------------

.. py:exception:: RepositoryValidationError

   Bases: :py:obj:`Exception`


   Raised when repository contract validation fails


.. py:exception:: TypeValidationError

   Bases: :py:obj:`TypeError`


   Raised when type validation fails with detailed diagnostics.


.. py:function:: ensure_repository_protocol(repository, protocol)

   Validate and return a repository with proper type annotation.

   This provides both runtime validation and static type checking benefits.

   :param repository: The repository implementation to validate
   :param protocol: The protocol class to validate against

   :returns: The validated repository (type checker knows it satisfies the
             protocol)

   :raises RepositoryValidationError: If validation fails

   .. admonition:: Example

      >>> from julee.util.validation.repository import ensure_repository_protocol
      >>> from julee.domain.repositories import DocumentRepository
      >>> repo = MinioDocumentRepository()
      >>> validated_repo = ensure_repository_protocol(repo, DocumentRepository)
      >>> # Type checker now knows validated_repo satisfies DocumentRepository


.. py:function:: guard_check(value, expected_type, context_name = 'value')

   Simple guard check function for manual validation.

   Usage:
       guard_check(queries, Dict[str, KnowledgeServiceQuery], "queries")
       guard_check(document, Document, "document")


.. py:function:: validate_parameter_types(**expected_types)

   Decorator to validate function parameters against their expected types.

   Usage:
       @validate_parameter_types(queries=Dict[str, KnowledgeServiceQuery])
       def my_function(self, queries):
           # parameters are validated before function runs
           pass

   Or automatically from type hints:
       @validate_parameter_types()
       def my_function(self, queries: Dict[str, KnowledgeServiceQuery]):
           # type hints are used automatically
           pass


.. py:function:: validate_repository_protocol(repository, protocol)

   Validate that a repository implementation satisfies a protocol contract.

   Uses Python's built-in isinstance() with @runtime_checkable for robust,
   idiomatic protocol validation.

   :param repository: The repository implementation to validate
   :param protocol: The protocol class to validate against

   :raises RepositoryValidationError: If validation fails

   .. admonition:: Example

      >>> from julee.util.validation.repository import validate_repository_protocol
      >>> from julee.domain.repositories import DocumentRepository
      >>> repo = MinioDocumentRepository()
      >>> validate_repository_protocol(repo, DocumentRepository)


.. py:function:: validate_type(value, expected_type, context_name = 'value', allow_none = False)

   Validate that a value matches the expected type with detailed diagnostics.

   :param value: The actual value to validate
   :param expected_type: The expected type (from type hints)
   :param context_name: Name for error messages (e.g., "parameter 'queries'")
   :param allow_none: Whether None values are acceptable

   :raises TypeValidationError: With detailed diagnosis if type doesn't match