From c0092e74ae40f97d802f9a156088adfd92a3039a Mon Sep 17 00:00:00 2001
From: Matt Furden <zolrath@gmail.com>
Date: Sun, 15 Oct 2017 21:48:38 -0700
Subject: [PATCH] Add prefer_past option for when

When parsing dates from websites when encountering ambiguous dates like "December 12th" this is interpreted in the future (when the current date is in October).

When parsing dates that we know must be in the past this is not the correct behavior.

Add a `prefer_past` keyword argument to `when` to allow the user to ensure the date is parsed as being in the past.
---
 maya/core.py       | 11 ++++++++---
 tests/test_maya.py | 11 +++++++++++
 2 files changed, 19 insertions(+), 3 deletions(-)

diff --git a/maya/core.py b/maya/core.py
index 042bfd8..423fb2c 100644
--- a/maya/core.py
+++ b/maya/core.py
@@ -578,7 +578,7 @@ def now():
     return MayaDT(epoch=epoch)
 
 
-def when(string, timezone='UTC'):
+def when(string, timezone='UTC', prefer_past=False):
     """"Returns a MayaDT instance for the human moment specified.
 
     Powered by dateparser. Useful for scraping websites.
@@ -589,10 +589,15 @@ def when(string, timezone='UTC'):
     Keyword Arguments:
         string -- string to be parsed
         timezone -- timezone referenced from (default: 'UTC')
+        prefer_past -- prefer parsing ambiguous date as in the past
 
     """
-    dt = dateparser.parse(string,
-                          settings={'TIMEZONE': timezone, 'RETURN_AS_TIMEZONE_AWARE': True, 'TO_TIMEZONE': 'UTC'})
+    settings = {'TIMEZONE': timezone, 'RETURN_AS_TIMEZONE_AWARE': True, 'TO_TIMEZONE': 'UTC'}
+
+    if prefer_past:
+        settings['PREFER_DATES_FROM'] = 'past'
+    
+    dt = dateparser.parse(string, settings=settings)
 
     if dt is None:
         raise ValueError('invalid datetime input specified.')
diff --git a/tests/test_maya.py b/tests/test_maya.py
index a28a54a..817d2ba 100644
--- a/tests/test_maya.py
+++ b/tests/test_maya.py
@@ -170,6 +170,17 @@ def test_parse():
     d = maya.parse('01/05/2016', day_first=True)
     assert format(d) == '2016-05-01 00:00:00+00:00'
 
+def test_when_past():
+    next_month = str(maya.now().add(months=1).month)
+    this_year = maya.now().year
+    last_year = this_year - 1
+
+    future_date = maya.when(next_month)
+    past_date = maya.when(next_month, prefer_past=True)
+
+    assert future_d.year == this_year
+    assert past_d.year == last_year
+
 
 def test_datetime_to_timezone():
     dt = maya.when('2016-01-01').datetime(to_timezone='US/Eastern')