WIP: v1.0.0: Dev to main Merge

.github/workflows/python-tests.yml

@@ -15,8 +15,9 @@ jobs:
   build:
     runs-on: ubuntu-latest
     strategy:
+      fail-fast: false
       matrix:
-        python-version: ["3.7", "3.8", "3.9", "3.10"]
+        python-version: ["3.7", "3.8", "3.9", "3.10", "3.11"]
 
     steps:
     - uses: actions/checkout@v2

.gitignore

@@ -134,6 +134,3 @@ dmypy.json
 
 # Pyre type checker
 .pyre/
-
-/.idea
-.idea/

README.md

@@ -29,17 +29,27 @@ Below you can find some examples of how datetimeparser can be used.
 ```python
 from datetimeparser import parse
 
-print(parse("next 3 years and 2 months"))
-# 2025-04-06 11:43:28
+print(parse("next 3 years and 2 months").time)
+# 2025-12-28 11:57:25
 
-print(parse("begin of advent of code 2022"))
+print(parse("begin of advent of code 2022").time)
 # 2022-12-01 06:00:00
 
-print(parse("in 1 Year 2 months 3 weeks 4 days 5 hours 6 minutes 7 seconds"))
-# 2023-05-01 17:59:52
+print(parse("in 1 Year 2 months 3 weeks 4 days 5 hours 6 minutes 7 seconds").time)
+# 2024-01-22 17:04:26
 
-print(parse("10 days and 2 hours after 3 months before christmas 2020"))
+print(parse("10 days and 2 hours after 3 months before christmas 2020").time)
 # 2020-10-05 02:00:00
+
+print(parse("sunrise"))
+# <Result: time='2022-10-28 08:15:19', timezone='Europe/Berlin', coordinates=[longitude='7.188402', latitude='50.652927999999996]'>
+
+print(parse("sunrise", timezone="Asia/Dubai"))
+# <Result: time='2022-10-28 06:23:17', timezone='Asia/Dubai', coordinates=[longitude='55.455098', latitude='25.269651999999997]'>
+
+# https://www.timeanddate.com/sun/japan/tokyo states that the sunset today (2022-10-28) is at '16:50' in Tokyo
+print(parse("sunset", coordinates=(139.839478, 	35.652832)))  # (Tokyo in Japan)
+# <Result: time='2022-10-28 16:50:04', timezone='Asia/Tokyo', coordinates=[longitude='139.839478', latitude='35.652832]'>
 ```
 
 ## Installation
@@ -115,6 +125,18 @@ We highly appreciate everyone who wants to help our project!
 <li>valentine day</li>
 </ul>
 </details><details>
+<summary><code>pi day</code></summary>
+<ul>
+<li>piday</li>
+<li>pi-day</li>
+</ul>
+</details><details>
+<summary><code>tau day</code></summary>
+<ul>
+<li>tauday</li>
+<li>tau-day</li>
+</ul>
+</details><details>
 <summary><code>summer end</code></summary>
 <ul>
 <li>end of summer</li>

datetimeparser/__init__.py

@@ -1,7 +1,6 @@
 from datetimeparser import parser
 from datetimeparser import evaluator
-from datetimeparser import enums
-from datetimeparser import baseclasses
-from datetimeparser import parsermethods
+from datetimeparser.utils import baseclasses, enums
+from datetimeparser.parser import parsermethods
 
 from datetimeparser.datetimeparser import parse

datetimeparser/datetimeparser.py

@@ -2,34 +2,42 @@
 Main module which provides the parse function.
 """
 
-__all__ = ['parse', '__version__', '__author__']
-__version__ = "0.12.2"
+__all__ = ['parse', 'Result', '__version__', '__author__']
+__version__ = "1.0.0"
 __author__ = "aridevelopment"
 
-import datetime
-from typing import Union
+from typing import Optional, Tuple
 
 from datetimeparser.evaluator import Evaluator
 from datetimeparser.parser import Parser
+from datetimeparser.utils.models import Result
 
 
-def parse(datetime_string: str, timezone: str = "Europe/Berlin") -> Union[datetime.datetime, None]:
+def parse(
+        datetime_string: str,
+        timezone: str = "Europe/Berlin",
+        coordinates: Optional[Tuple[float, float]] = None
+) -> Optional[Result]:
     """
     Parses a datetime string and returns a datetime object.
     If the datetime string cannot be parsed, None is returned.
 
     :param datetime_string: The datetime string to parse.
     :param timezone: The timezone to use. Should be a valid timezone for pytz.timezone(). Default: Europe/Berlin
-    :return: A datetime object or None
+    :param coordinates: A tuple containing longitude and latitude. If coordinates are given, the timezone will be calculated,
+        independently of the given timezone param.
+        NOTE: It can take some seconds until a result is returned
+    :return: A result object containing the returned time, the timezone and optional coordinates.
+             If the process fails, None will be returned
     """
     parser_result = Parser(datetime_string).parse()
 
     if parser_result is None:
         return None
 
-    evaluator_result = Evaluator(parser_result, tz=timezone).evaluate()
+    evaluator_result, tz, coordinates = Evaluator(parser_result, tz=timezone, coordinates=coordinates).evaluate()
 
     if evaluator_result is None:
         return None
 
-    return evaluator_result
+    return Result(evaluator_result, tz, coordinates)

datetimeparser/evaluator/__init__.py

@@ -0,0 +1 @@
+from .evaluator import Evaluator

datetimeparser/evaluator/evaluator.py

@@ -0,0 +1,60 @@
+from datetime import datetime
+from typing import Optional, Tuple, Union
+from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
+
+from datetimeparser.utils.baseclasses import AbsoluteDateTime, RelativeDateTime
+from datetimeparser.utils.enums import Method
+from datetimeparser.evaluator.evaluatormethods import EvaluatorMethods
+from datetimeparser.utils.exceptions import FailedEvaluation, InvalidValue
+from datetimeparser.utils.geometry import TimeZoneManager
+
+
+class Evaluator:
+    def __init__(self, parsed_object, tz="Europe/Berlin", coordinates: Optional[Tuple[float, float]] = None):
+        """
+        :param parsed_object: the parsed object from parser
+        :param tz: the timezone for the datetime
+        :param coordinates: longitude and latitude for timezone calculation and for sunrise and sunset
+        """
+
+        if coordinates:
+            tz = TimeZoneManager().timezone_at(lng=coordinates[0], lat=coordinates[1])
+        try:
+            tiz = ZoneInfo(tz)
+        except ZoneInfoNotFoundError:
+            raise InvalidValue(f"Unknown timezone: '{tz}'")
+
+        self.parsed_object_type = parsed_object[0]
+        self.parsed_object_content: Union[list, AbsoluteDateTime, RelativeDateTime] = parsed_object[1]
+        self.current_datetime: datetime = datetime.strptime(datetime.strftime(datetime.now(tz=tiz), "%Y-%m-%d %H:%M:%S"), "%Y-%m-%d %H:%M:%S")
+        self.offset = tiz.utcoffset(self.current_datetime)
+        self.timezone: ZoneInfo = tiz
+        self.coordinates = coordinates
+
+    def evaluate(self) -> Union[Tuple[datetime, str, Tuple[float, float]], None]:
+        ev_out: Optional[datetime] = None
+        coordinates: Optional[Tuple[float, float]] = None
+        ev = EvaluatorMethods(self.parsed_object_content, self.current_datetime, self.timezone.key, self.coordinates, self.offset)
+
+        if self.parsed_object_type == Method.ABSOLUTE_DATE_FORMATS:
+            ev_out = ev.evaluate_absolute_date_formats()
+
+        if self.parsed_object_type == Method.ABSOLUTE_PREPOSITIONS:
+            ev_out = ev.evaluate_absolute_prepositions()
+
+        if self.parsed_object_type == Method.CONSTANTS:
+            ev_out, coordinates = ev.evaluate_constants()
+
+        if self.parsed_object_type == Method.RELATIVE_DATETIMES:
+            ev_out = ev.evaluate_relative_datetime()
+
+        if self.parsed_object_type == Method.CONSTANTS_RELATIVE_EXTENSIONS:
+            ev_out = ev.evaluate_constant_relatives()
+
+        if self.parsed_object_type == Method.DATETIME_DELTA_CONSTANTS:
+            ev_out = ev.evaluate_datetime_delta_constants()
+
+        if ev_out:
+            return ev_out, self.timezone.key, self.coordinates or coordinates
+        else:
+            raise FailedEvaluation(self.parsed_object_content)

datetimeparser/evaluatormethods.py → datetimeparser/evaluator/evaluatormethods.py

@@ -1,23 +1,34 @@
-from .baseclasses import *
-from .enums import *
-from .evaluatorutils import EvaluatorUtils
+from typing import Any, Optional, Tuple
+
+from datetimeparser.evaluator.evaluatorutils import EvaluatorUtils
+from datetimeparser.utils.baseclasses import *
+from datetimeparser.utils.enums import *
+from datetimeparser.utils.exceptions import InvalidValue
+from datetimeparser.utils.formulars import calc_sun_time
+from datetimeparser.utils.geometry import TimeZoneManager
 
 
 class EvaluatorMethods(EvaluatorUtils):
     """
     Evaluates a datetime-object from a given list returned from the parser
     """
 
-    def __init__(self, parsed, current_time: datetime, offset: timedelta = None):
+    def __init__(
+            self, parsed: Any, current_time: datetime, timezone: str, coordinates: Optional[Tuple[float, float]], offset: timedelta = None
+    ):
         """
         :param parsed: object returned from the parser
         :param current_time: the current datetime
