alpha release: 0.6.0a1

Update README.rst

AUTHORS.rst

@@ -24,3 +24,4 @@ In chronological order:
 - Evan Mattiza <emattiza@gmail.com> (`@emattiza <https://github.com/emattiza>`_)
 - Dima Spivak <dima@spivak.ch> (`@dimaspivak <https://github.com/dimaspivak>`_)
 - Tom Barron <tusculum@gmail.com> (`@dtbarron <https://github.com/tbarron>`_)
+- Alex Ward <alxwrd@gmail.com> (`@alxwrd <https://github.com/alxwrd>`_)

Pipfile

@@ -1,3 +1,8 @@
+[[source]]
+name = "pypi"
+url = "https://pypi.org/simple"
+verify_ssl = true
+
 [dev-packages]
 freezegun = "*"
 pytest = "*"

README.rst

@@ -22,6 +22,11 @@ Maya is mostly built around the headaches and use-cases around parsing datetime
 
 .. image:: https://farm4.staticflickr.com/3702/33288285996_5b69d2b8f7_k_d.jpg
 
+Art by `Sam Flores
+<https://www.instagram.com/samagram12/>`_ (Photo by `Kenneth Reitz
+<https://www.instagram.com/kennethreitz/>`_). 
+
+If you're interested in financially supporting Kenneth Reitz open source, consider `visiting this link <https://cash.me/$KennethReitz>`_. Your support helps tremendously with sustainability of motivation, as Open Source is no longer part of my day job.
 
 ☤ Basic Usage of Maya
 ---------------------
@@ -73,6 +78,10 @@ Behold, datetimes for humans!
     >>> m = maya.MayaDT.from_struct(time.gmtime())
     >>> print(m)
     Wed, 20 Sep 2017 17:24:32 GMT
+    
+    >>> m = maya.MayaDT(time.time())
+    >>> print(m)
+    Wed, 20 Sep 2017 17:24:32 GMT
 
     >>> rand_day.day
     7
@@ -129,7 +138,7 @@ From here, there are a number of methods available to you, which you can use to
 ☤ What about Delorean, Arrow, & Pendulum?
 -----------------------------------------
 
-All these project complement each other, and are friends. Pendulum, for example, helps power Maya's parsing.
+All these projects complement each other, and are friends. Pendulum, for example, helps power Maya's parsing.
 
 Arrow, for example, is a fantastic library, but isn't what I wanted in a datetime library. In many ways, it's better than Maya for certain things. In some ways, in my opinion, it's not.
 

maya/__version__.py

@@ -1 +1 @@
-__version__ = '0.3.4'
+__version__ = '0.6.0a1'

maya/core.py

@@ -14,6 +14,7 @@ import pendulum
 import snaptime
 from tzlocal import get_localzone
 from dateutil.relativedelta import relativedelta
+from dateparser.languages.loader import default_loader
 
 from .compat import cmp, comparable
 
@@ -152,7 +153,7 @@ class MayaDT(object):
 
     def subtract_date(self, **kwargs):
         """Returns a timedelta object with the duration between the dates"""
-        return timedelta(self.epoch - kwargs['dt'].epoch)
+        return timedelta(seconds=self.epoch - kwargs['dt'].epoch)
 
     def snap(self, instruction):
         """
@@ -257,6 +258,14 @@ class MayaDT(object):
                 dt = dt.replace(tzinfo=self._tz)
         return dt
 
+    def local_datetime(self):
+        """Returns a local timezone-aware datetime object
+
+        It's the same as:
+        mayaDt.datetime(to_timezone=mayaDt.local_timezone)
+        """
+        return self.datetime(to_timezone=self.local_timezone, naive=False)
+
     def iso8601(self):
         """Returns an ISO 8601 representation of the MayaDT."""
         # Get a timezone-naive datetime.
@@ -269,7 +278,7 @@ class MayaDT(object):
 
     def rfc3339(self):
         """Returns an RFC 3339 representation of the MayaDT."""
-        return self.datetime().strftime("%Y-%m-%dT%H:%M:%S.%f")[:-4] + "Z"
+        return self.datetime().strftime("%Y-%m-%dT%H:%M:%S.%f")[:-5] + "Z"
 
     # Properties
     # ----------
@@ -323,15 +332,38 @@ class MayaDT(object):
 
     # Human Slang Extras
     # ------------------
-    def slang_date(self):
-        """"Returns human slang representation of date."""
-        dt = self.datetime(naive=True, to_timezone=self.local_timezone)
-        return humanize.naturaldate(dt)
+    def slang_date(self, locale="en"):
+        """"Returns human slang representation of date.
 
-    def slang_time(self):
-        """"Returns human slang representation of time."""
-        dt = self.datetime(naive=True, to_timezone=self.local_timezone)
-        return humanize.naturaltime(dt)
+        Keyword Arguments:
+            locale -- locale to translate to, e.g. 'fr' for french.
+                       (default: 'en' - English)
+        """
+        dt = pendulum.instance(self.datetime())
+
+        try:
+            return _translate(dt, locale)
+        except KeyError:
+            pass
+
+        delta = humanize.time.abs_timedelta(
+            timedelta(seconds=(self.epoch - now().epoch)))
+
+        format_string = "DD MMM"
+        if delta.days >= 365:
+            format_string += " YYYY"
+
+        return dt.format(format_string, locale=locale).title()
+
+    def slang_time(self, locale="en"):
+        """"Returns human slang representation of time.
+
+        Keyword Arguments:
+            locale -- locale to translate to, e.g. 'fr' for french.
+                       (default: 'en' - English)
+        """
+        dt = self.datetime()
+        return pendulum.instance(dt).diff_for_humans(locale=locale)
 
 
 def utc_offset(time_struct=None):
@@ -464,7 +496,7 @@ class MayaInterval(object):
 
         try:
             end = parse(end)
-        except pendulum.parsing.exceptions.ParserError as e:
+        except (pendulum.parsing.exceptions.ParserError, TypeError) as e:
             end = cls.parse_iso8601_duration(end, start=start)
 
         return cls(start=start, end=end)
@@ -675,7 +707,7 @@ def now():
     return MayaDT(epoch=epoch)
 
 
-def when(string, timezone='UTC', prefer_past=False):
+def when(string, timezone='UTC', prefer_dates_from='current_period'):
     """"Returns a MayaDT instance for the human moment specified.
 
     Powered by dateparser. Useful for scraping websites.
@@ -686,16 +718,20 @@ def when(string, timezone='UTC', prefer_past=False):
     Keyword Arguments:
         string -- string to be parsed
         timezone -- timezone referenced from (default: 'UTC')
-        prefer_past -- prefer parsing ambiguous date as in the past
+        prefer_dates_from -- what dates are prefered when `string` is ambigous.
+                             options are 'past', 'future', and 'current_period'
+                             (default: 'current_period'). see: [1]
 
+    Reference:
+        [1] dateparser.readthedocs.io/en/latest/usage.html#handling-incomplete-dates
     """
     settings = {
         'TIMEZONE': timezone,
         'RETURN_AS_TIMEZONE_AWARE': True,
         'TO_TIMEZONE': 'UTC',
+        'PREFER_DATES_FROM': prefer_dates_from,
     }
-    if prefer_past:
-        settings['PREFER_DATES_FROM'] = 'past'
+
     dt = dateparser.parse(string, settings=settings)
     if dt is None:
         raise ValueError('invalid datetime input specified.')
@@ -703,7 +739,7 @@ def when(string, timezone='UTC', prefer_past=False):
     return MayaDT.from_datetime(dt)
 
 
-def parse(string, timezone='UTC', day_first=False, year_first=True):
+def parse(string, timezone='UTC', day_first=False, year_first=True, strict=False):
     """"Returns a MayaDT instance for the machine-produced moment specified.
 
     Powered by pendulum.
@@ -718,11 +754,14 @@ def parse(string, timezone='UTC', day_first=False, year_first=True):
                      between YDM and YMD. (default: False)
         year_first -- if true, the first value (e.g. 2016/05/01)
                       is parsed as year (default: True)
+        strict -- if False, allow pendulum to fall back on datetime parsing
+                  if pendulum's own parsing fails
     """
     options = {}
     options['tz'] = timezone
     options['day_first'] = day_first
     options['year_first'] = year_first
+    options['strict'] = strict
 
     dt = pendulum.parse(str(string), **options)
     return MayaDT.from_datetime(dt)
@@ -747,6 +786,16 @@ def _seconds_or_timedelta(duration):
     return dt_timedelta
 
 
+def _translate(dt, target_locale):
+    en = default_loader.get_locale("en")
+    target = default_loader.get_locale(target_locale)
+    naturaldate = humanize.naturaldate(dt)
+
+    base = en.translate(naturaldate, settings=dateparser.conf.settings)
+
+    return target.info["relative-type"][base][-1]
+
+
 def intervals(start, end, interval):
     """
     Yields MayaDT objects between the start and end MayaDTs given,

setup.py

@@ -25,7 +25,7 @@ required = [
     'pytz',
     'dateparser>=0.7.0',
     'tzlocal',
-    'pendulum>=1.0',
+    'pendulum>=2.0.2',
     'snaptime'
 ]
 

tests/test_maya.py

@@ -1,5 +1,6 @@
 import copy
 import time
+import calendar
 from datetime import timedelta, datetime as Datetime
 
 import pytz
@@ -157,9 +158,19 @@ def test_slang_date():
     assert d.slang_date() == 'tomorrow'
 
 
+def test_slang_date_locale():
+    d = maya.when('tomorrow')
+    assert d.slang_date(locale='fr') == 'demain'
+
+
 def test_slang_time():
     d = maya.when('1 hour ago')
-    assert d.slang_time() == 'an hour ago'
+    assert d.slang_time() == '1 hour ago'
+
+
+def test_slang_time_locale():
+    d = maya.when('1 hour ago')
+    assert d.slang_time(locale='de') == 'vor 1 Stunde'
 
 
 @pytest.mark.parametrize("string,kwds,expected", [
@@ -191,16 +202,46 @@ def test_parse(string, kwds, expected):
 
 @pytest.mark.usefixtures("frozen_now")
 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_date.year == this_year
-    if next_month == '1':
-        assert past_date.year == this_year
-    else:
-        assert past_date.year == last_year
+    two_days_away = maya.now().add(days=2)
+
+    past_date = maya.when(
+            two_days_away.slang_date(),
+            prefer_dates_from='past')
+
+    assert past_date < maya.now()
+
+
+@pytest.mark.usefixtures("frozen_now")
+def test_when_future():
+    two_days_away = maya.now().add(days=2)
+
+    future_date = maya.when(
+            two_days_away.slang_date(),
+            prefer_dates_from='future')
+
+    assert future_date > maya.now()
+
+
+@pytest.mark.usefixtures("frozen_now")
+def test_when_past_day_name():
+    two_days_away = maya.now().add(days=2)
+
+    past_date = maya.when(
+            calendar.day_name[two_days_away.weekday],
+            prefer_dates_from='past')
+
+    assert past_date < maya.now()
+
+
+@pytest.mark.usefixtures("frozen_now")
+def test_when_future_day_name():
+    two_days_away = maya.now().add(days=2)
+
+    future_date = maya.when(
+            calendar.day_name[two_days_away.weekday],
+            prefer_dates_from='future')
+
+    assert future_date > maya.now()
 
 
 def test_datetime_to_timezone():
@@ -208,13 +249,20 @@ def test_datetime_to_timezone():
     assert dt.tzinfo.zone == 'US/Eastern'
 
 
-def test_rfc3339():
+def test_rfc3339_epoch():
     mdt = maya.when('2016-01-01')
     out = mdt.rfc3339()
     mdt2 = maya.MayaDT.from_rfc3339(out)
     assert mdt.epoch == mdt2.epoch
 
 
+def test_rfc3339_format():
+    rfc3339 = maya.MayaDT.rfc3339(maya.when('2016-01-01T12:03:03Z'))
+    # it's important that the string has got a "max 1-digit millis" fragment
+    # as per https://tools.ietf.org/html/rfc3339#section-5.6
+    assert rfc3339 == '2016-01-01T12:03:03.0Z'
+
+
 @pytest.mark.usefixtures("frozen_now")
 def test_comparison_operations():
     now = maya.now()
@@ -289,8 +337,8 @@ def test_dunder_sub():
 def test_mayaDT_sub():
     now = maya.now()
     then = now.add(days=1)
-    assert then - now == timedelta(24 * 60 * 60)
-    assert now - then == timedelta(-24 * 60 * 60)
+    assert then - now == timedelta(seconds=24 * 60 * 60)
+    assert now - then == timedelta(seconds=-24 * 60 * 60)
 
 
 def test_core_local_timezone(monkeypatch):
@@ -311,6 +359,28 @@ def test_core_local_timezone(monkeypatch):
     assert mdt.local_timezone == 'UTC'
 
 
+def test_getting_datetime_for_local_timezone(monkeypatch):
+
+    @property
+    def mock_local_tz(self):
+        class StaticTzInfo(object):
+            zone = 'Europe/Zurich'
+
+            def __repr__(self):
+                return "<StaticTzInfo 'Europe/Zurich'>"
+
+        return StaticTzInfo()
+
+    monkeypatch.setattr(maya.MayaDT, '_local_tz', mock_local_tz)
+
+    d = maya.parse('1994-02-21T12:00:00+05:30')
+
+    dt = pytz.timezone('Europe/Zurich').localize(
+            Datetime(1994, 2, 21, 7, 30))
+
+    assert d.local_datetime() == dt
+
+
 @pytest.mark.parametrize("when_str,snap_str,expected_when", [
     ('Mon, 21 Feb 1994 21:21:42 GMT', '@d',
      'Mon, 21 Feb 1994 00:00:00 GMT'),