Getting started with django-generic-links¶

Simple and generic application for Django projects to attach and handle links for any object. Compatible with Django 4.2 to 5.2 and Python 3.10 to 3.14.

Features¶

Model for creating generic link relations
Reverse Generic Relation (Django) for your models
Model Admin
Generic inline admin to manage any model's generic links
A template tag to get all links for a given model instance
A fully working example project

Installation¶

Via pip command:

pip install django-generic-links

...or you can clone the repo and install it using pip too:

git clone git://github.com/matagus/django-generic-links.git
cd django-generic-links
pip install -e .

Quick Start¶

Add generic_links to your INSTALLED_APPS in settings.py:

INSTALLED_APPS = (
    # ...
    "generic_links",
    # ...
)

Then run the migrations:

python manage.py migrate

Finally, add the reverse generic relation to each of the models you're going to add generic links to:

from django.db import models
from django.contrib.contenttypes.fields import GenericRelation


class Artist(models.Model):
    name = models.CharField(max_length=100)
    bio = models.TextField()

    # This is important so that we can get the GenericLink related instances for an object of this model
    generic_links = GenericRelation("generic_links.GenericLink")


class Album(models.Model):
    title = models.CharField(max_length=100)
    artist = models.ForeignKey(Artist, on_delete=models.CASCADE)
    release_date = models.DateField(null=True, blank=True)

    generic_links = GenericRelation("generic_links.GenericLink")

Usage¶

Using django-generic-links models¶

>>> from generic_links.models import GenericLink
>>> from music.models import Artist
>>>
>>> # Get an artist from the database...
>>> lou_reed = Artist.objects.get(pk=1)
>>> lou_reed
<Artist: Lou Reed>
>>>
>>> # Create the first link
>>> link1 = GenericLink(title="Wikipedia Page", url="http://en.wikipedia.org/wiki/Lou_Reed", content_object=lou_reed)
>>> link1.save()
>>>
>>> # and then a second one
>>> link2 = GenericLink(title="Encyclopaedia Britannica", url="https://www.britannica.com/biography/Lou-Reed",
content_object=lou_reed)
>>> link2.save()
>>>
>>> # Now get all the links for the artist object:
>>> lou_reed.generic_links.all()
<QuerySet [<GenericLink: Encyclopaedia Britannica :: https://www.britannica.com/biography/Lou-Reed>,
<GenericLink: Wikipedia Page :: https://en.wikipedia.org/wiki/Lou_Reed>]>

Generic Links Inline Admin¶

Since a GenericLink instance will be associated to another object you usually wish to show an inline model admin form in that model form.

from django.contrib import admin

from generic_links.admin import GenericLinkStackedInline

from music_app.models import Artist


@admin.register(Artist)
class ArtistAdmin(admin.ModelAdmin):
    # ...
    inlines = [GenericLinkStackedInline]

Using django-generic-links templatetags¶

Now imagine you have an artist page. You're passing artist object using template context and you want to get all the links for it:

{% load generic_links_tags %}

<h1>{{ artist.name }}</h1>
<p>{{ artist.description }}</p>
<h2>Links for {{ artist.name }}</h2>
{% get_links_for artist as artist_links %}
<ul>
{% for link in artist_links %}
  <li><a href="{{ link.url }}" title="{{ link.title }}">{{ link.title }}</a></li>
{% endfor %}
</ul>

Running Tests¶

Prerequisites: Install Hatch if not already installed: pip install hatch

List available test environments:

hatch env show test

Run all tests (all Python + Django combinations):

hatch run test:test

Run tests for specific Python/Django version:

hatch run test.py3.14-5.2:test  # Python 3.14 + Django 5.2
hatch run test.py3.13-5.1:test  # Python 3.13 + Django 5.1

Run specific test file:

hatch run test.py3.13-5.2:test tests.test_models

Coverage:

hatch run test:cov  # Run tests with coverage report

Troubleshooting: If you encounter environment issues, clean and rebuild: hatch env prune