dataframely 2.13.0__tar.gz → 2.13.2__tar.gz

{dataframely-2.13.0 → dataframely-2.13.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dataframely
-Version: 2.13.0
+Version: 2.13.2
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11

dataframely-2.13.2/dataframely/_deprecation.py

@@ -0,0 +1,58 @@
+# Copyright (c) QuantCo 2025-2026
+# SPDX-License-Identifier: BSD-3-Clause
+
+from __future__ import annotations
+
+import sys
+import warnings
+from functools import wraps
+from typing import TYPE_CHECKING, TypeVar
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+    from typing import ParamSpec
+
+    P = ParamSpec("P")
+    T = TypeVar("T")
+
+
+def issue_deprecation_warning(message: str, *, version: str = "") -> None:
+    """Issue a deprecation warning pointing at the caller of the deprecated method.
+
+    This must be called directly from the body of the deprecated (public) method so
+    that the warning points at the user's code rather than at dataframely internals.
+
+    Args:
+        message: The message associated with the warning.
+        version: The dataframely version in which the deprecation occurred (if not
+            already part of ``message``).
+    """
+    if version:
+        message = f"{message.strip()}\n(Deprecated in dataframely {version})"
+    # `stacklevel=2` blames the caller of the deprecated method (one frame up from this
+    # function). All call sites invoke this directly from the deprecated method body.
+    warnings.warn(message, DeprecationWarning, stacklevel=2)
+
+
+if sys.version_info >= (3, 13):
+    from warnings import deprecated
+else:
+    try:
+        from typing_extensions import deprecated
+    except ImportError:  # pragma: no cover
+
+        def deprecated(  # type: ignore[no-redef]
+            message: str,
+        ) -> Callable[[Callable[P, T]], Callable[P, T]]:
+            """Fallback for :func:`warnings.deprecated` without :pep:`702` support."""
+
+            def decorate(function: Callable[P, T]) -> Callable[P, T]:
+                @wraps(function)
+                def wrapper(*args: P.args, **kwargs: P.kwargs) -> T:
+                    issue_deprecation_warning(message)
+                    return function(*args, **kwargs)
+
+                wrapper.__deprecated__ = message  # type: ignore[attr-defined]
+                return wrapper
+
+            return decorate

{dataframely-2.13.0 → dataframely-2.13.2}/dataframely/collection/_base.py

@@ -133,12 +133,18 @@ class CollectionMeta(ABCMeta):
         ]
 
         # 1) Check that there are overlapping primary keys that allow the application
-        # of filters.
-        if len(non_ignored_member_schemas) > 0 and len(result.filters) > 0:
+        # of filters and the propagation of row failures.
+        has_failure_propagation = any(
+            member.propagate_row_failures and not member.ignored_in_filters
+            for member in result.members.values()
+        )
+        if len(non_ignored_member_schemas) > 0 and (
+            len(result.filters) > 0 or has_failure_propagation
+        ):
             if len(_common_primary_key(non_ignored_member_schemas)) == 0:
                 raise ImplementationError(
                     "Members of a collection must have an overlapping primary key "
-                    "but did not find any."
+                    "if they use filters or failure-propagation, but did not find any."
                 )
 
         # 2) Check that filter names do not overlap with any column or rule names
@@ -371,7 +377,7 @@ class BaseCollection(metaclass=CollectionMeta):
         return {
             name
             for name, member in cls.members().items()
-            if member.propagate_row_failures
+            if member.propagate_row_failures and not member.ignored_in_filters
         }
 
     @classmethod

{dataframely-2.13.0 → dataframely-2.13.2}/dataframely/collection/collection.py

@@ -28,6 +28,7 @@ import polars as pl
 import polars.exceptions as plexc
 
 from dataframely._compat import deltalake
+from dataframely._deprecation import deprecated, issue_deprecation_warning
 from dataframely._filter import Filter
 from dataframely._native import format_rule_failures
 from dataframely._plugin import all_rules_required
@@ -63,6 +64,15 @@ else:
 
 _FILTER_COLUMN_PREFIX = "__DATAFRAMELY_FILTER_COLUMN__"
 
+#: Deprecation message emitted when reading a collection with implicit validation, i.e.
+#: with any ``validation`` other than ``"skip"`` (see #367).
+_IMPLICIT_VALIDATION_DEPRECATION = (
+    "Reading a collection with `validation != 'skip'` is deprecated. Starting with "
+    "dataframely v3, data is read without inspecting schema metadata and without "
+    "running validation. Pass `validation='skip'` to opt into the future behavior, or "
+    "call `validate` explicitly if you require validation."
+)
+
 P = ParamSpec("P")
 T = TypeVar("T")
 
