Added on() and at() methods which replace with_date() and with_time().

Author: sdispater

CHANGELOG.md

@@ -2,9 +2,13 @@
 
 ## [Unreleased]
 
-### Fixed
+### Added
+
+- Added `on()` and `at()` methods which replace `with_date()` and `with_time()`.
+
+### Deprecated
 
-- Fixed parsing of some ISO 8601 strings.
+- `with_date()` and `with_time()` are deprecated. Use `on()` and `at()` instead.
 
 
 ## [0.7.0] - 2016-12-07

docs/_docs/fluent_helpers.rst

@@ -10,13 +10,17 @@ setting the timestamp will not set the corresponding timezone to UTC.
 .. code-block:: python
 
     import pendulum
+    from datetime import time, date
 
     dt = pendulum.now()
 
-    dt.year_(1975).month_(5).day_(21).hour_(22).minute_(32).second_(5).to_datetime_string()
-    '1975-05-21 22:32:05'
+    dt = dt.year_(1975).month_(5).day_(21).to_datetime_string()
+    '1975-05-21 13:45:18'
+
+    dt.hour_(22).minute_(32).second_(5).to_datetime_string()
+    '2016-11-16 22:32:05'
 
-    dt.with_date(1975, 5, 21).with_time(22, 32, 5).to_datetime_string()
+    dt.on(1975, 5, 21).at(22, 32, 5).to_datetime_string()
     '1975-05-21 22:32:05'
 
     dt.timestamp_(169957925).timezone_('Europe/London')

pendulum/pendulum.py

@@ -4,6 +4,7 @@
 
 import calendar
 import datetime
+import warnings
 
 from .date import Date
 from .time import Time
@@ -612,7 +613,7 @@ def date(self):
     def time(self):
         return Time(self.hour, self.minute, self.second, self.microsecond)
 
-    def with_date(self, year, month, day):
+    def on(self, year, month, day):
         """
         Returns a new instance with the current date set to a different date.
 
@@ -627,13 +628,34 @@ def with_date(self, year, month, day):
 
         :rtype: Pendulum
         """
