Skip to content

Contracts

Use these helpers in Annotated DataFrame parameters and return types to choose how a transform checks a schema. Each helper takes a dataclass or Pydantic model.

data_joinery.contract.Strict 

Strict(schema)

Require the DataFrame to have exactly the model's fields and types.

Field order and nullability are ignored.

PARAMETER DESCRIPTION
schema

Dataclass or Pydantic model that defines the expected fields.

TYPE: type

RETURNS DESCRIPTION
DataFrameContract

A DataFrame contract for use in a transform annotation.
Source code in src/data_joinery/contract.py 
193
194
195
196
197
198
199
200
201
202
203
204
def Strict(schema: type) -> DataFrameContract:
    """Require the DataFrame to have exactly the model's fields and types.

    Field order and nullability are ignored.

    Args:
        schema: Dataclass or Pydantic model that defines the expected fields.

    Returns:
        A DataFrame contract for use in a transform annotation.
    """
    return DataFrameContract(coercion_mode="strict", schema=Schema(schema))

data_joinery.contract.ProjectTopLevel 

ProjectTopLevel(schema)

Keep the model's top-level columns and validate nested fields.

PARAMETER DESCRIPTION
schema

Dataclass or Pydantic model that defines the expected fields.

TYPE: type

RETURNS DESCRIPTION
DataFrameContract

A DataFrame contract for use in a transform annotation.
Source code in src/data_joinery/contract.py 
169
170
171
172
173
174
175
176
177
178
def ProjectTopLevel(schema: type) -> DataFrameContract:
    """Keep the model's top-level columns and validate nested fields.

    Args:
        schema: Dataclass or Pydantic model that defines the expected fields.

    Returns:
        A DataFrame contract for use in a transform annotation.
    """
    return DataFrameContract(coercion_mode="project_top_level", schema=Schema(schema))

data_joinery.contract.Project 

Project(schema)

Keep the model's fields, including fields in nested structs.

PARAMETER DESCRIPTION
schema

Dataclass or Pydantic model that defines the expected fields.

TYPE: type

RETURNS DESCRIPTION
DataFrameContract

A DataFrame contract for use in a transform annotation.
Source code in src/data_joinery/contract.py 
181
182
183
184
185
186
187
188
189
190
def Project(schema: type) -> DataFrameContract:
    """Keep the model's fields, including fields in nested structs.

    Args:
        schema: Dataclass or Pydantic model that defines the expected fields.

    Returns:
        A DataFrame contract for use in a transform annotation.
    """
    return DataFrameContract(coercion_mode="project", schema=Schema(schema))

data_joinery.contract.ProjectCast 

ProjectCast(schema)

Project columns and cast their values to the model's field types.

PARAMETER DESCRIPTION
schema

Dataclass or Pydantic model that defines the expected fields.

TYPE: type

RETURNS DESCRIPTION
DataFrameContract

A DataFrame contract for use in a transform annotation.
Source code in src/data_joinery/contract.py 
157
158
159
160
161
162
163
164
165
166
def ProjectCast(schema: type) -> DataFrameContract:
    """Project columns and cast their values to the model's field types.

    Args:
        schema: Dataclass or Pydantic model that defines the expected fields.

    Returns:
        A DataFrame contract for use in a transform annotation.
    """
    return DataFrameContract(coercion_mode="project_cast", schema=Schema(schema))

Strict is also the default mode for Schema.coerce_dataframe().

No output

data_joinery.contract.VoidContract dataclass 

VoidContract()

Contract for transforms that do not produce an output.

accepts 

accepts(produced)
Source code in src/data_joinery/contract.py 
47
48
def accepts(self, produced: Contract) -> bool:
    return isinstance(produced, VoidContract)

validate 

validate(value)
Source code in src/data_joinery/contract.py 
50
51
52
def validate(self, value: object) -> None:
    if value is not None:
        raise ContractTypeMismatch("None")