__version__ = "1.4.3"
from collections.abc import Callable, Iterable
from datetime import datetime
from typing import Any
from ._parts_of_day import PartOfDay as PartOfDay
from ._parts_of_day import PartsOfDay as PartsOfDay
from .conf import Settings, apply_settings
from .date import DateDataParser as DateDataParser
_default_parser = DateDataParser()
[docs]
@apply_settings
def parse(
date_string: str,
date_formats: Iterable[str] | None = None,
languages: Iterable[str] | None = None,
locales: Iterable[str] | None = None,
region: str | None = None,
settings: Settings | dict[str, Any] | None = None,
detect_languages_function: Callable[..., list[str]] | None = None,
) -> datetime | None:
"""Parse date and time from given date string.
:param date_string:
A string representing date and/or time in a recognizably valid format.
:type date_string: str
:param date_formats:
A list of format strings using directives as given
`here <https://docs.python.org/2/library/datetime.html#strftime-and-strptime-behavior>`_.
The parser applies formats one by one, taking into account the detected
languages/locales. A UTC offset matched by ``%z`` is kept, while a time
zone name matched by ``%Z`` is ignored. If no format matches, the other
parsers of the :ref:`PARSERS <settings>` setting are tried; set it to
``['custom-formats']`` to use only these formats.
:type date_formats: list
:param languages:
A list of language codes, e.g. ['en', 'es', 'zh-Hant'].
If locales are not given, languages and region are used to construct locales for translation.
:type languages: list
:param locales:
A list of locale codes, e.g. ['fr-PF', 'qu-EC', 'af-NA'].
The parser uses only these locales to translate date string.
:type locales: list
:param region:
A region code, e.g. 'IN', '001', 'NE'.
If locales are not given, languages and region are used to construct locales for translation.
:type region: str
:param settings:
Configure customized behavior using settings defined in :mod:`dateparser.conf.Settings`.
:type settings: dict
:param detect_languages_function:
A function for language detection that takes as input a string (the `date_string`) and
a `confidence_threshold`, and returns a list of detected language codes.
Note: this function is only used if ``languages`` and ``locales`` are not provided.
:type detect_languages_function: function
:return: Returns :class:`datetime <datetime.datetime>` representing parsed date if successful, else returns None
:rtype: :class:`datetime <datetime.datetime>`.
:raises:
``ValueError``: Unknown Language, ``TypeError``: Languages argument must be a list,
``SettingValidationError``: A provided setting is not valid.
"""
assert isinstance(settings, Settings)
parser = _default_parser
if (
languages
or locales
or region
or detect_languages_function
or not settings._default
):
parser = DateDataParser(
languages=languages,
locales=locales,
region=region,
settings=settings,
detect_languages_function=detect_languages_function,
)
data = parser.get_date_data(date_string, date_formats)
date_obj: datetime | None = data["date_obj"]
return date_obj