# Usage

The main classes are :class:chrono.Date, :class:chrono.Time, and :class:chrono.DateTime, which handles dates, times, and date/times respectively. A range of other classes are also available, which provide the functionality that these classes build upon.

python-chrono does not include any handling of time zones or daylight savings time, but this is planned for a future release.

The following sections describe some typical usage of the :class:chrono.Date class. The :class:chrono.Time and :class:chrono.DateTime classes behave in much the same way, but for simplicity only :class:chrono.Date is covered here.

## 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 set in :attr:chrono.DEFAULT_PARSER - normally :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 either set another default in :attr:chrono.DEFAULT_PARSER, or 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 attributes :attr:chrono.Date.year, :attr:chrono.Date.month, and :attr:chrono.Date.day will contain the respective date parts:

To retrieve all the attributes at once, use :meth:chrono.Date.get:

The default :class:chrono.parser.CommonParser parser handles most normal date formats, such as:

In order to parse all valid date formats for a region, you can pass the proper parser class to :class:chrono.Date:

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) if the date was parsed properly but contained an invalid date value:

You can also pass a range of non-string inputs to the class, which will be handled according to the object type:

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 parser classes directly:

See the :mod:chrono.parser documentation for more information on parser classes.

## Calendar info

python-chrono supports both the ISO and US calendars, which have the following characteristics:

ISO Calendar:

• Weeks start on Monday
• The first week of a year is the week which contains the first Thursday

US Calendar:

• Weeks start on Sunday
• The first week of a year is the week which contains January 1st

By default the calendar set in :attr:chrono.DEFAULT_CALENDAR is used, normally :class:chrono.calendar.ISOCalendar. To use another calendar, either set it as the default in :attr:chrono.DEFAULT_CALENDAR, or pass the proper calendar to :class:chrono.Date. 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:

To use the US calendar instead, pass the :class:chrono.calendar.USCalendar class to :class:chrono.Date:

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 calendar class directly:

See the :mod:chrono.calendar documentation for more information.

## 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 attributes. If any of these are set to a value that is outside their valid range, the object will automatically update the attributes to a proper date, by incrementing or decrementing values as necessary.

Here are some examples:

Warning

When the date is on one of the last days of a month, and the :attr:chrono.Date.month or :attr:chrono.Date.year attribute is changed, you may get a result which is in a different month than the one you expect. This happens when the day number is out of range for the new month, due to differences in month lengths:

When :attr:chrono.Date.month is set to 6, the date will become 2009-06-31. Since June only has 30 days this will trigger the overflow-handling that the date arithmetic relies on, and update the date to a valid date. The same happens with leap years:

## 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:

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 <:

If the value that is being compared with is not a :class:chrono.Date object, it will be converted to one if possible. This allows for comparisons with strings, UNIX timestamps, :class:time.struct_time or :class:datetime.date objects, and any other value that :class:chrono.Date is able to process:

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.