### Generate Test Data with Patito Examples

Source: https://github.com/jakobgm/patito/blob/main/README.md

Demonstrates how to use the `Product.examples()` method to create a dataframe with valid dummy data. This method fills in unspecified columns based on the model schema, simplifying test setup.

```python
products = Product.examples({"is_for_sale": [True, True, False]})
```

--------------------------------

### Generate example values for model fields

Source: https://github.com/jakobgm/patito/blob/main/docs/api/patito/Model/example_value.md

Define a `patito.Model` and then use `example_value` to get sample data for specific fields like 'product_id', 'name', or 'temperature_zone'.

```python
class Product(pt.Model):
    product_id: int = pt.Field(unique=True)
    name: str
    temperature_zone: Literal["dry", "cold", "frozen"]

Product.example_value("product_id")
Product.example_value("name")
Product.example_value("temperature_zone")
```

--------------------------------

### Install Patito

Source: https://github.com/jakobgm/patito/blob/main/docs/index.md

Install the Patito library using pip.

```console
pip install patito
```

--------------------------------

### Install Pre-commit Hooks

Source: https://github.com/jakobgm/patito/blob/main/docs/index.md

Set up pre-commit hooks for the project using uv.

```console
uv run pre-commit install
```

--------------------------------

### Generate DataFrame with patito.Model.pandas_examples

Source: https://github.com/jakobgm/patito/blob/main/docs/api/patito/Model/pandas_examples.md

Create a pandas DataFrame with dummy data for a patito Model. This example shows how to provide partial data, and patito fills in the rest.

```python
Product.pandas_examples({"name": ["product A", "product B"]})
```

--------------------------------

### Generate Model Instance with Dummy Data

Source: https://github.com/jakobgm/patito/blob/main/docs/api/patito/Model/example.md

Use the `example` class method to create a model instance with dummy data for unspecified fields. Provide keyword arguments to override dummy values for specific fields. This is useful for testing or generating sample data.

```python
>>> from typing import Literal
>>> import patito as pt
```

```python
>>> class Product(pt.Model):
...     product_id: int = pt.Field(unique=True)
...     name: str
...     temperature_zone: Literal["dry", "cold", "frozen"]
...
>>> Product.example(product_id=1)
Product(product_id=1, name='dummy_string', temperature_zone='dry')
```

--------------------------------

### Define a patito Model with dummy data generation

Source: https://github.com/jakobgm/patito/blob/main/docs/api/patito/Model/examples.md

Define a sample Product model inheriting from pt.Model. This snippet sets up a model with different data types and a unique field, preparing it for example data generation.

```python
class Product(pt.Model):
    product_id: int = pt.Field(unique=True)
    name: str
    temperature_zone: Literal["dry", "cold", "frozen"]
```

--------------------------------

### Define a Model

Source: https://github.com/jakobgm/patito/blob/main/docs/api/patito/Model/select.md

Defines a sample model with three integer fields (a, b, c) for use in subsequent examples.

```python
>>> class MyModel(Model):
...     a: int
...     b: int
...     c: int
...
```

--------------------------------

### Define Models for Joining

Source: https://github.com/jakobgm/patito/blob/main/docs/api/patito/Model/join.md

Define two simple patito Models, A and B, each with a single integer field, to be used in join examples.

```python
>>> class A(Model):
...     a: int
...
>>> class B(Model):
...     b: int
...
```

--------------------------------

### Model.example_value

Source: https://github.com/jakobgm/patito/blob/main/docs/api/patito/Model/example_value.md

Returns a valid example value for a given model field. This method is useful for generating test data or understanding the expected data types for your model fields.

```APIDOC
## classmethod Model.example_value(field: str | None = None, properties: dict[str, Any] | None = None) -> date | datetime | time | timedelta | float | int | str | None | Mapping | list

### Description
Return a valid example value for the given model field.

### Parameters
#### Parameters
- **field** (str | None) - Field name identifier.
- **properties** (dict[str, Any] | None) - Pydantic v2-style properties dict

### Returns
A single value which is consistent with the given field definition.

### Raises
**NotImplementedError** – If the given field has no example generator.

### Example
```pycon
>>> from typing import Literal
>>> import patito as pt
>>> class Product(pt.Model):
...     product_id: int = pt.Field(unique=True)
...     name: str
...     temperature_zone: Literal["dry", "cold", "frozen"]
...
>>> Product.example_value("product_id")
-1
>>> Product.example_value("name")
'dummy_string'
>>> Product.example_value("temperature_zone")
'dry'
```
```

--------------------------------

### Get Model Columns

Source: https://github.com/jakobgm/patito/blob/main/docs/api/patito/Model/columns.md

Demonstrates how to access the `columns` property on a `patito.Model` subclass to get the list of field names. This property is automatically generated based on the model's field definitions.

```python
>>> import patito as pt
>>> class Product(pt.Model):
...     name: str
...     price: int
...
>>> Product.columns
['name', 'price']
```

--------------------------------

### Accessing Nullable Columns in a Patito Model

Source: https://github.com/jakobgm/patito/blob/main/docs/api/patito/Model/nullable_columns.md

Demonstrates how to define a patito Model with both nullable and non-nullable fields and then access the `nullable_columns` property to get a sorted list of nullable field names. Ensure `Optional` from `typing` is imported.

```python
>>> from typing import Optional
>>> import patito as pt
>>> class MyModel(pt.Model):
...     nullable_field: Optional[int]
...     another_nullable_field: Optional[int] = None
...     non_nullable_field: int
...     another_non_nullable_field: str
...
>>> sorted(MyModel.nullable_columns)
['another_nullable_field', 'nullable_field']
```

--------------------------------

### Define and Use Custom Model with get()

Source: https://github.com/jakobgm/patito/blob/main/docs/api/patito/DataFrame/get.md

Associates a custom Pydantic model with the DataFrame and uses it to represent the fetched row.

