django-data-purger 0.2.3__tar.gz

django_data_purger-0.2.3/PKG-INFO

@@ -0,0 +1,174 @@
+Metadata-Version: 2.1
+Name: django-data-purger
+Version: 0.2.3
+Summary: Periodically remove data from your Django app.
+License: MIT
+Author: Eirik Martiniussen Sylliaas
+Author-email: eirik@sylliaas.no
+Requires-Python: >=3.11,<3.14
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: pydantic (>=2.11.6,<3.0.0)
+Description-Content-Type: text/markdown
+
+# django-data-purger
+
+> Periodically remove data from your Django app.
+
+## Getting Started
+
+1. Install django-data-purger
+
+Use Poetry to add the package
+
+```bash
+$ poetry add django-data-purger
+```
+
+2. Add `django_data_purger` to `INSTALLED_APPS`
+
+Update your `INSTALLED_APP` setting:
+
+```python
+INSTALLED_APPS = [
+    'django...',
+    ...
+    'django_data_purger',
+]
+```
+
+3. Create a data purger in the Django app you want to clean periodically
+
+Example:
+
+```python
+# data_purger.py
+from django_data_purger.data_purger import DataPurger, PurgeResult
+from app.models import DataModel
+from datetime import datetime, timedelta
+
+class PurgeDataModel(DataPurger):
+    expected_delete_models = ("app.DataModel",)
+
+    def run(self, *, now: datetime) -> list[PurgeResult]:
+        old_threshold = now - timedelta(weeks=6)
+
+        entries = DataModel.objects.filter(
+            created_time__lte=old_threshold,
+        )
+
+        return self._delete_queryset_in_batch(
+            entries, batch_size=DataPurger.BATCH_SIZE_LARGE
+        )
+```
+
+4. Register the data purger in the `DATA_PURGERS` setting
+
+Add the purger to your settings:
+
+```python
+DATA_PURGERS = [
+    "app.data_purger.PurgeDataModel",
+]
+```
+
+
+5. Run the management command to purge old data
+
+Configure this command to run periodically using a scheduler like cron:
+
+```bash
+$ python manage.py run_data_purgers --force
+```
+
+## Settings
+
+| Setting name            | Type        | Default | Description                                                |
+| ----------------------- | ----------- | ------- | ---------------------------------------------------------- |
+| `DATA_PURGERS`          | `list[str]` | `[]`    | Array with import strings to data purgers in your project. |
+
+## The DataPurger Class
+
+The DataPurger class can be used to UPDATE or DELETE models. It runs within a transaction and ensures that updates or deletions are only applied to whitelisted models.
+
+### Update Model Instances
+
+```python
+class PurgeDataModel(DataPurger):
+    expected_update_models = ("app.DataModel",)
+
+    def run(self, *, now: datetime) -> list[PurgeResult]:
+        old_threshold = now - timedelta(weeks=6)
+
+        entries = DataModel.objects.filter(
+            created_time__lte=old_threshold,
+        )
+
+        return self._update_queryset_in_batch(
+            entries, updates={"is_deleted": True}, batch_size=DataPurger.BATCH_SIZE_MEDIUM
+        )
+```
+
+### Delete Model Instances
+
+```python
+class PurgeDataModel(DataPurger):
+    expected_delete_models = ("app.DataModel",)
+
+    def run(self, *, now: datetime) -> list[PurgeResult]:
+        old_threshold = now - timedelta(weeks=6)
+
+        entries = DataModel.objects.filter(
+            created_time__lte=old_threshold,
+        )
+
+        return self._delete_queryset_in_batch(
+            entries, batch_size=DataPurger.BATCH_SIZE_LARGE
+        )
+```
+
+## Planning for Model Instance Deletion
+
+Models often depend on each other via `ForeignKey` or `ManyToManyField` relationships. It can be challenging to determine the correct order for deleting models without causing unexpected cascading deletions or errors from `on_delete=models.PROTECT`.
+
+django-data-purger includes a tool to explore model dependencies. ✅ and 🛑 icons indicate whether a data purger for the model is already defined.
+
+Example:
+
+```bash
+$ poetry run python manage.py calculate_model_dependencies --model app.DataModel
+The following models depend on app.DataModel:
+- ...
+
+The following models depend on ...:
+- ...
+
+==============
+
+2 models depend on app.DataModel.
+
+==============
+
+The models need to be deleted in the following order to safely delete app.DataModel:
+(Models in the same batch can be deleted in any order.)
+
+Batch 1:
+- ✅ ...
+- 🛑 ...
+
+Batch 2:
+- ✅ ...
+```
+
+## Listing Models with Enabled Data Purgers
+
+To view all models with a configured data purger:
+
+```bash
+$ python manage.py print_data_purging_enabled_tables --action delete
+
+- app.DataModel
+```
+

