From 25939269d06d01d5c8bd4fee376a615d66f0d79b Mon Sep 17 00:00:00 2001 From: Gerhard Weis Date: Sun, 23 Feb 2014 09:22:58 +1000 Subject: rename README.txt to README.rst --- README.rst | 104 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ README.txt | 103 ------------------------------------------------------------ 2 files changed, 104 insertions(+), 103 deletions(-) create mode 100644 README.rst delete mode 100644 README.txt 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 ``_. + +.. image: https://travis-ci.org/gweis/isodate.png?branch=master diff --git a/README.txt b/README.txt deleted file mode 100644 index 771b31f..0000000 --- a/README.txt +++ /dev/null @@ -1,103 +0,0 @@ -[![Build Status](https://travis-ci.org/gweis/isodate.png?branch=master)](https://travis-ci.org/gweis/isodate) - -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 ``_. -- cgit v1.2.1