```python
class Product(pt.Model):
    product_id: int = pt.Field(unique=True)
    price: float

df.set_model(Product).get(pl.col("product_id") == 1)
```

--------------------------------

### Define Model Fields with Patito Field Constraints

Source: https://github.com/jakobgm/patito/blob/main/docs/api/patito/Field/index.md

Use patito.Field to specify constraints like uniqueness, data types, and string length for model fields. This example demonstrates defining 'product_id', 'price', and 'name' with specific validation rules.

```python
import patito as pt
import polars as pl

class Product(pt.Model):
    # Do not allow duplicates
    product_id: int = pt.Field(unique=True)

    # Price must be stored as unsigned 16-bit integers
    price: int = pt.Field(dtype=pl.UInt16)

    # The product name should be from 3 to 128 characters long
    name: str = pt.Field(min_length=3, max_length=128)


Product.DataFrame(
    {
        "product_id": [1, 1],
        "price": [400, 600],
    }
).validate()

```

--------------------------------

### Get Polars dtypes from a patito Model

Source: https://github.com/jakobgm/patito/blob/main/docs/api/patito/Model/dtypes.md

Instantiate a patito Model and access its `dtypes` property to retrieve a dictionary of column names and their corresponding Polars dtype classes. This shows the inferred Polars types for the model's fields.

```python
>>> import patito as pt
>>> class Product(pt.Model):
...     name: str
...     ideal_temperature: int
...     price: float
...
>>> Product.dtypes
{'name': String, 'ideal_temperature': Int64, 'price': Float64}
```

--------------------------------

### Import necessary modules

Source: https://github.com/jakobgm/patito/blob/main/docs/api/patito/Model/example_value.md

Before using `example_value`, import `typing` and `patito`.

```python
from typing import Literal
import patito as pt
```

--------------------------------

### Get Non-Nullable Columns from Model

Source: https://github.com/jakobgm/patito/blob/main/docs/api/patito/Model/non_nullable_columns.md

Use the `non_nullable_columns` property on a patito Model class to get a set of strings representing the names of columns that do not allow null values. This is useful for validating data integrity.

```python
>>> from typing import Optional
>>> import patito as pt
>>> class MyModel(pt.Model):
...     nullable_field: Optional[int]
...     another_nullable_field: Optional[int] = None
...     non_nullable_field: int
...     another_non_nullable_field: str
...
>>> sorted(MyModel.non_nullable_columns)
['another_non_nullable_field', 'non_nullable_field']
```

--------------------------------

### Create DataFrame

Source: https://github.com/jakobgm/patito/blob/main/docs/api/patito/DataFrame/get.md

Initializes a Patito DataFrame with sample data.

```python
df = pt.DataFrame({"product_id": [1, 2, 3], "price": [10, 10, 20]})
```

--------------------------------

### Get Single Row Without Predicate

Source: https://github.com/jakobgm/patito/blob/main/docs/api/patito/DataFrame/get.md

Fetches the single row from a DataFrame that is known to contain exactly one row.

```python
df.filter(pl.col("product_id") == 1).get()
```

--------------------------------

### Get Row with Predicate (Untyped)

Source: https://github.com/jakobgm/patito/blob/main/docs/api/patito/DataFrame/get.md

Fetches a single row matching the predicate using a dynamically constructed pydantic model.

```python
df.get(pl.col("product_id") == 1)
```

--------------------------------

### Define Product Model and Process DataFrame

Source: https://github.com/jakobgm/patito/blob/main/README.md

Illustrates defining a Patito model with fields, default values, and derived columns, then processing a DataFrame through a chain of model-aware methods.

```python
from typing import Literal

import patito as pt
import polars as pl


class Product(pt.Model):
    product_id: int = pt.Field(unique=True)
    # Specify a specific dtype to be used
    popularity_rank: int = pt.Field(dtype=pl.UInt16)
    # Field with default value "for-sale"
    status: Literal["draft", "for-sale", "discontinued"] = "for-sale"
    # The eurocent cost is extracted from the Euro cost string "€X.Y EUR"
    eurocent_cost: int = pt.Field(
        derived_from=100 * pl.col("cost").str.extract(r"€(\d+\.\+\d+)").cast(float).round(2)
    )


products = pt.DataFrame(
    {
        "product_id": [1, 2],
        "popularity_rank": [2, 1],
        "status": [None, "discontinued"],
        "cost": ["€2.30 EUR", "€1.19 EUR"],
    }
)
product = (
    products
    # Specify the schema of the given data frame
    .set_model(Product)
    # Derive the `eurocent_cost` int column from the `cost` string column using regex
    .derive()
    # Drop the `cost` column as it is not part of the model
    .drop()
    # Cast the popularity rank column to an unsigned 16-bit integer and cents to an integer
    .cast()
    # Fill missing values with the default values specified in the schema
    .fill_null(strategy="defaults")
    # Assert that the data frame now complies with the schema
    .validate()
    # Retrieve a single row and cast it to the model class
    .get(pl.col("product_id") == 1)
)
print(repr(product))
```

--------------------------------

### Test Function Using Patito Generated Data

Source: https://github.com/jakobgm/patito/blob/main/README.md

Shows a refactored test function that utilizes `Product.examples()` to generate test data. This approach avoids manual creation of dummy data and reduces boilerplate, making the test cleaner.

```python
def test_num_products_for_sale():
    products = Product.examples({"is_for_sale": [True, True, False]})
    assert num_products_for_sale(products) == 2
```

--------------------------------

### Instantiate and Validate a Product Object

Source: https://github.com/jakobgm/patito/blob/main/docs/tutorial/dataframe-validation.md

Create an instance of a Patito model. The model automatically validates the input data against the defined types and constraints.

```python
>>> Product(product_id=1, name="Apple", temperature_zone="dry", demand_percentage=0.23)
Product(product_id=1, name='Apple', temperature_zone='dry', demand_percentage=0.23)
```

--------------------------------

### DataFrame.set_model

