diff --git a/pep-0000.txt b/pep-0000.txt index 8d7c9562c..3de9ba58e 100644 --- a/pep-0000.txt +++ b/pep-0000.txt @@ -116,6 +116,7 @@ Index by Category S 315 Enhanced While Loop Carroll S 318 Function/Method Decorator Syntax Smith S 319 Python Synchronize/Asynchronize Block Pelletier + S 321 Date/Time Parsing and Formatting Kuchling S 754 IEEE 754 Floating Point Special Values Warnes Finished PEPs (done, implemented in CVS) @@ -333,6 +334,7 @@ Numerical Index S 318 Function/Method Decorator Syntax Smith S 319 Python Synchronize/Asynchronize Block Pelletier I 320 Python 2.4 Release Schedule Warsaw + S 321 Date/Time Parsing and Formatting Kuchling SR 666 Reject Foolish Indentation Creighton S 754 IEEE 754 Floating Point Special Values Warnes diff --git a/pep-0321.txt b/pep-0321.txt new file mode 100644 index 000000000..991085a10 --- /dev/null +++ b/pep-0321.txt @@ -0,0 +1,138 @@ +PEP: 321 +Title: Date/Time Parsing and Formatting +Version: $Revision$ +Last-Modified: $Date$ +Author: A.M. Kuchling +Status: Draft +Type: Standards Track +Content-Type: text/x-rst +Python-Version: 2.4 +Created: 16-Sep-2003 +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`_, `RFC2822`_, `ctime`_, +and some that are commonly written by humans such as the American +"MM/DD/YYYY", the European "YYYY/MM/DD", and variants such as +"DD-Month-YYYY". + +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; RFC2822 +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() + + +References +========== + +.. _RFC2822: http://rfc2822.x42.com + +.. _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 + +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 + + +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: