Adds experimental support for Python 3.6 and the fold attribute.

Fixes #83

Author: sdispater

.travis.yml

@@ -22,6 +22,10 @@ matrix:
       env: PENDULUM_EXTENSIONS=1
     - python: 3.5
       env: PENDULUM_EXTENSIONS=0
+    - python: 3.6-dev
+      env: PENDULUM_EXTENSIONS=1
+    - python: 3.6-dev
+      env: PENDULUM_EXTENSIONS=0
     - python: pypy
 
 before_install:

docs/_docs/timezones.rst

@@ -57,6 +57,38 @@ given timezone to properly handle any transition that might have occurred.
     Note that it only affects instances at creation time. Shifting time around
     transition times still behaves the same.
 
+.. note::
+
+    As of version **0.7.0**, and to be consistent with the standard library (Python 3.6+),
+    the ``Pendulum`` class accepts a ``fold`` keyword argument which will be used, when set explicitely,
+    to determine the rule to apply on ambiguous or non-existing times.
+    Be aware that when it is not set explicitely, the previous behavior remains,
+    i.e. the configured transition rule or the default one will be used.
+
+    .. code-block:: python
+
+        from pendulum import Pendulum
+
+        dt = Pendulum(2013, 3, 31, 2, 30, 0, 0, 'Europe/Paris')
+        dt.isoformat()
+        '2013-03-31T03:30:00+02:00'
+
+        dt = Pendulum(2013, 3, 31, 2, 30, 0, 0, 'Europe/Paris', fold=0)
+        dt.isoformat()
+        '2013-03-31T02:30:00+01:00'
+
+        dt = Pendulum(2013, 3, 31, 2, 30, 0, 0, 'Europe/Paris', fold=1)
+        dt.isoformat()
+        '2013-03-31T02:30:00+01:00'
+
+        dt = Pendulum(2013, 10, 27, 2, 30, 0, 0, 'Europe/Paris', fold=0)
+        dt.isoformat()
+        '2013-10-27T02:30:00+02:00'
+
+        dt = Pendulum(2013, 10, 27, 2, 30, 0, 0, 'Europe/Paris', fold=1)
+        dt.isoformat()
+        '2013-10-27T02:30:00+01:00'
+
 Shifting time to transition
 ---------------------------
 
@@ -113,6 +145,41 @@ Like said in the introduction, you can use the timezone library
 directly with standard ``datetime`` objects but with limitations, especially
 when adding and subtracting time around transition times.
 
+.. warning::
+
+    By default in **Python 3.6+**, the value of the ``fold`` attribute will be used
+    to determine the transition rule. So the behavior will be slightly different
+    compared to previous versions.
+
+    .. code-block:: python
+
+        from datetime import datetime
+        from pendulum import timezone
+
+        paris = timezone('Europe/Paris')
+        dt = datetime(2013, 3, 31, 2, 30)
+        # By default, fold is set to 0
+        dt = paris.convert(dt)
+        dt.isoformat()
+        '2013-03-31T02:30:00+01:00'
+
+        dt = datetime(2013, 3, 31, 2, 30, fold=1)
+        dt = paris.convert(dt)
+        dt.isoformat()
+        '2013-03-31T03:30:00+02:00'
+
+    You can override this behavior by explicitely passing the
+    transition rule to ``convert()``.
+
+    .. code-block:: python
+
+        paris = timezone('Europe/Paris')
+        dt = datetime(2013, 3, 31, 2, 30)
+        # By default, fold is set to 0
+        dt = paris.convert(dt, dst_rule=paris.POST_TRANSITION)
+        dt.isoformat()
+        '2013-03-31T03:30:00+02:00'
+
 
 .. code-block:: python
 

pendulum/_compat.py

@@ -5,6 +5,7 @@
 PY2 = sys.version_info[0] == 2
 PY3K = sys.version_info[0] >= 3
 PY33 = sys.version_info >= (3, 3)
+PY36 = sys.version_info >= (3, 6)
 
 
 if PY2:

pendulum/pendulum.py

