/
periods.txt
143 lines (93 loc) · 4.67 KB
/
periods.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
=======
Periods
=======
One of the goals of DjangoSchedule is to make occurrence generation and persistence easy. To do this it creates simple classes for accessing these
occurrences. These are Periods. Period is an object that is initiated with an iterable object of events, a start datetime, and an end datetime.
It is common to subclass Period for common periods of time. Some of these already exist in the project. Year, Month, Week, Day
Expect more in the future: Hour, HalfHour
Period Base Class
-----------------
This is the base class from which all other periods inherit. It contains all
of the base functionality for retrieving occurrences. It is instantiated with
a list of events, a start date, and an end date. *The start date is inclusive,
the end date is exclusive.* ie [start, end)
>>> p = Period(datetime.datetime(2008,4,1,0,0))
``get_occurrences()``
~~~~~~~~~~~~~~~~~~~~~
This method is for getting the occurrences from the list of passed in events. It returns the occurrences that exist in the period for every event. If I have a list of events ``my_events``, and I want to know all of the occurrences from today to next week I simply create a Period object and then call get_occurrences. It will return a sorted list of Occurrences.
::
import datetime
today = datetime.datetime.now()
this_week = Period(my_events, today, today+datetime.timedelta(days=7))
this_week.get_occurrences()
``classify_occurrence(occurrence)``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You use this method to determine how the Occurrence ``occurrence`` relates to the period. This method returns a dictionary. The keys are ``"class"`` and ``"occurrence"``. The class key returns a a number from 0 to 3 and the occurrence key returns the occurrence.
Classes:
0: Only started during this period.
1: Started and ended during this period.
2: Didn't start or end in this period, but does exist during this period.
3: Only ended during this period.
``get_occurrence_partials()``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This method is used for getting all the occurrences, but getting them as classified occurrences. Simply it runs classify_occurrence on each occurrence in get_occurrence and returns that list.
::
import datetime
today = datetime.datetime.now()
this_week = Period(my_events, today, today+datetime.timedelta(days=7))
this_week.get_occurrences() == [classified_occurrence['occurrence'] for classified_occurrence in this_week.get_occurrence_partials()]
``has_occurrence()``
~~~~~~~~~~~~~~~~~~~~
This method returns whether there are any occurrences in this period
Year
----
The year period is instaniated with a list of events and a date or datetime object. It will resemble the year in which that date exists.
>>> p = Year(events, datetime.datetime(2008,4,1))
>>> p.start
datetime.datetime(2008, 1, 1, 0, 0)
>>> p.end
datetime.datetime(2009, 1, 1, 0, 0)
>>> -Remember start is inclusive and end is exclusive
``get_months()``
~~~~~~~~~~~~~~~~
This function returns 12 Month objects which resemble the 12 months in the Year period.
Month
-----
The Month period is instantiated with a list of events and a date or datetime object. It resembles the month that contains the date or datetime object that was passed in.
>>> p = Month(events, datetime.datetime(2008,4,4))
>>> p.start
datetime.datetime(2008, 4, 1, 0, 0)
>>> p.end
datetime.datetime(2008, 5, 1, 0, 0)
>>> -Remember start is inclusive and end is exclusive
``get_weeks()``
~~~~~~~~~~~~~~~
This method returns a list of Week objects that occur at all during that month. The week does not have to be fully encapsulated in the month just have
exist in the month at all
``get_days()``
~~~~~~~~~~~~~~
This method returns a list of Day objects that occur during the month.
``get_day(day_number)``
~~~~~~~~~~~~~~~~~~~~~~~
This method returns a specific day in a year given its day number.
Week
----
The Week period is instantiated with a list of events and a date or datetime object. It resembles the week that contains the date or datetime object that was passed in.
>>> p = Week(events, datetime.datetime(2008,4,1))
>>> p.start
datetime.datetime(2008, 3, 30, 0, 0)
>>> p.end
datetime.datetime(2008, 4, 6, 0, 0)
>>> -Remember start is inclusive and end is exclusive
``get_days()``
~~~~~~~~~~~~~~
This method returns the 7 Day objects that represent the days in a Week period.
Day
---
The Day period is instantiated with a list of events and a date or datetime object. It resembles the day that contains the date or datetime object that was passed in.
>>> p = Day(events, datetime.datetime(2008,4,1))
>>> p.start
datetime.datetime(2008, 4, 1, 0, 0)
>>> p.end
datetime.datetime(2008, 4, 2, 0, 0)
>>> -Remember start is inclusive and end is exclusive