django_data_purger-0.2.3/README.md

@@ -0,0 +1,158 @@
+# django-data-purger
+
+> Periodically remove data from your Django app.
+
+## Getting Started
+
+1. Install django-data-purger
+
+Use Poetry to add the package
+
+```bash
+$ poetry add django-data-purger
+```
+
+2. Add `django_data_purger` to `INSTALLED_APPS`
+
+Update your `INSTALLED_APP` setting:
+
+```python
+INSTALLED_APPS = [
+    'django...',
+    ...
+    'django_data_purger',
+]
+```
+
+3. Create a data purger in the Django app you want to clean periodically
+
+Example:
+
+```python
+# data_purger.py
+from django_data_purger.data_purger import DataPurger, PurgeResult
+from app.models import DataModel
+from datetime import datetime, timedelta
+
+class PurgeDataModel(DataPurger):
+    expected_delete_models = ("app.DataModel",)
+
+    def run(self, *, now: datetime) -> list[PurgeResult]:
+        old_threshold = now - timedelta(weeks=6)
+
+        entries = DataModel.objects.filter(
+            created_time__lte=old_threshold,
+        )
+
+        return self._delete_queryset_in_batch(
+            entries, batch_size=DataPurger.BATCH_SIZE_LARGE
+        )
+```
+
+4. Register the data purger in the `DATA_PURGERS` setting
+
+Add the purger to your settings:
+
+```python
+DATA_PURGERS = [
+    "app.data_purger.PurgeDataModel",
+]
+```
+
+
+5. Run the management command to purge old data
+
+Configure this command to run periodically using a scheduler like cron:
+
+```bash
+$ python manage.py run_data_purgers --force
+```
+
+## Settings
+
+| Setting name            | Type        | Default | Description                                                |
+| ----------------------- | ----------- | ------- | ---------------------------------------------------------- |
+| `DATA_PURGERS`          | `list[str]` | `[]`    | Array with import strings to data purgers in your project. |
+
+## The DataPurger Class
+
+The DataPurger class can be used to UPDATE or DELETE models. It runs within a transaction and ensures that updates or deletions are only applied to whitelisted models.
+
+### Update Model Instances
+
+```python
+class PurgeDataModel(DataPurger):
+    expected_update_models = ("app.DataModel",)
+
+    def run(self, *, now: datetime) -> list[PurgeResult]:
+        old_threshold = now - timedelta(weeks=6)
+
+        entries = DataModel.objects.filter(
+            created_time__lte=old_threshold,
+        )
+
+        return self._update_queryset_in_batch(
+            entries, updates={"is_deleted": True}, batch_size=DataPurger.BATCH_SIZE_MEDIUM
+        )
+```
+
+### Delete Model Instances
+
+```python
+class PurgeDataModel(DataPurger):
+    expected_delete_models = ("app.DataModel",)
+
+    def run(self, *, now: datetime) -> list[PurgeResult]:
+        old_threshold = now - timedelta(weeks=6)
+
+        entries = DataModel.objects.filter(
+            created_time__lte=old_threshold,
+        )
+
+        return self._delete_queryset_in_batch(
+            entries, batch_size=DataPurger.BATCH_SIZE_LARGE
+        )
+```
+
+## Planning for Model Instance Deletion
+
+Models often depend on each other via `ForeignKey` or `ManyToManyField` relationships. It can be challenging to determine the correct order for deleting models without causing unexpected cascading deletions or errors from `on_delete=models.PROTECT`.
+
+django-data-purger includes a tool to explore model dependencies. ✅ and 🛑 icons indicate whether a data purger for the model is already defined.
+
+Example:
+
+```bash
+$ poetry run python manage.py calculate_model_dependencies --model app.DataModel
+The following models depend on app.DataModel:
+- ...
+
+The following models depend on ...:
+- ...
+
+==============
+
+2 models depend on app.DataModel.
+
+==============
+
+The models need to be deleted in the following order to safely delete app.DataModel:
+(Models in the same batch can be deleted in any order.)
+
+Batch 1:
+- ✅ ...
+- 🛑 ...
+
+Batch 2:
+- ✅ ...
+```
+
+## Listing Models with Enabled Data Purgers
+
+To view all models with a configured data purger:
+
+```bash
+$ python manage.py print_data_purging_enabled_tables --action delete
+
+- app.DataModel
+```

django_data_purger-0.2.3/pyproject.toml