@@ -110,7 +110,7 @@ def _timezone(cls, zone):
 
     def __new__(cls, year, month, day,
                 hour=0, minute=0, second=0, microsecond=0,
-                tzinfo=None):
+                tzinfo=None, fold=None):
         """
         Constructor.
 
@@ -125,7 +125,7 @@ def __new__(cls, year, month, day,
 
     def __init__(self, year, month, day,
                  hour=0, minute=0, second=0, microsecond=0,
-                 tzinfo=UTC):
+                 tzinfo=UTC, fold=None):
         # If a TimezoneInfo is passed we do not convert
         if isinstance(tzinfo, TimezoneInfo):
             self._tz = tzinfo.tz
@@ -139,6 +139,15 @@ def __init__(self, year, month, day,
             self._microsecond = microsecond
             self._tzinfo = tzinfo
 
+            if fold is None:
+                # Converting rule to fold value
+                if self._TRANSITION_RULE == Timezone.POST_TRANSITION:
+                    fold = 1
+                else:
+                    fold = 0
+
+            self._fold = fold
+
             dt = datetime.datetime(
                 year, month, day,
                 hour, minute, second, microsecond,
@@ -147,10 +156,24 @@ def __init__(self, year, month, day,
         else:
             self._tz = self._safe_create_datetime_zone(tzinfo)
 
+            # Support for explicit fold attribute
+            if fold is None:
+                transition_rule = self._TRANSITION_RULE
+
+                # Converting rule to fold value
+                if self._TRANSITION_RULE == Timezone.POST_TRANSITION:
+                    fold = 1
+                else:
+                    fold = 0
+            elif fold == 1:
+                transition_rule = Timezone.POST_TRANSITION
+            else:
+                transition_rule = Timezone.PRE_TRANSITION
+
             dt = self._tz.convert(datetime.datetime(
                 year, month, day,
                 hour, minute, second, microsecond
-            ), dst_rule=self._TRANSITION_RULE)
+            ), dst_rule=transition_rule)
 
             self._year = dt.year
             self._month = dt.month
@@ -160,6 +183,7 @@ def __init__(self, year, month, day,
             self._second = dt.second
             self._microsecond = dt.microsecond
             self._tzinfo = dt.tzinfo
+            self._fold = getattr(dt, 'fold', fold)
 
         self._timestamp = None
         self._int_timestamp = None
@@ -337,7 +361,7 @@ def create(cls, year=None, month=None, day=None,
                 now = cls.get_test_now().in_tz(tz)
             else:
                 now = datetime.datetime.utcnow().replace(tzinfo=UTC)
-                now = tz.convert(now, dst_rule=cls._TRANSITION_RULE)
+                now = tz.convert(now)
 
             if year is None:
                 year = now.year
@@ -510,6 +534,10 @@ def microsecond(self):
     def tzinfo(self):
         return self._tzinfo
 
+    @property
+    def fold(self):
+        return self._fold
+
     @property
     def timestamp(self):
         if self._timestamp is None:
@@ -1108,7 +1136,10 @@ def add(self, years=0, months=0, weeks=0, days=0,
         if any([years, months, weeks, days]):
             # If we specified any of years, months, weeks or days
             # we will not apply the transition (if any)
-            dt = self._tz.convert(dt.replace(tzinfo=None))
+            dt = self._tz.convert(
+                dt.replace(tzinfo=None),
+                dst_rule=Timezone.POST_TRANSITION
+            )
         else:
             # Else, we need to apply the transition properly (if any)
             dt = self._tz.convert(dt)
@@ -1956,7 +1987,7 @@ def __hash__(self):
     def __getnewargs__(self):
         return(self, )
 
-    def _getstate(self):
+    def _getstate(self, protocol=3):
         tz = self.timezone_name
 
         # Fix for fixed timezones not being properly unpickled
@@ -1966,11 +1997,15 @@ def _getstate(self):
         return (
             self.year, self.month, self.day,
             self.hour, self.minute, self.second, self.microsecond,
-            tz
+            tz,
+            self.fold
         )
 
     def __reduce__(self):
-        return self.__class__, self._getstate()
+        return self.__reduce_ex__(2)
+
+    def __reduce_ex__(self, protocol):
+        return self.__class__, self._getstate(protocol)
 
 Pendulum.min = Pendulum.instance(datetime.datetime.min.replace(tzinfo=UTC))
 Pendulum.max = Pendulum.instance(datetime.datetime.max.replace(tzinfo=UTC))

pendulum/period.py

@@ -284,7 +284,7 @@ def __repr__(self):
             self._start, self._end
         )
 
-    def _getstate(self):
+    def _getstate(self, protocol=3):
         start, end = self.start, self.end
 
         if self._invert and self._absolute:
@@ -295,4 +295,7 @@ def _getstate(self):
         )
 
     def __reduce__(self):
-        return self.__class__, self._getstate()
+        return self.__reduce_ex__(2)
+
+    def __reduce_ex__(self, protocol):
+        return self.__class__, self._getstate(protocol)

pendulum/time.py

@@ -14,7 +14,8 @@ class Time(TranslatableMixin, FormattableMixing, TestableMixin, time):
     Represents a time instance as hour, minute, second, microsecond.
     """
 
-    def __init__(self, hour, minute=0, second=0, microsecond=0, tzinfo=None):
+    def __init__(self, hour, minute=0, second=0, microsecond=0,
+                 tzinfo=None, fold=0):
         """
         Constructor.
 
@@ -39,6 +40,7 @@ def __init__(self, hour, minute=0, second=0, microsecond=0, tzinfo=None):
         self._microsecond = microsecond
         self._tzinfo = tzinfo
         self._time = time(hour, minute, second, microsecond, tzinfo)
+        self._fold = fold
 
     @classmethod
     def instance(cls, t, copy=True):
@@ -107,6 +109,10 @@ def microsecond(self):
     def tzinfo(self):
         return self._tzinfo
 
+    @property
+    def fold(self):
+        return self._fold
+
     # Comparisons
 
     def between(self, dt1, dt2, equal=True):
@@ -503,7 +509,7 @@ def tzname(self):
 
         return self._time.tzname()
 
-    def _getstate(self):
+    def _getstate(self, protocol=3):
         tz = self.tzinfo
 
         return (
@@ -512,7 +518,10 @@ def _getstate(self):
         )
 
     def __reduce__(self):
-        return self.__class__, self._getstate()
+        return self.__reduce_ex__(2)
+
+    def __reduce_ex__(self, protocol):
+        return self.__class__, self._getstate(protocol)
 
 Time.min = Time(0, 0, 0)
 Time.max = Time(23, 59, 59, 999999)