Source: https://github.com/jakobgm/patito/blob/main/docs/api/patito/DataFrame/set_model.md

Associates a patito Model with the DataFrame. The model schema is used by methods that depend on a model being associated with the given DataFrame, such as validate() and get().

```APIDOC
## DataFrame.set_model

### Description
Associate a given patito `Model` with the dataframe. The model schema is used by methods that depend on a model being associated with the given dataframe such as `DataFrame.validate()` and `DataFrame.get()`.

`DataFrame(...).set_model(Model)` is equivalent with `Model.DataFrame(...)`.

### Method
```python
DataFrame.set_model(model: type[OtherModelType]) -> DataFrame[OtherModelType]
```

### Parameters
#### Path Parameters
* **model** (`Model`) – Sub-class of `patito.Model` declaring the schema of the dataframe.

### Returns
Returns the same dataframe, but with an attached model that is required for certain model-specific dataframe methods to work.

### Return type
[DataFrame](index.md#patito.DataFrame)[[Model](../Model/index.md#patito.Model)]

### Examples
```pycon
>>> from typing_extensions import Literal
>>> import patito as pt
>>> import polars as pl
>>> class SchoolClass(pt.Model):
...     year: int = pt.Field(dtype=pl.UInt16)
...     letter: Literal["A", "B"] = pt.Field(dtype=pl.Categorical)
...
>>> classes = pt.DataFrame(
...     {"year": [1, 1, 2, 2], "letter": list("ABAB")}
... ).set_model(SchoolClass)
>>> classes
shape: (4, 2)
┌──────┬────────┐
│ year ┆ letter │
│ ---  ┆ ---    │
│ i64  ┆ str    │
╞══════╪════════╡
│ 1    ┆ A      │
│ 1    ┆ B      │
│ 2    ┆ A      │
│ 2    ┆ B      │
└──────┴────────┘
>>> casted_classes = classes.cast()
>>> casted_classes
shape: (4, 2)
┌──────┬────────┐
│ year ┆ letter │
│ ---  ┆ ---    │
│ u16  ┆ cat    │
╞══════╪════════╡
│ 1    ┆ A      │
│ 1    ┆ B      │
│ 2    ┆ A      │
│ 2    ┆ B      │
└──────┴────────┘
>>> casted_classes.validate()
```
```

--------------------------------

### Model.example

Source: https://github.com/jakobgm/patito/blob/main/docs/api/patito/Model/example.md

Produces a model instance with dummy data for all unspecified fields. The type annotation of unspecified fields is used to fill in type-correct dummy data. The first item of Literal annotations is used for dummy values.

```APIDOC
## classmethod Model.example

### Description
Produce model instance with filled dummy data for all unspecified fields.

The type annotation of unspecified field is used to fill in type-correct
dummy data, e.g. `-1` for `int`, `"dummy_string"` for `str`, and so
on…

The first item of `typing.Literal` annotations are used for dummy values.

### Parameters
#### Keyword Arguments
- **kwargs**: Provide explicit values for any fields which should not be
  filled with dummy data.

### Returns
A pydantic model object filled with dummy data for all unspecified
model fields.

### Return type
[Model](index.md#patito.Model)

### Raises
**TypeError** – If one or more of the provided keyword arguments do not match any
    fields on the model.

### Example

```pycon
>>> from typing import Literal
>>> import patito as pt
```

```pycon
>>> class Product(pt.Model):
...     product_id: int = pt.Field(unique=True)
...     name: str
...     temperature_zone: Literal["dry", "cold", "frozen"]
...
>>> Product.example(product_id=1)
Product(product_id=1, name='dummy_string', temperature_zone='dry')
```
```

--------------------------------

### Model.pandas_examples

Source: https://github.com/jakobgm/patito/blob/main/docs/api/patito/Model/pandas_examples.md

Generates a pandas DataFrame with dummy data for all unspecified columns, mirroring the pandas.DataFrame constructor's API. Non-iterable values are repeated to match the length of iterable arguments.

```APIDOC
## classmethod Model.pandas_examples

### Description
Generate dataframe with dummy data for all unspecified columns. Offers the same API as the pandas.DataFrame constructor. Non-iterable values, besides strings, are repeated until they become as long as the iterable arguments.

### Method
classmethod

### Signature
Model.pandas_examples(data: dict | Iterable, columns: Iterable[str] | None = None) -> pd.DataFrame

### Parameters
#### Data
- **data** (dict | Iterable) - Required - Data to populate the dummy dataframe with. If not a dict, column names must also be provided.
- **columns** (Iterable[str] | None) - Optional - Ignored if data is a dict. If data is an iterable, it will be used as the column names in the resulting dataframe.

### Returns
- **pd.DataFrame** - A pandas DataFrame filled with dummy example data.

### Raises
- **ImportError** - If pandas has not been installed. You should install patito[pandas] in order to integrate patito with pandas.
- **TypeError** - If column names have not been specified in the input data.

### Example
```pycon
>>> from typing import Literal
>>> import patito as pt

>>> class Product(pt.Model):
...     product_id: int = pt.Field(unique=True)
...     name: str
...     temperature_zone: Literal["dry", "cold", "frozen"]
...

>>> Product.pandas_examples({"name": ["product A", "product B"]})
product_id       name temperature_zone
0          -1  product A              dry
1          -1  product B              dry
```
```

--------------------------------

### Import patito library

Source: https://github.com/jakobgm/patito/blob/main/docs/api/patito/DataFrame/validate.md

Import the patito library to use its functionalities.

```python
import patito as pt
```

--------------------------------

### Validate a DataFrame with errors

Source: https://github.com/jakobgm/patito/blob/main/docs/api/patito/Model/validate.md

Validate a Polars DataFrame against the Product model. This example demonstrates how validation errors for missing columns, duplicate values, and invalid enumerated values are caught and reported.

