From c4a252d1fb38c8fa7c645bc9292712e2fdf4d7c1 Mon Sep 17 00:00:00 2001 From: Remy Suen Date: Wed, 20 Mar 2019 05:07:00 -0400 Subject: [PATCH] Explain usage of timeframed model manager in the documentation (#365) * Provide a sample for using the timeframed manager Signed-off-by: Remy Suen * Update CHANGES.rst file Signed-off-by: Remy Suen * Update AUTHORS.rst file Signed-off-by: Remy Suen --- AUTHORS.rst | 1 + CHANGES.rst | 1 + docs/models.rst | 37 ++++++++++++++++++++++++++++++++++--- 3 files changed, 36 insertions(+), 3 deletions(-) diff --git a/AUTHORS.rst b/AUTHORS.rst index 06a3e01..80d8f44 100644 --- a/AUTHORS.rst +++ b/AUTHORS.rst @@ -33,6 +33,7 @@ | Patryk Zawadzki | Paul McLanahan | Philipp Steinhardt +| Remy Suen | Rinat Shigapov | Rodney Folz | Romain Garrigues diff --git a/CHANGES.rst b/CHANGES.rst index 41ef7de..12d525f 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -3,6 +3,7 @@ CHANGES master (unreleased) ------------------- +- Update documentation to explain usage of `timeframed` model manager, fixes GH-118 - Honor `OneToOneField.parent_link=False`. - Fix handling of deferred attributes on Django 1.10+, fixes GH-278 - Fix `FieldTracker.has_changed()` and `FieldTracker.previous()` to return diff --git a/docs/models.rst b/docs/models.rst index 51bde8f..5ddbd08 100644 --- a/docs/models.rst +++ b/docs/models.rst @@ -5,10 +5,41 @@ TimeFramedModel --------------- An abstract base class for any model that expresses a time-range. Adds -``start`` and ``end`` nullable DateTimeFields, and a ``timeframed`` -manager that returns only objects for whom the current date-time lies -within their time range. +``start`` and ``end`` nullable DateTimeFields, and provides a new +``timeframed`` manager on the subclass whose queryset pre-filters results +to only include those which have a ``start`` which is not in the future, +and an ``end`` which is not in the past. If either ``start`` or ``end`` is +``null``, the manager will include it. +.. code-block:: python + + from model_utils.models import TimeFramedModel + from datetime import datetime, timedelta + class Post(TimeFramedModel): + pass + + p = Post() + p.start = datetime.utcnow() - timedelta(days=1) + p.end = datetime.utcnow() + timedelta(days=7) + p.save() + + # this query will return the above Post instance: + Post.timeframed.all() + + p.start = None + p.end = None + p.save() + + # this query will also return the above Post instance, because + # the `start` and/or `end` are NULL. + Post.timeframed.all() + + p.start = datetime.utcnow() + timedelta(days=7) + p.save() + + # this query will NOT return our Post instance, because + # the start date is in the future. + Post.timeframed.all() TimeStampedModel ----------------