Erik Grinaker avatar Erik Grinaker committed 2c5482b

improved documentation

Comments (0)

Files changed (17)

 python-chrono is a Python module for simple and convenient date/time
 handling, including parsing, arithmetic, comparison, formatting,
-and calendar functionality.
+and calendar functionality. It supports both the ISO and US calendars,
+and dates/times in ISO, US, or european formats.
 
 This software is licensed under the terms of the GNU General Public
 License version 3, the full text is available in the file LICENSE.

chrono/clock/us.py

 
 class USClock(clock.Clock):
     """
-    US 12-hour clock.
+    US 12-hour clock handling.
     """
 
     @classmethod
 
 from __future__ import absolute_import
 
-from . import calendar
+from . import calendar as calendarmod
 from . import error
 from . import formatter
-from . import parser
+from . import parser as parsermod
 from . import utility
 
 import datetime
 
     Valid values for *date* can be:
 
-    * string: parses date from a string, see :class:`chrono.parser.ISOParser`
-      for valid formats
+    * string: parses date from a string using the given parser (by default
+      :class:`chrono.parser.CommonParser`)
     * **True**: sets the date to the current date
     * integer: assumes input is a UNIX timestamp, sets date accordingly
     * :class:`chrono.Date`: sets date from another Date object
 
     If both *date* and keywords are specified, *date* takes precedence.
 
-    *parser* determines which parser to use for parsing dates and times
-    from strings. By default :class:`chrono.parser.CommonParser` is used,
-    which supports the most common date and time formats. See
-    :mod:`chrono.parser` for available parsers.
+    *parser* determines which parser to use for parsing dates from strings.
+    By default :class:`chrono.parser.CommonParser` is used, which supports
+    the most common date and time formats. See :mod:`chrono.parser` for
+    a list of available parsers.
+
+    *calendar* determines which calendar to use for calendar operations.
+    By default :class:`chrono.calendar.ISOCalendar` is used, see
+    :mod:`chrono.calendar` for a list of available calendars.
     """
 
-    calendar = calendar.ISOCalendar
+    calendar = None
     """
-    Calendar to use for calendar operations, defaults to
+    Calendar to use for calendar operations. Defaults to
     :class:`chrono.calendar.ISOCalendar`. See :mod:`chrono.calendar`
     for available calendars.
     """
     month = None
     "Month number, range 1-12."
 
-    parser = parser.CommonParser
+    parser = None
     """
     Parser to use for parsing dates and times from strings. See
     :mod:`chrono.parser` for available parsers.
 
     def __init__(self, date=None, parser=None, calendar=None, **kwargs):
 
-        if parser:
-            self.parser = parser
-
-        if calendar:
-            self.calendar = calendar
+        self.parser = parser or parsermod.CommonParser
+        self.calendar = calendar or calendarmod.ISOCalendar
 
         if isinstance(date, str):
             self.set_string(date)
     def format(self, template):
         """
         Formats the date using *template*, replacing variables as
-        supported by :class:`chrono.formatter.Formatter`.
+        supported by :class:`chrono.formatter.Formatter`. This value is dependent
+        on the calendar set in :attr:`chrono.Date.calendar`, by default
+        :class:`chrono.calendar.ISOCalendar`.
 
         Raises :exc:`chrono.error.NoDateTimeError` on missing date data.
         """
     def week(self):
         """
         Returns the week of the set date as a tuple with year and week
-        number.
+        number. This value is dependent on the calendar set in
+        :attr:`chrono.Date.calendar`, by default
+        :class:`chrono.calendar.ISOCalendar`.
 
         Raises :exc:`chrono.error.NoDateTimeError` on missing date data.
         """
     def weekdate(self):
         """
         Returns the week date of the set date as a tuple with year,
-        week, and weekday.
+        week, and weekday. This value is dependent on the calendar set in
+        :attr:`chrono.Date.calendar`, by default
+        :class:`chrono.calendar.ISOCalendar`.
 
         Raises :exc:`chrono.error.NoDateTimeError` on missing date data.
         """
     def weekday(self):
         """
         Returns the week day of the set date, or **None** if no
-        date is set.
+        date is set. This value is dependent on the calendar set in
+        :attr:`chrono.Date.calendar`, by default
+        :class:`chrono.calendar.ISOCalendar`.
 
         Raises :exc:`chrono.error.NoDateTimeError` on missing date data.
         """
 
     def weeks(self):
         """
-        Returns the number of weeks in the set year.
+        Returns the number of weeks in the set year. This value is
+        dependent on the calendar set in :attr:`chrono.Date.calendar`,
+        by default :class:`chrono.calendar.ISOCalendar`.
 
         Raises :exc:`chrono.error.NoDateTimeError` on missing date data.
         """