@@ -1061,7 +1071,16 @@ class Collection(BaseCollection, ABC):
         Attention:
             Be aware that this method suffers from the same limitations as
             :meth:`serialize`.
+
+        .. deprecated:: 3.0.0
+            Reading with `validation != "skip"` is deprecated. Starting with
+            dataframely v3, this method reads the data without inspecting any schema
+            metadata and without running validation. Pass `validation="skip"` to opt
+            into this behavior, or call :meth:`validate` explicitly if you require
+            validation.
         """
+        if validation != "skip":
+            issue_deprecation_warning(_IMPLICIT_VALIDATION_DEPRECATION)
         return cls._read(
             backend=ParquetStorageBackend(),
             validation=validation,
@@ -1118,7 +1137,16 @@ class Collection(BaseCollection, ABC):
         Attention:
             Be aware that this method suffers from the same limitations as
             :meth:`serialize`.
+
+        .. deprecated:: 3.0.0
+            Reading with `validation != "skip"` is deprecated. Starting with
+            dataframely v3, this method reads the data without inspecting any schema
+            metadata and without running validation. Pass `validation="skip"` to opt
+            into this behavior, or call :meth:`validate` explicitly if you require
+            validation.
         """
+        if validation != "skip":
+            issue_deprecation_warning(_IMPLICIT_VALIDATION_DEPRECATION)
         return cls._read(
             backend=ParquetStorageBackend(),
             validation=validation,
@@ -1127,6 +1155,10 @@ class Collection(BaseCollection, ABC):
             **kwargs,
         )
 
+    @deprecated(
+        "`Collection.write_delta` is deprecated and will be removed in dataframely v3. "
+        "Write the individual members with `polars.DataFrame.write_delta` instead."
+    )
     def write_delta(
         self, target: str | Path | deltalake.DeltaTable, **kwargs: Any
     ) -> None:
@@ -1153,6 +1185,10 @@ class Collection(BaseCollection, ABC):
             break your schema.
 
             This method suffers from the same limitations as :meth:`~dataframely.Schema.serialize`.
+
+        .. deprecated:: 3.0.0
+            This method is deprecated and will be removed in dataframely v3. Write the
+            individual members with :meth:`polars.DataFrame.write_delta` instead.
         """
         self._write(
             backend=DeltaStorageBackend(),
@@ -1161,6 +1197,11 @@ class Collection(BaseCollection, ABC):
         )
 
     @classmethod
+    @deprecated(
+        "`Collection.scan_delta` is deprecated and will be removed in dataframely v3. "
+        "Read the individual members with `polars.scan_delta` and call `validate` "
+        "explicitly instead."
+    )
     def scan_delta(
         cls,
         source: str | Path | deltalake.DeltaTable,
@@ -1214,6 +1255,11 @@ class Collection(BaseCollection, ABC):
             break your schema.
 
             Be aware that this method suffers from the same limitations as :meth:`serialize`.
+
+        .. deprecated:: 3.0.0
+            This method is deprecated and will be removed in dataframely v3. Read the
+            individual members with :meth:`polars.scan_delta` and call :meth:`validate`
+            explicitly instead.
         """
         return cls._read(
             backend=DeltaStorageBackend(),
@@ -1223,6 +1269,11 @@ class Collection(BaseCollection, ABC):
         )
 
     @classmethod
+    @deprecated(
+        "`Collection.read_delta` is deprecated and will be removed in dataframely v3. "
+        "Read the individual members with `polars.read_delta` and call `validate` "
+        "explicitly instead."
+    )
     def read_delta(
         cls,
         source: str | Path | deltalake.DeltaTable,
@@ -1275,6 +1326,11 @@ class Collection(BaseCollection, ABC):
             break your schema.
 
             Be aware that this method suffers from the same limitations as :meth:`serialize`.
+
+        .. deprecated:: 3.0.0
+            This method is deprecated and will be removed in dataframely v3. Read the
+            individual members with :meth:`polars.read_delta` and call :meth:`validate`
+            explicitly instead.
         """
         return cls._read(
             backend=DeltaStorageBackend(),

{dataframely-2.13.0 → dataframely-2.13.2}/dataframely/schema.py

@@ -18,6 +18,7 @@ from polars._typing import FileSource
 
 from ._base_schema import ORIGINAL_COLUMN_PREFIX, BaseSchema
 from ._compat import PartitionSchemeOrSinkDirectory, deltalake, pa, pydantic, sa
+from ._deprecation import deprecated
 from ._match_to_schema import match_to_schema
 from ._native import format_rule_failures
 from ._plugin import all_rules, all_rules_horizontal, all_rules_required
@@ -897,6 +898,10 @@ class Schema(BaseSchema, ABC):
     # ------------------------------------ PARQUET ----------------------------------- #
 
     @classmethod
+    @deprecated(
+        "`Schema.write_parquet` is deprecated and will be removed in dataframely v3. "
+        "Use `polars.DataFrame.write_parquet` directly instead."
+    )
     def write_parquet(
         cls, df: DataFrame[Self], /, file: str | Path | IO[bytes], **kwargs: Any
     ) -> None:
@@ -919,10 +924,18 @@ class Schema(BaseSchema, ABC):
         Attention:
             Be aware that this method suffers from the same limitations as
             :meth:`serialize`.
+
+        .. deprecated:: 3.0.0
+            This method is deprecated and will be removed in dataframely v3. Use
+            :meth:`polars.DataFrame.write_parquet` directly instead.
         """
         cls._write(df=df, backend=ParquetStorageBackend(), file=file, **kwargs)
 
     @classmethod
+    @deprecated(
+        "`Schema.sink_parquet` is deprecated and will be removed in dataframely v3. "
+        "Use `polars.LazyFrame.sink_parquet` directly instead."
+    )
     def sink_parquet(
         cls,
         lf: LazyFrame[Self],
@@ -947,10 +960,18 @@ class Schema(BaseSchema, ABC):
         Attention:
             Be aware that this method suffers from the same limitations as
             :meth:`serialize`.
+
+        .. deprecated:: 3.0.0
+            This method is deprecated and will be removed in dataframely v3. Use
+            :meth:`polars.LazyFrame.sink_parquet` directly instead.
         """
         cls._sink(lf=lf, backend=ParquetStorageBackend(), file=file, **kwargs)
 
     @classmethod
+    @deprecated(
+        "`Schema.read_parquet` is deprecated and will be removed in dataframely v3. "
+        "Use `polars.read_parquet` and call `validate` explicitly instead."
+    )
     def read_parquet(
         cls,
         source: FileSource,
@@ -997,6 +1018,10 @@ class Schema(BaseSchema, ABC):
         Attention:
             Be aware that this method suffers from the same limitations as
             :meth:`serialize`.
+
+        .. deprecated:: 3.0.0
+            This method is deprecated and will be removed in dataframely v3. Use
+            :meth:`polars.read_parquet` and call :meth:`validate` explicitly instead.
         """
         return cls._read(
             ParquetStorageBackend(),
@@ -1007,6 +1032,10 @@ class Schema(BaseSchema, ABC):
         )
 
     @classmethod
+    @deprecated(
+        "`Schema.scan_parquet` is deprecated and will be removed in dataframely v3. "
+        "Use `polars.scan_parquet` and call `validate` explicitly instead."
+    )
     def scan_parquet(
         cls,
         source: FileSource,
@@ -1053,6 +1082,10 @@ class Schema(BaseSchema, ABC):
         Attention:
             Be aware that this method suffers from the same limitations as
             :meth:`serialize`.
+
+        .. deprecated:: 3.0.0
+            This method is deprecated and will be removed in dataframely v3. Use
+            :meth:`polars.scan_parquet` and call :meth:`validate` explicitly instead.
         """
         return cls._read(
             ParquetStorageBackend(),
@@ -1099,6 +1132,10 @@ class Schema(BaseSchema, ABC):
 
     # --------------------------------- Delta -----------------------------------------#
     @classmethod
+    @deprecated(
+        "`Schema.write_delta` is deprecated and will be removed in dataframely v3. "
+        "Use `polars.DataFrame.write_delta` directly instead."
+    )
     def write_delta(
         cls,
         df: DataFrame[Self],
@@ -1127,6 +1164,10 @@ class Schema(BaseSchema, ABC):
             in violation of group constraints that dataframely cannot catch
             without re-validating. Only use appends if you are certain that they do not
             break your schema.
+
+        .. deprecated:: 3.0.0
+            This method is deprecated and will be removed in dataframely v3. Use
+            :meth:`polars.DataFrame.write_delta` directly instead.
         """
         DeltaStorageBackend().write_frame(
             df=df,
@@ -1135,6 +1176,10 @@ class Schema(BaseSchema, ABC):
         )
 
     @classmethod
+    @deprecated(
+        "`Schema.scan_delta` is deprecated and will be removed in dataframely v3. "
+        "Use `polars.scan_delta` and call `validate` explicitly instead."
+    )
     def scan_delta(
         cls,
         source: str | Path | deltalake.DeltaTable,
@@ -1182,6 +1227,10 @@ class Schema(BaseSchema, ABC):
             that are not through dataframely will result in losing the metadata.
 
             This method suffers from the same limitations as :meth:`serialize`.
+
+        .. deprecated:: 3.0.0
+            This method is deprecated and will be removed in dataframely v3. Use
+            :meth:`polars.scan_delta` and call :meth:`validate` explicitly instead.
         """
         return cls._read(
             DeltaStorageBackend(),
@@ -1192,6 +1241,10 @@ class Schema(BaseSchema, ABC):
         )
 
     @classmethod
+    @deprecated(
+        "`Schema.read_delta` is deprecated and will be removed in dataframely v3. "
+        "Use `polars.read_delta` and call `validate` explicitly instead."
+    )
     def read_delta(
         cls,
         source: str | Path | deltalake.DeltaTable,
@@ -1244,6 +1297,10 @@ class Schema(BaseSchema, ABC):
             break your schema.
 
             This method suffers from the same limitations as :meth:`serialize`.
+
+        .. deprecated:: 3.0.0
+            This method is deprecated and will be removed in dataframely v3. Use
+            :meth:`polars.read_delta` and call :meth:`validate` explicitly instead.
         """
         return cls._read(
             DeltaStorageBackend(),

{dataframely-2.13.0 → dataframely-2.13.2}/docs/guides/features/serialization.md

@@ -1,5 +1,27 @@
 # Serialization
 
+```{warning}
+Most of the I/O functionality described on this page is **deprecated** and will be
+removed in dataframely v3 (see [#367](https://github.com/Quantco/dataframely/issues/367)).
+Calling any of these methods now emits a {class}`DeprecationWarning`. Specifically:
+
+- All I/O methods on {class}`~dataframely.Schema`
+  ({meth}`~dataframely.Schema.write_parquet`, {meth}`~dataframely.Schema.sink_parquet`,
+  {meth}`~dataframely.Schema.read_parquet`, {meth}`~dataframely.Schema.scan_parquet`,
+  {meth}`~dataframely.Schema.write_delta`, {meth}`~dataframely.Schema.read_delta`,
+  {meth}`~dataframely.Schema.scan_delta`) are deprecated. Use the corresponding
+  `polars` functions directly and call {meth}`~dataframely.Schema.validate` explicitly
+  where validation is required.
+- The `deltalake` I/O methods on {class}`~dataframely.Collection`
+  ({meth}`~dataframely.Collection.write_delta`, {meth}`~dataframely.Collection.read_delta`,
+  {meth}`~dataframely.Collection.scan_delta`) are deprecated.
+- {meth}`~dataframely.Collection.read_parquet` and
+  {meth}`~dataframely.Collection.scan_parquet` continue to exist, but reading with
+  `validation != "skip"` is deprecated: metadata will no longer be inspected and
+  validation will no longer run implicitly. Pass `validation="skip"` to opt into the
+  future behavior, or call {meth}`~dataframely.Collection.validate` explicitly.
+```
+
 `dataframely` provides support for easily storing and reading validated data.
 `polars` already provides native support for serializing data frames into different storage
 backends. For the storage of the data itself, `dataframely` usually dispatches to polars-native

{dataframely-2.13.0 → dataframely-2.13.2}/docs/guides/migration/index.md

@@ -26,17 +26,16 @@ As always, automated testing is useful here, but we also recommend checking the
 [published on GitHub](https://github.com/Quantco/dataframely/releases).
 
 In order to give users a heads-up before breaking changes are released, we introduce
-[FutureWarnings](https://docs.python.org/3/library/exceptions.html#FutureWarning).
+[DeprecationWarnings](https://docs.python.org/3/library/exceptions.html#DeprecationWarning).
 Warnings are the most direct and effective tool at our disposal for reaching users directly.
 We therefore generally recommend that users do not silence such warnings explicitly, but instead migrate their code
 proactively, whenever possible.
 However, we also understand that the need for migration may catch users at an inconvenient time, and a temporary band
 aid solution might be required.
-Users can disable `FutureWarnings` either through
-[python builtins](https://docs.python.org/3/library/warnings.html#warnings.filterwarnings),
-builtins from tools
-like [pytest](https://docs.pytest.org/en/stable/how-to/capture-warnings.html#controlling-warnings),
-or by setting the `DATAFRAMELY_NO_FUTURE_WARNINGS` environment variable to `true` or `1`.
+Users can disable `DeprecationWarnings` either through
+[python builtins](https://docs.python.org/3/library/warnings.html#warnings.filterwarnings)
+or through builtins from tools
+like [pytest](https://docs.pytest.org/en/stable/how-to/capture-warnings.html#controlling-warnings).
 
 ## Experimental features