DataExcept 0.4.3__tar.gz → 1.1.0__tar.gz

{dataexcept-0.4.3 → dataexcept-1.1.0}/CHANGELOG.md

@@ -7,6 +7,63 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.1.0] - 2026-09-02
+
+### Added
+
+- **`wrap` and `wrapping`**, for turning a third-party exception into a
+  DataExcept one:
+
+  ```python
+  with wrapping(OSError, DataLoadingError, source=path):
+      frame = pd.read_csv(path)
+  ```
+
+  The hand-written form is easy to get subtly wrong: a missing `from exc` loses
+  the traceback, the original passed to the wrong parameter is not recorded,
+  and a broad `except` relabels a `KeyboardInterrupt` as a data error. These
+  settle the wiring — the original goes to whichever constructor parameter
+  takes a cause (`original`, `original_exception` or `cause`) and is set as
+  `__cause__` either way, which matters because only 17 of the 100 classes
+  record one on an attribute.
+- Guidance in the advanced usage guide on building a project-specific
+  hierarchy on these bases, and what deriving from a domain root gets you.
+
+## [1.0.0] - 2026-08-25
+
+First stable release. The public API is frozen; see the
+[stability policy](https://diogoribeiro7.github.io/DataExcept/stability/)
+and the [migration guide](https://diogoribeiro7.github.io/DataExcept/migration/).
+
+### Added
+
+- A [migration guide](https://diogoribeiro7.github.io/DataExcept/migration/)
+  covering every rename between 0.1 and 1.0, with the one-line check for
+  whether any of it applies to you:
+  `python -W error::DeprecationWarning -m pytest` on 0.4.3.
+
+### Changed
+
+- **The public API is frozen.** The stability policy no longer carries a
+  pre-1.0 caveat: nothing public is renamed or removed outside a major release,
+  and anything that will be removed is deprecated first.
+
+### Removed
+
+- **`dataexcept.job_exceptions`**, deprecated since 0.1.0. Every name it
+  exported is available from `dataexcept.exceptions` and from the top-level
+  package, and they are the same class objects, so this is a change of import
+  line only.
+- **The four aliases introduced in 0.2.0**: `ConnectionError`,
+  `TimeoutError`, `datascience_exceptions.SerializationError` and
+  `pipeline_exceptions.FeatureEngineeringError`. Each has emitted a
+  `DeprecationWarning` naming 1.0.0 as its removal since 0.2.0.
+  `SerializationError` and `FeatureEngineeringError` remain exported — the
+  rename applied to the *duplicate* in each pair, and the original kept its
+  name.
+- The deprecation machinery itself (`dataexcept._deprecation`), which nothing
+  uses now.
+
 ### Fixed
 
 - The release workflow's `verify-wheel` job installed a hand-written list of
@@ -474,7 +531,9 @@ First public release.
 - Published to PyPI via OIDC trusted publishing; no long-lived API token is
   involved in a release.
 
-[Unreleased]: https://github.com/DiogoRibeiro7/DataExcept/compare/v0.4.3...HEAD
+[Unreleased]: https://github.com/DiogoRibeiro7/DataExcept/compare/v1.1.0...HEAD
+[1.1.0]: https://github.com/DiogoRibeiro7/DataExcept/compare/v1.0.0...v1.1.0
+[1.0.0]: https://github.com/DiogoRibeiro7/DataExcept/compare/v0.4.3...v1.0.0
 [0.4.3]: https://github.com/DiogoRibeiro7/DataExcept/compare/v0.4.2...v0.4.3
 [0.4.2]: https://github.com/DiogoRibeiro7/DataExcept/compare/v0.4.1...v0.4.2
 [0.4.1]: https://github.com/DiogoRibeiro7/DataExcept/compare/v0.4.0...v0.4.1

{dataexcept-0.4.3 → dataexcept-1.1.0}/CITATION.cff

@@ -1,7 +1,7 @@
 cff-version: 1.2.0
 message: "If you use this software, please cite it using the following metadata."
 title: "DataExcept"
-version: "0.4.3"
+version: "1.1.0"
 authors:
   - family-names: "Ribeiro"
     given-names: "Diogo"
@@ -11,4 +11,4 @@ authors:
 type: software
 url: "https://github.com/DiogoRibeiro7/DataExcept"
 repository-code: "https://github.com/DiogoRibeiro7/DataExcept"
-date-released: "2026-08-25"
+date-released: "2026-09-02"

{dataexcept-0.4.3 → dataexcept-1.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: DataExcept
-Version: 0.4.3
+Version: 1.1.0
 Summary: A Python package providing structured, easily-extendable custom exception types.
 License-Expression: MIT
 License-File: LICENSE
@@ -225,7 +225,7 @@ BiasDetectionError
 
 # Check version
 $ dataexcept --version
-dataexcept 0.4.3
+dataexcept 1.0.0
 ```
 
 ## 🎯 Use Cases
@@ -362,6 +362,7 @@ through [SECURITY.md](SECURITY.md), not the public issue tracker.
 - **Full Documentation**: [diogoribeiro7.github.io/DataExcept](https://diogoribeiro7.github.io/DataExcept/)
 - **API Reference**: [API Docs](https://diogoribeiro7.github.io/DataExcept/api/)
 - **API Stability**: [What is public and what may change](https://diogoribeiro7.github.io/DataExcept/stability/)
+- **Upgrading from 0.x**: [Migration guide](https://diogoribeiro7.github.io/DataExcept/migration/)
 - **Advanced Usage**: [Advanced Guide](https://diogoribeiro7.github.io/DataExcept/advanced_usage/)
 - **CLI Reference**: [CLI Guide](https://diogoribeiro7.github.io/DataExcept/cli/)
 - **Changelog**: [CHANGELOG.md](CHANGELOG.md)
@@ -375,7 +376,7 @@ If you use DataExcept in your research, please cite it:
   author = {Ribeiro, Diogo},
   title = {DataExcept: Structured Exception Handling for Data Science},
   url = {https://github.com/DiogoRibeiro7/DataExcept},
-  version = {0.4.3},
+  version = {1.0.0},
   year = {2026},
   publisher = {GitHub}
 }

{dataexcept-0.4.3 → dataexcept-1.1.0}/README.md

@@ -198,7 +198,7 @@ BiasDetectionError
 
 # Check version
 $ dataexcept --version
-dataexcept 0.4.3
+dataexcept 1.0.0
 ```
 
 ## 🎯 Use Cases
@@ -335,6 +335,7 @@ through [SECURITY.md](SECURITY.md), not the public issue tracker.
 - **Full Documentation**: [diogoribeiro7.github.io/DataExcept](https://diogoribeiro7.github.io/DataExcept/)
 - **API Reference**: [API Docs](https://diogoribeiro7.github.io/DataExcept/api/)
 - **API Stability**: [What is public and what may change](https://diogoribeiro7.github.io/DataExcept/stability/)
+- **Upgrading from 0.x**: [Migration guide](https://diogoribeiro7.github.io/DataExcept/migration/)
 - **Advanced Usage**: [Advanced Guide](https://diogoribeiro7.github.io/DataExcept/advanced_usage/)
 - **CLI Reference**: [CLI Guide](https://diogoribeiro7.github.io/DataExcept/cli/)
 - **Changelog**: [CHANGELOG.md](CHANGELOG.md)
@@ -348,7 +349,7 @@ If you use DataExcept in your research, please cite it:
   author = {Ribeiro, Diogo},
   title = {DataExcept: Structured Exception Handling for Data Science},
   url = {https://github.com/DiogoRibeiro7/DataExcept},
-  version = {0.4.3},
+  version = {1.0.0},
   year = {2026},
   publisher = {GitHub}
 }

{dataexcept-0.4.3 → dataexcept-1.1.0}/dataexcept/__init__.py

@@ -4,8 +4,8 @@ Every exception the package defines is importable straight from here::
 
     from dataexcept import ValidationError, ModelTrainingError
 
-They all derive from :class:`DataExceptError`, so one clause catches anything
-this package raises::
+They all derive from :class:`DataExceptError`, so one clause catches every
+operational exception this package raises::
 
     except DataExceptError:
         ...
@@ -22,8 +22,7 @@ try:  # Python >=3.11
 except ModuleNotFoundError:  # pragma: no cover - fallback for Python <3.11
     import tomli as tomllib  # type: ignore
 
-from importlib import import_module, metadata
-from typing import Any
+from importlib import metadata
 
 from . import (  # noqa: F401
     database_exceptions,
@@ -37,7 +36,6 @@ from . import (  # noqa: F401
     pipeline_exceptions,
     security_exceptions,
 )
-from ._deprecation import resolve_deprecated
 from .base import DataExceptError, UnpicklableCause, UnpicklableValue
 from .database_exceptions import (
     DatabaseConnectionError,
@@ -161,6 +159,7 @@ from .security_exceptions import (
     InvalidTokenError,
     SecurityError,
 )
+from .wrapping import wrap, wrapping
 
 __all__ = [
     # The root of the hierarchy: catches every operational exception the
@@ -268,15 +267,15 @@ __all__ = [
     "UnderfittingError",
     "ValidationError",
     "WebhookError",
+    # Turning a third-party exception into one of these.
+    "wrap",
+    "wrapping",
     # Logging helpers.
     "Context",
     "log_and_raise",
     "log_exception",
     "log_then_raise",
     # Domain modules, for callers who prefer a qualified import.
-    # job_exceptions is deliberately absent: it is deprecated, and listing it
-    # makes `from dataexcept import *` emit a DeprecationWarning, which turns
-    # into an error under -W error::DeprecationWarning. It stays importable.
     "database_exceptions",
     "dataengineering_exceptions",
     "datascience_exceptions",
@@ -295,19 +294,3 @@ except metadata.PackageNotFoundError:  # pragma: no cover - fallback during dev
     _root = Path(__file__).resolve().parents[1]
     with open(_root / "pyproject.toml", "rb") as _f:
         __version__ = tomllib.load(_f)["project"]["version"]
-
-
-#: Renamed in 0.2.0 because they shadowed Python builtins without inheriting
-#: from them. Each alias is the same class object as its replacement.
-_DEPRECATED_ALIASES = {
-    "ConnectionError": ServiceConnectionError,
-    "TimeoutError": OperationTimeoutError,
-}
-
-
-def __getattr__(name: str) -> Any:
-    if name == "job_exceptions":
-        module = import_module("dataexcept.job_exceptions")
-        globals()[name] = module
-        return module
-    return resolve_deprecated(__name__, _DEPRECATED_ALIASES, name)

{dataexcept-0.4.3 → dataexcept-1.1.0}/dataexcept/__main__.py

@@ -12,14 +12,9 @@ from typing import Iterable
 from . import __path__ as _PKG_PATH
 from . import __version__
 
-#: Deprecated compatibility shims. Listing these would advertise names that are
-#: scheduled for removal, and importing them emits a DeprecationWarning at
-#: anyone who merely wanted to see what the package offers.
-_DEPRECATED_MODULES = frozenset({"dataexcept.job_exceptions"})
-
 
 def _iter_exception_modules() -> Iterable[ModuleType]:
-    """Yield every non-deprecated submodule that explicitly defines ``__all__``."""
+    """Yield every submodule that explicitly defines ``__all__``."""
     allowed_suffixes = ("exceptions", "_exceptions")
     # dataexcept.base holds DataExceptError, the root of the hierarchy, and
     # does not match the suffix rule.
@@ -33,8 +28,6 @@ def _iter_exception_modules() -> Iterable[ModuleType]:
             and module_info.name not in always_include
         ):
             continue
-        if module_info.name in _DEPRECATED_MODULES:
-            continue
         try:
             module = import_module(module_info.name)
         except ImportError as exc:  # pragma: no cover - defensive guard

{dataexcept-0.4.3 → dataexcept-1.1.0}/dataexcept/datascience_exceptions/__init__.py

@@ -1,8 +1,5 @@
 """Custom exceptions for data science workflows."""
 
-from typing import Any
-
-from .._deprecation import resolve_deprecated
 from .base import DataScienceError
 from .ingestion import (
     DataAugmentationError,
@@ -86,11 +83,3 @@ __all__ = [
     "FeatureScalingError",
     "ModelCompatibilityError",
 ]
-
-#: Renamed in 0.2.0: this named the same thing as
-#: ``dataexcept.exceptions.SerializationError`` while being a different class.
-_DEPRECATED_ALIASES = {"SerializationError": ModelSerializationError}
-
-
-def __getattr__(name: str) -> Any:
-    return resolve_deprecated(__name__, _DEPRECATED_ALIASES, name)

{dataexcept-0.4.3 → dataexcept-1.1.0}/dataexcept/exceptions/__init__.py

@@ -1,7 +1,5 @@
 # __init__.py
-from typing import Any
 
-from .._deprecation import resolve_deprecated
 from .authentication import AuthenticationError, AuthorizationError
 from .base import JobError
 from .configuration import ConfigurationError
@@ -37,14 +35,3 @@ __all__ = [
     "WebhookError",
     "JobCancellationError",
 ]
-
-#: Renamed in 0.2.0 because they shadowed Python builtins without inheriting
-#: from them. The alias is the same class object, so ``except`` keeps working.
-_DEPRECATED_ALIASES = {
-    "ConnectionError": ServiceConnectionError,
-    "TimeoutError": OperationTimeoutError,
-}
-
-
-def __getattr__(name: str) -> Any:
-    return resolve_deprecated(__name__, _DEPRECATED_ALIASES, name)

{dataexcept-0.4.3 → dataexcept-1.1.0}/dataexcept/pipeline_exceptions.py

@@ -4,7 +4,6 @@ from __future__ import annotations
 
 from typing import Any, Optional
 
-from ._deprecation import resolve_deprecated
 from .base import DataExceptError
 from .redaction import redact_if_url, redact_url
 
@@ -210,12 +209,3 @@ __all__ = [
     "TypeCheckError",
     "DataFetchError",
 ]
-
-#: Renamed in 0.2.0: this named the same thing as
-#: ``dataexcept.datascience_exceptions.FeatureEngineeringError`` while being a
-#: different class, so catching one silently missed the other.
-_DEPRECATED_ALIASES = {"FeatureEngineeringError": FeaturePreprocessingError}
-
-
-def __getattr__(name: str) -> Any:
-    return resolve_deprecated(__name__, _DEPRECATED_ALIASES, name)

dataexcept-1.1.0/dataexcept/wrapping.py

@@ -0,0 +1,103 @@
+"""Turning a third-party exception into a DataExcept one.
+
+The pattern this replaces is everywhere in pipeline code::
+
+    try:
+        frame = pd.read_csv(path)
+    except OSError as exc:
+        raise DataLoadingError(path, exc) from exc
+
+It is easy to write and easy to get subtly wrong: forget the ``from exc`` and
+the traceback stops showing what actually failed; pass the original to the
+wrong parameter and it is not recorded at all; catch too broadly and a
+``KeyboardInterrupt`` becomes a data-loading error.
+
+:func:`wrap` and :func:`wrapping` do the same thing with the wiring settled.
+The original is passed to whichever constructor parameter takes a cause --
+``original``, ``original_exception`` or ``cause``, whichever that class uses --
+and set as ``__cause__`` either way, so a traceback always shows both.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import inspect
+from typing import Any, Iterator, Tuple, Type, Union
+
+from .base import DataExceptError
+
+__all__ = ["wrap", "wrapping"]
+
+#: Constructor parameter names used across the package for a wrapped
+#: exception. Checked in this order; the first the target accepts wins.
+_CAUSE_PARAMETERS = ("original", "original_exception", "cause")
+
+Catchable = Union[Type[BaseException], Tuple[Type[BaseException], ...]]
+
+
+def _cause_parameter(target: Type[DataExceptError]) -> str | None:
+    """Return the parameter of *target* that takes a wrapped exception."""
+    try:
+        parameters = inspect.signature(target.__init__).parameters
+    except (TypeError, ValueError):  # pragma: no cover - builtins and C types
+        return None
+    for name in _CAUSE_PARAMETERS:
+        if name in parameters:
+            return name
+    return None
+
+
+def wrap(
+    original: BaseException,
+    target: Type[DataExceptError],
+    /,
+    **kwargs: Any,
+) -> DataExceptError:
+    """Build *target* from *original*, recording it as the cause.
+
+    Extra keyword arguments go to the constructor::
+
+        raise wrap(exc, DataLoadingError, source=path) from exc
+
+    If *target* accepts a cause parameter, *original* is passed to it. Either
+    way ``__cause__`` is set, so a traceback shows the underlying failure even
+    for a class that records nothing.
+
+    An explicit ``original``/``cause`` keyword wins, so a caller can still say
+    exactly what they mean.
+    """
+    parameter = _cause_parameter(target)
+    if parameter is not None and parameter not in kwargs:
+        kwargs[parameter] = original
+
+    exception = target(**kwargs)
+    # Set unconditionally: the target may record nothing, and the point is that
+    # the traceback shows what actually failed.
+    exception.__cause__ = original
+    return exception
+
+
+@contextlib.contextmanager
+def wrapping(
+    catch: Catchable,
+    target: Type[DataExceptError],
+    /,
+    **kwargs: Any,
+) -> Iterator[None]:
+    """Translate *catch* raised inside the block into *target*.
+
+    ::
+
+        with wrapping(OSError, DataLoadingError, source=path):
+            frame = pd.read_csv(path)
+
+    Only exceptions matching *catch* are translated; everything else propagates
+    untouched, including anything already raised by this package. Because
+    *catch* is given explicitly there is no default broad ``except``, so a
+    ``KeyboardInterrupt`` or a bug in the block is never relabelled as a data
+    error.
+    """
+    try:
+        yield
+    except catch as exc:
+        raise wrap(exc, target, **kwargs) from exc

{dataexcept-0.4.3 → dataexcept-1.1.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "DataExcept"
-version = "0.4.3"
+version = "1.1.0"
 description = "A Python package providing structured, easily-extendable custom exception types."
 readme = "README.md"
 license = "MIT"

dataexcept-0.4.3/dataexcept/_deprecation.py

@@ -1,38 +0,0 @@
-"""Internal support for names that have been renamed.
-
-A rename keeps the old name working as an alias bound to the *same* class
-object, so an existing ``except OldName:`` keeps catching exactly what it
-caught before -- the alias is not a separate class.
-
-Access goes through a PEP 562 module ``__getattr__`` rather than a plain
-``OldName = NewName`` assignment, because an assignment cannot warn. This is
-private; see the stability policy for the user-facing contract.
-"""
-
-from __future__ import annotations
-
-import warnings
-from typing import Any, Mapping
-
-#: Version in which every currently deprecated alias is removed.
-REMOVED_IN = "1.0.0"
-
-
-def resolve_deprecated(module: str, aliases: Mapping[str, Any], name: str) -> Any:
-    """Return the target of the deprecated *name*, warning first.
-
-    Raises ``AttributeError`` for anything not in *aliases*, so normal
-    attribute lookup on the module keeps behaving normally.
-    """
-    try:
-        target = aliases[name]
-    except KeyError:
-        raise AttributeError(f"module {module!r} has no attribute {name!r}") from None
-    warnings.warn(
-        f"{module}.{name} is deprecated and will be removed in {REMOVED_IN}; "
-        f"use {target.__name__} instead",
-        DeprecationWarning,
-        # resolve_deprecated -> __getattr__ -> the caller we want to blame.
-        stacklevel=3,
-    )
-    return target

dataexcept-0.4.3/dataexcept/job_exceptions.py

@@ -1,71 +0,0 @@
-"""Backward compatible job-related exceptions.
-
-.. deprecated:: 0.1.0
-    Use :mod:`dataexcept.exceptions` instead. This module is scheduled for
-    removal in 1.0.0; see the stability policy in the documentation.
-
-This module re-exports the core job exceptions defined in
-:mod:`dataexcept.exceptions`. Importing it emits a :class:`DeprecationWarning`.
-Every name it exports is available from :mod:`dataexcept.exceptions` and from
-the top-level :mod:`dataexcept` package, so the migration is a change of import
-line only -- the classes are identical objects, not replacements, so existing
-``except`` clauses keep working during the transition.
-"""
-
-from __future__ import annotations
-
-import warnings
-
-from .exceptions import (
-    AuthenticationError,
-    AuthorizationError,
-    ConfigurationError,
-    CronExpressionError,
-    DependencyError,
-    DeserializationError,
-    EmailError,
-    JobCancellationError,
-    JobError,
-    NotificationError,
-    OperationTimeoutError,
-    ParsingError,
-    ResourceNotFoundError,
-    ScheduleConflictError,
-    SerializationError,
-    ServiceConnectionError,
-    ValidationError,
-    WebhookError,
-)
-
-# This module is itself deprecated, so it binds the pre-0.2.0 names directly
-# rather than going through the alias machinery and warning a second time.
-ConnectionError = ServiceConnectionError
-TimeoutError = OperationTimeoutError
-
-__all__ = [
-    "JobError",
-    "ValidationError",
-    "ConfigurationError",
-    "ConnectionError",
-    "TimeoutError",
-    "ResourceNotFoundError",
-    "DependencyError",
-    "AuthenticationError",
-    "AuthorizationError",
-    "ParsingError",
-    "SerializationError",
-    "DeserializationError",
-    "ScheduleConflictError",
-    "CronExpressionError",
-    "NotificationError",
-    "EmailError",
-    "WebhookError",
-    "JobCancellationError",
-]
-
-warnings.warn(
-    "dataexcept.job_exceptions is deprecated and will be removed in 1.0.0; "
-    "use dataexcept.exceptions instead",
-    DeprecationWarning,
-    stacklevel=2,
-)