chrono/datetime.py

 
 from __future__ import absolute_import
 
-from . import calendar
+from . import calendar as calendarmod
 from . import clock
 from . import date
 from . import error
 from . import formatter
-from . import parser
+from . import parser as parsermod
 from . import time
 from . import utility
 
     *parser* determines which parser to use for parsing dates and times
     from strings. By default :class:`chrono.parser.CommonParser` is used,
     which supports the most common date and time formats. See
-    :mod:`chrono.parser` for available parsers.
+    :mod:`chrono.parser` for a list of available parsers.
 
     *calendar* determines which calendar to use for calendar operations.
     By default :class:`chrono.calendar.ISOCalendar` is used, see
-    :mod:`chrono.calendar` for available calendars.
+    :mod:`chrono.calendar` for a list of available calendars.
     """
 
     def __cmp__(self, other):
 
     def __init__(self, datetime=None, parser=None, calendar=None, **kwargs):
 
-        if parser:
-            self.parser = parser
-
-        if calendar:
-            self.calendar = calendar
+        self.parser = parser or parsermod.CommonParser
+        self.calendar = calendar or calendarmod.ISOCalendar
 
         if isinstance(datetime, str):
             self.set_string(datetime)
     def format(self, template):
         """
         Formats the date using *template*, replacing variables as
-        supported by :class:`chrono.formatter.Formatter`.
+        supported by :class:`chrono.formatter.Formatter`. This value is dependent
+        on the calendar set in :attr:`chrono.Date.calendar`, by default
+        :class:`chrono.calendar.ISOCalendar`.
 
         Raises :exc:`chrono.error.NoDateTimeError` on missing date data.
         """

chrono/parser/common.py

 
 class CommonParser(parser.Parser):
     """
-    A parser for the most common date formats. Only has the methods
+    A parser for the most common date and time formats. Only the methods
     :meth:`chrono.parser.CommonParser.parse_date`,
     :meth:`chrono.parser.CommonParser.parse_datetime`,
-    and :meth:`chrono.parser.CommonParser.parse_time`, are implmented here,
+    and :meth:`chrono.parser.CommonParser.parse_time`, are implemented here,
     methods for individual formats can be found in the classes
     :class:`chrono.parser.EuroParser`, :class:`chrono.parser.ISOParser`,
     and :class:`chrono.parser.USParser`.
 
     Datetime formats can consist of any combination of the date and time
     formats above, separated by space, or a T in the case of ISO formats.
+
+    Leading zeroes may be omitted in days and months, and years may be
+    specified with 2 digits in non-ISO formats, which will be interpreted in the
+    range 1930-2029.
+
+    Seconds and minutes may be omitted in times, which will be interpreted
+    as 0.
     """
 
     re_datetime = re.compile('''
     @classmethod
     def parse_datetime(cls, datetime):
         """
-        Parses a datetime in any supported format and returns a tuple
-        with year, month, day, hour, minute, and second. Omitted minutes
-        and/or seconds will be interpreted as 0.
+        Parses a date and time in any supported format and returns a tuple
+        with year, month, day, hour, minute, and second.
 
         Raises :exc:`chrono.error.ParseError` for invalid input format,
         :exc:`TypeError` for invalid input type, and an appropriate
     def parse_time(cls, time):
         """
         Parses a time in any supported format and returns a tuple with
-        hour, minutes, and seconds. Omitted minutes and/or seconds will be
-        interpreted as 0.
+        hour, minutes, and seconds.
 
         Raises :exc:`chrono.error.ParseError` for invalid
         input format, :exc:`TypeError` for invalid input type, and an

chrono/parser/euro.py

 
 class EuroParser(parser.Parser):
     """
-    A parser for european/western date formats, such as *dd.mm.yyyy*.
+    A parser for european date formats, such as *dd.mm.yyyy*.
+    
     Valid formats:
 
     =================== =================== ======================= ===============================================
     Format              Example             Description             Method
     =================== =================== ======================= ===============================================
     dd.mm.yyyy          23.07.2010          Date                    :meth:`chrono.parser.EuroParser.date`
