PEP: 321

PEP: 321
Title: Date/Time Parsing and Formatting
Version: $Revision$
Last-Modified: $Date$
Author: A.M. Kuchling <[email protected]>
Status: Withdrawn
Type: Standards Track
Content-Type: text/x-rst
Created: 16-Sep-2003
Python-Version: 2.4
Post-History:

Abstract
========

Python 2.3 added a number of simple date and time types in the
``datetime`` module. There's no support for parsing strings in various
formats and returning a corresponding instance of one of the types.
This PEP proposes adding a family of predefined parsing function for
several commonly used date and time formats, and a facility for generic
parsing.

The types provided by the ``datetime`` module all have
``.isoformat()`` and ``.ctime()`` methods that return string
representations of a time, and the ``.strftime()`` method can be used
to construct new formats. There are a number of additional
commonly-used formats that would be useful to have as part of the
standard library; this PEP also suggests how to add them.

Input Formats
=======================

Useful formats to support include:

* `ISO8601`_
* ARPA/:rfc:`2822`
* `ctime`_
* Formats commonly written by humans such as the American
"MM/DD/YYYY", the European "YYYY/MM/DD", and variants such as
"DD-Month-YYYY".
* CVS-style or tar-style dates ("tomorrow", "12 hours ago", etc.)

XXX The Perl `ParseDate.pm`_ module supports many different input formats,
both absolute and relative. Should we try to support them all?

Options:

1) Add functions to the ``datetime`` module::

import datetime
d = datetime.parse_iso8601("2003-09-15T10:34:54")

2) Add class methods to the various types. There are already various
class methods such as ``.now()``, so this would be pretty natural.::

import datetime
d = datetime.date.parse_iso8601("2003-09-15T10:34:54")

3) Add a separate module (possible names: date, date_parse, parse_date)
or subpackage (possible names: datetime.parser) containing parsing
functions::

import datetime
d = datetime.parser.parse_iso8601("2003-09-15T10:34:54")

Unresolved questions:

* Naming convention to use.
* What exception to raise on errors? ValueError, or a specialized exception?
* Should you know what type you're expecting, or should the parsing figure
it out? (e.g. ``parse_iso8601("yyyy-mm-dd")`` returns a ``date`` instance,
but parsing "yyyy-mm-ddThh:mm:ss" returns a ``datetime``.) Should
there be an option to signal an error if a time is provided where
none is expected, or if no time is provided?
* Anything special required for I18N? For time zones?

Generic Input Parsing
=======================

Is a strptime() implementation that returns ``datetime`` types sufficient?

XXX if yes, describe strptime here. Can the existing pure-Python
implementation be easily retargeted?

Output Formats
=======================

Not all input formats need to be supported as output formats, because it's
pretty trivial to get the ``strftime()`` argument right for simple things
such as YYYY/MM/DD. Only complicated formats need to be supported; :rfc:`2822`
is currently the only one I can think of.

Options:

1) Provide predefined format strings, so you could write this::

import datetime
d = datetime.datetime(...)
print d.strftime(d.RFC2822_FORMAT) # or datetime.RFC2822_FORMAT?

2) Provide new methods on all the objects::

d = datetime.datetime(...)
print d.rfc822_time()

Relevant functionality in other languages includes the `PHP date`_
function (Python implementation by Simon Willison at
http://simon.incutio.com/archive/2003/10/07/dateInPython)

References
==========

. _ISO8601: http://www.cl.cam.ac.uk/~mgk25/iso-time.html

. _ParseDate.pm: http://search.cpan.org/author/MUIR/Time-modules-2003.0211/lib/Time/ParseDate.pm

. _ctime: http://www.opengroup.org/onlinepubs/007908799/xsh/asctime.html

. _PHP date: http://www.php.net/date

Other useful links:

http://www.egenix.com/files/python/mxDateTime.html
http://ringmaster.arc.nasa.gov/tools/time_formats.html
http://www.thinkage.ca/english/gcos/expl/b/lib/0tosec.html
https://moin.conectiva.com.br/DateUtil

Copyright
=========

This document has been placed in the public domain.

.
Local Variables:
mode: indented-text
indent-tabs-mode: nil
sentence-end-double-space: t
fill-column: 70
End: