Docs and test.

1 files changed, 16 insertions, 2 deletions

diff --git a/string_utils.py b/string_utils.py
index 7c40dc9..24fc595 100644
--- a/string_utils.py
+++ b/string_utils.py
@@ -1388,7 +1388,21 @@ def to_date(in_str: str) -> Optional[datetime.date]:
     return None
 
 
-def extract_date(in_str: Any) -> Optional[str]:
+def extract_date(in_str: Any) -> Optional[datetime.datetime]:
+    """Finds and extracts a date from the string, if possible.
+
+    Args:
+        in_str: the string to extract a date from
+
+    Returns:
+        a datetime if date was found, otherwise None
+
+    >>> extract_date("filename.txt    dec 13, 2022")
+    datetime.datetime(2022, 12, 13, 0, 0)
+
+    >>> extract_date("Dear Santa, please get me a pony.")
+
+    """
     import itertools
 
     import dateparse.dateparse_utils as du
@@ -1405,7 +1419,7 @@ def extract_date(in_str: Any) -> Optional[str]:
             expr = " ".join(ngram)
             logger.debug(f"Trying {expr}")
             if d.parse(expr):
-                return d.get_date()
+                return d.get_datetime()
         except du.ParseException:  # type: ignore
             pass
     return None