python-peps/pep-0321.txt

150 lines
4.3 KiB
Plaintext
Raw Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

PEP: 321
Title: Date/Time Parsing and Formatting
Version: $Revision$
Last-Modified: $Date$
Author: A.M. Kuchling <amk@amk.ca>
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: