scitex-compat

Backward compatibility shims and deprecation wrappers for the SciTeX ecosystem.

Full Documentation · uv pip install scitex-compat[all]

Problem and Solution

Installation

pip install scitex-compat

Architecture

scitex-compat is the SSOT (single source of truth) for the @deprecated decorator across the SciTeX ecosystem. Other packages (notably scitex-decorators) re-export from here, so there is exactly one implementation to fix bugs in or extend.

scitex-compat/
├── src/scitex_compat/
│   ├── __init__.py              # deprecated, notify, notify_async
│   └── _compat.py               # @deprecated impl + notify/notify_async shims
├── docs/adr/
│   └── 0001-canonical-deprecated-decorator.md   # SSOT decision
└── tests/

See also: scitex-decorators ADR-0001 documenting the re-export contract from the other side.

Quick Start

from scitex_compat import deprecated

# 1. Warn-only form
@deprecated(reason="use new_function instead; removed in 3.0")
def old_function():
    pass

# 2. Forwarding form — redirects calls to the new location
@deprecated(reason="moved to scitex.session.start", forward_to="..session.start")
def start():
    pass

1 Interfaces

from scitex_compat import deprecated, notify, notify_async

# Warn-only: emits DeprecationWarning, still calls the wrapped body.
@deprecated(reason="use new_func instead")
def old_func(*args, **kwargs):
    ...

# Forwarding: warning + transparent redirect via importlib.
# forward_to may be absolute ("pkg.mod.func") or relative ("..mod.func")
# resolved against the decorated function's __module__.
@deprecated(reason="moved", forward_to="scitex_other.mod.replacement")
def renamed_func(*args, **kwargs):
    ...

# Compat shims (forward to scitex.notify if installed)
notify("hello")
await notify_async("hello")

Demo

sequenceDiagram
    participant U as user code
    participant O as old_func (deprecated)
    participant N as new_func
    participant W as warnings
    U->>O: old_func(x=1)
    O->>W: DeprecationWarning("old_func is deprecated: <reason>")
    O->>N: importlib resolves forward_to → new_func(x=1)
    N-->>U: result
    Note over U,N: One release later, old_func can be removed.

Part of SciTeX

scitex-compat is part of SciTeX. Install via the umbrella with pip install scitex[compat] to use as scitex.compat (Python) or scitex compat ... (CLI).

Four Freedoms for Research

0. The freedom to run your research anywhere — your machine, your terms.
1. The freedom to study how every step works — from raw data to final manuscript.
2. The freedom to redistribute your workflows, not just your papers.
3. The freedom to modify any module and share improvements with the community.

AGPL-3.0 — because we believe research infrastructure deserves the same freedoms as the software it runs on.

License

AGPL-3.0