patito 0.6.1__py3-none-any.whl → 0.6.2__py3-none-any.whl

patito/__init__.py

@@ -1,4 +1,5 @@
 """Patito, a data-modelling library built on top of polars and pydantic."""
+
 from polars import Expr, Series, col
 
 from patito import exceptions

patito/_docs.py

@@ -1,2 +1,3 @@
 """Ugly workaround for Sphinx + autodoc + ModelMetaclass + classproperty."""
+
 from patito.pydantic import ModelMetaclass as Model  # noqa: F401, pragma: no cover

patito/_pydantic/__init__.py

@@ -1 +0,0 @@
-

patito/_pydantic/column_info.py

@@ -19,10 +19,9 @@ from patito._pydantic.dtypes import parse_composite_dtype
 
 
 class ColumnInfo(BaseModel, arbitrary_types_allowed=True):
-    """patito-side model for storing column metadata
+    """patito-side model for storing column metadata.
 
     Args:
-    ----
         constraints (Union[polars.Expression, List[polars.Expression]): A single
             constraint or list of constraints, expressed as a polars expression objects.
             All rows must satisfy the given constraint. You can refer to the given column
@@ -40,6 +39,22 @@ class ColumnInfo(BaseModel, arbitrary_types_allowed=True):
     derived_from: Optional[Union[str, pl.Expr]] = None
     unique: Optional[bool] = None
 
+    def __repr__(self) -> str:
+        """Print only Field attributes whose values are not default (mainly None)."""
+        not_default_field = {
+            field: getattr(self, field)
+            for field in self.model_fields
+            if getattr(self, field) is not self.model_fields[field].default
+        }
+
+        string = ""
+        for field, value in not_default_field.items():
+            string += f"{field}={value}, "
+        if string:
+            # remove trailing comma and space
+            string = string[:-2]
+        return f"ColumnInfo({string})"
+
     @field_serializer("constraints", "derived_from")
     def serialize_exprs(self, exprs: str | pl.Expr | Sequence[pl.Expr] | None) -> Any:
         if exprs is None:
@@ -56,17 +71,17 @@ class ColumnInfo(BaseModel, arbitrary_types_allowed=True):
     def _serialize_expr(self, expr: pl.Expr) -> Dict:
         if isinstance(expr, pl.Expr):
             return json.loads(
-                expr.meta.write_json(None)
+                expr.meta.serialize(None)
             )  # can we access the dictionary directly?
         else:
             raise ValueError(f"Invalid type for expr: {type(expr)}")
 
     @field_serializer("dtype")
     def serialize_dtype(self, dtype: DataTypeClass | DataType | None) -> Any:
-        """References
-        ----------
-            [1] https://stackoverflow.com/questions/76572310/how-to-serialize-deserialize-polars-datatypes
+        """Serialize a polars dtype.
 
+        References:
+            [1] https://stackoverflow.com/questions/76572310/how-to-serialize-deserialize-polars-datatypes
         """
         if dtype is None:
             return None

patito/_pydantic/dtypes/dtypes.py

@@ -39,24 +39,17 @@ def valid_dtypes_for_model(
 @cache
 def default_dtypes_for_model(
     cls: Type[ModelType],
-) -> dict[str, DataTypeClass | DataType]:
-    default_dtypes = {}
+) -> dict[str, DataType]:
+    default_dtypes: dict[str, DataType] = {}
     for column in cls.columns:
-        dtype = cls.column_infos[column].dtype
+        dtype = (
+            cls.column_infos[column].dtype
+            or DtypeResolver(cls.model_fields[column].annotation).default_polars_dtype()
+        )
         if dtype is None:
-            default_dtype = DtypeResolver(
-                cls.model_fields[column].annotation
-            ).default_polars_dtype()
-            if default_dtype is None:
-                raise ValueError(
-                    f"Unable to find a default dtype for column `{column}`"
-                )
-            else:
-                default_dtypes[column] = default_dtype
-        else:
-            default_dtypes[column] = (
-                dtype if isinstance(dtype, DataType) else dtype()
-            )  # if dtype is not instantiated, instantiate it
+            raise ValueError(f"Unable to find a default dtype for column `{column}`")
+
+        default_dtypes[column] = dtype if isinstance(dtype, DataType) else dtype()
     return default_dtypes
 
 
@@ -68,7 +61,6 @@ def validate_polars_dtype(
     """Check that the polars dtype is valid for the given annotation. Raises ValueError if not.
 
     Args:
-    ----
         annotation (type[Any] | None): python type annotation
         dtype (DataType | DataTypeClass | None): polars dtype
         column (Optional[str], optional): column name. Defaults to None.
@@ -96,7 +88,6 @@ def validate_annotation(
     """Check that the provided annotation has polars/patito support (we can resolve it to a default dtype). Raises ValueError if not.
 
     Args:
-    ----
         annotation (type[Any] | None): python type annotation
         column (Optional[str], optional): column name. Defaults to None.
 
@@ -130,9 +121,9 @@ class DtypeResolver:
             return PT_BASE_SUPPORTED_DTYPES
         return self._valid_polars_dtypes_for_schema(self.schema)
 
-    def default_polars_dtype(self) -> DataTypeClass | DataType | None:
+    def default_polars_dtype(self) -> DataType | None:
         if self.annotation == Any:
-            return pl.String
+            return pl.String()
         return self._default_polars_dtype_for_schema(self.schema)
 
     def _valid_polars_dtypes_for_schema(
@@ -197,9 +188,7 @@ class DtypeResolver:
             PydanticBaseType(pyd_type), props.get("format"), props.get("enum")
         )
 
-    def _default_polars_dtype_for_schema(
-        self, schema: Dict
-    ) -> DataTypeClass | DataType | None:
+    def _default_polars_dtype_for_schema(self, schema: Dict) -> DataType | None:
         if "anyOf" in schema:
             if len(schema["anyOf"]) == 2:  # look for optionals first
                 schema = _without_optional(schema)
@@ -216,10 +205,12 @@ class DtypeResolver:
     def _pydantic_subschema_to_default_dtype(
         self,
         props: Dict,
-    ) -> DataTypeClass | DataType | None:
+    ) -> DataType | None:
         if "column_info" in props:  # user has specified in patito model
             if props["column_info"]["dtype"] is not None:
-                return dtype_from_string(props["column_info"]["dtype"])
+                dtype = dtype_from_string(props["column_info"]["dtype"])
+                dtype = dtype() if isinstance(dtype, DataTypeClass) else dtype
+                return dtype
         if "type" not in props:
             if "enum" in props:
                 raise TypeError("Mixed type enums not supported by patito.")

patito/_pydantic/dtypes/utils.py

@@ -78,11 +78,9 @@ def is_optional(type_annotation: type[Any] | Any | None) -> bool:
     """Return True if the given type annotation is an Optional annotation.
 
     Args:
-    ----
         type_annotation: The type annotation to be checked.
 
     Returns:
-    -------
         True if the outermost type is Optional.
 
     """
@@ -92,7 +90,7 @@ def is_optional(type_annotation: type[Any] | Any | None) -> bool:
 
 
 def parse_composite_dtype(dtype: DataTypeClass | DataType) -> str:
-    """For serialization, converts polars dtype to string representation"""
+    """For serialization, converts polars dtype to string representation."""
     if dtype in pl.NESTED_DTYPES:
         if dtype == pl.Struct or isinstance(dtype, pl.Struct):
             raise NotImplementedError("Structs not yet supported by patito")
@@ -110,7 +108,7 @@ def parse_composite_dtype(dtype: DataTypeClass | DataType) -> str:
 
 
 def dtype_from_string(v: str) -> Optional[Union[DataTypeClass, DataType]]:
-    """For deserialization"""
+    """For deserialization."""
     # TODO test all dtypes
     return convert.dtype_short_repr_to_dtype(v)
 

patito/_pydantic/repr.py

@@ -82,7 +82,7 @@ class Representation:
     def __pretty__(
         self, fmt: Callable[[Any], Any], **kwargs: Any
     ) -> Generator[Any, None, None]:
-        """Used by devtools (https://python-devtools.helpmanual.io/) to provide a human readable representations of objects"""
+        """Used by devtools (https://python-devtools.helpmanual.io/) to provide a human readable representations of objects."""
         yield self.__repr_name__() + "("
         yield 1
         for name, value in self.__repr_args__():
@@ -101,7 +101,7 @@ class Representation:
         return f'{self.__repr_name__()}({self.__repr_str__(", ")})'
 
     def __rich_repr__(self) -> "RichReprResult":
-        """Get fields for Rich library"""
+        """Get fields for Rich library."""
         for name, field_repr in self.__repr_args__():
             if name is None:
                 yield field_repr

patito/_pydantic/schema.py

@@ -16,14 +16,12 @@ if TYPE_CHECKING:
 def schema_for_model(cls: Type[ModelType]) -> Dict[str, Dict[str, Any]]:
     """Return schema properties where definition references have been resolved.
 
-    Returns
-    -------
+    Returns:
         Field information as a dictionary where the keys are field names and the
             values are dictionaries containing metadata information about the field
             itself.
 
-    Raises
-    ------
+    Raises:
         TypeError: if a field is annotated with an enum where the values are of
             different types.
 

patito/exceptions.py

@@ -1,3 +1,5 @@
+"""Exceptions used by patito."""
+
 from typing import (
     TYPE_CHECKING,
     Any,
@@ -34,19 +36,24 @@ __all__ = "ErrorWrapper", "DataFrameValidationError"
 
 
 class ErrorWrapper(Representation):
+    """Error handler for nicely accumulating errors."""
+
     __slots__ = "exc", "_loc"
 
     def __init__(self, exc: Exception, loc: Union[str, "Loc"]) -> None:
+        """Wrap an error in an ErrorWrapper."""
         self.exc = exc
         self._loc = loc
 
     def loc_tuple(self) -> "Loc":
+        """Represent error as tuple."""
         if isinstance(self._loc, tuple):
             return self._loc
         else:
             return (self._loc,)
 
     def __repr_args__(self) -> "ReprArgs":
+        """Pydantic repr."""
         return [("exc", self.exc), ("loc", self.loc_tuple())]
 
 
@@ -56,19 +63,24 @@ ErrorList = Union[Sequence[Any], ErrorWrapper]
 
 
 class DataFrameValidationError(Representation, ValueError):
+    """Parent error for DataFrame validation errors."""
+
     __slots__ = "raw_errors", "model", "_error_cache"
 
     def __init__(self, errors: Sequence[ErrorList], model: Type["BaseModel"]) -> None:
+        """Create a dataframe validation error."""
         self.raw_errors = errors
         self.model = model
         self._error_cache: Optional[List["ErrorDict"]] = None
 
     def errors(self) -> List["ErrorDict"]:
+        """Get list of errors."""
         if self._error_cache is None:
             self._error_cache = list(flatten_errors(self.raw_errors))
         return self._error_cache
 
     def __str__(self) -> str:
+        """String reprentation of error."""
         errors = self.errors()
         no_errors = len(errors)
         return (
@@ -77,6 +89,7 @@ class DataFrameValidationError(Representation, ValueError):
         )
 
     def __repr_args__(self) -> "ReprArgs":
+        """Pydantic repr."""
         return [("model", self.model.__name__), ("errors", self.errors())]
 
 

patito/polars.py

@@ -9,6 +9,7 @@ from typing import (
     Dict,
     Generic,
     Iterable,
+    Literal,
     Optional,
     Sequence,
     Tuple,
@@ -21,7 +22,6 @@ from typing import (
 import polars as pl
 from polars.type_aliases import IntoExpr
 from pydantic import AliasChoices, AliasPath, create_model
-from typing_extensions import Literal
 
 from patito._pydantic.column_info import ColumnInfo
 from patito.exceptions import MultipleRowsReturned, RowDoesNotExist
@@ -53,12 +53,10 @@ class LazyFrame(pl.LazyFrame, Generic[ModelType]):
         DataFrame.set_model(model) is implicitly invoked at collection.
 
         Args:
-        ----
             model: A patito model which should be used to validate the final dataframe.
                 If None is provided, the regular LazyFrame class will be returned.
 
         Returns:
-        -------
             A custom LazyFrame model class where LazyFrame.model has been correctly
                 "hard-coded" to the given model.
 
@@ -101,21 +99,17 @@ class LazyFrame(pl.LazyFrame, Generic[ModelType]):
         result of which will be used to populate the column values.
 
         Args:
-        ----
             columns: Optionally, a list of column names to derive. If not provided, all
                 columns are used.
 
         Returns:
-        -------
             DataFrame[Model]: A new dataframe where all derivable columns are provided.
 
         Raises:
-        ------
             TypeError: If the ``derived_from`` parameter of ``patito.Field`` is given
                 as something else than a string or polars expression.
 
         Examples:
-        --------
             >>> import patito as pt
             >>> import polars as pl
             >>> class Foo(pt.Model):
@@ -189,8 +183,7 @@ class LazyFrame(pl.LazyFrame, Generic[ModelType]):
 
         limitation - AliasChoice validation type only supports selecting a single element of an array
 
-        Returns
-        -------
+        Returns:
             DataFrame[Model]: A dataframe with columns normalized to model names.
 
         """
@@ -247,7 +240,6 @@ class LazyFrame(pl.LazyFrame, Generic[ModelType]):
         """Cast columns to `dtypes` specified by the associated Patito model.
 
         Args:
-        ----
             strict: If set to ``False``, columns which are technically compliant with
                 the specified field type, will not be casted. For example, a column
                 annotated with ``int`` is technically compliant with ``pl.UInt8``, even
@@ -258,11 +250,9 @@ class LazyFrame(pl.LazyFrame, Generic[ModelType]):
                 columns are casted.
 
         Returns:
-        -------
             LazyFrame[Model]: A dataframe with columns casted to the correct dtypes.
 
         Examples:
-        --------
             Create a simple model:
 
             >>> import patito as pt
@@ -348,11 +338,9 @@ class DataFrame(pl.DataFrame, Generic[ModelType]):
         DataFrame.set_model(model) is implicitly invoked at instantiation.
 
         Args:
-        ----
             model: A patito model which should be used to validate the dataframe.
 
         Returns:
-        -------
             A custom DataFrame model class where DataFrame._model has been correctly
                 "hard-coded" to the given model.
 
@@ -369,15 +357,14 @@ class DataFrame(pl.DataFrame, Generic[ModelType]):
 
         See documentation of polars.DataFrame.lazy() for full description.
 
-        Returns
-        -------
+        Returns:
             A new LazyFrame object.
 
         """
-        lazyframe_class: LazyFrame[
-            ModelType
-        ] = LazyFrame._construct_lazyframe_model_class(
-            model=getattr(self, "model", None)
+        lazyframe_class: LazyFrame[ModelType] = (
+            LazyFrame._construct_lazyframe_model_class(
+                model=getattr(self, "model", None)
+            )
         )  # type: ignore
         ldf = lazyframe_class._from_pyldf(super().lazy()._ldf)
         return ldf
@@ -392,17 +379,14 @@ class DataFrame(pl.DataFrame, Generic[ModelType]):
         ``DataFrame(...).set_model(Model)`` is equivalent with ``Model.DataFrame(...)``.
 
         Args:
-        ----
             model (Model): Sub-class of ``patito.Model`` declaring the schema of the
                 dataframe.
 
         Returns:
-        -------
             DataFrame[Model]: Returns the same dataframe, but with an attached model
             that is required for certain model-specific dataframe methods to work.
 
         Examples:
-        --------
             >>> from typing_extensions import Literal
             >>> import patito as pt
             >>> import polars as pl
@@ -454,8 +438,7 @@ class DataFrame(pl.DataFrame, Generic[ModelType]):
 
         limitation - AliasChoice validation type only supports selecting a single element of an array
 
-        Returns
-        -------
+        Returns:
             DataFrame[Model]: A dataframe with columns normalized to model names.
 
         """
@@ -467,7 +450,6 @@ class DataFrame(pl.DataFrame, Generic[ModelType]):
         """Cast columns to `dtypes` specified by the associated Patito model.
 
         Args:
-        ----
             strict: If set to ``False``, columns which are technically compliant with
                 the specified field type, will not be casted. For example, a column
                 annotated with ``int`` is technically compliant with ``pl.UInt8``, even
@@ -478,11 +460,9 @@ class DataFrame(pl.DataFrame, Generic[ModelType]):
                 columns are casted.
 
         Returns:
-        -------
             DataFrame[Model]: A dataframe with columns casted to the correct dtypes.
 
         Examples:
-        --------
             Create a simple model:
 
             >>> import patito as pt
@@ -519,18 +499,15 @@ class DataFrame(pl.DataFrame, Generic[ModelType]):
         :ref:`DataFrame.set_model <DataFrame.set_model>`, are dropped.
 
         Args:
-        ----
             columns: A single column string name, or list of strings, indicating
                 which columns to drop. If not specified, all columns *not*
                 specified by the associated dataframe model will be dropped.
             more_columns: Additional named columns to drop.
 
         Returns:
-        -------
             DataFrame[Model]: New dataframe without the specified columns.
 
         Examples:
-        --------
             >>> import patito as pt
             >>> class Model(pt.Model):
             ...     column_1: int
@@ -552,20 +529,16 @@ class DataFrame(pl.DataFrame, Generic[ModelType]):
         else:
             return self.drop(list(set(self.columns) - set(self.model.columns)))
 
-    def validate(
-        self: DF, columns: Optional[Sequence[str]] = None, **kwargs: Any
-    ) -> DF:
+    def validate(self, columns: Optional[Sequence[str]] = None, **kwargs: Any):
         """Validate the schema and content of the dataframe.
 
         You must invoke ``.set_model()`` before invoking ``.validate()`` in order
         to specify how the dataframe should be validated.
 
-        Returns
-        -------
+        Returns:
             DataFrame[Model]: The original dataframe, if correctly validated.
 
-        Raises
-        ------
+        Raises:
             TypeError: If ``DataFrame.set_model()`` has not been invoked prior to
                 validation. Note that ``patito.Model.DataFrame`` automatically invokes
                 ``DataFrame.set_model()`` for you.
@@ -573,8 +546,7 @@ class DataFrame(pl.DataFrame, Generic[ModelType]):
             patito.exceptions.DataFrameValidationError: If the dataframe does not match the
                 specified schema.
 
-        Examples
-        --------
+        Examples:
             >>> import patito as pt
 
 
@@ -621,17 +593,14 @@ class DataFrame(pl.DataFrame, Generic[ModelType]):
         column name. Alternatively, an arbitrary polars expression can be given, the
         result of which will be used to populate the column values.
 
-        Returns
-        -------
+        Returns:
             DataFrame[Model]: A new dataframe where all derivable columns are provided.
 
-        Raises
-        ------
+        Raises:
             TypeError: If the ``derived_from`` parameter of ``patito.Field`` is given
                 as something else than a string or polars expression.
 
-        Examples
-        --------
+        Examples:
             >>> import patito as pt
             >>> import polars as pl
             >>> class Foo(pt.Model):
@@ -665,11 +634,10 @@ class DataFrame(pl.DataFrame, Generic[ModelType]):
     ) -> DF:
         """Fill null values using a filling strategy, literal, or ``Expr``.
 
-        If ``"default"`` is provided as the strategy, the model fields with default
+        If ``"defaults"`` is provided as the strategy, the model fields with default
         values are used to fill missing values.
 
         Args:
-        ----
             value: Value used to fill null values.
             strategy: Accepts the same arguments as ``polars.DataFrame.fill_null`` in
                 addition to ``"defaults"`` which will use the field's default value if
@@ -680,12 +648,10 @@ class DataFrame(pl.DataFrame, Generic[ModelType]):
 
 
         Returns:
-        -------
             DataFrame[Model]: A new dataframe with nulls filled in according to the
             provided ``strategy`` parameter.
 
         Example:
-        -------
             >>> import patito as pt
             >>> class Product(pt.Model):
             ...     name: str
@@ -737,7 +703,6 @@ class DataFrame(pl.DataFrame, Generic[ModelType]):
         you can use ``.get()`` without any arguments to return that row.
 
         Raises:
-        ------
             RowDoesNotExist: If zero rows evaluate to true for the given predicate.
             MultipleRowsReturned: If more than one row evaluates to true for the given
                 predicate.
@@ -746,15 +711,12 @@ class DataFrame(pl.DataFrame, Generic[ModelType]):
                 same class.
 
         Args:
-        ----
             predicate: A polars expression defining the criteria of the filter.
 
         Returns:
-        -------
             Model: A pydantic-derived base model representing the given row.
 
         Example:
-        -------
             >>> import patito as pt
             >>> import polars as pl
             >>> df = pt.DataFrame({"product_id": [1, 2, 3], "price": [10, 10, 20]})
@@ -819,8 +781,7 @@ class DataFrame(pl.DataFrame, Generic[ModelType]):
     def _pydantic_model(self) -> Type[Model]:
         """Dynamically construct patito model compliant with dataframe.
 
-        Returns
-        -------
+        Returns:
             A pydantic model class where all the rows have been specified as
                 `typing.Any` fields.
 
@@ -853,16 +814,13 @@ class DataFrame(pl.DataFrame, Generic[ModelType]):
         to populate the given column(s).
 
         Args:
-        ----
             *args: All positional arguments are forwarded to ``polars.read_csv``.
             **kwargs: All keyword arguments are forwarded to ``polars.read_csv``.
 
         Returns:
-        -------
             DataFrame[Model]: A dataframe representing the given CSV file data.
 
         Examples:
-        --------
             The ``DataFrame.read_csv`` method can be used to automatically set the
             correct column names when reading CSV files without headers.
 
@@ -908,8 +866,22 @@ class DataFrame(pl.DataFrame, Generic[ModelType]):
 
         """
         kwargs.setdefault("dtypes", cls.model.dtypes)
-        if not kwargs.get("has_header", True) and "columns" not in kwargs:
+        has_header = kwargs.get("has_header", True)
+        if not has_header and "columns" not in kwargs:
             kwargs.setdefault("new_columns", cls.model.columns)
+        alias_gen = cls.model.model_config.get("alias_generator")
+        if alias_gen:
+            alias_func = alias_gen.validation_alias or alias_gen.alias
+        if has_header and alias_gen and alias_func:
+            fields_to_cols = {
+                field_name: alias_func(field_name)
+                for field_name in cls.model.model_fields
+            }
+            kwargs["dtypes"] = {
+                fields_to_cols.get(field, field): dtype
+                for field, dtype in kwargs["dtypes"].items()
+            }
+            # TODO: other forms of alias setting like in Field
         df = cls.model.DataFrame._from_pydf(pl.read_csv(*args, **kwargs)._df)
         return df.derive()