crosscontract 0.2.2__py3-none-any.whl

crosscontract/__init__.py

@@ -0,0 +1,14 @@
+"""crosscontract package for data contracts and related utilities."""
+
+from .contracts import BaseContract, CrossContract, SchemaValidationError, TableSchema
+from .crossclient import CrossClient
+
+__version__ = "0.2.2"
+
+__all__ = [
+    "CrossClient",
+    "CrossContract",
+    "TableSchema",
+    "BaseContract",
+    "SchemaValidationError",
+]

crosscontract/contracts/__init__.py

@@ -0,0 +1,9 @@
+from .contracts import BaseContract, CrossContract
+from .schema import SchemaValidationError, TableSchema
+
+__all__ = [
+    "TableSchema",
+    "BaseContract",
+    "CrossContract",
+    "SchemaValidationError",
+]

crosscontract/contracts/contracts/__init__.py

@@ -0,0 +1,4 @@
+from .base_contract import BaseContract, BaseMetaData
+from .cross_contract import CrossContract, CrossMetaData
+
+__all__ = ["BaseContract", "CrossContract", "BaseMetaData", "CrossMetaData"]

crosscontract/contracts/contracts/base_contract.py

@@ -0,0 +1,103 @@
+from pathlib import Path
+from typing import Self
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+from ..schema import TableSchema
+from ..utils import read_yaml_or_json_file
+
+
+class BaseMetaData(BaseModel):
+    """
+    The BaseMetadata class encapsulates the essential metadata attributes
+    required for defining a data contract. Every data contract MUST include
+    these metadata fields to ensure proper identification and description.
+    To extend the metadata for specific use cases, inherit from this class
+    and add additional fields as necessary. Then use the extended metadata
+    class as a base for your custom contract together with BaseContract.
+
+    Attributes:
+        name (str): A unique identifier for the data contract.
+            Must contain only alphanumeric characters, underscores, or hyphens.
+            Maximum length is 100 characters.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    name: str = Field(
+        pattern="^[a-zA-Z0-9_-]+$",
+        max_length=100,
+        description="A unique identifier for the data contract.",
+    )
+
+
+class BaseContract(BaseMetaData):
+    """
+    The BaseContract class is the most basic representation of a data contract.
+    It combines the minimum required metadata with the contract structure given by
+    Schema.
+
+    It serves as the foundational blueprint for defining data contracts.
+    Any custom contract implementation MUST inherit from this class to ensure
+    structural consistency and compatibility with the system.
+
+    Attributes:
+        name (str): A unique identifier for the data contract.
+            Must contain only alphanumeric characters, underscores, or hyphens.
+            Maximum length is 100 characters.
+        tableschema (TableSchema): The schema defining the structure of the contract
+            (fields, primary keys, foreign keys, field descriptors).
+
+    Example:
+        To implement a custom contract with additional metadata:
+
+        ```python
+        from pydantic import Field
+        from crosscontract.contracts import BaseContract
+
+        class MyCustomContract(BaseContract):
+            # Add custom metadata fields
+            owner: str = Field(description="The owner of this dataset")
+            version: str = Field(description="Semantic version of the contract")
+
+            # The 'schema' field is already inherited from BaseContract!
+        ```
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+    tableschema: TableSchema = Field(
+        description="The Frictionless Table Schema definition.",
+    )
+
+    @classmethod
+    def from_file(cls, file_path: str | Path) -> Self:
+        """
+        Load a BaseContract from a YAML or JSON file.
+
+        Args:
+            file_path (str | Path): The path to the YAML or JSON file.
+
+        Returns:
+            Self: An instance of BaseContract loaded from the file.
+
+        Raises:
+            FileNotFoundError: If the specified file does not exist.
+            ValueError: If the file format is not supported (not .json, .yaml, or .yml).
+        """
+        data = read_yaml_or_json_file(file_path)
+        return cls.model_validate(data)
+
+    @model_validator(mode="after")
+    def validate_self_reference(self) -> Self:
+        """Validate that self-referencing foreign keys are given as None on the
+        resource field. Raise if a reference has the same name as the contract itself.
+        """
+        for fk in self.tableschema.foreignKeys:
+            if fk.reference.resource == self.name:
+                raise ValueError(
+                    f"Foreign key reference resource '{fk.reference.resource}' "
+                    "cannot be the same as the contract name. Self-references must "
+                    "use None for the resource field."
+                )
+        return self

crosscontract/contracts/contracts/cross_contract.py

