[Python-checkins] python/nondist/peps pep-0321.txt, NONE, 1.1 pep-0000.txt, 1.251, 1.252

[akuchling at users.sourceforge.net]

Update of /cvsroot/python/python/nondist/peps
In directory sc8-pr-cvs1:/tmp/cvs-serv7859

Modified Files:
	pep-0000.txt 
Added Files:
	pep-0321.txt 
Log Message:
Add PEP 321: Date/time parsing

--- NEW FILE: pep-0321.txt ---
PEP: 321
Title: Date/Time Parsing and Formatting
Version: $Revision: 1.1 $
Last-Modified: $Date: 2003/09/16 12:07:56 $
Author: A.M. Kuchling <amk at 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:

Index: pep-0000.txt
===================================================================
RCS file: /cvsroot/python/python/nondist/peps/pep-0000.txt,v
retrieving revision 1.251
retrieving revision 1.252
diff -C2 -d -r1.251 -r1.252
*** pep-0000.txt	7 Sep 2003 13:56:12 -0000	1.251
--- pep-0000.txt	16 Sep 2003 12:07:56 -0000	1.252
***************
*** 117,120 ****
--- 117,121 ----
   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
  
***************
*** 334,337 ****
--- 335,339 ----
   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