-    dd-mm-yyyy          23-07-2010          Dashed date             :meth:`chrono.parser.EuroParser.dashdate`
-    dd/mm/yyyy          23/07/2010          Slashed date            :meth:`chrono.parser.EuroParser.slashdate`
+    dd-mm-yyyy          23-07-2010          Dash-separated date     :meth:`chrono.parser.EuroParser.dashdate`
+    dd/mm/yyyy          23/07/2010          Slash-separated date    :meth:`chrono.parser.EuroParser.slashdate`
     ddmmyyyy            23072010            Compact date            :meth:`chrono.parser.EuroParser.compactdate`
     hh:mm:ss            15:27:43            Time                    :meth:`chrono.parser.EuroParser.time`
     hhmmss              152743              Compact time            :meth:`chrono.parser.EuroParser.compacttime`
     =================== =================== ======================= ===============================================
+
+    Datetime formats can consist of any combination of the date and time
+    formats above, separated by space.
+
+    Leading zeroes may be omitted in days and months, and years may be
+    specified with 2 digits, which will be interpreted in the range 1930-2029.
+
+    Seconds and minutes may be omitted in times, which will be interpreted
+    as 0.
     """
 
     re_compactdate = re.compile('''
     def compactdate(cls, date):
         """
         Parses a compact european date (*ddmmyyyy*), and returns a tuple
-        with year, month, and day. Two-digit years will be interpreted in range
-        1930-2029.
+        with year, month, and day.
 
         Raises :exc:`chrono.error.ParseError` for invalid input format,
         :exc:`TypeError` for invalid input type, and
     def compacttime(cls, time):
         """
         Parses a compact european time (*hhmmss*), and returns a tuple with
-        hour, minute, and second. Minutes and/or seconds may be omitted,
-        which will be interpreted as 0.
+        hour, minute, and second.
 
         Raises :exc:`chrono.error.ParseError`
         for invalid input format, :exc:`TypeError` for invalid input type,
     def dashdate(cls, date):
         """
         Parses a dash-separated european date (*dd-mm-yyyy*), and returns a
-        tuple with year, month, and day. Two-digit years will be interpreted
-        in range 1930-2029.
+        tuple with year, month, and day.
 
         Raises :exc:`chrono.error.ParseError` for invalid input format,
         :exc:`TypeError` for invalid input type, and
     def date(cls, date):
         """
         Parses a european date (*dd.mm.yyyy*), and returns a tuple with year,
-        month, and day. Two-digit years will be interpreted in range
-        1930-2029.
+        month, and day.
 
         Raises :exc:`chrono.error.ParseError` for invalid input format,
         :exc:`TypeError` for invalid input type, and
     @classmethod
     def parse_datetime(cls, datetime):
         """
-        Parses a US datetime in any supported format and returns a tuple
-        with year, month, day, hour, minute, and second. Omitted minutes
-        and/or seconds will be interpreted as 0.
+        Parses a european datetime in any supported format and returns a tuple
+        with year, month, day, hour, minute, and second.
 
         Raises
         :exc:`chrono.error.ParseError` for invalid input format,
     def parse_time(cls, time):
         """
         Parses a european time in any supported format and returns a tuple with
-        hour, minutes, and seconds. Omitted minutes and/or seconds will be
-        interpreted as 0.
+        hour, minutes, and seconds.
 
         Raises :exc:`chrono.error.ParseError` for invalid
         input format, :exc:`TypeError` for invalid input type, and an
     def slashdate(cls, date):
         """
         Parses a slash-separated european date (*mm/dd/yyyy*), and returns a
-        tuple with year, month, and day. Two-digit years will be interpreted
-        in range 1930-2029.
+        tuple with year, month, and day.
 
         Raises :exc:`chrono.error.ParseError` for invalid input format,
         :exc:`TypeError` for invalid input type, and
     def time(cls, time):
         """
         Parses a european time (*hh:mm:ss*), and returns a tuple with hour,
-        minute, and second. Minutes and/or seconds may be omitted, which
-        will be interpreted as 0. Leading zeroes may be omitted.
+        minute, and second.
 
         Raises :exc:`chrono.error.ParseError`
         for invalid input format, :exc:`TypeError` for invalid input type,

chrono/parser/iso.py

 
 class ISOParser(parser.Parser):
     """
