sqlalchemy-deprecated-column 0.1.0__py3-none-any.whl

sqlalchemy_deprecated_column/__init__.py

@@ -0,0 +1,3 @@
+from .deprecate_field import configure, deprecated_column
+
+__all__ = ["configure", "deprecated_column"]

sqlalchemy_deprecated_column/deprecate_field.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+import warnings
+from dataclasses import dataclass
+from typing import Any
+
+from sqlalchemy import null
+from sqlalchemy.ext.hybrid import hybrid_property
+from sqlalchemy.orm import mapped_column
+
+
+@dataclass
+class _Configuration:
+    alembic_mode: bool = False
+
+
+_config = _Configuration()
+
+
+def configure(alembic_mode: bool = False) -> None:
+    """Configure sqlalchemy-deprecate-fields behaviour.
+
+    Call with ``alembic_mode=True`` at the top of ``alembic/env.py``, before
+    any model imports, so that Alembic sees deprecated columns as real nullable
+    columns and does not generate DROP COLUMN migrations.
+    """
+    _config.alembic_mode = alembic_mode
+
+
+class _DeprecatedColumn:
+    def __init__(self, *_args: Any, **_kwargs: Any) -> None:
+        pass
+
+    def __set_name__(self, owner: type, name: str) -> None:
+        @hybrid_property
+        def prop(instance: Any) -> None:
+            warnings.warn(
+                f"accessing deprecated field {type(instance).__name__}.{name}",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+            return None
+
+        @prop.inplace.setter
+        def _(instance: Any, value: Any) -> None:
+            warnings.warn(
+                f"writing to deprecated field {type(instance).__name__}.{name}",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+
+        @prop.inplace.expression
+        @classmethod
+        def _(cls: type) -> Any:
+            warnings.warn(
+                f"referencing deprecated class field {cls.__name__}.{name}",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+            return null()
+
+        setattr(owner, name, prop)
+
+
+def deprecated_column(*args: Any, **kwargs: Any) -> Any:
+    """Drop-in replacement for mapped_column() that marks the column as deprecated.
+
+    In normal mode the column is excluded from the ORM mapper entirely:
+    it will not appear in SELECT, INSERT, UPDATE, or RETURNING statements.
+    Instance reads return None and emit a DeprecationWarning; writes emit a
+    warning and are silently discarded.
+
+    In Alembic mode (after ``configure(alembic_mode=True)``) the call is
+    forwarded to ``mapped_column(*args, nullable=True, **kwargs)`` so that
+    Alembic sees the column as a regular nullable column and generates correct
+    migrations.
+
+    Usage::
+
+        class User(Base):
+            __tablename__ = "users"
+            id: Mapped[int] = mapped_column(primary_key=True)
+            old_email: Mapped[str] = deprecated_column(String(200))
+    """
+    if _config.alembic_mode:
+        kwargs["nullable"] = True
+        return mapped_column(*args, **kwargs)
+    return _DeprecatedColumn(*args, **kwargs)

sqlalchemy_deprecated_column-0.1.0.dist-info/METADATA

@@ -0,0 +1,95 @@
+Metadata-Version: 2.4
+Name: sqlalchemy-deprecated-column
+Version: 0.1.0
+Summary: Utility to mark SQLAlchemy ORM columns as deprecated to allow removing them in a backwards compatible manner.
+Author: Jakub Bacic
+Author-email: Jakub Bacic <jakub.bacic@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries
+Requires-Dist: sqlalchemy>=2.0
+Requires-Python: >=3.10
+Project-URL: Repository, https://github.com/jakub-bacic/sqlalchemy-deprecate-fields
+Project-URL: Issues, https://github.com/jakub-bacic/sqlalchemy-deprecate-fields/issues
+Project-URL: Changelog, https://github.com/jakub-bacic/sqlalchemy-deprecate-fields/blob/main/CHANGELOG.md
+Description-Content-Type: text/markdown
+
+# sqlalchemy-deprecated-column
+
+Safely remove SQLAlchemy ORM columns through a gradual deprecation process.
+Inspired by [django-deprecate-fields](https://github.com/3YOURMIND/django-deprecate-fields).
+
+## Installation
+
+```bash
+pip install sqlalchemy-deprecated-column
+```
+
+## How it works
+
+Removing a column from a live database requires coordination between code and schema changes. Dropping the column in a single step would break any running application instances that still reference it. `deprecated_column()` lets you do this safely in three steps:
+
+1. **Deprecate**: replace `mapped_column()` with `deprecated_column()` and run an Alembic migration. The column stays in the database but becomes nullable if it wasn't already.
+2. **Deploy**: the column is hidden from the ORM — it no longer appears in any generated SQL. Any remaining code that reads or writes the column gets a `DeprecationWarning` at runtime, making stale references easy to find and remove.
+3. **Remove**: once all references are gone, delete the `deprecated_column()` definition from the model and run a final migration to drop the column from the database.
+
+## Usage
+
+Replace `mapped_column()` with `deprecated_column()` for any column you want to deprecate:
+
+```python
+from sqlalchemy_deprecated_column import deprecated_column
+
+class User(Base):
+    __tablename__ = "users"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    email: Mapped[str] = mapped_column(String)
+    old_username: Mapped[str] = deprecated_column(String)  # was: mapped_column(String)
+```
+
+While the column is deprecated the library:
+
+- **Hides it from the ORM**: the column is excluded from all generated SQL queries — existing application code stays compatible even after the column is eventually dropped from the database.
+- **Warns on instance read**: `instance.old_username` returns `None` and emits a `DeprecationWarning` naming the model and column, so the call site is easy to locate.
+- **Warns on class-level reference**: `User.old_username` (e.g. in filter expressions) emits a `DeprecationWarning` and evaluates to SQL `NULL`.
+- **Warns on write and discards the value**: `instance.old_username = "x"` emits a `DeprecationWarning` and silently drops the value, so no stale data is written to the database.
+
+## Alembic integration
+
+Add the following **at the top of `alembic/env.py`, before any model imports**:
+
+```python
+import sqlalchemy_deprecated_column
+sqlalchemy_deprecated_column.configure(alembic_mode=True)
+
+# model imports must come after configure()
+from myapp import mymodel
+target_metadata = mymodel.Base.metadata
+```
+
+In Alembic mode, `deprecated_column()` acts as `mapped_column(nullable=True)`. Alembic will:
+
+- **Not** generate `DROP COLUMN` for deprecated columns.
+- **Generate `ALTER TABLE … DROP NOT NULL`** if the column was originally non-nullable. This is needed because once the column is deprecated the ORM stops including it in `INSERT` statements — a `NOT NULL` column without a value would cause those inserts to fail.
+
+## Requirements
+
+- Python 3.10+
+- SQLAlchemy 2.0+
+
+## License
+
+The code in this project is licensed under MIT license. See [LICENSE](./LICENSE) for more information.

sqlalchemy_deprecated_column-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+sqlalchemy_deprecated_column/__init__.py,sha256=zXxb7K26pIx6f36BbV0VBZVDEk9_wmwVQRhJZ9EKVc8,104
+sqlalchemy_deprecated_column/deprecate_field.py,sha256=SirAUjWaluYb8eO8T4UJKVQI_eH7zGau-rgztyMmRWs,2758
+sqlalchemy_deprecated_column/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+sqlalchemy_deprecated_column-0.1.0.dist-info/licenses/LICENSE,sha256=m77pqLLodhsaWr2RD7HxLjVDhci81XufaS719DWKrAI,1068
+sqlalchemy_deprecated_column-0.1.0.dist-info/WHEEL,sha256=WvwXFgRajeoYkfRVmDhkP4Qlqo31Mk687zIO2QQoFmw,80
+sqlalchemy_deprecated_column-0.1.0.dist-info/METADATA,sha256=rw8YdGSZcePNNKdz2O0TuqU7VlOk1fK3XdtgH7fO76s,4472
+sqlalchemy_deprecated_column-0.1.0.dist-info/RECORD,,

sqlalchemy_deprecated_column-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.11.7
+Root-Is-Purelib: true
+Tag: py3-none-any

sqlalchemy_deprecated_column-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jakub Bacic
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.