```python
df = pl.DataFrame(
    {
        "product_id": [1, 1, 3],
        "temperature_zone": ["dry", "dry", "oven"],
    }
)
try:
    Product.validate(df)
except pt.DataFrameValidationError as exc:
    print(exc)
```

--------------------------------

### Run Nox for Development Tasks

Source: https://github.com/jakobgm/patito/blob/main/docs/index.md

Execute tests, linting, and other development tasks using Nox, managed by uv.

```console
uv run nox
```

--------------------------------

### Define Product Model with Field Constraints

Source: https://github.com/jakobgm/patito/blob/main/README.md

Illustrates how to define a data model with various field constraints using `patito.Field`. This includes specifying dtypes, uniqueness, bounds, multiples, default values, and regex patterns for string validation.

```python
import polars as pl
import patito as pt

class Product(pt.BaseModel):
    is_for_sale: bool
    temperature_zone: str = pt.Field(min_length=1)
    product_id: int = pt.Field(gt=0, lt=1000)

    class Meta:
        # Example of a custom constraint applied to all rows
        constraints = [
            pl.col("product_id") % 2 == 0
        ]
        # Example of a default value for a column
        defaults = {
            "temperature_zone": "dry"
        }
```

--------------------------------

### Define Product Model with URL Property

Source: https://github.com/jakobgm/patito/blob/main/README.md

Defines a Patito model with basic fields and adds a computed property 'url' that generates a URL based on the model's attributes.

```python
# models.py
import patito as pt

class Product(pt.Model):
    product_id: int = pt.Field(unique=True)
    name: str

    @property
    def url(self) -> str:
        return (
            "https://example.com/no/products/"
            f"{self.product_id}-"
            f"{self.name.lower().replace(' ', '-')}"
        )
```

--------------------------------

### Model.examples

Source: https://github.com/jakobgm/patito/blob/main/docs/api/patito/Model/examples.md

Generates a polars DataFrame with dummy data for all unspecified columns. This class method accepts data in a format compatible with polars.DataFrame.

```APIDOC
## classmethod Model.examples

### Description
Generate polars dataframe with dummy data for all unspecified columns.
This constructor accepts the same data format as polars.DataFrame.

### Method
classmethod

### Signature
Model.examples(data: dict | Iterable | None = None, columns: Iterable[str] | None = None) -> patito.polars.DataFrame

### Parameters
#### Parameters
- **data** (dict | Iterable | None) - Data to populate the dummy dataframe with. If given as an iterable of values, then column names must also be provided. If not provided at all, a dataframe with a single row populated with dummy data is provided.
- **columns** (Iterable[str] | None) - Ignored if `data` is provided as a dictionary. If data is provided as an `iterable`, then `columns` will be used as the column names in the resulting dataframe. Defaults to None.

### Returns
A polars dataframe where all unspecified columns have been filled with dummy data which should pass model validation.

### Raises
**TypeError** – If one or more of the model fields are not mappable to polars column dtype equivalents.

### Example
```python
>>> from typing import Literal
>>> import patito as pt

>>> class Product(pt.Model):
...     product_id: int = pt.Field(unique=True)
...     name: str
...     temperature_zone: Literal["dry", "cold", "frozen"]

>>> Product.examples()
shape: (1, 3)
┌──────────────┬──────────────────┬────────────┐
│ name         ┆ temperature_zone ┆ product_id │
│ ---          ┆ ---              ┆ ---        │
│ str          ┆ enum             ┆ i64        │
╞══════════════╪══════════════════╪════════════╡
│ dummy_string ┆ dry              ┆ 1          │
└──────────────┴──────────────────┴────────────┘

>>> Product.examples({"name": ["product A", "product B"]})
shape: (2, 3)
┌───────────┬──────────────────┬────────────┐
│ name      ┆ temperature_zone ┆ product_id │
│ ---       ┆ ---              ┆ ---        │
│ str       ┆ enum             ┆ i64        │
╞═══════════╪══════════════════╪════════════╡
│ product A ┆ dry              ┆ 1          │
│ product B ┆ dry              ┆ 2          │
└───────────┴──────────────────┴────────────┘
```
```

--------------------------------

### List Model Columns

Source: https://github.com/jakobgm/patito/blob/main/docs/api/patito/Model/drop.md

View all columns defined in the model.

```python
MyModel.columns
```

--------------------------------

### Apply Suffix to Model Fields

Source: https://github.com/jakobgm/patito/blob/main/docs/api/patito/Model/suffix.md

Demonstrates how to use the Model.suffix class method to create a new model where all field names are appended with '_x'. It then shows how to access the suffixed column names.

```python
>>> MyModel.suffix("_x").columns
['a_x', 'b_x']
```

--------------------------------

### Retrieve Model Instance using DataFrame.get()

Source: https://github.com/jakobgm/patito/blob/main/README.md

Shows how to use the `.get()` method on a Patito DataFrame (connected to a model) to filter a single row and cast it directly to the model class.

```python
products = Product.DataFrame(
    {
        "product_id": [1, 2],
        "name": ["Skimmed milk", "Eggs"],
    }
)
milk = products.get(pl.col("product_id") == 1)
print(milk.url)
```

--------------------------------

### Apply prefix and check columns

Source: https://github.com/jakobgm/patito/blob/main/docs/api/patito/Model/prefix.md

Apply a prefix to the model and verify that the field names have been updated in the columns attribute.

```python
MyModel.prefix("x_").columns
```

--------------------------------

### Define a Patito Model for Product Data

Source: https://github.com/jakobgm/patito/blob/main/docs/tutorial/dataframe-validation.md

Define a data model using patito.Model with type annotations for each column. Use typing.Literal to enforce specific string values for a column.

```python
from typing import Literal

import patito as pt


class Product(pt.Model):
    product_id: int
    name: str
    temperature_zone: Literal["dry", "cold", "frozen"]
    demand_percentage: float
```

--------------------------------

### Model.prefix

Source: https://github.com/jakobgm/patito/blob/main/docs/api/patito/Model/prefix.md

