Contributing

Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.

You can contribute in many ways:

Types of Contributions

Report Bugs

Report bugs at https://github.com/scrapinghub/dateparser/issues.

If you are reporting a bug, please include:

Your operating system name and version.
Any details about your local setup that might be helpful in troubleshooting.
Detailed steps to reproduce the bug.

Fix Bugs and Implement Features

Look through the GitHub issues for bugs and feature requests. To avoid duplicate efforts, try to choose issues without related PRs or with staled PRs. We also encourage you to add new languages to the existing stack.

Write Documentation

Dateparser could always use more documentation, whether as part of the official Dateparser docs, in docstrings, or even on the web in blog posts, articles, and such.

After you make local changes to the documentation, you will be able to build the project running:

tox -e docs

Then open .tox/docs/tmp/html/index.html in a web browser to see your local build of the documentation.

Note

If you don’t have tox installed, you need to install it first using pip install tox.

Submit Feedback

The best way to send feedback is to file an issue at https://github.com/scrapinghub/dateparser/issues.

If you are proposing a feature:

Explain in detail how it would work.
Keep the scope as narrow as possible, to make it easier to implement.
Remember that contributions are welcome :)

Get Started!

Ready to contribute? Here’s how to set up dateparser for local development.

Fork the dateparser repo on GitHub.

Clone your fork locally:

$ git clone git@github.com:your_name_here/dateparser.git

3. Install your local copy into a virtualenv. Assuming you have virtualenvwrapper installed, this is how you set up your fork for local development:

$ mkvirtualenv dateparser
$ cd dateparser/
$ pip install -e . pytest parameterized tox

Create a branch for local development:
```
$ git checkout -b name-of-your-bugfix-or-feature
```
Now you can make your changes locally.
Run the tests and the ruff linting and formatting hooks:
```
$ pytest
$ tox -e pre-commit
```
Bare pytest runs the tests/ directory. Optional calendar and language detection tests require pip install -e '.[calendars,langdetect]'. The suite turns warnings into errors (filterwarnings in pytest.ini), so a new deprecation warning fails the run: use pytest -W default to see such a warning without failing, fix it when it comes from dateparser itself, and otherwise add a narrowly scoped ignore: line to pytest.ini. The ruff formatter uses its default line length of 88; the linter does not enforce a maximum line length.

Use tox to run the full environment list, including the supported Python versions, documentation, scripts, packaging checks, and benchmarks. These environments require their configured Python interpreters to be installed. To run just the packaging check, use tox -e twinecheck.

Commit your changes and push your branch to GitHub:

$ git add .
$ git commit -m "Your detailed description of your changes."
$ git push origin name-of-your-bugfix-or-feature

Submit a pull request through the GitHub website.

Pull Request Guidelines

Before you submit a pull request, check that it meets these guidelines:

The pull request should include tests.
If the pull request adds functionality, the docs should be updated. Put your new functionality into a function with a docstring, and add the feature to the list in README.rst.
Check the pipelines (Github Actions) in the PR comments (or in https://github.com/scrapinghub/dateparser/actions) and make sure that the tests pass for all supported Python versions.
Check the new project coverage in the PR comments (or in https://app.codecov.io/gh/scrapinghub/dateparser/pulls) and make sure that it remained equal or higher than previously.
Follow the core developers’ advice which aims to ensure code’s consistency regardless of the variety of approaches used by many contributors.
In case you are unable to continue working on a PR, please leave a short comment to notify us. We will be pleased to make any changes required to get it done.

Guidelines for Editing Translation Data

English is the primary language of Dateparser. Dates in all other languages are translated into English equivalents before they are parsed.

The language data that Dateparser uses to parse dates is in dateparser/data/date_translation_data. For each supported language, there is a Python file containing translation data.

Each translation data Python files contains different kinds of translation data for date parsing: month and week names - and their abbreviations, prepositions, conjunctions, frequently used descriptive words and phrases (like “today”), etc.

Translation data Python files are generated from the following sources:

Unicode CLDR data in JSON format, located at dateparser_data/cldr_language_data/date_translation_data
Additional data from the Dateparser community in YAML format, located at dateparser_data/supplementary_language_data/date_translation_data

If you wish to extend the data of an existing language, or add data for a new language, you must:

Edit or create the corresponding file within dateparser_data/supplementary_language_data/date_translation_data

See existing files to learn how they are defined, and see Language Data Template for details.
Regenerate the corresponding file within dateparser/data/date_translation_data after installing the script dependencies:
```
pip install -r dateparser_scripts/requirements.txt
python -m dateparser_scripts.write_complete_data
```
Write tests that cover your changes

You should be able to find tests that cover the affected data, and use copy-and-paste to create the corresponding new test.

If in doubt, ask Dateparser maintainers for help.

Updating the List of Supported Languages and Locales

Whenever the content of dateparser.data.languages_info.language_locale_dict is modified, use dateparser_scripts/update_supported_languages_and_locales.py to update the corresponding documentation table:

dateparser_scripts/update_supported_languages_and_locales.py

Updating Timezone Abbreviations

dateparser/timezones.py maps each timezone abbreviation to a single UTC offset. Unrelated zones often share the same letters, so to check that those offsets still match the tz database, run:

python -m dateparser_scripts.tz_abbreviation_conflicts

It reports every abbreviation whose offset no tz database zone uses, and exits non-zero when it finds any. tests/test_timezone_parser.py runs the same check, so a clean test run means the table is in sync.

Abbreviations the tz database resolves to several offsets, such as CST, are left alone: there is no single answer to prefer, so dateparser keeps its long-standing choice.

When refreshing the table, slide REFERENCE_YEARS forward rather than widening it. Reaching further back re-admits abbreviations the tz database has since dropped and reports them as current.

Evaluating against real-world dates

dateparser_scripts/article_dates.py runs dateparser on the 300k article publication dates from #928, which it downloads to ~/.cache/dateparser/ on first use, and reports how often each of these checks fails, per language and grouped by format:

python -m dateparser_scripts.article_dates --sample 5000

error: Parsing raised an exception.
unparsed: dateparser.parse() returned None.
searchable: dateparser.parse() returned None, but dateparser.search.search_dates() finds a date.
future: The date is after March 2021, when the dataset was collected.
hint-dependent: Passing the language of the article in languages changes the date.
misdetected: The text parses in the language of the article, but a different one was detected.

The dataset has no expected dates, so these checks point at likely bugs rather than prove them. To see how a change affects real-world input, run the script with --output before and after the change, and compare both files with diff. The full dataset takes about 40 minutes on 8 cores.