-    A parser for ISO 8601 date formats, using the ISO calendar.
-    For more information on the ISO calendar, see the
-    :class:`chrono.calendar.ISOCalendar` documentation.
-
-    The most commonly used ISO formats are *yyyy-mm-dd* and
-    *yyyy-mm-dd hh:mm:ss*, but the standard specifies a range of formats,
-    listed below. Datetimes can be composed of any combination of
-    the date and time formats listed, separated by whitespace or
-    a T.
+    A parser for ISO 8601 date formats, such as *yyyy-mm-dd*, using the ISO
+    calendar for week calculations. For more information on the ISO calendar,
+    see the :class:`chrono.calendar.ISOCalendar` documentation.
+    
+    Valid formats:
 
     =================== =================== ======================= ===============================================
     Format              Example             Description             Method
     =================== =================== ======================= ===============================================
     yyyy-mm-dd          2009-12-27          Date                    :meth:`chrono.parser.ISOParser.date`
-    hh:mm:ss            15:27:43            Time [#f1]_             :meth:`chrono.parser.ISOParser.time`
+    hh:mm:ss            15:27:43            Time                    :meth:`chrono.parser.ISOParser.time`
     yyyy-ddd            2009-163            Ordinal day             :meth:`chrono.parser.ISOParser.ordinal`
     yyyy-Www-d          2009-W36-3          Week and weekday        :meth:`chrono.parser.ISOParser.weekdate`
     yyyy-Www            2009-W36            Week                    :meth:`chrono.parser.ISOParser.week`
     yyyy-mm             2009-12             Month                   :meth:`chrono.parser.ISOParser.month`
     yyyy                2009                Year                    :meth:`chrono.parser.ISOParser.year`
     yyyymmdd            20091227            Compact date            :meth:`chrono.parser.ISOParser.compactdate`
-    hhmmss              152743              Compact time [#f1]_     :meth:`chrono.parser.ISOParser.compacttime`
+    hhmmss              152743              Compact time            :meth:`chrono.parser.ISOParser.compacttime`
     yyyyddd             2009163             Compact ordinal day     :meth:`chrono.parser.ISOParser.compactordinal`
     yyyyWwwd            2009W363            Compact week and day    :meth:`chrono.parser.ISOParser.compactweekdate`
     yyyyWww             2009W36             Compact week            :meth:`chrono.parser.ISOParser.compactweek`
     =================== =================== ======================= ===============================================
 
-    .. [#f1] Seconds and minutes may be omitted in times
+    Datetime formats can consist of any combination of the date and time
+    formats above, separated by space or a T.
+
+    Leading zeroes may be omitted in days and months.
+
+    Seconds and minutes may be omitted in times, which will be interpreted
+    as 0.
     """
 
     re_compactdate = re.compile('''
     def compacttime(cls, time):
         """
         Parses a compact ISO time (*hhmmss*), and returns a tuple with
-        hour, minute, and second. Minutes and/or seconds may be omitted,
-        which will be interpreted as 0.
+        hour, minute, and second.
 
         Raises :exc:`chrono.error.ParseError`
         for invalid input format, :exc:`TypeError` for invalid input type,
     def compactweek(cls, date):
         """
         Parses a compact ISO week (*yyyyWww*), and returns a tuple with year,
-        month, and day (the first Monday of the week). Leading zeroes may be
-        omitted, even though the ISO standard requires them.
+        month, and day (the first Monday of the week).
 
         Raises :exc:`chrono.error.ParseError`
         for invalid input format, :exc:`TypeError` for invalid input type,
     def date(cls, date):
         """
         Parses a ISO date (*yyyy-mm-dd*), and returns a tuple with year,
-        month, and day. Leading zeroes may be omitted, even though the ISO
-        standard requires them.
+        month, and day.
 
         Raises :exc:`chrono.error.ParseError` for
         invalid input format, :exc:`TypeError` for invalid input type,
     def month(cls, date):
         """
         Parses an ISO month (*yyyy-mm*), and returns a tuple with year, month,
-        and day (the first day of the month). Leading zeroes may be omitted,
-        even though the ISO standard requires them.
+        and day (the first day of the month).
 
         Raises :exc:`chrono.error.ParseError` for
         invalid input format, :exc:`TypeError` for invalid input type,
     def parse_datetime(cls, datetime):
         """
         Parses an ISO datetime in any supported format and returns a tuple
-        with year, month, day, hour, minute, and second. Omitted minutes
-        and/or seconds will be interpreted as 0.
+        with year, month, day, hour, minute, and second.
 
         Raises
         :exc:`chrono.error.ParseError` for invalid input format,
     def parse_time(cls, time):
         """
         Parses an ISO time in any supported format and returns a tuple with
-        hour, minutes, and seconds. Omitted minutes and/or seconds will be
-        interpreted as 0.
+        hour, minutes, and seconds.
 
         Raises :exc:`chrono.error.ParseError` for invalid
         input format, :exc:`TypeError` for invalid input type, and an
     def time(cls, time):
         """
         Parses an ISO time (*hh:mm:ss*), and returns a tuple with hour,
-        minute, and second. Minutes and/or seconds may be omitted, which
-        will be interpreted as 0. Leading zeroes may be omitted, even though
-        the ISO standard requires them.
+        minute, and second.
 
         Raises :exc:`chrono.error.ParseError`
         for invalid input format, :exc:`TypeError` for invalid input type,
     def week(cls, date):
         """
         Parses an ISO week (*yyyy-Www*), and returns a tuple with year,
-        month, and day (the first Monday of the week). Leading zeroes may
-        be omitted, even though the ISO standard requires them.
+        month, and day (the first Monday of the week).
 
         Raises :exc:`chrono.error.ParseError`
         for invalid input format, :exc:`TypeError` for invalid input type,
     def weekdate(cls, date):
         """
         Parses an ISO weekdate (*yyyy-Www-d*), and returns a tuple with
-        year, month, and day. Leading zeroes may be omitted, even though
-        the ISO standard requires them.
+        year, month, and day.
 
         Raises :exc:`chrono.error.ParseError`
         for invalid input format, :exc:`TypeError` for invalid input type,
     def year(cls, date):
         """
         Parses an ISO year (*yyyy*), and returns a tuple with year,
-        month, and day (the first day of the year). Leading zeroes may be
-        omitted, even though the ISO standard requires them.
+        month, and day (the first day of the year).
 
         Raises :exc:`chrono.error.ParseError` for invalid input format,
         :exc:`TypeError` for invalid input type, and

chrono/parser/us.py

 
 class USParser(parser.Parser):
     """
-    A parser for US date formats, such as mm/dd/yyyy. Valid formats:
+    A parser for US date formats, such as *mm/dd/yyyy*.
+
+    Valid formats:
 
     =================== =================== ======================== ===============================================
     Format              Example             Description              Method
     hhmmss am/pm        042743 PM           Compact time, 12-hour    :meth:`chrono.parser.USParser.compacttime`
     =================== =================== ======================== ===============================================
 
+    Datetime formats can consist of any combination of the date and time
+    formats above, separated by space.
+
     Leading zeroes may be omitted in days and months, and years may be
-    specified with 2 digits, which will be interpreted in the range
-    1930-2029.
+    specified with 2 digits, which will be interpreted in the range 1930-2029.
 
     Seconds and minutes may be omitted in times, which will be interpreted
     as 0.
     def compactdate(cls, date):
         """
         Parses a compact US date (*mmddyyyy*), and returns a tuple with year,
-        month, and day. Two-digit years will be interpreted in range
-        1930-2029.
+        month, and day.
 
         Raises :exc:`chrono.error.ParseError` for invalid input format,
         :exc:`TypeError` for invalid input type, and
     def compacttime(cls, time):
         """
         Parses a compact US time (*hhmmss am/pm*), and returns a tuple with
-        hour, minute, and second, using 24-hour clock. Minutes and/or seconds
-        may be omitted, which will be interpreted as 0.
+        hour, minute, and second, using 24-hour clock.
 
         Raises :exc:`chrono.error.ParseError` for invalid input format,
         :exc:`TypeError` for invalid input type, and
     def dashdate(cls, date):
         """
         Parses a dash-separated US date (*mm/dd/yyyy*), and returns a tuple
-        with year, month, and day. Two-digit years will be interpreted in range
-        1930-2029.
+        with year, month, and day.
 
         Raises :exc:`chrono.error.ParseError` for invalid input format,
         :exc:`TypeError` for invalid input type, and
     def date(cls, date):
         """
         Parses a US date (*mm/dd/yyyy*), and returns a tuple with year,
-        month, and day. Two-digit years will be interpreted in range
-        1930-2029.
+        month, and day.
 
         Raises :exc:`chrono.error.ParseError` for invalid input format,
         :exc:`TypeError` for invalid input type, and
     def dotdate(cls, date):
         """
         Parses a dot-separated US date (*mm.dd.yyyy*), and returns a tuple
-        with year, month, and day. Two-digit years will be interpreted in range
-        1930-2029.
+        with year, month, and day.
 
         Raises :exc:`chrono.error.ParseError` for invalid input format,
         :exc:`TypeError` for invalid input type, and
     def namedate(cls, date):
         """
         Parses a US date with short month name (*dd-mmm-yyyy*), and returns a
-        tuple with year, month, and day. Two-digit years will be interpreted in
-        range 1930-2029.
+        tuple with year, month, and day.
 
         Raises :exc:`chrono.error.ParseError` for invalid input format,
         :exc:`TypeError` for invalid input type, and
     def parse_datetime(cls, datetime):
         """
         Parses an ISO datetime in any supported format and returns a tuple
-        with year, month, day, hour, minute, and second. Omitted minutes
-        and/or seconds will be interpreted as 0.
+        with year, month, day, hour, minute, and second.
 
         Raises
         :exc:`chrono.error.ParseError` for invalid input format,
     def time(cls, time):
         """
         Parses a US time (*hh:mm:ss am/pm*), and returns a tuple with hour,
-        minute, and second, using 24-hour clock. Minutes and/or seconds may be
-        omitted, which will be interpreted as 0. Leading zeroes may be omitted.
+        minute, and second, using 24-hour clock.
 
         Raises :exc:`chrono.error.ParseError` for invalid input format,
         :exc:`TypeError` for invalid input type, and
 
     *parser* determines which parser to use for parsing times from strings.
     By default :class:`chrono.parser.CommonParser` is used, which supports the
-    most common time formats. See :mod:`chrono.parser` for available parsers.
+    most common time formats. See :mod:`chrono.parser` for a list of available
+    parsers.
     """
 
     hour = None

doc/source/formatter.rst

-:class:`chrono.formatter.Formatter` - date/time template formatting
-===================================================================
+:class:`chrono.formatter.Formatter` - Template formatting for dates and times
+=============================================================================
 
 .. autoclass:: chrono.formatter.Formatter
    :members:

doc/source/index.rst

 
 python-chrono is a Python module for simple and convenient date/time
 handling, including parsing, arithmetic, comparison, formatting,
-and calendar functionality.
+and calendar functionality. It supports both the ISO and US calendars,
+and dates/times in ISO, US, or european formats.
 
 The module is written by Erik Grinaker <erikg@codepoet.no>, and licensed
 under the `GNU General Public License version 3 <http://www.gnu.org/licenses/gpl.html>`_.
-The project website is located at:
 
-http://oss.codepoet.no/python-chrono/
+The project website is located at http://oss.codepoet.no/python-chrono/
 
 Contents:
 

doc/source/install.rst

 Installation
 ============
 
-It is preferrable to install python-chrono using your operating systems
-package manager, if possible.
+It is recommended to install python-chrono via your operating systems
+package manager, if possible. See your operating system documentation
+for details.
 
 Requirements
 ------------
 
 python-chrono only needs a recent version of Python installed. It has been
-tested on Python versions 2.6 and 3.1, but is believed to work on all
-versions from Python 2.3 and upwards.
+tested on Python versions 2.6 and 3.1, but is believed to work with version
+2.5 as well.
 
 Installing from source
 ----------------------

doc/source/parser/common.rst

-:class:`chrono.parser.CommonParser` - Common formats parser
-===========================================================
+:class:`chrono.parser.CommonParser` - Parser for most common formats
+====================================================================
 
 .. autoclass:: chrono.parser.CommonParser
    :members:

doc/source/parser/euro.rst

-:class:`chrono.parser.EuroParser` - European parser
-===================================================
+:class:`chrono.parser.EuroParser` - Parser for european formats
+===============================================================
 
 .. autoclass:: chrono.parser.EuroParser
    :members:

doc/source/parser/iso.rst

-:class:`chrono.parser.ISOParser` - ISO 8601 parser
-==================================================
+:class:`chrono.parser.ISOParser` - Parser for ISO 8601 formats
+==============================================================
 
 .. autoclass:: chrono.parser.ISOParser
    :members:

doc/source/parser/us.rst

-:class:`chrono.parser.USParser` - US parser
-===========================================
+:class:`chrono.parser.USParser` - Parser for US formats
+=======================================================
 
 .. autoclass:: chrono.parser.USParser
    :members:

doc/source/usage.rst

 respectively. A range of other classes are also available, which provide
 the functionaliy that these classes build upon.
 
-Currently, python-chrono uses the ISO 8601 date standard, which is
-widely used internationally (especially in west-Europe and east-Asia),
-with the notable exception of the United States. As such, it only accepts
-dates in ISO format (for example, *yyyy-mm-dd*), and calendar-related
-functionality is based on the ISO calendar - more on this later. Support
-for the US date standard is planned for a future release.
-
 python-chrono does not include any functionality for time zones or daylight
 savings time, but this is planned for a future release.
 
 classes behave in much the same way, but for simplicity only :class:`chrono.Date` is
 covered here.
 
-Date parsing
-------------
+Parsing
+-------
+
+Dates can be specified using either ISO, US, or european formats. Lists
+of valid formats are available in the :mod:`chrono.parser` documentation.
+
+By default, python-chrono uses the parser :class:`chrono.parser.CommonParser`,
+which accepts the most commonly used date formats. The notable exceptions
+are formats without separators (which for example can be interpreted as
+either US or european dates), and unusual separators such as . in US dates
+(which is the standard separator in Europe). In order to parse such formats,
+you need to pass the proper parser to :class:`chrono.Date`.
 
 Date parsing is done simply by instantiating a :class:`chrono.Date` object,
 passing the date string to be parsed as input. Once instantiated, the
    >>> date.get()
    (2009, 7, 23)
 
+The default :class:`chrono.parser.CommonParser` parser handles most normal
+date formats, such as::
+
+   >>> # ISO dates
+   >>> chrono.Date("2009-07-23").get()
+   (2009, 7, 23)
+
+   >>> # US dates
+   >>> chrono.Date("07/23/2009").get()
+   (2009, 7, 23)
+
+   >>> # european dates
+   >>> chrono.Date("23.07.2009").get()
+
+   >>> # ISO week dates
+   >>> chrono.Date("2009-W32").get()
+   (2009, 8, 3)
+
+   >>> # ISO ordinal dates
+   >>> chrono.Date("2009-314").get()
+   (2009, 11, 10)
+
+   >>> # ISO month dates
+   >>> chrono.Date("2009-07").get()
+   (2009, 7, 1)
+
+In order to parse all valid date formats for a region, you can pass the
+proper parser class to :class:`chrono.Date`::
+
+   >>> # US dates with two-digit year and no separator
+   >>> chrono.Date("072309", chrono.parser.USParser).get()
+   (2009, 7, 23)
+
+   >>> # slash-separated european dates
+   >>> chrono.Date("23/07/2009", chrono.parser.EuroParser).get()
+   (2009, 7, 23)
+
 If :class:`chrono.Date` is passed an invalid date it will raise either
 :exc:`chrono.error.ParseError` for invalid/unknown format, or a subclass
 of :exc:`chrono.error.DateError` (such as :exc:`chrono.error.MonthError`)
    >>> date = chrono.Date("2009-13-27")
    chrono.error.MonthError: Month '13' not in range 1-12
 
-All the date formats described in the ISO 8601 standard are supported,
-such as::
-
-   >>> # week dates
-   >>> chrono.Date("2009-W32").get()
-   (2009, 8, 3)
-
-   >>> # ordinal dates
-   >>> chrono.Date("2009-314").get()
-   (2009, 11, 10)
-
-   >>> # month dates
-   >>> chrono.Date("2009-07").get()
-   (2009, 7, 1)
-
 You can also pass a range of non-string inputs to the class, which will
 be handled according to the object type::
 
-   >>> # boolean True indicates the current time
+   >>> # boolean True indicates the current date
    >>> chrono.Date(True).get()
    (2010, 1, 23)
 
    >>> chrono.Date(datetime.date(2010, 7, 23)).get()
    (2010, 7, 23)
 
-For a complete list of valid formats, see the :class:`chrono.parser.ISOParser`
-documentation. For other input types, see the :class:`chrono.Date` documentation.
+For a complete list of all accepted input types, see the :class:`chrono.Date`
+documentation.
 
 To parse date strings without instantiating a :class:`chrono.Date` object, you
-can use the underlying :class:`chrono.parser.ISOParser` class directly::
+can use the parser classes directly::
 
-   >>> # parses all supported date formats
+   >>> # parses all supported ISO date formats
    >>> chrono.parser.ISOParser.parse_date("2009-07-23")
    (2009, 7, 23)
 
    >>> # only parses week dates
    >>> chrono.parser.ISOParser.week("2009-W32")
-   (2009, 32)
+   (2009, 8, 3)
 
    >>> # only parses ordinal dates
    >>> chrono.parser.ISOParser.ordinal("2009-314")
-   (2009, 314)
+   (2009, 11, 10)
 
-See the :class:`chrono.parser.ISOParser` documentation for more
-information.
+See the :mod:`chrono.parser` documentation for more information on parser
+classes.
 
-Date formatting
----------------
+Calendar info
+-------------
 
-Date formatting is done via the :meth:`chrono.Date.format` method, which
-takes a string containing substitution variables of the form ``$name`` or
-``${name}``, and replaces them with actual values::
+python-chrono supports both the ISO and US calendars, which have the
+following characteristics:
 
-   >>> # full human-readable date
-   >>> chrono.Date("2009-07-23").format("$weekdayname $day. $monthname $year")
-   'Thursday 23. July 2009'
-
-   >>> # ISO-date, using 0-padded values
-   >>> chrono.Date("2009-07-23").format("$0year-$0month-$0day")
-   '2009-07-23'
-
-For a full list of substitution variables, see the
-:class:`chrono.formatter.Formatter` documentation.
-
-Calendar information
---------------------
-
-python-chrono uses the ISO calendar, which has the following
-characteristics:
+**ISO Calendar:**
 
  * Weeks start on Monday
  * The first week of a year is the week which contains the first Thursday
 
-:class:`chrono.Date` has a number of methods for retreiving
-calendar-related information about the date - for example::
+**US Calendar:**
+
+ * Weeks start on Sunday
+ * The first week of a year is the week which contains January 1st
+
+By default, the ISO calendar is used. As can be seen above, this only
+affects functionality related to week numbers or week days.
+
+:class:`chrono.Date` has a number of methods for retreiving calendar-related
+information about about a date, such as::
 
    >>> # week that contains the date
    >>> chrono.Date("2009-07-23").week()
    >>> chrono.Date("2009-07-23").weekday()
    4
 
-For a full list of such methods, see the :class:`chrono.Date` documentation.
+To use the US calendar instead, pass the :class:`chrono.calendar.USCalendar`
+class to :class:`chrono.Date`::
+
+   >>> # US week containing date
+   >>> chrono.Date("2009-07-23", calendar=chrono.calendar.USCalendar).week()
+   (2009, 30)
+
+   >>> US weekday of the date
+   >>> chrono.Date("2009-07-23", calendar=chrono.calendar.USCalendar).weekday()
+   5
+
+For a full list of calendar-related methods, see the :class:`chrono.Date`
+documentation.
 
 If you would like to retreive calendar information without having to
 instantiate a :class:`chrono.Date` object, you can use the underlying
-:class:`chrono.calendar.ISOCalendar` class directly::
+calendar class directly::
 
    >>> chrono.calendar.ISOCalendar.yeardays(2008)
    366
    >>> chrono.calendar.ISOCalendar.weekdate(2009, 7, 23)
    (2009, 30, 4)
 
-See the :class:`chrono.calendar.ISOCalendar` documentation for more
+See the :mod:`chrono.calendar` documentation for more
 information.
 
-Date arithmetic
----------------
+Arithmetic
+----------
 
 Date arithmetic (addition, subtraction, etc) is done by special handling of
 the :attr:`chrono.Date.year`, :attr:`chrono.Date.month`, and :attr:`chrono.Date.day`
       >>> date.get()
       (2009, 3, 1)
 
-Date comparison
----------------
+Formatting
+----------
+
+Date formatting is done via the :meth:`chrono.Date.format` method, which
+takes a string containing substitution variables of the form ``$name`` or
+``${name}``, and replaces them with actual values::
+
+   >>> # full human-readable date
+   >>> chrono.Date("2009-07-23").format("$weekdayname $day. $monthname $year")
+   'Thursday 23. July 2009'
+
+   >>> # ISO-date, using 0-padded values
+   >>> chrono.Date("2009-07-23").format("$0year-$0month-$0day")
+   '2009-07-23'
+
+For a full list of substitution variables, see the
+:class:`chrono.formatter.Formatter` documentation.
+
+Comparison
+----------
 
 Date comparisons can be done using the normal Python comparison operators: ``==``,
 ``!=``, ``>``, and ``<``::
    >>> # datetime.date objects
    >>> chrono.Date("2009-07-31") < datetime.date(2009, 2, 17)
    True
-
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.