Parse human-readable date/time strings
Python Makefile
Latest commit 5670a7d Mar 10, 2017 @bear bump version to 2.4
Failed to load latest commit information.
.autocode Initialize Autocode Dec 8, 2015
examples Now it works for Python 3.4.1 Jul 11, 2014
notes move THANKS to notes directory Nov 5, 2015
parsedatetime bump version to 2.4 Mar 10, 2017
tests fix delta test by using a static source time, issue #215 Mar 10, 2017
.coveragerc Uses `codecov` to generate coverage report Oct 19, 2015
.editorconfig missing newline character at end of file Sep 25, 2015
.gitignore add pyenv local file Jul 13, 2016
AUTHORS.txt add latest contributors Sep 21, 2015
CHANGES.txt bump version to 2.4 Mar 10, 2017
LICENSE.txt Initial copy of the Parsedatetime SVN trunk over to GIT Sep 12, 2012 update manifest, clean up and move historical text files Oct 20, 2015
Makefile move pyenv installs to the Makefile Aug 1, 2016
README.rst Tiny grammar and punctuation changes. Jan 9, 2017
circle.yml move pyenv installs to the Makefile Aug 1, 2016
epydoc.conf release prep work and cleanup Jul 11, 2014
pytest.ini update and test environment to py.test; minor lint fixes; ad… Mar 18, 2016
requirements.testing.txt use tox-pyenv to have better control over test environment in both lo… Aug 1, 2016
requirements.txt ok, added requirements.txt back and I promise to stop pushing to master Oct 20, 2015
setup.cfg update and test environment to py.test; minor lint fixes; ad… Mar 18, 2016 update and test environment to py.test; minor lint fixes; ad… Mar 18, 2016
tox.ini Add import exception for unittest2 when run under Python 2.6 Jul 30, 2016



Parse human-readable date/time strings.

Python 2.6 or greater is required for parsedatetime version 1.0 or greater.

While we still test with Python 2.6 we cannot guarantee that future changes will not break under 2.6

Downloads Travis CI Codecov Requirements Status Dependency Status


You can install parsedatetime using:

pip install parsedatetime

Running Tests

From the source directory:

make test

To run tests on several python versions, type make tox:

$ make tox
[... tox creates a virtualenv for every python version and runs tests inside of each]
py27: commands succeeded
py35: commands succeeded

This assumes that you have the versions you want to test under installed as part of your PyEnv environment:

pyenv install -s 2.6.9
pyenv install -s 2.7.11
pyenv install -s 3.5.2
pyenv install -s pypy-5.3
pyenv global 2.7.11 3.5.2 2.6.9 pypy-5.3

The tests depend on PyICU being installed. PyICU depends on icu4c which on OS X requires homebrew:

brew install icu4c

and then will require that you pass in the LDFLAGS and CPPFLAGS that homebrew will display after the install:

LDFLAGS:  -L/usr/local/opt/icu4c/lib
CPPFLAGS: -I/usr/local/opt/icu4c/include

The Makefile contains the OS X default values for them so you may need to tweak them.

Using parsedatetime

An example of how to use parsedatetime:

import parsedatetime

cal = parsedatetime.Calendar()


To get it to a Python datetime object:

from datetime import datetime

time_struct, parse_status = cal.parse("tomorrow")

Parse datetime with timezone support (using pytz package):

import parsedatetime
import pytz
from pytz import timezone

cal = parsedatetime.Calendar()

datetime_obj, _ = cal.parseDT(datetimeString="tomorrow", tzinfo=timezone("US/Pacific"))

More detailed examples can be found in the examples directory.


The generated documentation is included by default in the docs directory and can also be viewed online at

The docs can be generated by running:

make docs


The Calendar class has a member property named ptc which is created during the class init method to be an instance of parsedatetime_consts.CalendarConstants().


The code in parsedatetime has been implemented over the years in many different languages (C, Clipper, Delphi) as part of different custom/proprietary systems I've worked on. Sadly the previous code is not "open" in any sense of that word.

When I went to work for Open Source Applications Foundation and realized that the Chandler project could benefit from my experience with parsing of date/time text I decided to start from scratch and implement the code using Python and make it truly open.

After working on the initial concept and creating something that could be shown to the Chandler folks, the code has now evolved to its current state with the help of the Chandler folks, most especially Darshana.