Module pyfdate

source code

@version: 0.7
@date:    2008-08-28
@status:  beta
@author:  Stephen Ferg
@contact: http://www.ferg.org/contact_info
@license: Creative Commons Attribution License 2.0 http://creativecommons.org/licenses/by/2.0/
@see:     http://www.ferg.org/pyfdate
@note:

ABOUT PYFDATE

The purpose of pyfdate is to provide a variety of user-friendly features
for working with datetimes, doing date arithmetic, and formatting dates,
times, and periods of time.

Pyfdate doesn't attempt to be all things to all people: rather, its goal
is to make it easy to do 95% if the things that people want to do with
dates and times.

Pyfdate provides two classes:

------------------------------------------------------------------------

Time:
        - A specific point in time, identified by
          year, month, day, hour, minute, second.
        (Python's datetime module calls this a "datetime".)

Period:
        - An amount of time, measured in days, hours, minutes, and seconds.

------------------------------------------------------------------------

In order to keep pyfdate simple, there are a number of things that it does not attempt to do.
        - Pyfdate doesn't know anything about timezones.
        - Pyfdate doesn't know anything about daylight savings time.
        - Pyfdate doesn't provide any facilities for parsing strings into date/times.
          (It does, however, provide a useful numsplit() function which performs a kind of parsing.)
        - The smallest unit of time that Pyfdate can handle is a second.
           It cannot be used to work with hundredths or thousandths of seconds.

INTERNATIONAL LANGUAGE SUPPORT

By default, pyfdate's language for displaying dates and times
(e.g. weekday names and month names) is American English.

If pyfdate can successfully import pyfdate_local,
the language for displaying dates and times
is taken from the pyfdate_local.py file.

Localization files are available for a number of languages.
For example: pyfdate_local_francais.py for French.

To use the file for language foobar,
simply copy pyfdate_local_foobar.py to pyfdate_local.py

And of course it is possible to customize pyfdate_local.py for any particular
language of your choice.  If you create (or correct) a localization file
for pyfdate, please share it with others by submitting it for inclusion
in the pyfdate distribution.


BACKGROUND

Many ideas for pyfdate functionality grew out of Steve Ferg's experiences with
an earlier (non-Python) program called "fdate", which provided datetime
arithmetic functionality for MS-DOS batch files. The name "pyfdate" is derived
from "Python" and "fdate".

>>> from pyfdate import *
>>> s = argsToString("test",2,Time())
>>> print s
arg     1: "test" <type 'str'>
arg     2: 2 <type 'int'>
arg     3: 2008-01-01 14:40:18 <type 'instance'>

>>> from pyfdate import *
>>> s = kwargsToString(first="test", second=2, third=Time())
>>> print s
first     : "test" <type 'str'>
second    : 2 <type 'int'>
third     : 2008-01-01 14:36:38 <type 'instance'>

>>> CalendarMonthToNumericMonth(2007,4)
24075

>>> NumericMonthToCalendarMonth(24075)
(2007, 4)

>>> isLeapYear(2004)
True
>>> isLeapYear(2000)
True
>>> isLeapYear(2005)
False

>>> to24hour(12,"am")
0
>>> to24hour(1,"am")
1
>>> to24hour(12,"PM")
12
>>> to24hour(1,"PM")
13

>>> from pyfdate import *
>>> numsplit("2007_10_09")
[2007, 10, 9]
>>> numsplit("2007-10-09T23:45:59")
[2007, 10, 9, 23, 45, 59]
>>> numsplit("2007/10/09 23.45.59")
[2007, 10, 9, 23, 45, 59]