~launchpad-pqm/launchpad/devel

« back to all changes in this revision

Viewing changes to lib/lp/app/doc/datehandling.txt

[r=sinzui][bug=855670] Add additional checks to the private team
        launchpad.LimitedView security adaptor so more users in defined
        roles can see the team.

Show diffs side-by-side

added added

removed removed

Lines of Context:
 
1
Date Handling
 
2
=============
 
3
 
 
4
She's really hot, you're really nervous. What are you going to wear? What if
 
5
she doesn't like the restaurant you suggested? What if you get spaghetti sauce
 
6
all over your shirt?
 
7
 
 
8
Handling dates can be tricky. This document is about handling dates.
 
9
Thankfully, it's not about handling /those/ kinds of dates.
 
10
 
 
11
Date Handling in Launchpad
 
12
==========================
 
13
 
 
14
Time differences
 
15
----------------
 
16
 
 
17
It's often useful to know how long ago something was created, or how long ago
 
18
something happened. So, let's demonstrate how this functionality can be
 
19
accessed in Launchpad, using the age of a bug task as an example. First, let's
 
20
pretend we're logged in as Sample Person:
 
21
 
 
22
    >>> from canonical.launchpad.ftests import login
 
23
    >>> login("testing@canonical.com")
 
24
 
 
25
Then let's grab one of his bug tasks to work with:
 
26
 
 
27
    >>> from zope.component import getUtility
 
28
    >>> from lp.bugs.interfaces.bugtask import IBugTaskSet
 
29
    >>> bugtaskset = getUtility(IBugTaskSet)
 
30
    >>> bt = bugtaskset.get(2)
 
31
 
 
32
Then let's create a bunch of sample dates to work with:
 
33
 
 
34
    >>> from datetime import datetime, timedelta
 
35
    >>> import pytz
 
36
    >>> right_now = datetime.now(pytz.timezone('UTC'))
 
37
    >>> one_minute_ago = right_now - timedelta(minutes = 1)
 
38
    >>> four_hours_ago = right_now - timedelta(hours = 4)
 
39
    >>> sixteen_days_ago = right_now - timedelta(days = 16)
 
40
    >>> six_months_ago = right_now - timedelta(days = 180)
 
41
    >>> one_year_ago = right_now - timedelta(days = 365)
 
42
 
 
43
An IBugTask extends the interface IHasDateCreated. IHasDateCreated can be
 
44
adapted to IAging:
 
45
 
 
46
    >>> from lp.app.interfaces.launchpad import IAging
 
47
    >>> bt.datecreated = one_minute_ago
 
48
    >>> aging_bug = IAging(bt)
 
49
 
 
50
IAging provides a method, currentApproximateAge, which returns a human-readable
 
51
approximation of the age of a something.
 
52
 
 
53
    >>> print aging_bug.currentApproximateAge()
 
54
    1 minute
 
55
 
 
56
We're cheating a bit below (swapping in different values for datecreated, which
 
57
you should never do in user code) to demonstrate the various kinds of values
 
58
currentApproximateAge returns.
 
59
 
 
60
    >>> aging_bug.context.datecreated = four_hours_ago
 
61
    >>> print aging_bug.currentApproximateAge()
 
62
    4 hours
 
63
    >>> aging_bug.context.datecreated = sixteen_days_ago
 
64
    >>> print aging_bug.currentApproximateAge()
 
65
    2 weeks
 
66
    >>> aging_bug.context.datecreated = six_months_ago
 
67
    >>> print aging_bug.currentApproximateAge()
 
68
    6 months
 
69
    >>> aging_bug.context.datecreated = one_year_ago
 
70
    >>> print aging_bug.currentApproximateAge()
 
71
    1 year