Metadata-Version: 2.4
Name: django-unused-model-inspector
Version: 0.1.1
Summary: Detect potentially unused Django model fields and methods.
Author: Abdou SEYE
License-Expression: MIT
Project-URL: Homepage, https://github.com/abduRahman49/django_unused_model_inspector
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: Django
Classifier: Framework :: Django :: 3.2
Classifier: Framework :: Django :: 4.2
Classifier: Framework :: Django :: 5
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Django>=3.2
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-django>=4.8; extra == "dev"
Requires-Dist: ruff>=0.5; extra == "dev"
Dynamic: license-file

# django-unused-model-inspector

`django-unused-model-inspector` is a Django app that reports model fields and model methods that appear to be unused across registered apps.

The package is intentionally conservative: it reports potentially unused members and includes confidence metadata. It does not delete or rewrite models.

References are tracked per model whenever the scanner can infer the model from querysets, annotations, admin classes, serializers/forms, templates, or runtime evidence. This avoids treating `Customer.status` as evidence that `Order.status` is also used.

## Installation

Add the app to `INSTALLED_APPS`:

```python
INSTALLED_APPS = [
    # ...
    "django_unused_model_inspector",
]
```

Run the management command:

```bash
python manage.py detect_unused_model_members
```

Useful options:

```bash
python manage.py detect_unused_model_members --app billing
python manage.py detect_unused_model_members --format json
python manage.py detect_unused_model_members --format sarif
python manage.py detect_unused_model_members --runtime-evidence runtime-evidence.json
python manage.py detect_unused_model_members --fail-on-findings
```

## Configuration

```python
UNUSED_MODEL_INSPECTOR = {
    "IGNORE_APPS": ["admin", "sessions"],
    "IGNORE_MODELS": ["accounts.User"],
    "IGNORE_FIELDS": ["accounts.User.legacy_external_id"],
    "IGNORE_METHODS": ["billing.Invoice.calculate_total"],
    "IGNORE_PATHS": ["*/migrations/*", "*/tests/*"],
    "SOURCE_PATHS": [],
    "TEMPLATE_PATHS": [],
    "TEMPLATE_EXTENSIONS": [".html", ".txt"],
    "SCAN_TEMPLATES": True,
}
```

When `SOURCE_PATHS` is empty, the command scans `settings.BASE_DIR`.
When `TEMPLATE_PATHS` is empty, the command scans the same paths as `SOURCE_PATHS` for Django template references.

## Runtime evidence

Static analysis cannot see every dynamic Django or Python access pattern. For those cases, wrap representative code or a test run with the runtime recorder:

```python
from django_unused_model_inspector.runtime import record_model_member_access


def test_dynamic_customer_usage():
    with record_model_member_access("runtime-evidence.json", app_labels=["customers"]):
        run_dynamic_customer_flow()
```

Then merge the evidence into a scan:

```bash
python manage.py detect_unused_model_members --runtime-evidence runtime-evidence.json
```

The recorder monkey-patches model `__getattribute__` while the context manager is active, records access to collected model fields, methods, and properties, then restores the original classes on exit.
