rename README.txt to README.rst

1 files changed, 104 insertions, 0 deletions

diff --git a/README.rst b/README.rst
new file mode 100644
index 0000000..f7ef62a
--- /dev/null
+++ b/README.rst
@@ -0,0 +1,104 @@
+
+ISO 8601 date/time parser
+=========================
+
+This module implements ISO 8601 date, time and duration parsing.
+The implementation follows ISO8601:2004 standard, and implements only
+date/time representations mentioned in the standard. If something is not
+mentioned there, then it is treated as non existent, and not as an allowed
+option.
+
+For instance, ISO8601:2004 never mentions 2 digit years. So, it is not
+intended by this module to support 2 digit years. (while it may still
+be valid as ISO date, because it is not explicitly forbidden.)
+Another example is, when no time zone information is given for a time,
+then it should be interpreted as local time, and not UTC.
+
+As this module maps ISO 8601 dates/times to standard Python data types, like
+*date*, *time*, *datetime* and *timedelta*, it is not possible to convert
+all possible ISO 8601 dates/times. For instance, dates before 0001-01-01 are
+not allowed by the Python *date* and *datetime* classes. Additionally
+fractional seconds are limited to microseconds. That means if the parser finds
+for instance nanoseconds it will round it to microseconds.
+
+Documentation
+-------------
+
+Currently there are four parsing methods available.
+   * parse_time:
+        parses an ISO 8601 time string into a *time* object
+   * parse_date:
+        parses an ISO 8601 date string into a *date* object
+   * parse_datetime:
+        parses an ISO 8601 date-time string into a *datetime* object
+   * parse_duration:
+        parses an ISO 8601 duration string into a *timedelta* or *Duration*
+        object.
+   * parse_tzinfo:
+        parses the time zone info part of an ISO 8601 string into a
+        *tzinfo* object.
+
+As ISO 8601 allows to define durations in years and months, and *timedelta*
+does not handle years and months, this module provides a *Duration* class,
+which can be used almost like a *timedelta* object (with some limitations).
+However, a *Duration* object can be converted into a *timedelta* object.
+
+There are also ISO formating methods for all supported data types. Each
+*xxx_isoformat* method accepts a format parameter. The default format is
+always the ISO 8601 expanded format. This is the same format used by
+*datetime.isoformat*:
+
+    * time_isoformat:
+        Intended to create ISO time strings with default format
+        *hh:mm:ssZ*.
+    * date_isoformat:
+        Intended to create ISO date strings with default format
+        *yyyy-mm-dd*.
+    * datetime_isoformat:
+        Intended to create ISO date-time strings with default format
+        *yyyy-mm-ddThh:mm:ssZ*.
+    * duration_isoformat:
+        Intended to create ISO duration strings with default format
+        *PnnYnnMnnDTnnHnnMnnS*.
+    * tz_isoformat:
+        Intended to create ISO time zone strings with default format
+        *hh:mm*.
+    * strftime:
+        A re-implementation mostly compatible with Python's *strftime*, but
+        supports only those format strings, which can also be used for dates
+        prior 1900. This method also understands how to format *datetime* and
+        *Duration* instances.
+
+Installation:
+-------------
+
+This module can easily be installed with Python standard installation methods.
+
+Either use *python setup.py install* or in case you have *setuptools* or
+*distribute* available, you can also use *easy_install*.
+
+Limitations:
+------------
+
+   * The parser accepts several date/time representation which should be invalid
+     according to ISO 8601 standard.
+
+     1. for date and time together, this parser accepts a mixture of basic and extended format.
+        e.g. the date could be in basic format, while the time is accepted in extended format.
+        It also allows short dates and times in date-time strings.
+     2. For incomplete dates, the first day is chosen. e.g. 19th century results in a date of
+        1901-01-01.
+     3. negative *Duration* and *timedelta* value are not fully supported yet.
+
+Further information:
+--------------------
+
+The doc strings and unit tests should provide rather detailed information about
+the methods and their limitations.
+
+The source release provides a *setup.py* script and a *buildout.cfg*. Both can
+be used to run the unit tests included.
+
+Source code is available at `<http://github.com/gweis/isodate>`_.
+
+.. image: https://travis-ci.org/gweis/isodate.png?branch=master