Returns a new model where all field names have been prefixed. This is a class method.

```APIDOC
## classmethod Model.prefix(prefix: str) -> type[Model]

### Description
Return a new model where all field names have been prefixed.

### Parameters
#### Path Parameters
- **prefix** (str) - Required - String prefix to add to all field names.

### Returns
New model class with all the same fields only prefixed with the given prefix.

### Example
```python
>>> class MyModel(Model):
...     a: int
...     b: int
...
>>> MyModel.prefix("x_").columns
['x_a', 'x_b']
```
```

--------------------------------

### Select Multiple Fields

Source: https://github.com/jakobgm/patito/blob/main/docs/api/patito/Model/select.md

Creates a new model containing the 'b' and 'c' fields and verifies its columns in sorted order.

```python
>>> sorted(MyModel.select(["b", "c"]).columns)
['b', 'c']
```

--------------------------------

### Deriving Columns from Existing and Expressions

Source: https://github.com/jakobgm/patito/blob/main/docs/api/patito/DataFrame/derive.md

Demonstrates how to use DataFrame.derive to populate columns defined with derived_from. This includes deriving from a string column name and from a polars expression.

```python
>>> import patito as pt
>>> import polars as pl
>>> class Foo(pt.Model):
...     bar: int = pt.Field(derived_from="foo")
...     double_bar: int = pt.Field(derived_from=2 * pl.col("bar"))
...
>>> Foo.DataFrame({"foo": [1, 2]}).derive()
shape: (2, 3)
┌─────┬────────────┬─────┐
│ bar ┆ double_bar ┆ foo │
│ --- ┆ ---        ┆ --- │
│ i64 ┆ i64        ┆ i64 │
╞═════╪════════════╪═════╡
│ 1   ┆ 2          ┆ 1   │
│ 2   ┆ 4          ┆ 2   │
└─────┴────────────┴─────┘
```

--------------------------------

### Define a Model

Source: https://github.com/jakobgm/patito/blob/main/docs/api/patito/Model/drop.md

Define a base model with multiple fields.

```python
class MyModel(Model):
    a: int
    b: int
    c: int
```

--------------------------------

### Fill Null with Model Defaults

Source: https://github.com/jakobgm/patito/blob/main/docs/api/patito/DataFrame/fill_null.md

Demonstrates filling null values in a DataFrame using the default values specified in the associated patito Model. This is useful when you want to impute missing data with predefined defaults.

```pycon
>>> import patito as pt
>>> class Product(pt.Model):
...     name: str
...     price: int = 19
...
>>> df = Product.DataFrame(
...     {"name": ["apple", "banana"], "price": [10, None]}
... )
>>> df.fill_null(strategy="defaults")
shape: (2, 2)
┌────────┬───────┐
│ name   ┆ price │
│ ---    ┆ ---   │
│ str    ┆ i64   │
╞════════╪═══════╡
│ apple  ┆ 10    │
│ banana ┆ 19    │
└────────┴───────┘
```

--------------------------------

### patito.DataFrame Constructor

Source: https://github.com/jakobgm/patito/blob/main/docs/api/patito/DataFrame/index.md

Constructs a patito.DataFrame. It can be initialized with data and an optional schema, or by using a model's custom DataFrame class.

```APIDOC
## patito.DataFrame Constructor

### Description
Initializes a patito.DataFrame, which is a subclass of polars.DataFrame with added model-aware capabilities. It can be constructed directly with data and schema definitions, or by leveraging a model's specific DataFrame class for automatic model association.

### Class Signature
```python
patito.DataFrame(data: FrameInitTypes | None = None, schema: SchemaDefinition | None = None, *, schema_overrides: SchemaDict | None = None, strict: bool = True, orient: Orientation | None = None, infer_schema_length: int | None = 100, nan_to_null: bool = False, height: int | None = None)
```

### Parameters
* **data** (FrameInitTypes | None, optional): The initial data for the DataFrame. Defaults to None.
* **schema** (SchemaDefinition | None, optional): The schema to apply to the DataFrame. Defaults to None.
* **schema_overrides** (SchemaDict | None, optional): Overrides for the schema definition. Defaults to None.
* **strict** (bool, optional): Whether to enforce strict schema adherence. Defaults to True.
* **orient** (Orientation | None, optional): The orientation of the data. Defaults to None.
* **infer_schema_length** (int | None, optional): The number of rows to infer the schema from. Defaults to 100.
* **nan_to_null** (bool, optional): Whether to convert NaN values to null. Defaults to False.
* **height** (int | None, optional): The height of the DataFrame. Defaults to None.

### Usage Examples

**Direct Initialization:**
```python
import patito as pt

df = pt.DataFrame({"name": ["apple", "banana"], "price": [25, 61]})
```

**Using Model's DataFrame Class:**
```python
class Product(pt.Model):
    name: str
    price_in_cents: int

df = Product.DataFrame({"name": ["apple", "banana"], "price": [25, 61]})
```
```

--------------------------------

### Import Patito and Polars

Source: https://github.com/jakobgm/patito/blob/main/docs/api/patito/DataFrame/get.md

Imports necessary libraries for DataFrame operations and Polars expressions.

```python
import patito as pt
import polars as pl
```

--------------------------------

### Adding fields to a model class

Source: https://github.com/jakobgm/patito/blob/main/docs/api/patito/Model/with_fields.md

Demonstrates how to use `with_fields` to add a new field 'b' to an existing model 'MyModel'. The new class 'ExpandedModel' is then compared to the class created by `with_fields`.

```python
>>> class MyModel(Model):
...     a: int
...
>>> class ExpandedModel(MyModel):
...     b: int
...
>>> MyModel.with_fields(b=(int, ...)).columns == ExpandedModel.columns
True
```

--------------------------------

### Handle Row Does Not Exist Exception

Source: https://github.com/jakobgm/patito/blob/main/docs/api/patito/DataFrame/get.md

Demonstrates catching the RowDoesNotExist exception when a predicate matches zero rows.

