Revised the documentation of Period in the Mia core application.
This commit is contained in:
parent
1b89fef01c
commit
783ecea5cb
@ -18,9 +18,8 @@
|
||||
"""The period chooser utilities of the Mia core application.
|
||||
|
||||
"""
|
||||
|
||||
import datetime
|
||||
import re
|
||||
from datetime import date, timedelta
|
||||
|
||||
from django.core.serializers.json import DjangoJSONEncoder
|
||||
from django.template import defaultfilters
|
||||
@ -35,47 +34,8 @@ class Period:
|
||||
|
||||
Args:
|
||||
spec (str): The current period specification
|
||||
data_start (date): The available first day of the data.
|
||||
data_end (date): The available last day of the data.
|
||||
|
||||
Attributes:
|
||||
spec (date): The currently-working period specification.
|
||||
start (date): The start day of the currently-specified period.
|
||||
end (date): The end day of the currently-specified period.
|
||||
description (str): The description of the currently-specified
|
||||
period.
|
||||
this_month (str): The specification of this month.
|
||||
last_month (str): The specification of last month.
|
||||
since_last_month (str): The specification since last month.
|
||||
has_months_to_choose (bool): Whether there are months to
|
||||
choose besides this month and
|
||||
last month.
|
||||
chosen_month (bool): The specification of the chosen month,
|
||||
or None if the current period is not a
|
||||
month or is out of available data range.
|
||||
this_year (str): The specification of this year.
|
||||
last_year (str): The specification of last year.
|
||||
has_years_to_choose (bool): Whether there are years to
|
||||
choose besides this year and
|
||||
last year.
|
||||
years_to_choose (list[str]): This specification of the
|
||||
available years to choose,
|
||||
besides this year and last year.
|
||||
today (str): The specification of today.
|
||||
yesterday (str): The specification of yesterday.
|
||||
chosen_start (str): The specification of the first day of the
|
||||
specified period, as the default date for
|
||||
the single-day chooser.
|
||||
has_days_to_choose (bool): Whether there is a day range to
|
||||
choose.
|
||||
data_start (str): The specification of the available first day.
|
||||
data_end (str): The specification of the available last day.
|
||||
chosen_start (str): The specification of the first day of the
|
||||
specified period
|
||||
chosen_end (str): The specification of the last day of the
|
||||
specified period
|
||||
month_picker_params (str): The month-picker parameters, as a
|
||||
JSON text string
|
||||
data_start (datetime.date): The available first day of the data.
|
||||
data_end (datetime.date): The available last day of the data.
|
||||
"""
|
||||
def __init__(self, spec=None, data_start=None, data_end=None):
|
||||
self._period = self.Parser(spec)
|
||||
@ -84,22 +44,48 @@ class Period:
|
||||
|
||||
@property
|
||||
def spec(self):
|
||||
"""Returns the period specification.
|
||||
|
||||
Returns:
|
||||
str: The period specification.
|
||||
"""
|
||||
return self._period.spec
|
||||
|
||||
@property
|
||||
def start(self):
|
||||
"""Returns the start day of the currently-specified period.
|
||||
|
||||
Returns:
|
||||
datetime.date: The start day of the currently-specified period.
|
||||
"""
|
||||
return self._period.start
|
||||
|
||||
@property
|
||||
def end(self):
|
||||
"""Returns the end day of the currently-specified period.
|
||||
|
||||
Returns:
|
||||
datetime.date: The end day of the currently-specified period.
|
||||
"""
|
||||
return self._period.end
|
||||
|
||||
@property
|
||||
def description(self):
|
||||
"""Returns the text description of the currently-specified period.
|
||||
|
||||
Returns:
|
||||
str: The text description of the currently-specified period
|
||||
"""
|
||||
return self._period.description
|
||||
|
||||
@property
|
||||
def error(self):
|
||||
"""Returns the error of the period specification format.
|
||||
|
||||
Returns:
|
||||
str|None: The error of the period specification format, or None on
|
||||
success.
|
||||
"""
|
||||
return self._period.error
|
||||
|
||||
@staticmethod
|
||||
@ -107,7 +93,7 @@ class Period:
|
||||
"""Returns the first day of the last month.
|
||||
|
||||
Returns:
|
||||
date: The first day of the last month.
|
||||
datetime.date: The first day of the last month.
|
||||
"""
|
||||
today = timezone.localdate()
|
||||
month = today.month - 1
|
||||
@ -115,14 +101,14 @@ class Period:
|
||||
if month < 1:
|
||||
month = 12
|
||||
year = year - 1
|
||||
return date(year, month, 1)
|
||||
return datetime.date(year, month, 1)
|
||||
|
||||
@staticmethod
|
||||
def _get_next_month_start():
|
||||
"""Returns the first day of the next month.
|
||||
|
||||
Returns:
|
||||
date: The first day of the next month.
|
||||
datetime.date: The first day of the next month.
|
||||
"""
|
||||
today = timezone.localdate()
|
||||
month = today.month + 1
|
||||
@ -130,14 +116,20 @@ class Period:
|
||||
if month > 12:
|
||||
month = 1
|
||||
year = year + 1
|
||||
return date(year, month, 1)
|
||||
return datetime.date(year, month, 1)
|
||||
|
||||
@property
|
||||
def this_month(self):
|
||||
"""Returns the specification of this month.
|
||||
|
||||
Returns:
|
||||
str|None: The specification of this month, or None if there is no
|
||||
data in or before this month.
|
||||
"""
|
||||
if self._data_start is None:
|
||||
return None
|
||||
today = timezone.localdate()
|
||||
first_month_start = date(
|
||||
first_month_start = datetime.date(
|
||||
self._data_start.year, self._data_start.month, 1)
|
||||
if today < first_month_start:
|
||||
return None
|
||||
@ -145,10 +137,16 @@ class Period:
|
||||
|
||||
@property
|
||||
def last_month(self):
|
||||
"""Returns the specification of last month.
|
||||
|
||||
Returns:
|
||||
str|None: The specification of last month, or None if there is no
|
||||
data in or before last month.
|
||||
"""
|
||||
if self._data_start is None:
|
||||
return None
|
||||
last_month_start = self._get_last_month_start()
|
||||
first_month_start = date(
|
||||
first_month_start = datetime.date(
|
||||
self._data_start.year, self._data_start.month, 1)
|
||||
if last_month_start < first_month_start:
|
||||
return None
|
||||
@ -156,6 +154,12 @@ class Period:
|
||||
|
||||
@property
|
||||
def since_last_month(self):
|
||||
"""Returns the specification since last month.
|
||||
|
||||
Returns:
|
||||
str|None: The specification since last month, or None if there is
|
||||
no data in or before last month.
|
||||
"""
|
||||
last_month = self.last_month
|
||||
if last_month is None:
|
||||
return None
|
||||
@ -163,8 +167,15 @@ class Period:
|
||||
|
||||
@property
|
||||
def has_months_to_choose(self):
|
||||
"""Returns whether there are months to choose besides this month and
|
||||
last month.
|
||||
|
||||
Returns:
|
||||
bool: True if there are months to choose besides this month and
|
||||
last month, or False otherwise.
|
||||
"""
|
||||
if self._data_start is None:
|
||||
return None
|
||||
return False
|
||||
if self._data_start < self._get_last_month_start():
|
||||
return True
|
||||
if self._data_end >= self._get_next_month_start():
|
||||
@ -173,6 +184,14 @@ class Period:
|
||||
|
||||
@property
|
||||
def chosen_month(self):
|
||||
"""Returns the specification of the chosen month, or None if the
|
||||
current period is not a month or is out of available data range.
|
||||
|
||||
Returns:
|
||||
str|None: The specification of the chosen month, or None if the
|
||||
current period is not a month or is out of available data
|
||||
range.
|
||||
"""
|
||||
if self._data_start is None:
|
||||
return None
|
||||
m = re.match("^[0-9]{4}-[0-2]{2}", self._period.spec)
|
||||
@ -186,6 +205,12 @@ class Period:
|
||||
|
||||
@property
|
||||
def this_year(self):
|
||||
"""Returns the specification of this year.
|
||||
|
||||
Returns:
|
||||
str|None: The specification of this year, or None if there is no
|
||||
data in or before this year.
|
||||
"""
|
||||
if self._data_start is None:
|
||||
return None
|
||||
this_year = timezone.localdate().year
|
||||
@ -195,6 +220,12 @@ class Period:
|
||||
|
||||
@property
|
||||
def last_year(self):
|
||||
"""Returns the specification of last year.
|
||||
|
||||
Returns:
|
||||
str|None: The specification of last year, or None if there is no
|
||||
data in or before last year.
|
||||
"""
|
||||
if self._data_start is None:
|
||||
return None
|
||||
last_year = timezone.localdate().year - 1
|
||||
@ -204,8 +235,15 @@ class Period:
|
||||
|
||||
@property
|
||||
def has_years_to_choose(self):
|
||||
"""Returns whether there are years to choose besides this year and
|
||||
last year.
|
||||
|
||||
Returns:
|
||||
bool: True if there are years to choose besides this year and
|
||||
last year, or False otherwise.
|
||||
"""
|
||||
if self._data_start is None:
|
||||
return None
|
||||
return False
|
||||
this_year = timezone.localdate().year
|
||||
if self._data_start.year < this_year - 1:
|
||||
return True
|
||||
@ -215,6 +253,11 @@ class Period:
|
||||
|
||||
@property
|
||||
def years_to_choose(self):
|
||||
"""Returns the years to choose besides this year and last year.
|
||||
|
||||
Returns:
|
||||
list[str]: The years to choose besides this year and last year.
|
||||
"""
|
||||
if self._data_start is None:
|
||||
return None
|
||||
this_year = timezone.localdate().year
|
||||
@ -225,8 +268,7 @@ class Period:
|
||||
return after + before[::-1]
|
||||
|
||||
def is_chosen_year(self, year):
|
||||
"""Returne whether the specified year is the currently-chosen
|
||||
year.
|
||||
"""Returns whether the specified year is the currently-chosen year.
|
||||
|
||||
Args:
|
||||
year (str): the year.
|
||||
@ -240,6 +282,12 @@ class Period:
|
||||
|
||||
@property
|
||||
def today(self):
|
||||
"""Returns the specification of today.
|
||||
|
||||
Returns:
|
||||
(str): The specification of today, or None if there is no data
|
||||
in or before today.
|
||||
"""
|
||||
if self._data_start is None:
|
||||
return None
|
||||
today = timezone.localdate()
|
||||
@ -249,19 +297,37 @@ class Period:
|
||||
|
||||
@property
|
||||
def yesterday(self):
|
||||
"""Returns the specification of yesterday.
|
||||
|
||||
Returns:
|
||||
(str): The specification of yesterday, or None if there is no data
|
||||
in or before yesterday.
|
||||
"""
|
||||
if self._data_start is None:
|
||||
return None
|
||||
yesterday = timezone.localdate() - timedelta(days=1)
|
||||
yesterday = timezone.localdate() - datetime.timedelta(days=1)
|
||||
if yesterday < self._data_start or yesterday > self._data_end:
|
||||
return None
|
||||
return dateformat.format(yesterday, "Y-m-d")
|
||||
|
||||
@property
|
||||
def chosen_day(self):
|
||||
"""Returns the specification of the chosen day.
|
||||
|
||||
Returns:
|
||||
(str): The specification of the chosen day, or the start day
|
||||
of the period if the current period is not a day.
|
||||
"""
|
||||
return dateformat.format(self._period.start, "Y-m-d")
|
||||
|
||||
@property
|
||||
def has_days_to_choose(self):
|
||||
"""Returns whether there are more than one day to choose from.
|
||||
|
||||
Returns:
|
||||
bool: True if there are more than one day to choose from,
|
||||
or False otherwise.
|
||||
"""
|
||||
if self._data_start is None:
|
||||
return False
|
||||
if self._data_start == self._data_end:
|
||||
@ -270,18 +336,35 @@ class Period:
|
||||
|
||||
@property
|
||||
def first_day(self):
|
||||
"""Returns the specification of the available first day.
|
||||
|
||||
Returns:
|
||||
str: The specification of the available first day.
|
||||
"""
|
||||
if self._data_start is None:
|
||||
return None
|
||||
return dateformat.format(self._data_start, "Y-m-d")
|
||||
|
||||
@property
|
||||
def last_day(self):
|
||||
"""Returns the specification of the available last day.
|
||||
|
||||
Returns:
|
||||
str: The specification of the available last day.
|
||||
"""
|
||||
if self._data_end is None:
|
||||
return None
|
||||
return dateformat.format(self._data_end, "Y-m-d")
|
||||
|
||||
@property
|
||||
def chosen_start(self):
|
||||
"""Returns the specification of of the first day of the
|
||||
specified period.
|
||||
|
||||
Returns:
|
||||
str: The specification of of the first day of the
|
||||
specified period.
|
||||
"""
|
||||
if self._data_start is None:
|
||||
return None
|
||||
day = self._period.start \
|
||||
@ -291,6 +374,13 @@ class Period:
|
||||
|
||||
@property
|
||||
def chosen_end(self):
|
||||
"""Returns the specification of of the last day of the
|
||||
specified period.
|
||||
|
||||
Returns:
|
||||
str: The specification of of the last day of the
|
||||
specified period.
|
||||
"""
|
||||
if self._data_end is None:
|
||||
return None
|
||||
day = self._period.end \
|
||||
@ -300,9 +390,14 @@ class Period:
|
||||
|
||||
@property
|
||||
def month_picker_params(self):
|
||||
"""Returns the parameters for the month-picker, as a JSON text string.
|
||||
|
||||
Returns:
|
||||
str: The parameters for the month-picker, as a JSON text string.
|
||||
"""
|
||||
if self._data_start is None:
|
||||
return None
|
||||
start = date(self._data_start.year, self._data_start.month, 1)
|
||||
start = datetime.date(self._data_start.year, self._data_start.month, 1)
|
||||
return DjangoJSONEncoder().encode({
|
||||
"locale": Language.current().locale,
|
||||
"minDate": start,
|
||||
@ -350,7 +445,7 @@ class Period:
|
||||
year = int(m.group(1))
|
||||
month = int(m.group(2))
|
||||
try:
|
||||
self.start = date(year, month, 1)
|
||||
self.start = datetime.date(year, month, 1)
|
||||
except ValueError:
|
||||
self.invalid_period()
|
||||
return
|
||||
@ -363,7 +458,7 @@ class Period:
|
||||
year = int(m.group(1))
|
||||
month = int(m.group(2))
|
||||
try:
|
||||
self.start = date(year, month, 1)
|
||||
self.start = datetime.date(year, month, 1)
|
||||
except ValueError:
|
||||
self.invalid_period()
|
||||
return
|
||||
@ -377,11 +472,11 @@ class Period:
|
||||
if m is not None:
|
||||
year = int(m.group(1))
|
||||
try:
|
||||
self.start = date(year, 1, 1)
|
||||
self.start = datetime.date(year, 1, 1)
|
||||
except ValueError:
|
||||
self.invalid_period()
|
||||
return
|
||||
self.end = date(year, 12, 31)
|
||||
self.end = datetime.date(year, 12, 31)
|
||||
today = timezone.localdate()
|
||||
if year == today.year:
|
||||
self.description = gettext("This Year")
|
||||
@ -392,7 +487,7 @@ class Period:
|
||||
return
|
||||
# All time
|
||||
if spec == "-":
|
||||
self.start = date(2000, 1, 1)
|
||||
self.start = datetime.date(2000, 1, 1)
|
||||
self.end = self.get_month_last_day(
|
||||
timezone.localdate())
|
||||
self.description = gettext("All")
|
||||
@ -402,7 +497,7 @@ class Period:
|
||||
spec)
|
||||
if m is not None:
|
||||
try:
|
||||
self.start = date(
|
||||
self.start = datetime.date(
|
||||
int(m.group(1)),
|
||||
int(m.group(2)),
|
||||
int(m.group(3)))
|
||||
@ -418,11 +513,11 @@ class Period:
|
||||
spec)
|
||||
if m is not None:
|
||||
try:
|
||||
self.start = date(
|
||||
self.start = datetime.date(
|
||||
int(m.group(1)),
|
||||
int(m.group(2)),
|
||||
int(m.group(3)))
|
||||
self.end = date(
|
||||
self.end = datetime.date(
|
||||
int(m.group(4)),
|
||||
int(m.group(5)),
|
||||
int(m.group(6)))
|
||||
@ -467,7 +562,7 @@ class Period:
|
||||
"""Sets the period to this month."""
|
||||
today = timezone.localdate()
|
||||
self.spec = dateformat.format(today, "Y-m")
|
||||
self.start = date(today.year, today.month, 1)
|
||||
self.start = datetime.date(today.year, today.month, 1)
|
||||
self.end = self.get_month_last_day(self.start)
|
||||
self.description = gettext("This Month")
|
||||
|
||||
@ -493,7 +588,8 @@ class Period:
|
||||
if next_month > 12:
|
||||
next_month = 1
|
||||
next_year = next_year + 1
|
||||
return date(next_year, next_month, 1) - timedelta(days=1)
|
||||
return datetime.date(
|
||||
next_year, next_month, 1) - datetime.timedelta(days=1)
|
||||
|
||||
@staticmethod
|
||||
def get_month_text(year, month):
|
||||
@ -514,7 +610,7 @@ class Period:
|
||||
if prev_month < 1:
|
||||
prev_month = 12
|
||||
prev_year = prev_year - 1
|
||||
prev = date(prev_year, prev_month, 1)
|
||||
prev = datetime.date(prev_year, prev_month, 1)
|
||||
if year == prev.year and month == prev.month:
|
||||
return gettext("Last Month")
|
||||
return "%d/%d" % (year, month)
|
||||
@ -532,7 +628,7 @@ class Period:
|
||||
today = timezone.localdate()
|
||||
if day == today:
|
||||
return gettext("Today")
|
||||
elif day == today - timedelta(days=1):
|
||||
elif day == today - datetime.timedelta(days=1):
|
||||
return gettext("Yesterday")
|
||||
elif day.year != today.year:
|
||||
return defaultfilters.date(day, "Y/n/j")
|
||||
|
||||
Loading…
Reference in New Issue
Block a user