Add PEP 321: Date/time parsing

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
 

pep-0321.txt

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