document settings (#722)

* document settings

* remove deprecated

* fix typo in

* improve docs

* add mention to SettingValidationError

* improve some other docs

* fix flake8 issue

Co-authored-by: marc <Marc>

Author: noviluni

dateparser/__init__.py

@@ -27,7 +27,7 @@ def parse(date_string, date_formats=None, languages=None, locales=None, region=N
 
     :param locales:
         A list of locale codes, e.g. ['fr-PF', 'qu-EC', 'af-NA'].
-        The parser uses locales to translate date string.
+        The parser uses only these locales to translate date string.
     :type locales: list
 
     :param region:
@@ -41,7 +41,9 @@ def parse(date_string, date_formats=None, languages=None, locales=None, region=N
 
     :return: Returns :class:`datetime <datetime.datetime>` representing parsed date if successful, else returns None
     :rtype: :class:`datetime <datetime.datetime>`.
-    :raises: ValueError - Unknown Language
+    :raises:
+        ``ValueError``: Unknown Language, ``TypeError``: Languages argument must be a list,
+        ``SettingValidationError``: A provided setting is not valid.
     """
     parser = _default_parser
 

dateparser/conf.py

@@ -11,17 +11,20 @@ class Settings:
     """Control and configure default parsing behavior of dateparser.
     Currently, supported settings are:
 
-    * `PREFER_DATES_FROM`: defaults to `current_period`. Options are `future` or `past`.
-    * `PREFER_DAY_OF_MONTH`: defaults to `current`. Could be `first` and `last` day of month.
-    * `SKIP_TOKENS`: defaults to `['t']`. Can be any string.
-    * `TIMEZONE`: defaults to `UTC`. Can be timezone abbreviation or any of
-      `tz database name as given here <https://en.wikipedia.org/wiki/List_of_tz_database_time_zones>`_.
-    * `RETURN_AS_TIMEZONE_AWARE`: return tz aware datetime objects in case timezone is detected in the date string.
-    * `RELATIVE_BASE`: count relative date from this base date. Should be datetime object.
-    * `RETURN_TIME_AS_PERIOD`: returns period as `time` in case time component is detected in the date string.
-    Default: False.
-    * `PARSERS`: list of date parsers to use, in order of preference. Default:
-    :attr:`dateparser.settings.default_parsers`.
+    * `DATE_ORDER`
+    * `PREFER_LOCALE_DATE_ORDER`
+    * `TIMEZONE`
+    * `TO_TIMEZONE`
+    * `RETURN_AS_TIMEZONE_AWARE`
+    * `PREFER_DAY_OF_MONTH`
+    * `PREFER_DATES_FROM`
+    * `RELATIVE_BASE`
+    * `STRICT_PARSING`
+    * `REQUIRE_PARTS`
+    * `SKIP_TOKENS`
+    * `NORMALIZE`
+    * `RETURN_TIME_AS_PERIOD`
+    * `PARSERS`
     """
 
     _default = True

dateparser/date.py

@@ -268,7 +268,7 @@ class DateDataParser:
 
     :param locales:
         A list of locale codes, e.g. ['fr-PF', 'qu-EC', 'af-NA'].
-        The parser uses locales to translate date string.
+        The parser uses only these locales to translate date string.
     :type locales: list
 
     :param region:
@@ -293,7 +293,8 @@ class DateDataParser:
     :return: A parser instance
 
     :raises:
-        ValueError - Unknown Language, TypeError - Languages argument must be a list
+         ``ValueError``: Unknown Language, ``TypeError``: Languages argument must be a list,
+         ``SettingValidationError``: A provided setting is not valid.
     """
 
     locale_loader = None

dateparser_data/settings.py

@@ -6,18 +6,27 @@
 ]
 
 settings = {
-    'PREFER_DATES_FROM': 'current_period',
-    'PREFER_DAY_OF_MONTH': 'current',
-    'SKIP_TOKENS': ["t"],
+    # Date order
+    'DATE_ORDER': 'MDY',
+    'PREFER_LOCALE_DATE_ORDER': True,
+
+    # Timezone related
     'TIMEZONE': 'local',
     'TO_TIMEZONE': False,
     'RETURN_AS_TIMEZONE_AWARE': 'default',
-    'NORMALIZE': True,
+
+    # Incomplete dates
+    'PREFER_DAY_OF_MONTH': 'current',
+    'PREFER_DATES_FROM': 'current_period',
     'RELATIVE_BASE': False,
-    'DATE_ORDER': 'MDY',
-    'PREFER_LOCALE_DATE_ORDER': True,
     'STRICT_PARSING': False,
+    'REQUIRE_PARTS': [],
+
+    # Language detection
+    'SKIP_TOKENS': ['t'],
+    'NORMALIZE': True,
+
+    # Other settings
     'RETURN_TIME_AS_PERIOD': False,
     'PARSERS': default_parsers,
-    'REQUIRE_PARTS': [],
 }

docs/conf.rst

@@ -48,6 +48,7 @@ Contents:
    introduction
    installation
    usage
+   settings
    supported_locales
    contributing
    authors

docs/index.rst

@@ -74,8 +74,7 @@ Relative Dates
 
 .. note:: Testing above code might return different values for you depending on your environment's current date and time.
 
-.. note:: Support for relative dates in future needs a lot of improvement, we look forward to community's contribution to get better on that part. See ":ref:`contributing`".
-
+.. note:: For `Finnish` language, please specify ``settings={'SKIP_TOKENS': []}`` to correctly parse relative dates.
 
 OOTB Language Based Date Order Preference
 -----------------------------------------
@@ -86,13 +85,12 @@ OOTB Language Based Date Order Preference
    >>> parse('le 02-03-2016')  # detects french, uses DMY date order
    datetime.datetime(2016, 3, 2, 0, 0)
 
-.. note:: Ordering is not locale based, that's why do not expect `DMY` order for UK/Australia English. You can specify date order in that case as follows using `settings`:
+.. note:: Ordering is not locale based, that's why do not expect `DMY` order for UK/Australia English. You can specify date order in that case as follows using :ref:`settings`:
 
     >>> parse('18-12-15 06:00', settings={'DATE_ORDER': 'DMY'})
     datetime.datetime(2015, 12, 18, 6, 0)
 
-For more on date order, please look at Settings.
-
+For more on date order, please look at :ref:`settings`.
 
 
 Timezone and UTC Offset
@@ -120,8 +118,8 @@ By default, `dateparser` returns tzaware `datetime` if timezone is present in da
     >>> parse('January 12, 2012 10:00 PM', settings={'TIMEZONE': '+0500'})
     datetime.datetime(2012, 1, 12, 22, 0)
 
-`TIMEZONE` option may not be useful alone as it only attaches given timezone to
-resultant `datetime` object. But can be useful in cases where you want conversions from and to different
+``TIMEZONE`` option may not be useful alone as it only attaches given timezone to
+resultant ``datetime`` object. But can be useful in cases where you want conversions from and to different
 timezones or when simply want a tzaware date with given timezone info attached.
 
     >>> parse('January 12, 2012 10:00 PM', settings={'TIMEZONE': 'US/Eastern', 'RETURN_AS_TIMEZONE_AWARE': True})
@@ -139,8 +137,8 @@ Some more use cases for conversion of timezones.
     >>> parse('now EST', settings={'TO_TIMEZONE': 'UTC'})  # relative dates
     datetime.datetime(2017, 3, 10, 23, 24, 47, 371823, tzinfo=<StaticTzInfo 'UTC'>)
 
-In case, no timezone is present in date string or defined in `settings`. You can still
-return tzaware `datetime`. It is especially useful in case of relative dates when uncertain
+In case, no timezone is present in date string or defined in :ref:`settings`. You can still
+return tzaware ``datetime``. It is especially useful in case of relative dates when uncertain
 what timezone is relative base.
 
     >>> parse('2 minutes ago', settings={'RETURN_AS_TIMEZONE_AWARE': True})
@@ -151,15 +149,15 @@ In case, you want to compute relative dates in UTC instead of default system's l
     >>> parse('4 minutes ago', settings={'TIMEZONE': 'UTC'})
     datetime.datetime(2017, 3, 10, 23, 27, 59, 647248, tzinfo=<StaticTzInfo 'UTC'>)
 
-.. note:: In case, when timezone is present both in string and also specified using `settings`, string is parsed into tzaware representation and then converted to timezone specified in `settings`.
+.. note:: In case, when timezone is present both in string and also specified using :ref:`settings`, string is parsed into tzaware representation and then converted to timezone specified in :ref:`settings`.
 
    >>> parse('10:40 pm PKT', settings={'TIMEZONE': 'UTC'})
    datetime.datetime(2017, 3, 12, 17, 40, tzinfo=<StaticTzInfo 'UTC'>)
 
    >>> parse('20 mins ago EST', settings={'TIMEZONE': 'UTC'})
    datetime.datetime(2017, 3, 12, 21, 16, 0, 885091, tzinfo=<StaticTzInfo 'UTC'>)
 
-For more on timezones, please look at Settings.
+For more on timezones, please look at :ref:`settings`.
 
 
 Incomplete Dates
@@ -186,17 +184,27 @@ You can also ignore parsing incomplete dates altogether by setting `STRICT_PARSI
     >>> parse('December 2015', settings={'STRICT_PARSING': True})
     None
 
-For more on handling incomplete dates, please look at Settings.
+For more on handling incomplete dates, please look at :ref:`settings`.
 
 
 Search for Dates in Longer Chunks of Text
 -----------------------------------------
 
+.. warning:: Support for searching dates is really limited and needs a lot of improvement, we look forward to community's contribution to get better on that part. See ":ref:`contributing`".
+
+
 You can extract dates from longer strings of text. They are returned as list of tuples with text chunk containing the date and parsed datetime object.
 
+
 .. automodule:: dateparser.search
    :members: search_dates
 
+
+Advanced Usage
+==============
+If you need more control over what is being parser check the :ref:`settings` section as well as the :ref:`using-datedataparser` section.
+
+
 Dependencies
 ============
 
@@ -221,26 +229,25 @@ You can check the supported locales by visiting the ":ref:`supported-locales`" s
 
 Supported Calendars
 ===================
-* Gregorian calendar.
 
-* Persian Jalali calendar. For more information, refer to `Persian Jalali Calendar <https://en.wikipedia.org/wiki/Iranian_calendars#Zoroastrian_calendar>`_.
+Apart from the Georgian calendar, `dateparser` supports the `Persian Jalali calendar` and the `Hijri/Islami calendar`
+
+To be able to use them you need to install the `calendar` extra by typing:
+
+    pip install dateparser[calendars]
+
+
+* Example using the `Persian Jalali calendar`. For more information, refer to `Persian Jalali Calendar <https://en.wikipedia.org/wiki/Iranian_calendars#Zoroastrian_calendar>`_.
 
     >>> from dateparser.calendars.jalali import JalaliCalendar
     >>> JalaliCalendar('جمعه سی ام اسفند ۱۳۸۷').get_date()
     {'date_obj': datetime.datetime(2009, 3, 20, 0, 0), 'period': 'day'}
 
 
-* Hijri/Islamic Calendar. For more information, refer to `Hijri Calendar <https://en.wikipedia.org/wiki/Islamic_calendar>`_.
+* Example using the `Hijri/Islamic Calendar`. For more information, refer to `Hijri Calendar <https://en.wikipedia.org/wiki/Islamic_calendar>`_.
 
     >>> from dateparser.calendars.hijri import HijriCalendar
     >>> HijriCalendar('17-01-1437 هـ 08:30 مساءً').get_date()
     {'date_obj': datetime.datetime(2015, 10, 30, 20, 30), 'period': 'day'}
 
 .. note:: `HijriCalendar` only works with Python ≥ 3.6.
-.. note:: For `Finnish` language, please specify `settings={'SKIP_TOKENS': []}` to correctly parse freshness dates.
-
-
-Install using following command to use calendars.
-
-.. tip::
-   pip install dateparser[calendars]