Django Anchor

Django Anchor is a reusable Django app that allows you to attach files to models.

Anchor works very similarly to Django's FileField and ImageField model fields, but adds a few extra features:

• Images can be resized, converted to another format and otherwise transformed.
• Files are served through signed URLs that can expire after a configurable amount of time, even when using the default file-system storage backend.

Django Anchor is essentially a port of the excellent Active Storage Ruby on Rails feature, but leveraging existing Django abstractions and packages of the Python ecosystem. Some features are not yet implemented, but the core concepts are there two eventually be able to support them.

Installation

Check out the installation guide in the documentation for more details.

Django-anchor is compatible with Django >= 4.2 and Python >= 3.12.

1. Add the django-anchor package to your dependencies. You can do this by running:

   pip install django-anchor
   

   or by adding django-anchor to your requirements.txt or pyproject.toml files if you have one.

2. Add anchor to settings.INSTALLED_APPS

3. Add URL configuration to your project:

   urlpatterns = [
       path('anchor/', include('anchor.urls')),
   ]
   

4. Run migrations:

   python manage.py migrate
   

In addition, if you wish to create image variants, a Pillow >= 9.5 should be available in your system.

Usage

💡 Check out the dummy Django project in the test folder for inspiration and the Getting Started guide in the documentation.

Adding files to models

The easiest way to add a file to a model is to add a BlobField to it:

from django.db import models
from anchor.models.fields import SingleAttachmentField


class Movie(models.Model):
    title = models.CharField(max_length=100)

    cover = SingleAttachmentField()

That's it! No need to run makemigrations or migrate since Django Anchor doesn't actually need any columns added to the model.

The cover field works just like any other model field:

# Create a new movie
movie = Movie.objects.create(title="My Movie")

# Attach an uploaded file
movie.cover = uploaded_file

# Get a URL to the file
movie.cover.url()

# Get a URL to a miniature version of the file
movie.cover.representation(resize_to_fit=(200, 200), format="webp").url()

# Delete the cover and remove the file from storage
movie.cover.purge()

Using files in templates

Django anchor comes with a handy template tag to render URLs of files you've stored:

{% load anchor %}
<img src="{% representation_url movie.cover resize_to_fit='300x600' format='jpeg' %}">

The above call to representation_url will generate an optimized version of the movie's cover in JPEG format which fits inside a 300x600 rectangle.

Contributing

PRs and issues are very welcome!

Check out CONTRIBUTING.md to learn how to set up the project locally.

License

This project is released under the MIT License. Check out LICENSE to get the full text of the license.