@@ -0,0 +1,131 @@
+[tool.poetry]
+name = "django-data-purger"
+version = "0.2.3"
+description = "Periodically remove data from your Django app."
+authors = ["Eirik Martiniussen Sylliaas <eirik@sylliaas.no>"]
+license = "MIT"
+readme = "README.md"
+packages = [{include = "django_data_purger", from = "src"}]
+
+[tool.poetry.dependencies]
+python = ">= 3.11, < 3.14"
+pydantic = "^2.11.6"
+
+[tool.poetry.group.dev.dependencies]
+ruff = "^0.11.13"
+mypy = "^1.16.1"
+pytest = "^8.4.0"
+pytest-cov = "^6.2.1"
+pytest-django = "^4.11.1"
+pytest-socket = "^0.7.0"
+django-stubs = "^5.2.0"
+pytest-xdist = "^3.7.0"
+django = "^5.2.3"
+networkx = "^3.4.2"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.ruff]
+exclude = [
+    ".git",
+    ".venv",
+    "__pycache__",
+    "migrations",
+]
+
+[tool.ruff.lint]
+select = [
+    # Regular flake8 rules
+    "C", "E", "F", "W",
+    # flake8-bugbear rules
+    "B",
+    # Import sorting rules
+    "I",
+    # Django rules
+    "DJ",
+    # flake8-comprehensions
+    "C4",
+    # Pylint rules
+    "PLC", "PLE", "PLR", "PLW",
+    # Ruff
+    "RUF",
+]
+ignore = [
+    # Disable magic value comparison. They're perfectly valid in tests and quite a few
+    # other places in the codebase. It would just be annoying to refactor.
+    "PLR2004",
+    # Too many return statements.
+    "PLR0911",
+    # Too many arguments to function call.
+    "PLR0913",
+    # DJ001 Avoid using null=True on string-based fields
+    "DJ001",
+    # DJ008 Model does not define __str__ method
+    "DJ008",
+]
+
+[tool.ruff.lint.flake8-tidy-imports]
+ban-relative-imports = "parents"
+
+[tool.ruff.lint.isort]
+combine-as-imports = true
+
+[tool.mypy]
+python_version = "3.12"
+plugins = ["mypy_django_plugin.main", "pydantic.mypy"]
+strict = true
+ignore_missing_imports = true
+
+[tool.django-stubs]
+django_settings_module = "tests.settings"
+
+[tool.pydantic-mypy]
+init_forbid_extra = true
+init_typed = true
+warn_required_dynamic_aliases = true
+
+[[tool.mypy.overrides]]
+module = [
+    # Disable typing in migration files generated by Django
+    "django_data_purger.*.migrations.*",
+]
+ignore_errors = true
+
+[tool.pytest.ini_options]
+pythonpath = [".", "src"]
+testpaths = ["tests"]
+# Reuse the database between tests
+addopts = [
+    "--reuse-db",
+    "--allow-hosts=localhost,::1,127.0.0.1",
+]
+# Include captured log messages in system-out in CI report file
+junit_logging = "system-out"
+markers = [ ]
+# --- pytest-django settings
+django_find_project = false
+DJANGO_SETTINGS_MODULE = "tests.settings"
+
+# Ignore select warnings from third party libraries.
+filterwarnings = [
+    "error",
+]
+
+[tool.coverage.run]
+branch = true
+source = [ "src/django_data_purger" ]
+omit = [
+    "*/migrations/*",
+]
+
+[tool.coverage.report]
+fail_under = 30
+exclude_lines = [
+    "pragma: no cover",
+    "if TYPE_CHECKING:",
+]
+
+[tool.coverage.html]
+directory = "coverage"

django_data_purger-0.2.3/src/django_data_purger/__init__.py