```python
try:
    df.get(pl.col("price") == 0)
except pt.exceptions.RowDoesNotExist as e:
    print(e)
```

--------------------------------

### Define a base model

Source: https://github.com/jakobgm/patito/blob/main/docs/api/patito/Model/prefix.md

Define a simple model class that will be used with the prefix method.

```python
class MyModel(Model):
    a: int
    b: int
```

--------------------------------

### Define a Model

Source: https://github.com/jakobgm/patito/blob/main/docs/api/patito/Model/suffix.md

Define a simple model class named MyModel with two integer fields, 'a' and 'b'. This serves as the base for demonstrating the suffix functionality.

```python
>>> class MyModel(Model):
...     a: int
...     b: int
...
```

--------------------------------

### Define a Simple Patito Model

Source: https://github.com/jakobgm/patito/blob/main/docs/api/patito/Model/DataFrame.md

Define a basic model class inheriting from patito.Model with type-hinted fields.

```python
>>> import patito as pt
>>> class Product(pt.Model):
...     name: str
...     price_in_cents: int
...
```

--------------------------------

### Associate Model with DataFrame using set_model

Source: https://github.com/jakobgm/patito/blob/main/docs/api/patito/Model/DataFrame.md

Construct a DataFrame and then associate a patito model with it using the set_model method. This allows the DataFrame to leverage model-specific functionalities.

```python
>>> df = pt.DataFrame({"name": ["apple", "banana"], "price": [25, 61]}).set_model(
...     Product
... )
```

--------------------------------

### Generate a dummy DataFrame with specified data

Source: https://github.com/jakobgm/patito/blob/main/docs/api/patito/Model/examples.md

Generate a polars DataFrame with dummy data, pre-populating the 'name' column with provided values. Other unspecified columns like 'temperature_zone' and 'product_id' are filled with default dummy data.

```python
Product.examples({"name": ["product A", "product B"]})
```

--------------------------------

### Instantiate Model from Polars DataFrame Row

Source: https://github.com/jakobgm/patito/blob/main/README.md

Demonstrates creating a model instance from a filtered Polars DataFrame row using the `from_row()` method.

```python
products = pl.DataFrame(
    {
        "product_id": [1, 2],
        "name": ["Skimmed milk", "Eggs"],
    }
)
milk_row = products.filter(pl.col("product_id" == 1))
milk = Product.from_row(milk_row)
print(milk.url)
```

--------------------------------

### Model.suffix

Source: https://github.com/jakobgm/patito/blob/main/docs/api/patito/Model/suffix.md

Returns a new model where all field names have been suffixed with the provided string.

```APIDOC
## Model.suffix(suffix: str) -> type[Model]

### Description
Return a new model where all field names have been suffixed.

### Parameters
#### Path Parameters
- **suffix** (str) - Required - String suffix to add to all field names.

### Returns
New model class with all the same fields only suffixed with the given suffix.

### Example
```python
>>> class MyModel(Model):
...     a: int
...     b: int
...
>>> MyModel.suffix("_x").columns
['a_x', 'b_x']
```
```

--------------------------------

### Select a Single Field

Source: https://github.com/jakobgm/patito/blob/main/docs/api/patito/Model/select.md

Creates a new model containing only the 'a' field and verifies its columns.

```python
>>> MyModel.select("a").columns
['a']
```

--------------------------------

### Model.LazyFrame Constructor

Source: https://github.com/jakobgm/patito/blob/main/docs/api/patito/Model/LazyFrame.md

Initializes a new LazyFrame. This constructor allows for schema definition, overrides, strictness, orientation, and inference length.

```APIDOC
## Model.LazyFrame Constructor

### Description
Initializes a new LazyFrame. This constructor allows for schema definition, overrides, strictness, orientation, and inference length.

### Signature
`Model.LazyFrame(schema: SchemaDefinition | None = None, *, schema_overrides: SchemaDict | None = None, strict: bool = True, orient: Orientation | None = None, infer_schema_length: int | None = 100, nan_to_null: bool = False, height: int | None = None) -> None`

### Parameters
#### Keyword Arguments
- **schema** (SchemaDefinition | None) - Optional. Defines the schema for the LazyFrame.
- **schema_overrides** (SchemaDict | None) - Optional. Allows overriding parts of the schema.
- **strict** (bool) - Optional. Defaults to True. If True, enforces schema strictness.
- **orient** (Orientation | None) - Optional. Specifies the orientation of the data.
- **infer_schema_length** (int | None) - Optional. Defaults to 100. The number of rows to infer the schema from.
- **nan_to_null** (bool) - Optional. Defaults to False. Whether to convert NaN values to null.
- **height** (int | None) - Optional. Specifies the height of the LazyFrame.
```

--------------------------------

### Define Model with Unique Columns

Source: https://github.com/jakobgm/patito/blob/main/docs/api/patito/Model/unique_columns.md

Define a `patito.Model` with fields that have uniqueness constraints. The `unique_columns` property can then be accessed to retrieve these column names.

```python
from typing import Optional
import patito as pt

class Product(pt.Model):
    product_id: int = pt.Field(unique=True)
    barcode: Optional[str] = pt.Field(unique=True)
    name: str

sorted(Product.unique_columns)
```

--------------------------------

### Define Patito Model with Sum Constraint

Source: https://github.com/jakobgm/patito/blob/main/docs/tutorial/dataframe-validation.md

Extends the `Product` model to include a custom constraint on `demand_percentage`, ensuring the sum of percentages equals 100.0 using a Polars expression.

```python
class Product(pt.Model):
    product_id: int = pt.Field(unique=True)
    name: str
    temperature_zone: Literal["dry", "cold", "frozen"]
    demand_percentage: float = pt.Field(constraints=pt.field.sum() == 100.0)
```

--------------------------------

### Construct DataFrame using Custom Model.DataFrame Class

Source: https://github.com/jakobgm/patito/blob/main/docs/api/patito/Model/DataFrame.md

