django-qsstats-magic 1.1.1__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,330 @@
1
+ Metadata-Version: 2.4
2
+ Name: django-qsstats-magic
3
+ Version: 1.1.1
4
+ Summary: A django microframework that eases the generation of aggregate data for querysets.
5
+ Author-email: Matt Croydon <mcroydon@gmail.com>, Mikhail Korobov <kmike84@gmail.com>
6
+ Maintainer-email: Basil Shubin <basil.shubin@gmail.com>
7
+ License-Expression: BSD-3-Clause
8
+ Project-URL: download, https://github.com/bashu/django-qsstats-magic/zipball/master
9
+ Project-URL: homepage, https://github.com/bashu/django-qsstats-magic/
10
+ Classifier: Development Status :: 4 - Beta
11
+ Classifier: Environment :: Web Environment
12
+ Classifier: Framework :: Django
13
+ Classifier: Framework :: Django :: 5.2
14
+ Classifier: Framework :: Django :: 6.0
15
+ Classifier: Framework :: Django :: 6.1
16
+ Classifier: Intended Audience :: Developers
17
+ Classifier: Operating System :: OS Independent
18
+ Classifier: Programming Language :: Python
19
+ Classifier: Programming Language :: Python :: 3 :: Only
20
+ Classifier: Programming Language :: Python :: 3.10
21
+ Classifier: Programming Language :: Python :: 3.11
22
+ Classifier: Programming Language :: Python :: 3.12
23
+ Classifier: Programming Language :: Python :: 3.13
24
+ Classifier: Programming Language :: Python :: 3.14
25
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
26
+ Requires-Python: >=3.10
27
+ Description-Content-Type: text/x-rst
28
+ License-File: LICENSE
29
+ License-File: AUTHORS
30
+ Requires-Dist: django>=5.2
31
+ Requires-Dist: python-dateutil
32
+ Requires-Dist: six
33
+ Dynamic: license-file
34
+
35
+ django-qsstats-magic
36
+ ====================
37
+
38
+ .. image:: https://badge.fury.io/py/django-qsstats-magic.svg
39
+ :target: https://badge.fury.io/py/django-qsstats-magic
40
+
41
+ .. image:: https://img.shields.io/pypi/pyversions/django-qsstats-magic.svg
42
+ :target: https://pypi.python.org/pypi/django-qsstats-magic/
43
+
44
+ .. image:: https://img.shields.io/pypi/djversions/django-qsstats-magic.svg
45
+ :target: https://pypi.python.org/pypi/django-qsstats-magic/
46
+
47
+ .. image:: https://github.com/bashu/django-qsstats-magic/actions/workflows/test.yml/badge.svg
48
+ :target: https://github.com/bashu/django-qsstats-magic/actions/workflows/test.yml
49
+
50
+ The goal of django-qsstats is to be a microframework to make
51
+ repetitive tasks such as generating aggregate statistics of querysets
52
+ over time easier. It's probably overkill for the task at hand, but yay
53
+ microframeworks!
54
+
55
+ django-qsstats-magic is a refactoring of django-qsstats app with slightly
56
+ changed API, simplified internals and faster time_series implementation.
57
+
58
+ Maintained by `Basil Shubin <https://github.com/bashu/>`_, and some great
59
+ `contributors <https://github.com/bashu/django-qsstats-magic/contributors>`_.
60
+
61
+ Installation
62
+ ------------
63
+
64
+ First install the module, preferably in a virtual environment. It can be installed from PyPI:
65
+
66
+ .. code-block:: shell
67
+
68
+ pip install django-qsstats-magic
69
+
70
+
71
+ Usage
72
+ -----
73
+
74
+ How many users signed up today? this month? this year?
75
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
76
+
77
+ .. code-block:: python
78
+
79
+ from django.contrib.auth.models import User
80
+ import qsstats
81
+
82
+ qs = User.objects.all()
83
+ qss = qsstats.QuerySetStats(qs, 'date_joined')
84
+
85
+ print '%s new accounts today.' % qss.this_day()
86
+ print '%s new accounts this week.' % qss.this_week()
87
+ print '%s new accounts this month.' % qss.this_month()
88
+ print '%s new accounts this year.' % qss.this_year()
89
+ print '%s new accounts until now.' % qss.until_now()
90
+
91
+ This might print something like::
92
+
93
+ 5 new accounts today.
94
+ 11 new accounts this week.
95
+ 27 new accounts this month.
96
+ 377 new accounts this year.
97
+ 409 new accounts until now.
98
+
99
+ Aggregating time-series data suitable for graphing
100
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
101
+
102
+ .. code-block:: python
103
+
104
+ from django.contrib.auth.models import User
105
+ import datetime, qsstats
106
+
107
+ qs = User.objects.all()
108
+ qss = qsstats.QuerySetStats(qs, 'date_joined')
109
+
110
+ today = datetime.date.today()
111
+ seven_days_ago = today - datetime.timedelta(days=7)
112
+
113
+ time_series = qss.time_series(seven_days_ago, today)
114
+ print 'New users in the last 7 days: %s' % [t[1] for t in time_series]
115
+
116
+ This might print something like::
117
+
118
+ New users in the last 7 days: [3, 10, 7, 4, 12, 9, 11]
119
+
120
+
121
+ Please see qsstats/tests/test_*.py for similar usage examples.
122
+
123
+ API
124
+ ---
125
+
126
+ The ``QuerySetStats`` object
127
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
128
+
129
+ In order to provide maximum flexibility, the ``QuerySetStats`` object
130
+ can be instantiated with as little or as much information as you like.
131
+ All keyword arguments are optional but ``DateFieldMissingError`` and
132
+ ``QuerySetMissingError`` will be raised if you try to use ``QuerySetStats``
133
+ without providing enough information.
134
+
135
+ ``qs``
136
+ The queryset to operate on.
137
+
138
+ Default: ``None``
139
+
140
+ ``date_field``
141
+ The date field within the queryset to use.
142
+
143
+ Default: ``None``
144
+
145
+ ``aggregate``
146
+ The django aggregation instance. Can be also set when
147
+ instantiating or calling one of the methods.
148
+
149
+ Default: ``Count('id')``
150
+
151
+ ``operator``
152
+ The default operator to use for the ``pivot`` function. Can be also set
153
+ when calling ``pivot``.
154
+
155
+ Default: ``'lte'``
156
+
157
+ ``today``
158
+ The date that will be considered as today date. If ``today`` param is None
159
+ QuerySetStats' today will be datetime.date.today().
160
+
161
+ Default: ``None``
162
+
163
+
164
+ All of the documented methods take a standard set of keyword arguments
165
+ that override any information already stored within the ``QuerySetStats``
166
+ object. These keyword arguments are ``date_field`` and ``aggregate``.
167
+
168
+ Once you have a ``QuerySetStats`` object instantiated, you can receive a
169
+ single aggregate result by using the following methods:
170
+
171
+ * ``for_minute``
172
+ * ``for_hour``
173
+ * ``for_day``
174
+ * ``for_week``
175
+ * ``for_month``
176
+ * ``for_year``
177
+
178
+ Positional arguments: ``dt``, a ``datetime.datetime`` or ``datetime.date``
179
+ object to filter the queryset to this interval (minute, hour, day, week,
180
+ month or year).
181
+
182
+ * ``this_minute``
183
+ * ``this_hour``
184
+ * ``this_day``
185
+ * ``this_week``
186
+ * ``this_month``
187
+ * ``this_year``
188
+
189
+ Wrappers around ``for_<interval>`` that uses ``dateutil.relativedelta`` to
190
+ provide aggregate information for this current interval.
191
+
192
+ ``QuerySetStats`` also provides a method for returning aggregated
193
+ time-series data which may be extremely useful in plotting data:
194
+
195
+ ``time_series``
196
+ Positional arguments: ``start`` and ``end``, each a
197
+ ``datetime.date`` or ``datetime.datetime`` object used in marking
198
+ the start and stop of the time series data.
199
+
200
+ Keyword arguments: In addition to the standard ``date_field`` and
201
+ ``aggregate`` keyword argument, ``time_series`` takes an optional
202
+ ``interval`` keyword argument used to mark which interval to use while
203
+ calculating aggregate data between ``start`` and ``end``. This argument
204
+ defaults to ``'days'`` and can accept ``'years'``, ``'months'``,
205
+ ``'weeks'``, ``'days'``, ``'hours'`` or ``'minutes'``.
206
+ It will raise ``InvalidIntervalError`` otherwise.
207
+
208
+ This methods returns a list of tuples. The first item in each
209
+ tuple is a ``datetime.datetime`` object for the current interval. The
210
+ second item is the result of the aggregate operation. For
211
+ example::
212
+
213
+ [(datetime.datetime(2010, 3, 28, 0, 0), 12), (datetime.datetime(2010, 3, 29, 0, 0), 0), ...]
214
+
215
+ Formatting of date information is left as an exercise to the user and may
216
+ vary depending on interval used.
217
+
218
+ ``until``
219
+ Provide aggregate information until a given date or time, filtering the
220
+ queryset using ``lte``.
221
+
222
+ Positional arguments: ``dt`` a ``datetime.date`` or ``datetime.datetime``
223
+ object to be used for filtering the queryset since.
224
+
225
+ Keyword arguments: ``date_field``, ``aggregate``.
226
+
227
+ ``until_now``
228
+ Aggregate information until now.
229
+
230
+ Positional arguments: ``dt`` a ``datetime.date`` or ``datetime.datetime``
231
+ object to be used for filtering the queryset since (using ``lte``).
232
+
233
+ Keyword arguments: ``date_field``, ``aggregate``.
234
+
235
+ ``after``
236
+ Aggregate information after a given date or time, filtering the queryset
237
+ using ``gte``.
238
+
239
+ Positional arguments: ``dt`` a ``datetime.date`` or ``datetime.datetime``
240
+ object to be used for filtering the queryset since.
241
+
242
+ Keyword arguments: ``date_field``, ``aggregate``.
243
+
244
+ ``after_now``
245
+ Aggregate information after now.
246
+
247
+ Positional arguments: ``dt`` a ``datetime.date`` or ``datetime.datetime``
248
+ object to be used for filtering the queryset since (using ``gte``).
249
+
250
+ Keyword arguments: ``date_field``, ``aggregate``.
251
+
252
+ ``pivot``
253
+ Used by ``until``, ``after``, and ``until_now`` but potentially useful if
254
+ you would like to specify your own operator instead of the defaults.
255
+
256
+ Positional arguments: ``dt`` a ``datetime.date`` or ``datetime.datetime``
257
+ object to be used for filtering the queryset since (using ``lte``).
258
+
259
+ Keyword arguments: ``operator``, ``date_field``, ``aggregate``.
260
+
261
+ Raises ``InvalidOperatorError`` if the operator provided is not one of ``'lt'``,
262
+ ``'lte'``, ``gt`` or ``gte``.
263
+
264
+ Testing
265
+ -------
266
+
267
+ If you'd like to test ``django-qsstats-magic`` against your local configuration, add
268
+ ``qsstats`` to your ``INSTALLED_APPS`` and run ``./manage.py test qsstats``.
269
+ The test suite assumes that ``django.contrib.auth`` is installed.
270
+
271
+ For testing against different python, DB and django versions install tox
272
+ (pip install tox) and run 'tox' from the source checkout::
273
+
274
+ $ tox
275
+
276
+ Db user 'qsstats_test' with password 'qsstats_test' and a DB 'qsstats_test'
277
+ should exist.
278
+
279
+ Difference from django-qsstats
280
+ ------------------------------
281
+
282
+ 1. Faster time_series method using 1 sql query (currently works for MySQL and
283
+ PostgreSQL, with a fallback to the old method for other DB backends).
284
+ 2. Single ``aggregate`` parameter instead of ``aggregate_field`` and
285
+ ``aggregate_class``. Default value is always ``Count('id')`` and can't be
286
+ specified in settings.py. ``QUERYSETSTATS_DEFAULT_OPERATOR`` option is also
287
+ unsupported now.
288
+ 3. Support for minute and hour aggregates.
289
+ 4. ``start_date`` and ``end_date`` arguments are renamed to ``start`` and
290
+ ``end`` because of 3.
291
+ 5. Internals are changed.
292
+
293
+ I don't know if original author (Matt Croydon) would like my changes so
294
+ I renamed a project for now. If the changes will be merged then
295
+ django-qsstats-magic will become obsolete.
296
+
297
+ Contributing
298
+ ------------
299
+
300
+ If you've found a bug, implemented a feature or customized the template and
301
+ think it is useful then please consider contributing. Patches, pull requests or
302
+ just suggestions are welcome!
303
+
304
+ Credits
305
+ -------
306
+
307
+ `django-qsstats-magic <https://github.com/bashu/django-qsstats-magic/>`_ was originally started by `Mikhail Korobov <http://kmike.ru/>`_ who has now unfortunately abandoned the project.
308
+
309
+ License
310
+ -------
311
+
312
+ ``django-qsstats-magic`` is released under the BSD license.
313
+
314
+ Changes
315
+ -------
316
+
317
+ 1.1.1 (2026-08-31)
318
+ ~~~~~~~~~~~~~~~~~~
319
+
320
+ * Renamed ``InvalidInterval``, ``InvalidOperator``, ``DateFieldMissing`` and
321
+ ``QuerySetMissing`` to ``InvalidIntervalError``, ``InvalidOperatorError``,
322
+ ``DateFieldMissingError`` and ``QuerySetMissingError``. The old names still
323
+ work but now raise a ``DeprecationWarning`` and will be removed in a future
324
+ release.
325
+ * Dropped the ``qsstats.compat`` module; ``django.utils.timezone.now()`` is
326
+ used directly.
327
+ * Now requires Python 3.10+ and Django 5.2+.
328
+ * Migrated packaging to ``pyproject.toml``, switched the test suite to
329
+ pytest, and added pre-commit hooks and GitHub Actions CI/release
330
+ workflows.
@@ -0,0 +1,15 @@
1
+ django_qsstats_magic-1.1.1.dist-info/licenses/AUTHORS,sha256=R1c9N44eFZxxRUmb8h85i8GiylinVMwPM0ACb83WxsI,145
2
+ django_qsstats_magic-1.1.1.dist-info/licenses/LICENSE,sha256=QEzK5JqXql__igpnXBmmTUcu-eDyJqWGXYM_n8EwDjY,1504
3
+ qsstats/__init__.py,sha256=IY8tdE17OsAZ2e-scyljeeg8hE2Z7U5zJ5B8UcJOL6E,7711
4
+ qsstats/exceptions.py,sha256=Fv7Zr8pa1w4jRs_ssovhOXgK2iXTOkk8s-sBjUmeGxk,1198
5
+ qsstats/models.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
6
+ qsstats/utils.py,sha256=BbC8vwx5E9ogTlVyiW2ERs9k5Xj4x3E6Zl5p5Furm_o,1940
7
+ qsstats/tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
8
+ qsstats/tests/conftest.py,sha256=J_Jkg-pI7juHVwzOyOgqh6L87GMdYejN_JQelRwAA-I,170
9
+ qsstats/tests/models.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
10
+ qsstats/tests/settings.py,sha256=t9ERbWMxFqcrbFl_DtYLPRM8LHlGjLN6OQS80fWjkL0,467
11
+ qsstats/tests/test_qs.py,sha256=O-m5w7O9VEyBa_roqAjxJzOloezQfWUP8q1SnCwu6WA,4561
12
+ django_qsstats_magic-1.1.1.dist-info/METADATA,sha256=t9UtjMhLNsWLHsGFtGylUB7v5sv16euwdgnAFcFMjdk,11381
13
+ django_qsstats_magic-1.1.1.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
14
+ django_qsstats_magic-1.1.1.dist-info/top_level.txt,sha256=ufbroPowoNYQ2_ibcKyuowJ7tidxLCq4XJVBWR9cWXQ,8
15
+ django_qsstats_magic-1.1.1.dist-info/RECORD,,
@@ -0,0 +1,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: setuptools (84.0.0)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+
@@ -0,0 +1,9 @@
1
+ Authors & Contributors
2
+ ======================
3
+
4
+ * Matt Croydon
5
+ * Mikhail Korobov
6
+ * Pawel Tomasiewicz
7
+ * Steve Jones
8
+ * Petr Dlouhý
9
+ * Ivan Virabyan
@@ -0,0 +1,24 @@
1
+ Copyright (c) 2010, Matt Croydon, Mikhail Korobov
2
+ All rights reserved.
3
+
4
+ Redistribution and use in source and binary forms, with or without
5
+ modification, are permitted provided that the following conditions are met:
6
+ * Redistributions of source code must retain the above copyright
7
+ notice, this list of conditions and the following disclaimer.
8
+ * Redistributions in binary form must reproduce the above copyright
9
+ notice, this list of conditions and the following disclaimer in the
10
+ documentation and/or other materials provided with the distribution.
11
+ * Neither the name of the tastypie nor the
12
+ names of its contributors may be used to endorse or promote products
13
+ derived from this software without specific prior written permission.
14
+
15
+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
16
+ ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
17
+ WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
18
+ DISCLAIMED. IN NO EVENT SHALL MATT CROYDON BE LIABLE FOR ANY
19
+ DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
20
+ (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
21
+ LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
22
+ ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
23
+ (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
24
+ SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
@@ -0,0 +1 @@
1
+ qsstats
qsstats/__init__.py ADDED
@@ -0,0 +1,227 @@
1
+ import warnings
2
+ from datetime import datetime
3
+ from functools import partial
4
+
5
+ from django.db import transaction
6
+ from django.db.models import Count
7
+ from django.db.models.functions import Trunc
8
+ from django.utils import timezone
9
+
10
+ from dateutil.parser import parse
11
+ from dateutil.relativedelta import relativedelta
12
+ from six import string_types
13
+
14
+ from qsstats import exceptions
15
+ from qsstats import utils
16
+ from qsstats.exceptions import DateFieldMissingError
17
+ from qsstats.exceptions import InvalidIntervalError
18
+ from qsstats.exceptions import InvalidOperatorError
19
+ from qsstats.exceptions import QuerySetMissingError
20
+
21
+ # Deprecated exception aliases (see qsstats.exceptions), resolved lazily so
22
+ # that accessing e.g. qsstats.DateFieldMissing warns, without warning for
23
+ # everyone who merely imports this package.
24
+ # TODO: remove in the next major release.
25
+ _DEPRECATED_EXCEPTION_ALIASES = frozenset(
26
+ {"InvalidInterval", "InvalidOperator", "DateFieldMissing", "QuerySetMissing"},
27
+ )
28
+
29
+
30
+ def __getattr__(name):
31
+ if name in _DEPRECATED_EXCEPTION_ALIASES:
32
+ return getattr(exceptions, name)
33
+ msg = f"module {__name__!r} has no attribute {name!r}"
34
+ raise AttributeError(msg)
35
+
36
+
37
+ class QuerySetStats:
38
+ """
39
+ Generates statistics about a queryset using Django aggregates. QuerySetStats
40
+ is able to handle snapshots of data (for example this day, week, month, or
41
+ year) or generate time series data suitable for graphing.
42
+ """
43
+
44
+ def __init__(self, qs=None, date_field=None, aggregate=None, today=None):
45
+ self.qs = qs
46
+ self.date_field = date_field
47
+ self.aggregate = aggregate or Count("id", distinct=True)
48
+ self.today = today or self.update_today()
49
+
50
+ # Aggregates for a specific period of time
51
+
52
+ def for_interval(self, interval, dt, date_field=None, aggregate=None):
53
+ start, end = utils.get_bounds(dt, interval)
54
+ date_field = date_field or self.date_field
55
+ kwargs = {f"{date_field}__range": (start, end)}
56
+ return self._aggregate(date_field, aggregate, kwargs)
57
+
58
+ def this_interval(self, interval, date_field=None, aggregate=None):
59
+ method = getattr(self, f"for_{interval}")
60
+ return method(self.today, date_field, aggregate)
61
+
62
+ # support for this_* and for_* methods
63
+ def __getattr__(self, name):
64
+ if name.startswith("for_"):
65
+ return partial(self.for_interval, name[4:])
66
+ if name.startswith("this_"):
67
+ return partial(self.this_interval, name[5:])
68
+ raise AttributeError
69
+
70
+ def time_series( # noqa: PLR0917, PLR0913
71
+ self,
72
+ start,
73
+ end=None,
74
+ interval="days",
75
+ date_field=None,
76
+ aggregate=None,
77
+ engine=None,
78
+ ):
79
+ """Aggregate over time intervals"""
80
+
81
+ end = end or self.today
82
+ args = [start, end, interval, date_field, aggregate]
83
+ sid = transaction.savepoint()
84
+ try:
85
+ return self._fast_time_series(*args)
86
+ except ValueError:
87
+ transaction.savepoint_rollback(sid)
88
+ warnings.warn(
89
+ "Your database doesn't support timezones. Switching to slower QSStats queries.", # noqa: E501
90
+ stacklevel=2,
91
+ )
92
+ return self._slow_time_series(*args)
93
+
94
+ def _slow_time_series(
95
+ self,
96
+ start,
97
+ end,
98
+ interval="days",
99
+ date_field=None,
100
+ aggregate=None,
101
+ ):
102
+ """Aggregate over time intervals using 1 sql query for one interval"""
103
+
104
+ num, interval = utils._parse_interval(interval) # noqa: SLF001
105
+
106
+ if (
107
+ interval not in ["minutes", "hours", "days", "weeks", "months", "years"]
108
+ or num != 1
109
+ ):
110
+ msg = "Interval is currently not supported."
111
+ raise InvalidIntervalError(msg)
112
+
113
+ method = getattr(self, f"for_{interval[:-1]}")
114
+
115
+ stat_list = []
116
+ dt, end = utils._to_datetime(start), utils._to_datetime(end) # noqa: SLF001
117
+ while dt <= end:
118
+ value = method(dt, date_field, aggregate)
119
+ stat_list.append((dt, value))
120
+ dt = dt + relativedelta(**{interval: 1})
121
+ return stat_list
122
+
123
+ def _fast_time_series(
124
+ self,
125
+ start,
126
+ end,
127
+ interval="days",
128
+ date_field=None,
129
+ aggregate=None,
130
+ ):
131
+ """Aggregate over time intervals using just 1 sql query"""
132
+
133
+ date_field = date_field or self.date_field
134
+ aggregate = aggregate or self.aggregate
135
+
136
+ num, interval = utils._parse_interval(interval) # noqa: SLF001
137
+
138
+ interval_s = interval.rstrip("s")
139
+ start, _ = utils.get_bounds(start, interval_s)
140
+ _, end = utils.get_bounds(end, interval_s)
141
+
142
+ kwargs = {f"{date_field}__range": (start, end)}
143
+
144
+ # TODO: maybe we could use the tzinfo for the user's location
145
+ aggregate_data = (
146
+ self.qs.filter(**kwargs)
147
+ .annotate(d=Trunc(date_field, interval_s, tzinfo=start.tzinfo))
148
+ .order_by()
149
+ .values("d")
150
+ .annotate(agg=aggregate)
151
+ )
152
+
153
+ today = utils._remove_time(timezone.now()) # noqa: SLF001
154
+
155
+ def to_dt(d):
156
+ if isinstance(d, string_types):
157
+ return parse(d, yearfirst=True, default=today)
158
+ if type(d).__name__ == "date":
159
+ return datetime(
160
+ year=d.year,
161
+ month=d.month,
162
+ day=d.day,
163
+ tzinfo=start.tzinfo,
164
+ )
165
+ return d
166
+
167
+ data = {to_dt(item["d"]): item["agg"] for item in aggregate_data}
168
+
169
+ stat_list = []
170
+ dt = start
171
+ while dt < end:
172
+ idx = 0
173
+ value = 0
174
+ for i in range(num):
175
+ value = value + data.get(dt, 0)
176
+ if i == 0:
177
+ stat_list.append((dt, value))
178
+ idx = len(stat_list) - 1
179
+ elif i == num - 1:
180
+ stat_list[idx] = (dt, value)
181
+ dt = dt + relativedelta(**{interval: 1})
182
+
183
+ return stat_list
184
+
185
+ # Aggregate totals using a date or datetime as a pivot
186
+
187
+ def until(self, dt, date_field=None, aggregate=None):
188
+ return self.pivot(dt, "lte", date_field, aggregate)
189
+
190
+ def until_now(self, date_field=None, aggregate=None):
191
+ return self.pivot(timezone.now(), "lte", date_field, aggregate)
192
+
193
+ def after(self, dt, date_field=None, aggregate=None):
194
+ return self.pivot(dt, "gte", date_field, aggregate)
195
+
196
+ def after_now(self, date_field=None, aggregate=None):
197
+ return self.pivot(timezone.now(), "gte", date_field, aggregate)
198
+
199
+ def pivot(self, dt, operator=None, date_field=None, aggregate=None):
200
+ operator = operator or self.operator
201
+ if operator not in ["lt", "lte", "gt", "gte"]:
202
+ msg = "Please provide a valid operator."
203
+ raise InvalidOperatorError(msg)
204
+
205
+ kwargs = {f"{date_field or self.date_field}__{operator}": dt}
206
+ return self._aggregate(date_field, aggregate, kwargs)
207
+
208
+ # Utility functions
209
+ def update_today(self):
210
+ _now = timezone.now()
211
+ self.today = utils._remove_time(_now) # noqa: SLF001
212
+ return self.today
213
+
214
+ def _aggregate(self, date_field=None, aggregate=None, filter_kwargs=None):
215
+ date_field = date_field or self.date_field
216
+ aggregate = aggregate or self.aggregate
217
+
218
+ if not date_field:
219
+ msg = "Please provide a date_field."
220
+ raise DateFieldMissingError(msg)
221
+
222
+ if self.qs is None:
223
+ msg = "Please provide a queryset."
224
+ raise QuerySetMissingError(msg)
225
+
226
+ agg = self.qs.filter(**filter_kwargs).aggregate(agg=aggregate)
227
+ return agg["agg"]
qsstats/exceptions.py ADDED
@@ -0,0 +1,53 @@
1
+ import warnings
2
+
3
+ __all__ = [
4
+ "DateFieldMissingError",
5
+ "InvalidIntervalError",
6
+ "InvalidOperatorError",
7
+ "QuerySetMissingError",
8
+ "QuerySetStatsError",
9
+ ]
10
+
11
+
12
+ class QuerySetStatsError(Exception):
13
+ pass
14
+
15
+
16
+ class InvalidIntervalError(QuerySetStatsError):
17
+ pass
18
+
19
+
20
+ class InvalidOperatorError(QuerySetStatsError):
21
+ pass
22
+
23
+
24
+ class DateFieldMissingError(QuerySetStatsError):
25
+ pass
26
+
27
+
28
+ class QuerySetMissingError(QuerySetStatsError):
29
+ pass
30
+
31
+
32
+ # Deprecated aliases, kept for backwards compatibility.
33
+ # TODO: remove in the next major release.
34
+ _DEPRECATED_ALIASES = {
35
+ "InvalidInterval": "InvalidIntervalError",
36
+ "InvalidOperator": "InvalidOperatorError",
37
+ "DateFieldMissing": "DateFieldMissingError",
38
+ "QuerySetMissing": "QuerySetMissingError",
39
+ }
40
+
41
+
42
+ def __getattr__(name):
43
+ new_name = _DEPRECATED_ALIASES.get(name)
44
+ if new_name is None:
45
+ msg = f"module {__name__!r} has no attribute {name!r}"
46
+ raise AttributeError(msg)
47
+ warnings.warn(
48
+ f"qsstats.exceptions.{name} is deprecated and will be removed in a "
49
+ f"future release, use {new_name} instead.",
50
+ DeprecationWarning,
51
+ stacklevel=2,
52
+ )
53
+ return globals()[new_name]
qsstats/models.py ADDED
File without changes
File without changes
@@ -0,0 +1,6 @@
1
+ """
2
+ Dummy conftest.py for qsstats.
3
+ If you don't know what this is for, just leave it empty.
4
+ Read more about conftest.py under:
5
+ https://pytest.org/latest/plugins.html
6
+ """
File without changes
@@ -0,0 +1,20 @@
1
+ import os
2
+
3
+ SECRET_KEY = "DUMMY_SECRET_KEY" # noqa: S105
4
+
5
+ # Application definition
6
+
7
+ PROJECT_APPS = ["qsstats.tests", "qsstats"]
8
+
9
+ INSTALLED_APPS = [
10
+ "django.contrib.auth",
11
+ "django.contrib.contenttypes",
12
+ *PROJECT_APPS,
13
+ ]
14
+
15
+ # Database
16
+ # https://docs.djangoproject.com/en/1.8/ref/settings/#databases
17
+
18
+ DATABASES = {"default": {"ENGINE": "django.db.backends.sqlite3", "NAME": ":memory:"}}
19
+
20
+ USE_TZ = os.environ.get("USE_TZ", "true").lower() not in ("0", "false")
@@ -0,0 +1,131 @@
1
+ import datetime
2
+
3
+ from django.contrib.auth.models import User
4
+ from django.test import TestCase
5
+ from django.utils import timezone
6
+
7
+ import pytest
8
+
9
+ import qsstats
10
+ from qsstats import DateFieldMissingError
11
+ from qsstats import InvalidIntervalError
12
+ from qsstats import InvalidOperatorError
13
+ from qsstats import QuerySetMissingError
14
+ from qsstats import QuerySetStats
15
+ from qsstats import utils
16
+
17
+
18
+ class QuerySetStatsTestCase(TestCase):
19
+ def setUp(self):
20
+ # We'll be making sure that this user is found
21
+ self.user = User.objects.create_user("u1", "u1@example.com")
22
+ # And that this user is not
23
+ self.another_user = User.objects.create_user("u2", "u2@example.com")
24
+ self.another_user.is_active = False
25
+ self.another_user.save()
26
+
27
+ def test_basic_today(self):
28
+ # Create a QuerySet and QuerySetStats
29
+ qss = QuerySetStats(User.objects.filter(is_active=True), "date_joined")
30
+
31
+ # We should only see a single user
32
+ assert qss.this_day() == 1
33
+
34
+ def assert_time_series_works(self, today):
35
+ seven_days_ago = today - datetime.timedelta(days=7)
36
+ for j in range(1, 8):
37
+ for i in range(j):
38
+ u = User.objects.create_user(
39
+ f"p-{j}-{i}",
40
+ f"p{j}-{i}@example.com",
41
+ )
42
+ u.date_joined = today - datetime.timedelta(days=i)
43
+ u.save()
44
+ qss = QuerySetStats(
45
+ User.objects.filter(username__startswith="p"),
46
+ "date_joined",
47
+ )
48
+ time_series = qss.time_series(seven_days_ago, today)
49
+ assert [t[1] for t in time_series] == [0, 1, 2, 3, 4, 5, 6, 7]
50
+
51
+ def test_time_series(self):
52
+ self.assert_time_series_works(utils._remove_time(timezone.now())) # noqa: SLF001
53
+
54
+ def test_time_series_naive(self):
55
+ self.assert_time_series_works(
56
+ datetime.datetime.now(tz=datetime.timezone.utc).date(),
57
+ )
58
+
59
+ def test_time_series_weeks(self):
60
+ day = datetime.date(year=2013, month=4, day=5)
61
+
62
+ self.user.date_joined = day
63
+ self.user.save()
64
+
65
+ qss = QuerySetStats(User.objects.filter(is_active=True), "date_joined")
66
+ qss.time_series(day - datetime.timedelta(days=30), day, interval="weeks")
67
+
68
+ def test_until(self):
69
+ now = timezone.now()
70
+ today = utils._remove_time(now) # noqa: SLF001
71
+ yesterday = today - datetime.timedelta(days=1)
72
+
73
+ self.user.date_joined = today
74
+ self.user.save()
75
+
76
+ qss = QuerySetStats(User.objects.filter(is_active=True), "date_joined")
77
+
78
+ assert qss.until(now) == 1
79
+ assert qss.until(today) == 1
80
+ assert qss.until(yesterday) == 0
81
+ assert qss.until_now() == 1
82
+
83
+ def test_after(self):
84
+ now = timezone.now()
85
+ today = utils._remove_time(now) # noqa: SLF001
86
+ tomorrow = today + datetime.timedelta(days=1)
87
+
88
+ self.user.date_joined = today
89
+ self.user.save()
90
+
91
+ qss = QuerySetStats(User.objects.filter(is_active=True), "date_joined")
92
+
93
+ assert qss.after(now) == 0
94
+ assert qss.after(today) == 1
95
+ assert qss.after(tomorrow) == 0
96
+ assert qss.after_now() == 0
97
+
98
+ # TODO: aggregate_field tests
99
+
100
+ def test_query_set_missing(self):
101
+ qss = QuerySetStats(date_field="foo")
102
+
103
+ for method in ["this_day", "this_month", "this_year"]:
104
+ with pytest.raises(QuerySetMissingError):
105
+ getattr(qss, method)()
106
+
107
+ def test_date_field_missing(self):
108
+ qss = QuerySetStats(User.objects.filter(is_active=True))
109
+
110
+ for method in ["this_day", "this_month", "this_year"]:
111
+ with pytest.raises(DateFieldMissingError):
112
+ getattr(qss, method)()
113
+
114
+ def test_invalid_interval(self):
115
+ qss = QuerySetStats(User.objects.filter(is_active=True), "date_joined")
116
+
117
+ with pytest.raises(InvalidIntervalError):
118
+ qss.time_series(qss.today, qss.today, interval="monkeys")
119
+
120
+ def test_deprecated_exception_aliases(self):
121
+ # The pre-1.2 exception names still resolve to the new Error-suffixed
122
+ # classes, but accessing them now warns.
123
+ aliases = {
124
+ "InvalidInterval": InvalidIntervalError,
125
+ "InvalidOperator": InvalidOperatorError,
126
+ "DateFieldMissing": DateFieldMissingError,
127
+ "QuerySetMissing": QuerySetMissingError,
128
+ }
129
+ for old_name, new_class in aliases.items():
130
+ with pytest.warns(DeprecationWarning, match=old_name):
131
+ assert getattr(qsstats, old_name) is new_class
qsstats/utils.py ADDED
@@ -0,0 +1,68 @@
1
+ import datetime
2
+ import re
3
+
4
+ from django.utils import timezone
5
+
6
+ from dateutil.relativedelta import MO
7
+ from dateutil.relativedelta import relativedelta
8
+
9
+ from qsstats.exceptions import InvalidIntervalError
10
+
11
+
12
+ def _remove_time(dt):
13
+ tzinfo = getattr(dt, "tzinfo", timezone.now().tzinfo)
14
+ return datetime.datetime(dt.year, dt.month, dt.day, tzinfo=tzinfo)
15
+
16
+
17
+ def _to_datetime(dt):
18
+ if isinstance(dt, datetime.datetime):
19
+ return dt
20
+ return _remove_time(dt)
21
+
22
+
23
+ def _parse_interval(interval):
24
+ num = 1
25
+ match = re.match(r"(\d+)([A-Za-z]+)", interval)
26
+
27
+ if match:
28
+ num = int(match.group(1))
29
+ interval = match.group(2)
30
+ return num, interval
31
+
32
+
33
+ def get_bounds(dt, interval):
34
+ """Returns interval bounds the datetime is in."""
35
+
36
+ day = _to_datetime(_remove_time(dt))
37
+ dt = _to_datetime(dt)
38
+
39
+ if interval == "minute":
40
+ begin = datetime.datetime(
41
+ dt.year,
42
+ dt.month,
43
+ dt.day,
44
+ dt.hour,
45
+ dt.minute,
46
+ tzinfo=dt.tzinfo,
47
+ )
48
+ end = begin + relativedelta(minutes=1)
49
+ elif interval == "hour":
50
+ begin = datetime.datetime(dt.year, dt.month, dt.day, dt.hour, tzinfo=dt.tzinfo)
51
+ end = begin + relativedelta(hours=1)
52
+ elif interval == "day":
53
+ begin = day
54
+ end = day + relativedelta(days=1)
55
+ elif interval == "week":
56
+ begin = day - relativedelta(weekday=MO(-1))
57
+ end = begin + datetime.timedelta(days=7)
58
+ elif interval == "month":
59
+ begin = datetime.datetime(dt.year, dt.month, 1, tzinfo=dt.tzinfo)
60
+ end = begin + relativedelta(months=1)
61
+ elif interval == "year":
62
+ begin = datetime.datetime(dt.year, 1, 1, tzinfo=dt.tzinfo)
63
+ end = datetime.datetime(dt.year + 1, 1, 1, tzinfo=dt.tzinfo)
64
+ else:
65
+ msg = "Interval not supported."
66
+ raise InvalidIntervalError(msg)
67
+ end = end - relativedelta(microseconds=1)
68
+ return begin, end