Metadata-Version: 2.4
Name: django-tag-me
Version: 2026.6.2.1
Summary: A simple approach to Django tagging
Author-email: Mark Sevelj <mark.sevelj@dunwright.com.au>
Maintainer-email: Mark Sevelj <mark.sevelj@dunwright.com.au>
License: BSD-3-Clause
Project-URL: Repository, https://codeberg.org/Dunwright/django-tag-me
Project-URL: Documentation, https://django-tag-me.readthedocs.io
Project-URL: Tracker, https://codeberg.org/Dunwright/django-tag-me/issues
Project-URL: Changelog, https://codeberg.org/Dunwright/django-tag-me/src/branch/main/CHANGELOG.md
Keywords: Django Tag Me,Django,django,django tagging,Django tags,Django field tags
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Framework :: Django :: 4.2
Classifier: Framework :: Django :: 5.0
Classifier: Framework :: Django :: 5.1
Classifier: Framework :: Django :: 5.2
Classifier: Framework :: Django :: 6.0
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
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
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Django>=4.2
Requires-Dist: structlog
Provides-Extra: dev
Requires-Dist: django-extensions; extra == "dev"
Requires-Dist: hypothesis; extra == "dev"
Requires-Dist: pyright; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-django; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: tox; extra == "dev"
Dynamic: license-file

# Django Tag Me

[![Project Status: Active](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)
[![PyPI - Version](https://img.shields.io/pypi/v/django-tag-me)](https://pypi.org/project/django-tag-me/)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/django-tag-me)](https://www.python.org/)
[![PyPI - Versions from Framework Classifiers](https://img.shields.io/pypi/frameworkversions/django/django-tag-me)](https://docs.djangoproject.com/en/5.2/)
[![Documentation Status](https://readthedocs.org/projects/django-tag-me/badge/?version=latest)](https://django-tag-me.readthedocs.io/en/latest/?badge=latest)

[![Total downloads](https://static.pepy.tech/badge/django-tag-me)](https://pepy.tech/projects/django-tag-me)
[![Monthly downloads](https://static.pepy.tech/badge/django-tag-me/month)](https://pepy.tech/projects/django-tag-me)
[![Weekly downloads](https://static.pepy.tech/badge/django-tag-me/week)](https://pepy.tech/projects/django-tag-me)

*Simple, flexible tagging for Django.*

Add tags to any Django model field -- with a polished widget, per-user tag customization, and automatic resilience to model renames.

## Features

- **Easy setup** -- Add `TagMeCharField` to your model and go
- **Beautiful widget** -- Searchable dropdown with tag pills, powered by Alpine.js
- **User tags** -- Each user gets their own customizable tag set per field
- **System tags** -- Define default tags available to all users
- **Tag synchronization** -- Keep tags in sync across related models
- **Model rename resilient** -- FK-based lookups with automatic orphan detection and repair
- **CLI diagnostics** -- Health checks, orphan repair, and built-in troubleshooting via `tag_me` command
- **Structured logging** -- Observability via structlog for production monitoring
- **Form integration** -- Drop-in mixin for your model forms
- **Template tags** -- Display tags as styled pills

## Quick Example

```python
# models.py
from tag_me.models import TagMeCharField

class Article(models.Model):
    tags = TagMeCharField(blank=True)
    category = TagMeCharField(choices=CategoryChoices.choices, system_tag=True)
```

```python
# forms.py
from tag_me.forms import TagMeModelFormMixin

class ArticleForm(TagMeModelFormMixin, forms.ModelForm):
    class Meta:
        model = Article
        fields = ["tags", "category"]
```

See the [Quickstart](https://django-tag-me.readthedocs.io/en/latest/how-to/quickstart.html) for the full setup including templates and frontend requirements.

## Widget Preview

**Dropdown with tag options**

![Tag dropdown with options](https://codeberg.org/Dunwright/django-tag-me/raw/branch/main/docs/source/imgs/tag_dropdown_with_options.png)

**Search and filter tags**

![Tag dropdown search functionality](https://codeberg.org/Dunwright/django-tag-me/raw/branch/main/docs/source/imgs/tag_dropdown_search.png)

## Model Rename Resilience

Rename your Django models without breaking tags. Tag-me uses ContentType foreign keys instead of model name strings, and automatically detects and merges orphaned records during migration.

```bash
# Rename your model, then:
python manage.py makemigrations   # answer "yes" to rename prompt
python manage.py migrate          # tag-me handles the rest

# Verify everything is clean:
python manage.py tag_me check
```

See [How to Upgrade to FK Lookup](https://django-tag-me.readthedocs.io/en/latest/how-to/how-to-FK-based-lookup-system.html) for details on the FK-based system.

## Management Command

Tag-me includes a CLI for diagnostics and administration:

```bash
python manage.py tag_me populate              # create/update tags
python manage.py tag_me check                 # data integrity audit
python manage.py tag_me fix-orphans --dry-run # preview orphan repair
python manage.py tag_me help                  # built-in documentation
```

Tag population runs automatically after every `migrate`. The CLI exists for diagnostics, manual repair, and single-user operations.

See [How to Use the Tag-me CLI](https://django-tag-me.readthedocs.io/en/latest/how-to/how-to-tag-me-management-command.html) for the full guide.

## Installation

```bash
pip install django-tag-me
```

See the [documentation](https://django-tag-me.readthedocs.io/) for setup and usage instructions.

## Links

- [Documentation](https://django-tag-me.readthedocs.io/)
- [Source Code](https://codeberg.org/Dunwright/django-tag-me)
- [Issue Tracker](https://codeberg.org/Dunwright/django-tag-me/issues)

## Credits

- Dropdown interface adapted from [alpinejs-multiselect](https://github.com/alexpechkarev/alpinejs-multiselect/)
- Built with [Django Cookiecutter](https://github.com/imAsparky/django-cookiecutter)