Instantiate a DataFrame directly using the custom Model.DataFrame class, which automatically associates the defined model. This is a convenient way to create model-aware DataFrames from the outset.

```python
>>> df = Product.DataFrame({"name": ["apple", "banana"], "price": [25, 61]})
```

--------------------------------

### Define Product Schema with Patito

Source: https://github.com/jakobgm/patito/blob/main/README.md

Define a data frame schema using a subclass of `patito.Model`. Specify column types and constraints like uniqueness. This model can then be used for validation and row representation.

```python
from typing import Literal

import patito as pt


class Product(pt.Model):
    product_id: int = pt.Field(unique=True)
    temperature_zone: Literal["dry", "cold", "frozen"]
    is_for_sale: bool
```

--------------------------------

### Model.join

Source: https://github.com/jakobgm/patito/blob/main/docs/api/patito/Model/join.md

Dynamically creates a new model class that represents the schema resulting from an SQL JOIN operation between two patito Model classes. It merges fields from both models and adjusts nullability based on the join type.

```APIDOC
## classmethod Model.join

### Description
Dynamically create a new model compatible with an SQL Join operation. Merges fields from two models and makes fields from the right-hand model nullable according to the SQL JOIN type.

### Method
classmethod

### Signature
Model.join(other: type[Model], how: Literal['inner', 'left', 'outer', 'asof', 'cross', 'semi', 'anti']) -> type[Model]

### Parameters
#### Path Parameters
* **other** (type[Model]) - Required - Another patito Model class.
* **how** (Literal['inner', 'left', 'outer', 'asof', 'cross', 'semi', 'anti']) - Required - The type of SQL Join operation.

### Returns
* **type[Model]** - A new model type compatible with the resulting schema produced by the given join operation.

### Examples
```pycon
>>> class A(Model):
...     a: int
...
>>> class B(Model):
...     b: int
...
>>> InnerJoinedModel = A.join(B, how="inner")
>>> InnerJoinedModel.columns
['a', 'b']
>>> InnerJoinedModel.nullable_columns
set()

>>> LeftJoinedModel = A.join(B, how="left")
>>> LeftJoinedModel.nullable_columns
{'b'}

>>> OuterJoinedModel = A.join(B, how="outer")
>>> sorted(OuterJoinedModel.nullable_columns)
['a', 'b']

>>> A.join(B, how="anti") is A
True
```
```

--------------------------------

### Create a Polars DataFrame

Source: https://github.com/jakobgm/patito/blob/main/docs/tutorial/dataframe-validation.md

This snippet demonstrates how to create a Polars DataFrame from a dictionary. It is used as input for Patito validation.

```python
import polars as pl

product_df = pl.DataFrame(
    {
        "product_id": [1, 2, 3],
        "name": ["Apple", "Milk", "Ice cubes"],
        "temperature_zone": ["dry", "cold", "frozen"],
        "demand_percentage": [0.23, 0.61, 0.01],
    }
)
```

--------------------------------

### Validate DataFrame with a Model

Source: https://github.com/jakobgm/patito/blob/main/docs/api/patito/DataFrame/validate.md

Create a DataFrame, set a model for validation using set_model(), and then call validate(). Catches and prints DataFrameValidationError if validation fails.

```python
df = pt.DataFrame(
    {
        "product_id": [1, 1, 3],
        "temperature_zone": ["dry", "dry", "oven"],
    }
).set_model(Product)
try:
    df.validate()
except pt.DataFrameValidationError as exc:
    print(exc)

```

--------------------------------

### Generate a default dummy DataFrame

Source: https://github.com/jakobgm/patito/blob/main/docs/api/patito/Model/examples.md

Generate a polars DataFrame with a single row of dummy data for all columns defined in the Product model. This is useful for quick data inspection or initial testing.

```python
Product.examples()
```

--------------------------------

### Define a patito Model

Source: https://github.com/jakobgm/patito/blob/main/docs/api/patito/DataFrame/validate.md

Define a data model using patito.Model to specify the schema and constraints for validation.

```python
class Product(pt.Model):
    product_id: int = pt.Field(unique=True)
    temperature_zone: Literal["dry", "cold", "frozen"]
    is_for_sale: bool

```

--------------------------------

### Model.select

Source: https://github.com/jakobgm/patito/blob/main/docs/api/patito/Model/select.md

Creates a new model class containing only a specified subset of the original model's fields. This is useful for creating specialized views or data transfer objects from a larger model.

```APIDOC
## Model.select

### Description
Creates a new model class consisting of only a subset of the original model's fields. This is useful for creating specialized views or data transfer objects from a larger model.

### Method
classmethod

### Parameters
#### Arguments
* **fields** (str | Iterable[str]) - Required - A single field name as a string or a collection of strings representing the fields to include in the new model.

### Returns
type[[Model](index.md#patito.Model)] - A new model class containing only the fields specified by `fields`.

### Raises
**ValueError** – If one or more non-existent fields are selected.

### Example
```python
>>> class MyModel(Model):
...     a: int
...     b: int
...     c: int
...
>>> MyModel.select("a").columns
['a']
>>> sorted(MyModel.select(["b", "c"]).columns)
['b', 'c']
```
```

--------------------------------

### Left Join Model Creation

Source: https://github.com/jakobgm/patito/blob/main/docs/api/patito/Model/join.md

Create a new model representing a left join between Model A and Model B. In a left join, all columns from the right table (Model B) become nullable.

```python
>>> LeftJoinedModel = A.join(B, how="left")
>>> LeftJoinedModel.nullable_columns
{'b'}
```

--------------------------------

### Model.defaults

Source: https://github.com/jakobgm/patito/blob/main/docs/api/patito/Model/defaults.md

Retrieves a dictionary of default field values for a patito Model.