@@ -0,0 +1,64 @@
+from pydantic import ConfigDict, Field
+
+from .base_contract import BaseContract, BaseMetaData
+
+
+class CrossMetaData(BaseMetaData):
+    """
+    Metadata specific to the CrossContract system,
+    extending the base metadata requirements
+
+    Attributes:
+        title (str): A human-readable title for the data.
+        description (str): A human-readable description of the data.
+        tags (list[str] | None): A list of tags for categorization and filtering.
+    """
+
+    model_config = ConfigDict(str_strip_whitespace=True)
+    title: str = Field(
+        description=(
+            "A human-readable title for the data."
+            "Think of this as the label that will be used in graphs and tables."
+        ),
+    )
+
+    description: str = Field(
+        description=(
+            "A human-readable description of the data. This should explain what "
+            " the data is about."
+        )
+    )
+
+    tags: list[str] = Field(
+        default_factory=list,
+        description=(
+            "A list of tags that can be used to categorize the table. "
+            "This can be used to filter tables in the UI."
+        ),
+    )
+
+
+class CrossContract(BaseContract, CrossMetaData):
+    """
+    A concrete implementation of a data contract for the CrossContract system.
+
+    This class extends `BaseContract` by adding tagging capabilities.
+    It serves as the standard contract definition for resources within the
+    CrossContract ecosystem.
+
+    Attributes:
+        name (str): A unique identifier for the data contract.
+            Must contain only alphanumeric characters, underscores, or hyphens.
+            Inherited from BaseContract.
+        title (str): A human-readable title for the data.
+        description (str): A human-readable description of the data.
+        tags (list[str] | None): A list of tags used for categorization and filtering.
+        schema (Schema): The Frictionless Table Schema definition.
+            Accessible via the `schema` property as well.
+    """
+
+    model_config = ConfigDict(
+        populate_by_name=True,
+        extra="forbid",
+        serialize_by_alias=True,
+    )

crosscontract/contracts/schema/__init__.py

@@ -0,0 +1,29 @@
+"""The schema is at the core of a contract, defining the structure and types of
+data it holds. Schemas ensure data integrity and consistency across different systems
+and applications. Schemas are based on Fritionless Schema
+standard (https://frictionlessdata.io/docs/specs/schema/).
+
+A schema consists of a collection of fields, each representing a specific data
+type and its associated constraints. The schema defines how data should be
+validated in the context of a contract.
+
+To make schemas operational, there are methods to convert schema definitions into
+Pydantic or Pandera models for data validation and manipulation, as well as into
+SQLAlchemy columns, enabling seamless integration with databases.
+"""
+
+from .adapters import (
+    convert_schema_to_pandera,
+    convert_schema_to_pydantic,
+    convert_schema_to_sqlalchemy,
+)
+from .exceptions import SchemaValidationError
+from .schema import TableSchema
+
+__all__ = [
+    "TableSchema",
+    "convert_schema_to_pydantic",
+    "convert_schema_to_pandera",
+    "convert_schema_to_sqlalchemy",
+    "SchemaValidationError",
+]

crosscontract/contracts/schema/adapters/__init__.py

@@ -0,0 +1,18 @@
+"""Adapters take a schema and convert it to a different format.
+For example, the PydanticAdapter converts a schema into a corresponding pydantic
+model that allows to validate a single row of data against the schema. Likewise,
+the PanderaAdapter converts a schema into a corresponding pandera schema that allows
+to validate a dataframe against the schema."""
+
+from .pandera_adapter import PanderaPandasAdapter, convert_schema_to_pandera
+from .pydantic_adapter import PydanticAdapter, convert_schema_to_pydantic
+from .sqlalchemy_adapter import SQLAlchemyPostgresAdapter, convert_schema_to_sqlalchemy
+
+__all__ = [
+    "PydanticAdapter",
+    "convert_schema_to_pydantic",
+    "SQLAlchemyPostgresAdapter",
+    "convert_schema_to_sqlalchemy",
+    "PanderaPandasAdapter",
+    "convert_schema_to_pandera",
+]

crosscontract/contracts/schema/adapters/abstract_adapter.py

@@ -0,0 +1,30 @@
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:  # pragma: no cover
+    from crosscontract.contracts.schema import TableSchema
+
+
+class AbstractAdapter(ABC):
+    """
+    Abstract base class for schema adapters. Adapters are responsible for converting
+    a TableSchema into a specific format, such as a Pydantic model, a Pandera DataFrame,
+    or SQLAlchemy columns.
+    """
+
+    def __init__(self, schema: "TableSchema", *args, **kwargs: Any):
+        self.schema = schema
+
+    @abstractmethod
+    def convert(self, *args, **kwargs) -> Any:
+        """Convert the given TableSchema into the target format."""
+        pass
+
+    @classmethod
+    @abstractmethod
+    def convert_schema(cls, schema: "TableSchema", *args, **kwargs) -> Any:
+        """Convenience method to convert a TableSchema without needing to instantiate
+        the adapter. Needs to be implemented by each adapter class to force
+        documentation of the expected arguments. But can simply call the instance
+        method by default."""
+        return cls(schema).convert(*args, **kwargs)