Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/scrapinghub/dateparser

python parser for human readable dates
https://github.com/scrapinghub/dateparser

hacktoberfest

Last synced: 4 days ago
JSON representation

python parser for human readable dates

Host: GitHub
URL: https://github.com/scrapinghub/dateparser
Owner: scrapinghub
License: bsd-3-clause
Created: 2014-11-24T17:30:12.000Z (about 10 years ago)
Default Branch: master
Last Pushed: 2024-10-23T17:57:16.000Z (about 2 months ago)
Last Synced: 2024-10-24T02:06:16.332Z (about 2 months ago)
Topics: hacktoberfest
Language: Python
Homepage:
Size: 5.4 MB
Stars: 2,550
Watchers: 137
Forks: 465
Open Issues: 336
Metadata Files:
- Readme: README.rst
- Changelog: HISTORY.rst
- Contributing: CONTRIBUTING.rst
- License: LICENSE
- Support: docs/supported_locales.rst
- Authors: AUTHORS.rst

Awesome Lists containing this project

best-of-python - GitHub - 46% open · ⏱️ 08.04.2024): (Date & Time Utilities)
awesome-github-star - dateparser
awesome-list - dateparser - Python parser for human readable dates. (Data Format & I/O / For Python)
starred-awesome - dateparser - python parser for human readable dates (Python)

README

        .. Note that we use raw HTML in the header section because centering images and paragraphs is not supported in Github (https://github.com/github/markup/issues/163)

.. raw:: html

    


        


        

            

        

        


    


    
Python parser for human readable dates

    


        

            

        

        

            

        

        

            

        

        

            

        

        

            

        

    


    


        Key Features •

        How To Use •

        Installation •

        Common use cases •

        You may also like... •

        License

    


Key Features

------------

-  Support for almost every existing date format: absolute dates,

   relative dates (``"two weeks ago"`` or ``"tomorrow"``), timestamps,

   etc.

-  Support for more than `200 language

   locales `__.

-  Language autodetection

-  Customizable behavior through

   `settings `__.

-  Support for `non-Gregorian calendar

   systems `__.

-  Support for dates with timezones abbreviations or UTC offsets

   (``"August 14, 2015 EST"``, ``"21 July 2013 10:15 pm +0500"``...)

-  `Search

   dates `__

   in longer texts.

Online demo

-----------

Do you want to try it out without installing any dependency? Now you can test

it quickly by visiting `this online demo `__!

How To Use

----------

The most straightforward way to parse dates with **dateparser** is to

use the ``dateparser.parse()`` function, that wraps around most of the

functionality of the module.

.. code:: python

    >>> import dateparser

    >>> dateparser.parse('Fri, 12 Dec 2014 10:55:50')

    datetime.datetime(2014, 12, 12, 10, 55, 50)

    >>> dateparser.parse('1991-05-17')

    datetime.datetime(1991, 5, 17, 0, 0)

    >>> dateparser.parse('In two months')  # today is 1st Aug 2020

    datetime.datetime(2020, 10, 1, 11, 12, 27, 764201)

    >>> dateparser.parse('1484823450')  # timestamp

    datetime.datetime(2017, 1, 19, 10, 57, 30)

    >>> dateparser.parse('January 12, 2012 10:00 PM EST')

    datetime.datetime(2012, 1, 12, 22, 0, tzinfo=)

As you can see, **dateparser** works with different date formats, but it

can also be used directly with strings in different languages:

.. code:: python

    >>> dateparser.parse('Martes 21 de Octubre de 2014')  # Spanish (Tuesday 21 October 2014)

    datetime.datetime(2014, 10, 21, 0, 0)

    >>> dateparser.parse('Le 11 Décembre 2014 à 09:00')  # French (11 December 2014 at 09:00)

    datetime.datetime(2014, 12, 11, 9, 0)

    >>> dateparser.parse('13 января 2015 г. в 13:34')  # Russian (13 January 2015 at 13:34)

    datetime.datetime(2015, 1, 13, 13, 34)

    >>> dateparser.parse('1 เดือนตุลาคม 2005, 1:00 AM')  # Thai (1 October 2005, 1:00 AM)

    datetime.datetime(2005, 10, 1, 1, 0)

    >>> dateparser.parse('yaklaşık 23 saat önce')  # Turkish (23 hours ago), current time: 12:46

    datetime.datetime(2019, 9, 7, 13, 46)

    >>> dateparser.parse('2小时前')  # Chinese (2 hours ago), current time: 22:30

    datetime.datetime(2018, 5, 31, 20, 30)

You can control multiple behaviors by using the ``settings`` parameter:

.. code:: python

    >>> dateparser.parse('2014-10-12', settings={'DATE_ORDER': 'YMD'})

    datetime.datetime(2014, 10, 12, 0, 0)

    >>> dateparser.parse('2014-10-12', settings={'DATE_ORDER': 'YDM'})

    datetime.datetime(2014, 12, 10, 0, 0)

    >>> dateparser.parse('1 year', settings={'PREFER_DATES_FROM': 'future'})  # Today is 2020-09-23

    datetime.datetime(2021, 9, 23, 0, 0)

    >>> dateparser.parse('tomorrow', settings={'RELATIVE_BASE': datetime.datetime(1992, 1, 1)})

    datetime.datetime(1992, 1, 2, 0, 0)

To see more examples on how to use the ``settings``, check the `settings

section `__

in the docs.

False positives

^^^^^^^^^^^^^^^

**dateparser** will do its best to return a date, dealing with multiple formats and different locales.

For that reason it is important that the input is a valid date, otherwise it could return false positives.

To reduce the possibility of receiving false positives, make sure that:

- The input string is a valid date and doesn't contain any other words or numbers.

- If you know the language or languages beforehand, you add them through the ``languages`` or ``locales`` properties.

On the other hand, if you want to exclude any of the default parsers

(``timestamp``, ``relative-time``...) or change the order in which they

are executed, you can do so through the

`settings PARSERS `_.

Installation

------------

Dateparser supports Python >= 3.9. You can install it by doing:

::

    $ pip install dateparser

If you want to use the jalali or hijri calendar, you need to install the

``calendars`` extra:

::

    $ pip install dateparser[calendars]

Common use cases

----------------

**dateparser** can be used for a wide variety of purposes,

but it stands out when it comes to:

Consuming data from different sources:

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

-  **Scraping**: extract dates from different places with several

   different formats and languages

-  **IoT**: consuming data coming from different sources with different

   date formats

-  **Tooling**: consuming dates from different logs / sources

-  **Format transformations**: when transforming dates coming from

   different files (PDF, CSV, etc.) to other formats (database, etc).

Offering natural interaction with users:

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

-  **Tooling and CLI**: allow users to write “3 days ago” to retrieve

   information.

-  **Search engine**: allow people to search by date in an easy /

   natural format.

-  **Bots**: allow users to interact with a bot easily

You may also like...

--------------------

-  `price-parser `__ - A

   small library for extracting price and currency from raw text

   strings.

-  `number-parser `__ -

   Library to convert numbers written in the natural language to it's

   equivalent numeric forms.

-  `Scrapy `__ - Web crawling and web

   scraping framework

License

-------

`BSD3-Clause `__