@@ -0,0 +1,30 @@
+"""Periodically remove data from your Django app."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from .data_purger import DataPurger, PurgeDeleteResult, PurgeResult, PurgeUpdateResult
+from .enums import DataPurgerAction
+from .exceptions import DataPurgerException
+from .services import (
+    get_tables_with_data_purging_enabled,
+    run_data_purger,
+    run_data_purgers,
+)
+
+try:
+    __version__ = version(__name__)
+except PackageNotFoundError:  # pragma: no cover
+    __version__ = "unknown"
+
+
+__all__ = [
+    "DataPurger",
+    "DataPurgerAction",
+    "DataPurgerException",
+    "PurgeDeleteResult",
+    "PurgeResult",
+    "PurgeUpdateResult",
+    "get_tables_with_data_purging_enabled",
+    "run_data_purger",
+    "run_data_purgers",
+]

django_data_purger-0.2.3/src/django_data_purger/apps.py

@@ -0,0 +1,12 @@
+from django.apps import AppConfig
+from django.core import checks
+
+from .checks import check_data_purgers
+
+
+class DjangoDataPurgerConfig(AppConfig):
+    name = "django_data_purger"
+    verbose_name = "Django Data Purger"
+
+    def ready(self) -> None:
+        checks.register(check_data_purgers)

django_data_purger-0.2.3/src/django_data_purger/checks.py

@@ -0,0 +1,44 @@
+from typing import Any
+
+from django.core.checks import Error, Warning
+
+from .conf import settings
+from .enums import DataPurgerAction
+from .exceptions import DataPurgerImportException, DataPurgerInvalidConfiguration
+from .services import import_data_purger
+
+
+def check_data_purgers(app_configs: Any, **kwargs: Any) -> list[Warning | Error]:
+    errors: list[Warning | Error] = []
+
+    for data_purger_import in settings.DATA_PURGERS:
+        # Make sure the data purger can be imported.
+        try:
+            data_purger_cls = import_data_purger(data_purger_import)
+        except DataPurgerImportException:
+            errors.append(
+                Error(
+                    f"django-data-purger is not able to import the data "
+                    f"purger {data_purger_import}.",
+                    hint=f"Make sure the {data_purger_import} entry in "
+                    "settings.DATA_PURGERS can be imported.",
+                )
+            )
+            continue
+
+        # Make sure we are able to retrieve the expected affected models tuples.
+        for action in DataPurgerAction:
+            try:
+                data_purger_cls.expected_affected_models(action=action)
+            except DataPurgerInvalidConfiguration:
+                errors.append(
+                    Error(
+                        f"django-data-purger could not find the expected affected "
+                        f"models when {action} operations is executed by "
+                        f"{data_purger_import}.",
+                        hint=f"Make sure the expected_{action.value}_models attr on "
+                        f"the data purger {data_purger_import} is a list of strings.",
+                    )
+                )
+
+    return errors

django_data_purger-0.2.3/src/django_data_purger/conf.py

@@ -0,0 +1,14 @@
+from django.conf import settings as django_settings
+
+
+class Settings:
+    @property
+    def DATA_PURGERS(self) -> list[str]:
+        return getattr(
+            django_settings,
+            "DATA_PURGERS",
+            [],
+        )
+
+
+settings = Settings()

django_data_purger-0.2.3/src/django_data_purger/data_purger.py

@@ -0,0 +1,155 @@
+from collections import defaultdict
+from datetime import datetime
+from typing import Any, ClassVar
+
+from django.db.models import QuerySet
+from pydantic import BaseModel, TypeAdapter, ValidationError
+
+from .enums import DataPurgerAction
+from .exceptions import DataPurgerInvalidConfiguration
+from .utils import queryset_in_batches_non_slicing
+
+
+class PurgeResult(BaseModel):
+    model: str
+    action: DataPurgerAction
+    affected_items: int
+
+
+class PurgeUpdateResult(PurgeResult):
+    action: DataPurgerAction = DataPurgerAction.UPDATE
+
+
+class PurgeDeleteResult(PurgeResult):
+    action: DataPurgerAction = DataPurgerAction.DELETE
+
+
+class DataPurger:
+    BATCH_SIZE_LARGE = 500_000
+    BATCH_SIZE_MEDIUM = 10_000
+    BATCH_SIZE_SMALL = 500
+
+    DRY_RUN_OVERRIDE: ClassVar[bool] = False
+
+    expected_update_models: ClassVar[tuple[str, ...]] = ()
+    expected_delete_models: ClassVar[tuple[str, ...]] = ()
+
+    def run(self, *, now: datetime) -> list[PurgeResult]:
+        raise NotImplementedError("Subclasses must implement run")
+
+    def _update_queryset_in_batch(
+        self,
+        queryset: QuerySet[Any],
+        *,
+        batch_size: int = BATCH_SIZE_MEDIUM,
+        updates: dict[str, Any],
+        affected_rows_limit: int | None = None,
+    ) -> list[PurgeResult]:
+        """Update queryset in batches, return a list of PurgeResults."""
+        results: list[PurgeResult] = []
+
+        for batch in queryset_in_batches_non_slicing(queryset, chunk_size=batch_size):
+            results += self._update_queryset(batch, updates)
+
+            if affected_rows_limit and (
+                sum(result.affected_items for result in results) >= affected_rows_limit
+            ):
+                break
+
+        # Some models may have multiple purge results in the result list.
+        # Group them together by model name for better output.
+        queryset_result: dict[str, int] = defaultdict(int)
+
+        for result in results:
+            queryset_result[result.model] += result.affected_items
+
+        return [
+            PurgeUpdateResult(model=model, affected_items=affected_items)
+            for model, affected_items in queryset_result.items()
+        ]
+
+    def _delete_queryset_in_batch(
+        self,
+        queryset: QuerySet[Any],
+        *,
+        batch_size: int = BATCH_SIZE_MEDIUM,
+        affected_rows_limit: int | None = None,
+    ) -> list[PurgeResult]:
+        """Delete queryset in batches, return a list of PurgeResults."""
+        results: list[PurgeResult] = []
+
+        for batch in queryset_in_batches_non_slicing(queryset, chunk_size=batch_size):
+            results += self._delete_queryset(batch)
+
+            if affected_rows_limit and (
+                sum(result.affected_items for result in results) >= affected_rows_limit
+            ):
+                break
+
+        # Some models may have multiple purge results in the result list.
+        # Group them together by model name for better output.
+        queryset_result: dict[str, int] = defaultdict(int)
+
+        for result in results:
+            queryset_result[result.model] += result.affected_items
+
+        return [
+            PurgeDeleteResult(model=model, affected_items=affected_items)
+            for model, affected_items in queryset_result.items()
+        ]
+
+    def _update_queryset(
+        self, queryset: QuerySet[Any], updates: dict[str, Any]
+    ) -> list[PurgeResult]:
+        """Update items in querset and return a list of PurgeResults."""
+        affected_models = queryset.update(**updates)
+
+        result: list[PurgeResult] = []
+
+        result.append(
+            PurgeUpdateResult(
+                model=queryset.model._meta.label,
+                affected_items=affected_models,
+            )
+        )
+
+        return result
+
+    def _delete_queryset(self, queryset: QuerySet[Any]) -> list[PurgeResult]:
+        """Delete items in querset and return a list of PurgeResults."""
+        _, affected_models = queryset.delete()
+
+        result: list[PurgeResult] = []
+
+        for model, affected_items in affected_models.items():
+            result.append(PurgeDeleteResult(model=model, affected_items=affected_items))
+
+        return result
+
+    #
+    # Expected models
+    #
+
+    @classmethod
+    def expected_affected_models(cls, action: DataPurgerAction) -> set[str]:
+        """Return a set with the expected models affected by this data purger."""
+
+        attr = f"expected_{action.value}_models"
+
+        if not hasattr(cls, attr):
+            raise DataPurgerInvalidConfiguration(
+                f"Data purger {cls} does not have the {attr} configured."
+            )
+
+        expected_models = getattr(cls, attr)
+
+        try:
+            TypeAdapter(set[str] | list[str] | tuple[str]).validate_python(
+                expected_models
+            )
+        except ValidationError as exc:
+            raise DataPurgerInvalidConfiguration(
+                f"The {attr} attr on the data purger {cls} has to be a list of strings."
+            ) from exc
+
+        return set(getattr(cls, attr))

django_data_purger-0.2.3/src/django_data_purger/enums.py

@@ -0,0 +1,8 @@
+from django.db.models import TextChoices
+
+
+class DataPurgerAction(TextChoices):
+    """Action to perform on the model by a data purger."""
+
+    UPDATE = "update"
+    DELETE = "delete"

django_data_purger-0.2.3/src/django_data_purger/exceptions.py

@@ -0,0 +1,10 @@
+class DataPurgerException(Exception):
+    """Base exception for all other exeptions raised by this library."""
+
+
+class DataPurgerImportException(DataPurgerException):
+    """Raised when the framework is unable to import a data purger."""
+
+
+class DataPurgerInvalidConfiguration(DataPurgerException):
+    """Raised when the data purger is configured incorrectly."""

django_data_purger-0.2.3/src/django_data_purger/management/commands/calculate_model_dependencies.py

@@ -0,0 +1,189 @@
+from collections import defaultdict
+from typing import Any, DefaultDict, cast
+
+try:
+    import networkx as nx
+except ImportError:
+    nx = None
+
+from django.apps import apps
+from django.core.management.base import BaseCommand, CommandParser
+from django.db import models
+
+from django_data_purger.enums import DataPurgerAction
+from django_data_purger.services import get_tables_with_data_purging_enabled
+
+
+class Collector:
+    def __init__(self, *, source_model: type[models.Model]) -> None:
+        if nx is None:
+            raise RuntimeError(
+                "Please install networkx before using the model dependency collector."
+            )
+
+        self.source_model = source_model
+
+        self.seen_models: set[type[models.Model]] = set()
+        self.dependencies: DefaultDict[type[models.Model], set[type[models.Model]]] = (
+            defaultdict(set)
+        )
+
+    def add_dependency(
+        self, *, model: type[models.Model], dependency: type[models.Model]
+    ) -> None:
+        self.dependencies[model].add(dependency)
+
+    def collect(self, *, model: type[models.Model]) -> None:
+        child_relations = (
+            rel
+            for rel in model._meta.get_fields(include_hidden=True)
+            if rel.auto_created
+            and not rel.concrete
+            and (rel.one_to_one or rel.one_to_many)
+        )
+
+        for rel in child_relations:
+            related_model = cast(type[models.Model], rel.related_model)
+
+            if model == related_model:
+                continue
+
+            if not related_model:
+                continue
+
+            self.add_dependency(model=model, dependency=related_model)
+
+            if related_model not in self.seen_models:
+                self.seen_models.add(related_model)
+                self.collect(model=related_model)
+
+    def calculate_affected_models(self) -> int:
+        affected_models: set[type[models.Model]] = set()
+
+        for dependencies in self.dependencies.values():
+            affected_models |= dependencies
+
+        return len(affected_models)
+
+    def calculate_dependency_ordering(self) -> list[list[type[models.Model]]]:  # noqa
+        # Grab a copy of the dependencies, we remove items from it while
+        # calculate the depencency ordering.
+        dependencies = self.dependencies.copy()
+
+        delete_batches: list[list[type[models.Model]]] = []
+
+        while dependencies:
+            models_to_delete: set[type[models.Model]] = set()
+            current_batch: set[type[models.Model]] = set()
+
+            for parent, model_dependencies in dependencies.items():
+                all_models = {parent, *list(model_dependencies)}
+
+                for model in all_models:
+                    # We can't delete the model if it exists as a key in
+                    # the dependencies mapping.
+                    if model in dependencies.keys():
+                        continue
+
+                    # It's safe to add the model to the current batch of models that
+                    # can be deleted independently of each other.
+                    current_batch.add(model)
+
+                    # Remove the model from the dependency tree.
+                    for deps in dependencies.values():
+                        try:
+                            deps.remove(model)
+                        except KeyError:
+                            pass
+
+                    # Models without any dependencies left can be deleted from
+                    # the dependency tree.
+                    for model_to_delete, deps in dependencies.items():
+                        if not deps:
+                            models_to_delete.add(model_to_delete)
+
+                    # Circular dependencies where only models form the circle exists
+                    # as dependencies has to be removed.
+                    edges = [[k, v] for k, items in dependencies.items() for v in items]
+                    graph = nx.DiGraph(edges)
+                    cycles = nx.simple_cycles(graph)
+
+                    for cycle in cycles:
+                        cycle_set = set(cycle)
+                        for _model, _dependencies in dependencies.items():
+                            if _model in cycle and _dependencies.issubset(cycle_set):
+                                models_to_delete.add(_model)
+
+            # Add the current batch of models to the result.
+            delete_batches.append(list(current_batch))
+
+            # Remove the models without any dependences left from the dependency tree
+            # before calculating the next batch.
+            for model in models_to_delete:
+                del dependencies[model]
+
+        return delete_batches
+
+    def print_dependency_results(self) -> None:
+        def get_model_name(model: type[models.Model]) -> str:
+            return f"{model._meta.app_label}.{model._meta.object_name}"
+
+        for model, dependencies in self.dependencies.items():
+            print(f"The following models depend on {get_model_name(model)}:")
+            for dependency in dependencies:
+                print(f"- {get_model_name(dependency)}")
+            print()
+
+        print()
+        print("==============")
+        print()
+
+        print(
+            f"{self.calculate_affected_models()} models depend "
+            f"on {get_model_name(self.source_model)}."
+        )
+
+        print()
+        print("==============")
+        print()
+
+        print(
+            f"The models have to be deleted in the following order "
+            f"before you can delete {get_model_name(self.source_model)}:"
+        )
+        print("(Models from each batch can be deleted in an arbitrary order.)")
+        print()
+
+        batches = self.calculate_dependency_ordering()
+        tables_with_purging = get_tables_with_data_purging_enabled(
+            action=DataPurgerAction.DELETE
+        )
+
+        for i, batch in enumerate(batches):
+            print(f"Batch {i + 1}:")
+            for model in batch:
+                model_name = get_model_name(model)
+                print(
+                    "- "
+                    + ("✅" if model_name in tables_with_purging else "🛑")
+                    + f"  {model_name}"
+                )
+
+            print()
+
+
+class Command(BaseCommand):
+    help = "List models depending on the input model"
+
+    def add_arguments(self, parser: CommandParser) -> None:
+        parser.add_argument("--model", required=True)
+
+    def handle(self, *args: Any, **options: Any) -> None:
+        model_full_name = options["model"]
+        app_label, model_name = model_full_name.split(".")
+
+        model = apps.get_model(app_label=app_label, model_name=model_name)
+
+        collector = Collector(source_model=model)
+        collector.collect(model=model)
+        collector.print_dependency_results()

django_data_purger-0.2.3/src/django_data_purger/management/commands/print_data_purging_enabled_tables.py

@@ -0,0 +1,33 @@
+from typing import Any
+
+from django.core.management.base import BaseCommand, CommandParser
+
+from django_data_purger.enums import DataPurgerAction
+from django_data_purger.exceptions import DataPurgerException
+from django_data_purger.services import get_tables_with_data_purging_enabled
+
+
+class Command(BaseCommand):
+    help = "Print tables with data purging enabled."
+
+    def add_arguments(self, parser: CommandParser) -> None:
+        parser.add_argument("--action", required=True)
+
+    def handle(self, *args: Any, **options: Any) -> None:
+        action_value = options["action"]
+
+        try:
+            action = DataPurgerAction(action_value)
+        except ValueError as exc:
+            supported_actions = ", ".join(DataPurgerAction)
+            raise DataPurgerException(
+                f"Action {action_value} is not a valid action, use one "
+                f"of {supported_actions}."
+            ) from exc
+
+        tables = get_tables_with_data_purging_enabled(action=action)
+
+        print("Print tables with data purging enabled:")
+
+        for table in tables:
+            print(f"- {table}")

django_data_purger-0.2.3/src/django_data_purger/management/commands/run_data_purgers.py

@@ -0,0 +1,18 @@
+from typing import Any
+
+from django.core.management import BaseCommand
+from django.core.management.base import CommandParser
+
+from django_data_purger.services.data_purger import run_data_purgers
+
+
+class Command(BaseCommand):
+    help: str = "Removes stale database objects."
+
+    def add_arguments(self, parser: CommandParser) -> None:
+        parser.add_argument("--force", default=False, action="store_true")
+
+    def handle(self, *args: Any, **options: Any) -> None:
+        force = options["force"]
+
+        run_data_purgers(dry_run=not force)

django_data_purger-0.2.3/src/django_data_purger/services/__init__.py

@@ -0,0 +1,9 @@
+from .data_purger import import_data_purger, run_data_purger, run_data_purgers
+from .tables import get_tables_with_data_purging_enabled
+
+__all__ = [
+    "get_tables_with_data_purging_enabled",
+    "import_data_purger",
+    "run_data_purger",
+    "run_data_purgers",
+]

django_data_purger-0.2.3/src/django_data_purger/services/data_purger.py

@@ -0,0 +1,139 @@
+import logging
+import time
+from datetime import datetime
+
+from django.db import transaction
+from django.utils import timezone
+from django.utils.module_loading import import_string
+
+from django_data_purger.conf import settings
+from django_data_purger.data_purger import DataPurger, PurgeResult
+from django_data_purger.enums import DataPurgerAction
+from django_data_purger.exceptions import DataPurgerImportException
+
+logger = logging.getLogger(__name__)
+
+
+class DryRunException(Exception):
+    """
+    Exception raised to rollback the transaction.
+
+    This exception is only used to controll the roll-back,
+    and it should not be exposed outside of this file.
+    """
+
+
+def import_data_purger(data_purger_path: str) -> type[DataPurger]:
+    """Import data purger, raise exception if the import failed."""
+
+    try:
+        data_purger_cls: type[DataPurger] = import_string(data_purger_path)
+        assert issubclass(data_purger_cls, DataPurger)
+    except ImportError as exc:
+        raise DataPurgerImportException(
+            "Data purger could not be imported, check the import path."
+        ) from exc
+    except AssertionError as exc:
+        raise DataPurgerImportException(
+            "Imported object is not based on the DataPurger base class."
+        ) from exc
+
+    return data_purger_cls
+
+
+def run_data_purgers(dry_run: bool = True) -> None:
+    """Run data purgers defined in settings.DATA_PURGERS."""
+    data_purgers_imports = settings.DATA_PURGERS
+
+    now = timezone.now()
+
+    results: list[PurgeResult] = []
+
+    for data_purger_import in data_purgers_imports:
+        try:
+            data_purger_cls = import_data_purger(data_purger_import)
+        except DataPurgerImportException:
+            logger.warning(
+                "Could not import data purger %s, skipping please fix your "
+                "purger imports.",
+                data_purger_import,
+            )
+            continue
+
+        data_purger = data_purger_cls()
+
+        results += run_data_purger(data_purger=data_purger, dry_run=dry_run, now=now)
+
+    updated_items = sum(
+        result.affected_items
+        for result in results
+        if result.action == DataPurgerAction.UPDATE
+    )
+    deleted_items = sum(
+        result.affected_items
+        for result in results
+        if result.action == DataPurgerAction.DELETE
+    )
+
+    logger.info(
+        f"Data purgers updated {updated_items:,} and deleted {deleted_items:,} items"
+    )
+
+
+def run_data_purger(
+    *, data_purger: DataPurger, dry_run: bool, now: datetime | None = None
+) -> list[PurgeResult]:
+    """Run a single data purger and log the result."""
+    purger_name = data_purger.__class__.__name__
+
+    logger.info(f"Running data purger {purger_name}")
+
+    now = now or timezone.now()
+
+    try:
+        with transaction.atomic():
+            start_time = time.monotonic()
+
+            results = data_purger.run(now=now)
+
+            done_time = time.monotonic()
+
+            logger.info(
+                f"Data purger {purger_name} done (in {(done_time - start_time):.1f}s)"
+            )
+
+            for result in results:
+                expected_affected_models = data_purger.expected_affected_models(
+                    action=result.action
+                )
+
+                if result.model not in expected_affected_models:
+                    raise RuntimeError(
+                        f"Unexpected {result.action} on model {result.model} by "
+                        f"{purger_name}, rolling back transaction"
+                    )
+
+            if dry_run:
+                raise DryRunException()
+
+            if data_purger.DRY_RUN_OVERRIDE:
+                logger.info(
+                    "Data purger %s has the DRY_RUN_OVERRIDE flag set to True, "
+                    "changes are going to be rolled back.",
+                    purger_name,
+                )
+                raise DryRunException()
+
+    except DryRunException:
+        pass
+
+    if len(results) == 0:
+        logger.info(f"No changes made by {purger_name}")
+
+    for result in results:
+        logger.info(
+            f"Purge result from {purger_name}: "
+            f"{result.model} {result.action} {result.affected_items:,} items"
+        )
+
+    return results

django_data_purger-0.2.3/src/django_data_purger/services/tables.py

@@ -0,0 +1,41 @@
+from logging import getLogger
+
+from django_data_purger.conf import settings
+from django_data_purger.enums import DataPurgerAction
+from django_data_purger.exceptions import DataPurgerImportException
+
+from .data_purger import import_data_purger
+
+logger = getLogger(__name__)
+
+
+def get_tables_with_data_purging_enabled(*, action: DataPurgerAction) -> list[str]:
+    """Return a list of tables with data purging enabled."""
+    data_purgers_imports = settings.DATA_PURGERS
+
+    tables: set[str] = set()
+
+    for data_purger_import in data_purgers_imports:
+        try:
+            data_purger_cls = import_data_purger(data_purger_import)
+        except DataPurgerImportException:
+            logger.warning(
+                "Could not import data purger %s, skipping please fix your "
+                "purger imports.",
+                data_purger_import,
+            )
+            continue
+
+        # Some data purgers is configured to always run with DRY_RUN mode enabled.
+        # Changes executed by the purger is always going to be rolled back.
+        if data_purger_cls.DRY_RUN_OVERRIDE:
+            logger.info(
+                "Data purger %s has the DRY_RUN_OVERRIDE flag set to True, "
+                "skipping tables.",
+                data_purger_import,
+            )
+            continue
+
+        tables |= data_purger_cls.expected_affected_models(action=action)
+
+    return sorted(tables)

django_data_purger-0.2.3/src/django_data_purger/utils.py

@@ -0,0 +1,37 @@
+from typing import Generator, TypeVar
+
+from django.db.models import Model, QuerySet
+
+TModel = TypeVar("TModel", bound=Model)
+
+
+def queryset_in_batches_non_slicing(
+    queryset: QuerySet[TModel], chunk_size: int = 1000
+) -> Generator[QuerySet[TModel], None, None]:
+    """
+    Iterate over a Django queryset that is ordered by primary key.
+
+    Does not slice the queryset and filters naively on upper and lower bounds
+    using pk and chunk size. This allows queryset operations to be performed
+    such as `.update()` and `.delete()`.
+    """
+
+    queryset = queryset.order_by("pk")
+
+    first_element = queryset.first()
+
+    # Empty queryset
+    if first_element is None:
+        return
+
+    pk = max(first_element.pk - 1, 0)
+
+    last_element = queryset.last()
+
+    assert last_element is not None
+
+    while pk < last_element.pk:
+        prev_pk = pk
+        pk = pk + chunk_size
+        queryset_to_yield = queryset.filter(pk__gt=prev_pk, pk__lte=pk)
+        yield queryset_to_yield