django-recurrence
=================
.. image:: https://img.shields.io/github/stars/django-recurrence/django-recurrence.svg?label=Stars&style=socialcA
:target: https://github.com/jazzband/django-recurrence
:alt: GitHub
.. image:: https://img.shields.io/pypi/v/django-recurrence.svg
:target: https://pypi.org/project/django-recurrence/
:alt: PyPI release
.. image:: https://img.shields.io/pypi/pyversions/django-recurrence.svg
:target: https://pypi.org/project/django-recurrence/
:alt: Supported Python versions
.. image:: https://img.shields.io/pypi/djversions/django-recurrence.svg
:target: https://pypi.org/project/django-recurrence/
:alt: Supported Django versions
.. image:: https://img.shields.io/readthedocs/django-recurrence.svg
:target: https://django-recurrence.readthedocs.io/
:alt: Documentation
.. image:: https://github.com/django-recurrence/django-recurrence/workflows/Test/badge.svg
:target: https://github.com/django-recurrence/django-recurrence/actions
:alt: GitHub actions
.. image:: https://codecov.io/gh/django-recurrence/django-recurrence/branch/master/graph/badge.svg
:target: https://codecov.io/gh/django-recurrence/django-recurrence
:alt: Coverage
django-recurrence is a utility for working with recurring dates in Django.
Functionality
-------------
* Recurrence/Rule objects using a subset of rfc2445
(wraps ``dateutil.rrule``) for specifying recurring date/times,
* ``RecurrenceField`` for storing recurring datetimes in the database, and
* JavaScript widget.
``RecurrenceField`` provides a Django model field which serializes
recurrence information for storage in the database.
For example - say you were storing information about a university course
in your app. You could use a model like this:
.. code:: python
import recurrence.fields
class Course(models.Model):
title = models.CharField(max_length=200)
start = models.TimeField()
end = models.TimeField()
recurrences = recurrence.fields.RecurrenceField()
You’ll notice that I’m storing my own start and end time.
The recurrence field only deals with *recurrences*
not with specific time information.
I have an event that starts at 2pm.
Its recurrences would be “every Friday”.
Documentation
-------------
For more information on installation and configuration see the documentation at:
https://django-recurrence.readthedocs.io/
Issues
------
If you have questions or have trouble using the app please file a bug report at:
https://github.com/django-recurrence/django-recurrence/issues
Contributions
-------------
All contributions are welcome!
It is best to separate proposed changes and PRs into small, distinct patches
by type so that they can be merged faster into upstream and released quicker.
One way to organize contributions would be to separate PRs for e.g.
* bugfixes,
* new features,
* code and design improvements,
* documentation improvements, or
* tooling and CI improvements.
Merging contributions requires passing the checks configured
with the CI. This includes running tests and linters successfully
on the currently officially supported Python and Django versions.
The test automation is run automatically with GitHub Actions, but you can
run it locally with the ``tox`` command before pushing commits.
Changes
=======
1.11.1 (2021-01-25)
-------------------
- Fix reStructuredTest syntax to be PyPI compliant.
1.11.0 (2021-01-21)
-------------------
- Add Django 4.0 and Python 3.10 support.
Deprecate EOL Django and Python versions.
[aleksihakli]
- Fix weekday deserialization typing bug.
[apirobot]
- Fix default ``recurrence.language_code`` not being set
by using ``en-us`` for locale in frontend as the default.
[jleclanche]
1.10.3
------
* Add Hungarian localisation #161.
1.10.2
------
* Add Hebrew localisation #159.
1.10.1
------
* Update path to jQuery to match the one Django admin provides #148.
1.10.0
------
* Fixes and official support for Django 2.1 and 2.2 #143, #142;
* Remove support for Python 2.7 and 3.5, remove support for Django 2.0 #145.
1.9.0
-----
* Fix for using the recurrence widget in admin inlines #137.
1.8.2
-----
* Minor fix for Django 2.0 #134;
* Minor packaging fix #135.
1.8.1
-----
* Bad release, do not use.
1.8.0
-----
This release contains two backwards incompatible changes -
please read the notes below for details.
* django-recurrence now returns timezone aware ``datetime`` objects
in most cases #130. If ``USE_TZ`` is ``True`` (it
defaults to off with a stock Django install) then you'll now get
timezone aware ``datetime`` objects back from django-recurrence. If
you have ``USE_TZ`` as ``True``, and you don't want this behaviour,
you can set ``RECURRENCE_USE_TZ`` to ``False``, but please let us
know (via GitHub issues) that you wanted to opt out, so we can
understand what your use case is.
* ``RecurrenceField`` instances without ``required=False`` will now
require at least one rule or date. This change is intended to bring
django-recurrence into line with how custom fields should
behave. If you don't want to require at least one rule or date,
just set ``require=False`` on your field #133.
* Improvements to avoid inline styles #85;
* Handle changes to ``javascript_catalog`` in Django 2 #131.
1.7.0
-----
* Drop official support for Django versions 1.7, 1.8, 1.9, 1.10;
* Fixes for saving ``None`` into a ``RecurrenceField`` causing a
``TypeError`` #89`, #122;
* Drop official support for Python 3.3 and Python 3.4;
* Provisional support for Python 3.7 (only for Django 2.0 and up);
* Ensure use of ``render`` on Django widgets always passes the
``renderer`` argument, to ensure support for Django 2.1 #125;
* Django 2.0 compatibility fix for usage of django-recurrence with
Django REST framework #126.
1.6.0
-----
* Fixes for Python 3 #105;
* Support for Django 2.0 #109, #110;
* Switch back a couple of instances of ``DeserializationError`` to
``ValidationError`` #111;
* Switch around how we set dates in the date selector widget to avoid
issues with short months #113.
1.5.0
-----
* Add Slovakian translations #98;
* Add support for events occurring at a fixed point before the
end of the month - e.g. the second last Tuesday before the end of the month #88;
* Add minor style changes to make django-recurrence compatible with Wagtail #100;
* Allow changing the behaviour of generating recurrences on
``dtstart`` by default. You can opt in to this by setting
``include_dtstart=False`` on your ``RecurrenceField`` #93;
* Ensure broken values raise ``DeserializationError`` where expected #103.
1.4.1
-----
* Make PO-Revision-Date parseable by babel #75;
* Update installation notes to cover Django 1.10 #74;
* Add German translation #77;
* Add Brazilian translation #79;
* Ensure the migrations are included when installing #78;
* Fix order of arguments to ``to_dateutil_rruleset`` #81.
1.4.0
-----
* Improve our testing setup to also cover Python 3.5;
* Fixes for Django 1.10 #69.
1.3.1
-----
* Add Basque translations #67.
1.3.0
-----
* Drop official support for Django 1.4, Django 1.5, Django 1.6 and
Python 2.6 (no changes have been made to deliberately break older
versions, but older versions will not be tested going forward);
* Add official support for Django 1.8 and Django 1.9 #62;
* Fix for a bug in ``Rule`` creation where the weekday parameter is
an instance of ``Weekday`` rather than an integer #57.
1.2.0
-----
* Added an option for events to occur on the fourth of a given
weekday of the month #29;
* Fixed an off-by-one bug in the ``to_text`` method for events
happening on a regular month each year #30;
* Fixed a bug in the JavaScript widget where the date for monthly
events on a fixed date of the month had the description rendered
incorrectly if the day selected was more than the number of days in
the current calendar month #31;
* Added a French translation #32 - this may be backwards
incompatible if have overriden the widget JavaScript such that
there is no ``language_code`` member of your recurrence object;
* Added a Spanish translation #49;
* Added database migrations - running ``python manage.py migrate
recurrence --fake`` should be sufficient for this version - nothing
has changed about the database schema between 1.1.0 and 1.2.0;
* Fix broken tests for Django 1.4.
1.1.0
-----
* Added experimental Python 3 support.
* Added extensive test coverage (from 0% to 81%).
* Added documentation (including this changelog).
* Removed ``RecurrenceModelField`` and ``RecurrenceModelDescriptor``,
which don't appear to have worked as expected for some time.
* Fixed a bug introduced in 1.0.3 which prevented the
django-recurrence JavaScript from working #27.
* Don't raise ``ValueError`` if you save ``None`` into a
``RecurrenceField`` with ``null=False`` #22, for
consistency with other field types.
* Make sure an empty recurrence object is falsey #25.
* Fix a copy-paste error in ``to_recurrence_object`` which prevented
exclusion rules from being populated correctly.
* Fix a typo in ``create_from_recurrence_object`` which prevented it
working with inclusion or exclusion rules.
* Various other very minor bugfixes.