Usage

django-birthday provides a birthday.fields.BirthdayField model field type which is a subclass of django.db.models.DateField and thus has the same characteristics as that. It also internally adds a second field to your model holding the day of the year for that birthday, this is used for the extra functionality exposed by birthday.managers.BirthdayManager which you should use as the manager on your model.

A model could look like this:

from django.db import models
from django.conf import settings

from birthday import BirthdayField, BirthdayManager


class UserProfile(models.Model):
    user = models.ForeignKey(settings.AUTH_USER_MODEL)
    birthday = BirthdayField()

    objects = BirthdayManager()

Get all user profiles within the next 30 days:

UserProfile.objects.get_upcoming_birthdays()

Get all user profiles which have their birthday today:

UserProfile.objects.get_birthdays()

Or order the user profiles according to their birthday:

UserProfile.objects.order_by_birthday()

Automatic backfill on migrate

The cached day-of-year column is normally kept in sync by a pre_save signal receiver. Any row written before your model started using birthday.fields.BirthdayField – or written via bulk_create() or update(), both of which bypass pre_save – would otherwise end up with an empty cache, and birthday.managers.BirthdayManager would silently return incomplete results for those rows.

django-birthday registers a post_migrate handler that runs automatically every time you run manage.py migrate. For every model in every installed app that uses a birthday.fields.BirthdayField, it finds rows whose cached value has never been computed and backfills it, in efficient batches, without loading whole tables into memory and without re-triggering pre_save for every row.

This is fully automatic – nothing to configure, and nothing to run by hand. If you add BirthdayField to an existing model with existing data, running manage.py migrate afterwards (Django always emits the post_migrate signal, even when there’s nothing new to apply) will bring the cache up to date.

Method References

birthday.managers.BirthdayManager.get_upcoming_birthdays()

Returns a queryset containing objects that have an upcoming birthday.

Parameters:

  • days – Optional. Amount of days that still count as ‘upcoming’, defaults to 30.

  • after – Optional. Start day to use, defaults to ‘today’.

  • include_day – Optional. Include the ‘after’ day for lookups.

  • order – Optional. Whether the queryset should be ordered by birthday, defaults to True.

  • reverse – Optional. Only applies when order is True. Apply reverse ordering.

Return type:

Instance of django.db.models.query.QuerySet.

birthday.managers.BirthdayManager.get_birthdays()

Returns a queryset containing objects which have the birthday on a specific day.

Parameters:

day – Optional. What day to get the birthdays of. Defaults to ‘today’.

Return type:

Instance of django.db.models.query.QuerySet.

birthday.managers.BirthdayManager.order_by_birthday()

Returns a queryset ordered by birthday (not age!).

Parameters:

reverse – Optional. Defaults to False. Whether or not to reverse the results.

Return type:

Instance of django.db.models.query.QuerySet.