```APIDOC
## Model.defaults

### Description
Returns default field values specified on the model.

### Returns
Dictionary containing fields with their respective default values.

### Example

```python
>>> from typing_extensions import Literal
>>> import patito as pt
>>> class Product(pt.Model):
...     name: str
...     price: int = 0
...     temperature_zone: Literal["dry", "cold", "frozen"] = "dry"
...
>>> Product.defaults
{'price': 0, 'temperature_zone': 'dry'}
```
```

--------------------------------

### Accessing Default Field Values

Source: https://github.com/jakobgm/patito/blob/main/docs/api/patito/Model/defaults.md

Demonstrates how to access the default values of fields defined in a patito Model. This property returns a dictionary where keys are field names and values are their default values.

```python
>>> from typing_extensions import Literal
>>> import patito as pt
>>> class Product(pt.Model):
...     name: str
...     price: int = 0
...     temperature_zone: Literal["dry", "cold", "frozen"] = "dry"
...
>>> Product.defaults
{'price': 0, 'temperature_zone': 'dry'}
```

--------------------------------

### Define a Patito Model

Source: https://github.com/jakobgm/patito/blob/main/docs/api/patito/DataFrame/cast.md

Define a simple Patito model with string and integer fields, specifying a custom dtype for the integer field.

```python
>>> import patito as pt
>>> import polars as pl
>>> class Product(pt.Model):
...     name: str
...     cent_price: int = pt.Field(dtype=pl.UInt16)
...
```

--------------------------------

### Define Patito Model with Unique Constraint

Source: https://github.com/jakobgm/patito/blob/main/docs/tutorial/dataframe-validation.md

Defines a Patito model for `Product` including a `unique=True` constraint on the `product_id` field, ensuring no duplicate IDs in the DataFrame.

```python
import patito as pt
from typing import Literal

class Product(pt.Model):
    product_id: int = pt.Field(unique=True)
    name: str
    temperature_zone: Literal["dry", "cold", "frozen"]
    demand_percentage: float
```

--------------------------------

### Read CSV without headers using patito

Source: https://github.com/jakobgm/patito/blob/main/docs/api/patito/DataFrame/read_csv.md

Use this method when your CSV file does not contain a header row. It automatically infers column names from the model.

```python
>>> import io
>>> import patito as pt
>>> class CSVModel(pt.Model):
...     a: float
...     b: str
...
>>> csv_file = io.StringIO("1,2")
>>> CSVModel.DataFrame.read_csv(csv_file, has_header=False)
shape: (1, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ f64 ┆ str │
╞═════╪═════╡
│ 1.0 ┆ 2   │
└─────┴─────┘
```

--------------------------------

### Read CSV with derived fields using patito

Source: https://github.com/jakobgm/patito/blob/main/docs/api/patito/DataFrame/read_csv.md

Utilize the `derived_from` parameter in `pt.Field` to map CSV column names to your model's fields, especially when source column names differ from intended model names.

```python
>>> import io
>>> import patito as pt
>>> class CSVModel(pt.Model):
...     a: float
...     b: str = pt.Field(derived_from="source_of_b")
...
>>> csv_file = io.StringIO("a,source_of_b\n1,1")
# >>> CSVModel.DataFrame.read_csv(csv_file).drop()
# shape: (1, 2)
# ┌─────┬─────┐
# │ a   ┆ b   │
# │ — ┆ — │
# │ f64 ┆ str │
# ╞═════╪═════╡
# │ 1.0 ┆ 1   │
# └─────┴─────┘
```

--------------------------------

### Define a Patito Model

Source: https://github.com/jakobgm/patito/blob/main/docs/api/patito/Model/from_row.md

Define a Pydantic-compatible model inheriting from pt.Model with specified fields and types.

```python
class Product(pt.Model):
    product_id: int
    name: str
    price: float
```

--------------------------------

### Model.with_fields

Source: https://github.com/jakobgm/patito/blob/main/docs/api/patito/Model/with_fields.md

Adds new fields to a Model class, returning a new class with the added fields. Fields are defined as keyword arguments where the key is the field name and the value is a tuple of (field_type, field_default). Use '...' for the default value if it's not provided.

```APIDOC
## classmethod Model.with_fields

### Description
Returns a new model class where the given fields have been added.

### Method
classmethod

### Parameters
#### Keyword Arguments
- **field_definitions** (Any) - Accepts keyword arguments of the form `field_name=(field_type, field_default)`. Specify `...` if no default value is provided. For instance, `column_name=(int, ...)` will create a new non-optional integer field named "column_name".

### Returns
- type[[Model](index.md#patito.Model)] - A new model with all the original fields and the additional field definitions.

### Example

```pycon
>>> class MyModel(Model):
...     a: int
...
>>> class ExpandedModel(MyModel):
...     b: int
...
>>> MyModel.with_fields(b=(int, ...)).columns == ExpandedModel.columns
True
```
```

--------------------------------

### Anti Join Behavior

Source: https://github.com/jakobgm/patito/blob/main/docs/api/patito/Model/join.md

Demonstrates that an anti join between Model A and Model B returns the original Model A. This is because an anti join filters out rows from the left table that have matches in the right table, effectively returning the left table itself when considering schema compatibility.

```python
>>> A.join(B, how="anti") is A
True
```

--------------------------------

### Original Test Function Failing Validation

Source: https://github.com/jakobgm/patito/blob/main/README.md

Illustrates a test function that would fail with a `DataFrameValidationError` because the input dataframe is missing required columns (`temperature_zone`, `product_id`) according to the `Product` model.

```python
def test_num_products_for_sale():
    products = pl.DataFrame({"is_for_sale": [True, True, False]})
    assert num_products_for_sale(products) == 2
```

--------------------------------

### Handle Multiple Rows Returned Exception

Source: https://github.com/jakobgm/patito/blob/main/docs/api/patito/DataFrame/get.md

Demonstrates catching the MultipleRowsReturned exception when a predicate matches more than one row.

```python
try:
    df.get(pl.col("price") == 10)
except pt.exceptions.MultipleRowsReturned as e:
    print(e)
```