+        :param timezone: the given timezone
+        :param coordinates: coordinates from the timezone
         :param offset: the UTC-offset from the current timezone. Default: None
         """
 
         self.parsed = parsed
         self.current_time = current_time
         self.offset = offset
+        self.coordinates = coordinates
+        self.timezone = timezone
 
     def evaluate_absolute_date_formats(self) -> datetime:
         ev_out = datetime(
@@ -32,7 +43,7 @@ def evaluate_absolute_date_formats(self) -> datetime:
         return ev_out
 
     def evaluate_constant_relatives(self) -> datetime:
-        sanitized = self.sanitize_input(self.current_time, self.parsed)
+        sanitized, _ = self.sanitize_input(self.current_time, self.parsed)
         base: datetime = self.current_time
         ev_out = None
 
@@ -45,7 +56,7 @@ def evaluate_constant_relatives(self) -> datetime:
             ev_out = datetime(base.year, base.month, base.day, hour, minute, sec)
 
         elif isinstance(sanitized[-1], RelativeDateTime):
-            base += self.prepare_relative_delta(sanitized[-1])
+            base = self.add_relative_delta(base, sanitized[-1], self.current_time)
 
             if sanitized[-2] in WeekdayConstants.ALL:
                 base = self.cut_time(base)
@@ -89,14 +100,17 @@ def evaluate_constant_relatives(self) -> datetime:
 
     def evaluate_absolute_prepositions(self) -> datetime:
         base_year = self.current_time.year
-        sanitized = self.sanitize_input(self.current_time, self.parsed)
-        base = self.get_base(sanitized, base_year, self.current_time)
+        sanitized, given_year = self.sanitize_input(self.current_time, self.parsed)
+        if not given_year:
+            base = self.get_base(sanitized, base_year, self.current_time)
+        else:
+            base = self.get_base(sanitized, given_year, self.current_time, forced=True)
         rel_out = self.calc_relative_time(sanitized)
-        base += self.prepare_relative_delta(rel_out)
+        base = self.add_relative_delta(base, rel_out, self.current_time)
 
-        return self.remove_milli_seconds(base)
+        return base
 
-    def evaluate_constants(self) -> datetime:
+    def evaluate_constants(self) -> Tuple[datetime, Optional[Tuple[float, float]]]:
         dt: datetime = self.current_time
         object_type: Constant = self.parsed[0]
 
@@ -109,18 +123,29 @@ def evaluate_constants(self) -> datetime:
                     dt = object_type.time_value(object_year + 1)
 
         else:
-            if object_type.name == "infinity":
-                raise ValueError("'infinity' isn't a valid time")
+            if object_type.name == "infinity":  # TODO: has to be improved for more invalid constants if needed
+                raise InvalidValue(object_type.name)
 
             elif object_type in WeekdayConstants.ALL:
                 dt: datetime = datetime.strptime(
                     object_type.time_value(self.cut_time(self.current_time)),
                     "%Y-%m-%d %H:%M:%S"
                 )
 
+            elif object_type.name == "sunset" or object_type.name == "sunrise":
+                ofs = self.offset.total_seconds() / 60 / 60  # -> to hours
+                # TODO: at the moment summer and winter time change the result for the offset around 1 hour
+                if not self.coordinates:
+                    self.coordinates = TimeZoneManager().get_coordinates(self.timezone)
+
+                dt = calc_sun_time(
+                    self.current_time,
+                    (self.coordinates[0], self.coordinates[1], ofs),
+                    object_type.name == "sunrise"
+                )
+
             else:
                 dt = object_type.time_value(self.current_time.year)
-
                 if isinstance(dt, tuple):
                     dt = datetime(
                         year=self.current_time.year,
@@ -130,23 +155,31 @@ def evaluate_constants(self) -> datetime:
                         minute=dt[1],
                         second=dt[2]
                     )
+                    return dt, self.coordinates
 
-            if self.current_time > dt and self.parsed[0] not in Constants.ALL_RELATIVE_CONSTANTS:
+            if self.current_time >= dt and self.parsed[0] not in (
+                    Constants.ALL_RELATIVE_CONSTANTS and WeekdayConstants.ALL and DatetimeDeltaConstants.CHANGING
+            ):
                 dt = object_type.time_value(self.current_time.year + 1)
 
+            if self.current_time >= dt and self.parsed[0] in WeekdayConstants.ALL:
+                dt += relativedelta(days=7)
+
         ev_out = datetime(
             dt.year, dt.month, dt.day, dt.hour, dt.minute, dt.second
         )
 
         if object_type.offset:
-            ev_out += self.prepare_relative_delta(self.get_offset(object_type, self.offset))
+            ev_out = self.add_relative_delta(ev_out, self.get_offset(object_type, self.offset), self.current_time)
+            if self.daylight_saving(self.timezone):
+                ev_out -= timedelta(hours=1)
 
-        return ev_out
+        return ev_out, self.coordinates
 
     def evaluate_relative_datetime(self) -> datetime:
         out: datetime = self.current_time
 
-        out += self.prepare_relative_delta(self.parsed)
+        out = self.add_relative_delta(out, self.parsed, self.current_time)
         ev_out = datetime(
             out.year, out.month, out.day, out.hour, out.minute, out.second
         )