-        dt = self.replace(
+        return self.replace(
             year=int(year), month=int(month), day=int(day)
         )
 
-        return self._tz.convert(dt)
+    def with_date(self, year, month, day):
+        """
+        Returns a new instance with the current date set to a different date.
 
-    def with_time(self, hour, minute, second, microsecond=0):
+        :param year: The year
+        :type year: int
+
+        :param month: The month
+        :type month: int
+
+        :param day: The day
+        :type day: int
+
+        :rtype: Pendulum
+        """
+        warnings.warn(
+            'with_date() is deprecated. Use on() instead.',
+            category=DeprecationWarning,
+            stacklevel=2
+        )
+
+        return self.on(year, month, day)
+
+    def at(self, hour, minute, second, microsecond=0):
         """
         Returns a new instance with the current time to a different time.
 
@@ -651,13 +673,36 @@ def with_time(self, hour, minute, second, microsecond=0):
 
         :rtype: Pendulum
         """
-        dt = self._datetime.replace(
-            hour=int(hour), minute=int(minute), second=int(second),
-            microsecond=microsecond,
-            tzinfo=None
+        return self.replace(
+            hour=hour, minute=minute, second=second,
+            microsecond=microsecond
+        )
+
+    def with_time(self, hour, minute, second, microsecond=0):
+        """
+        Returns a new instance with the current time set to a different time.
+
+        :param hour: The hour
+        :type hour: int
+
+        :param minute: The minute
+        :type minute: int
+
+        :param second: The second
+        :type second: int
+
+        :param microsecond: The microsecond
+        :type microsecond: int
+
+        :rtype: Pendulum
+        """
+        warnings.warn(
+            'with_time() is deprecated. Use at() instead.',
+            category=DeprecationWarning,
+            stacklevel=2
         )
 
-        return self.instance(dt, self._tz)
+        return self.at(hour, minute, second, microsecond)
 
     def with_date_time(self, year, month, day, hour, minute, second, microsecond=0):
         """
@@ -672,15 +717,12 @@ def with_date_time(self, year, month, day, hour, minute, second, microsecond=0):
 
         :rtype: Pendulum
         """
-        dt = self._datetime.replace(
+        return self.replace(
             year=year, month=month, day=day,
-            hour=int(hour), minute=int(minute), second=int(second),
-            microsecond=microsecond,
-            tzinfo=None
+            hour=hour, minute=minute, second=second,
+            microsecond=microsecond
         )
 
-        return self.instance(dt, self._tz)
-
     def with_time_from_string(self, time):
         """
         Returns a new instance with the time set by time string.
@@ -692,11 +734,11 @@ def with_time_from_string(self, time):
         """
         time = time.split(':')
 
-        hour = time[0]
-        minute = time[1] if len(time) > 1 else 0
-        second = time[2] if len(time) > 2 else 0
+        hour = int(time[0])
+        minute = int(time[1]) if len(time) > 1 else 0
+        second = int(time[2]) if len(time) > 2 else 0
 
-        return self.with_time(hour, minute, second)
+        return self.at(hour, minute, second)
 
     def in_timezone(self, tz):
         """
@@ -1425,15 +1467,15 @@ def _start_of_day(self):
 
         :rtype: Pendulum
         """
-        return self.with_time(0, 0, 0)
+        return self.at(0, 0, 0)
 
     def _end_of_day(self):
         """
         Reset the time to 23:59:59.999999
 
         :rtype: Pendulum
         """
-        return self.with_time(23, 59, 59, 999999)
+        return self.at(23, 59, 59, 999999)
 
     def _start_of_month(self):
         """
@@ -1753,7 +1795,7 @@ def _first_of_quarter(self, day_of_week=None):
 
         :rtype: Pendulum
         """
-        return self.with_date(self.year, self.quarter * 3 - 2, 1).first_of('month', day_of_week)
+        return self.on(self.year, self.quarter * 3 - 2, 1).first_of('month', day_of_week)
 
     def _last_of_quarter(self, day_of_week=None):
         """
@@ -1766,7 +1808,7 @@ def _last_of_quarter(self, day_of_week=None):
 
         :rtype: Pendulum
         """
-        return self.with_date(self.year, self.quarter * 3, 1).last_of('month', day_of_week)
+        return self.on(self.year, self.quarter * 3, 1).last_of('month', day_of_week)
 
     def _nth_of_quarter(self, nth, day_of_week):
         """
@@ -1795,7 +1837,7 @@ def _nth_of_quarter(self, nth, day_of_week):
         if last_month < dt.month or year != dt.year:
             return False
 
-        return self.with_date(self.year, dt.month, dt.day).start_of('day')
+        return self.on(self.year, dt.month, dt.day).start_of('day')
 
     def _first_of_year(self, day_of_week=None):
         """
@@ -1848,7 +1890,7 @@ def _nth_of_year(self, nth, day_of_week):
         if year != dt.year:
             return False
 
-        return self.with_date(self.year, dt.month, dt.day).start_of('day')
+        return self.on(self.year, dt.month, dt.day).start_of('day')
 
     def average(self, dt=None):
         """
@@ -1939,7 +1981,8 @@ def utctimetuple(self):
         return self._datetime.utctimetuple()
 
     def replace(self, year=None, month=None, day=None, hour=None,
-                minute=None, second=None, microsecond=None, tzinfo=True):
+                minute=None, second=None, microsecond=None, tzinfo=True,
+                fold=None):
         year = year if year is not None else self._year
         month = month if month is not None else self._month
         day = day if day is not None else self._day
@@ -1952,14 +1995,14 @@ def replace(self, year=None, month=None, day=None, hour=None,
         if tzinfo is not None and tzinfo is not True:
             tzinfo = self._safe_create_datetime_zone(tzinfo)
         elif tzinfo is None:
-            tzinfo = tzinfo
+            tzinfo = UTC
         else:
-            tzinfo = self._tzinfo
+            tzinfo = self._tzinfo.tz
 
-        return self.instance(
-            self._datetime.replace(year=year, month=month, day=day,
-                                   hour=hour, minute=minute, second=second,
-                                   microsecond=microsecond, tzinfo=tzinfo)
+        return self.__class__(
+            year, month, day,
+            hour, minute, second, microsecond,
+            tzinfo=tzinfo, fold=fold
         )
 
     def astimezone(self, tz=None):

tests/pendulum_tests/test_fluent_setters.py

@@ -87,6 +87,17 @@ def test_fluid_with_date(self):
         self.assertEqual(7, d.month)
         self.assertEqual(2, d.day)
 
+    def test_fluid_on(self):
+        d = Pendulum.create(2016, 7, 2, 0, 41, 20)
+        new = d.on(1995, 11, 9)
+        self.assertIsInstanceOfPendulum(new)
+        self.assertEqual(1995, new.year)
+        self.assertEqual(11, new.month)
+        self.assertEqual(9, new.day)
+        self.assertEqual(2016, d.year)
+        self.assertEqual(7, d.month)
+        self.assertEqual(2, d.day)
+
     def test_fluid_with_date_with_transition(self):
         d = Pendulum.create(2013, 3, 31, 0, 0, 0, 0, 'Europe/Paris')
         new = d.with_date(2013, 4, 1)
@@ -100,7 +111,20 @@ def test_fluid_with_date_with_transition(self):
         self.assertEqual(31, d.day)
         self.assertEqual(3600, d.offset)
 
-    def test_fluid_set_time(self):
+    def test_fluid_on_with_transition(self):
+        d = Pendulum.create(2013, 3, 31, 0, 0, 0, 0, 'Europe/Paris')
+        new = d.on(2013, 4, 1)
+        self.assertIsInstanceOfPendulum(new)
+        self.assertEqual(2013, new.year)
+        self.assertEqual(4, new.month)
+        self.assertEqual(1, new.day)
+        self.assertEqual(7200, new.offset)
+        self.assertEqual(2013, d.year)
+        self.assertEqual(3, d.month)
+        self.assertEqual(31, d.day)
+        self.assertEqual(3600, d.offset)
+
+    def test_fluid_with_time(self):
         d = Pendulum.create(2016, 7, 2, 0, 41, 20)
         new = d.with_time(5, 32, 49)
         self.assertIsInstanceOfPendulum(new)
@@ -111,6 +135,17 @@ def test_fluid_set_time(self):
         self.assertEqual(41, d.minute)
         self.assertEqual(20, d.second)
 
+    def test_fluid_at(self):
+        d = Pendulum.create(2016, 7, 2, 0, 41, 20)
+        new = d.at(5, 32, 49)
+        self.assertIsInstanceOfPendulum(new)
+        self.assertEqual(5, new.hour)
+        self.assertEqual(32, new.minute)
+        self.assertEqual(49, new.second)
+        self.assertEqual(0, d.hour)
+        self.assertEqual(41, d.minute)
+        self.assertEqual(20, d.second)
+
     def test_fluid_set_time_with_transition(self):
         d = Pendulum.create(2013, 3, 31, 0, 0, 0, 0, 'Europe/Paris')
         new = d.with_time(2, 30, 0)
@@ -119,6 +154,14 @@ def test_fluid_set_time_with_transition(self):
         self.assertEqual(30, new.minute)
         self.assertEqual(0, new.second)
 
+    def test_fluid_at_with_transition(self):
+        d = Pendulum.create(2013, 3, 31, 0, 0, 0, 0, 'Europe/Paris')
+        new = d.at(2, 30, 0)
+        self.assertIsInstanceOfPendulum(new)
+        self.assertEqual(3, new.hour)
+        self.assertEqual(30, new.minute)
+        self.assertEqual(0, new.second)
+
     def test_fluid_set_timestamp(self):
         d = Pendulum.create(2016, 7, 2, 0, 41, 20)
         new = d.timestamp_(0)