Add deprecation warnings for methods that will no longer be supported in pendulum 2.0

Author: sdispater

CHANGELOG.md

@@ -1,5 +1,25 @@
 # Change Log
 
+## [Unreleased]
+
+### Added
+
+- Added the `set()` method to set properties.
+- Added the `is_utc()` and `is_local()` methods.
+
+### Deprecated
+
+- `year_()`, `month_()`, `day_`, `hour_`, `minute_`, `second_`, `microsecond_()` are now deprecated.
+- `timezone_()` and `tz_()` are now deprecated.
+- `timestamp_()` is now deprecated.
+- `with_date_time()`, `with_time_from_string()` and `with_timestamp()` are now deprecated.
+- `between()` is now deprecated.
+- `min_()`, `max_()`, `minimum()`, `maximum()` are now deprecated.
+- `is_today()`, `is_yesterday()`, `is_tomorrow()` and `is_same_day()` are now depecreated.
+- `is_sunday()` -> `is_saturday()` are now deprecated.
+- The `utc` and `local` properties are now deprecated. Use `is_utc()` and `is_local()` instead.
+
+
 ## [1.4.4] - 2018-03-21
 
 ### Fixed

docs/_docs/addition_subtraction.rst

@@ -9,7 +9,7 @@ Each method returns a new ``Pendulum`` instance.
 
     import pendulum
 
-    dt = pendulum.create(2012, 1, 31, 0)
+    dt = pendulum.datetime(2012, 1, 31, 0)
 
     dt.to_datetime_string()
     '2012-01-31 00:00:00'

docs/_docs/attributes_properties.rst

@@ -41,7 +41,7 @@ Pendulum gives access to more attributes and properties than the default ``datet
     dt.int_timestamp
     1346887571
 
-    pendulum.create(1975, 5, 21).age
+    pendulum.datetime(1975, 5, 21).age
     41 # calculated vs now in the same tz
     dt.quarter
     3
@@ -59,9 +59,9 @@ Pendulum gives access to more attributes and properties than the default ``datet
     9.5
 
     # Indicates if day light savings time is on
-    pendulum.create(2012, 1, 1, tz='America/Toronto').is_dst
+    pendulum.datetime(2012, 1, 1, tz='America/Toronto').is_dst
     False
-    pendulum.create(2012, 9, 1, tz='America/Toronto').is_dst
+    pendulum.datetime(2012, 9, 1, tz='America/Toronto').is_dst
     True
 
     # Indicates if the instance is in the same timezone as the local timezone

docs/_docs/comparison.rst

@@ -8,8 +8,8 @@ Remember that the comparison is done in the UTC timezone so things aren't always
 
     import pendulum
 
-    first = pendulum.create(2012, 9, 5, 23, 26, 11, 0, tz='America/Toronto')
-    second = pendulum.create(2012, 9, 5, 20, 26, 11, 0, tz='America/Vancouver')
+    first = pendulum.datetime(2012, 9, 5, 23, 26, 11, tz='America/Toronto')
+    second = pendulum.datetime(2012, 9, 5, 20, 26, 11, tz='America/Vancouver')
 
     first.to_datetime_string()
     '2012-09-05 23:26:11'
@@ -58,14 +58,14 @@ The default is ``True`` which determines if its between or equal to the boundari
 
     import pendulum
 
-    first = pendulum.create(2012, 9, 5, 1)
-    second = pendulum.create(2012, 9, 5, 5)
+    first = pendulum.datetime(2012, 9, 5, 1)
+    second = pendulum.datetime(2012, 9, 5, 5)
 
-    pendulum.create(2012, 9, 5, 3).between(first, second)
+    pendulum.datetime(2012, 9, 5, 3).between(first, second)
     True
-    pendulum.create(2012, 9, 5, 3).between(first, second)
+    pendulum.datetime(2012, 9, 5, 3).between(first, second)
     True
-    pendulum.create(2012, 9, 5, 5).between(first, second, False)
+    pendulum.datetime(2012, 9, 5, 5).between(first, second, False)
     False
 
 There are also the ``min_()`` and ``max_()`` methods.
@@ -75,8 +75,8 @@ As usual the default parameter is ``now`` if ``None`` is specified.
 
     import pendulum
 
-    dt1 =  pendulum.create(2012, 1, 1, 0, 0, 0, 0)
-    dt2 =  pendulum.create(2014, 1, 30, 0, 0, 0, 0)
+    dt1 =  pendulum.datetime(2012, 1, 1, 0, 0, 0, 0)
+    dt2 =  pendulum.datetime(2014, 1, 30, 0, 0, 0, 0)
 
     print(dt1.min_(dt2))
     '2012-01-01T00:00:00+00:00'
@@ -104,15 +104,9 @@ the ``now()`` is created in the same timezone as the instance.
 
     dt = pendulum.now()
 
-    dt.is_weekday()
-    dt.is_weekend()
-    dt.is_yesterday()
-    dt.is_today()
-    dt.is_tomorrow()
     dt.is_future()
     dt.is_past()
     dt.is_leap_year()
-    dt.is_same_day(pendulum.now())
 
     born = pendulum.create(1987, 4, 23)
     not_birthday = pendulum.create(2014, 9, 26)

docs/_docs/difference.rst

@@ -17,8 +17,8 @@ This will default to ``True``, return the absolute value. The comparisons are do
 
     import pendulum
 
-    dt_ottawa = pendulum.create(2000, 1, 1, tz='America/Toronto')
-    dt_vancouver = pendulum.create(2000, 1, 1, tz='America/Vancouver')
+    dt_ottawa = pendulum.datetime(2000, 1, 1, tz='America/Toronto')
+    dt_vancouver = pendulum.datetime(2000, 1, 1, tz='America/Vancouver')
 
     dt_ottawa.diff(dt_vancouver).in_hours()
     3
@@ -27,19 +27,19 @@ This will default to ``True``, return the absolute value. The comparisons are do
     dt_vancouver.diff(dt_ottawa, False).in_hours()
     -3
 
-    dt = pendulum.create(2012, 1, 31, 0)
+    dt = pendulum.datetime(2012, 1, 31, 0)
     dt.diff(dt.add(months=1)).in_days()
     29
     dt.diff(dt.subtract(months=1), False).in_days()
     -31
 
-    dt = pendulum.create(2012, 4, 30, 0)
+    dt = pendulum.datetime(2012, 4, 30, 0)
     dt.diff(dt.add(months=1)).in_days()
     30
     dt.diff(dt.add(weeks=1)).in_days()
     7
 
-    dt = pendulum.create(2012, 1, 1, 0)
+    dt = pendulum.datetime(2012, 1, 1, 0)
     dt.diff(dt.add(seconds=59)).in_minutes()
     0
     dt.diff(dt.add(seconds=60)).in_minutes()
@@ -89,7 +89,7 @@ You may also pass ``True`` as a 2nd parameter to remove the modifiers `ago`, `fr
     pendulum.now().diff_for_humans(pendulum.now().subtract(years=1))
     '1 year after'
 
-    dt = pendulum.create(2011, 8, 1)
+    dt = pendulum.datetime(2011, 8, 1)
     dt.diff_for_humans(dt.add(months=1))
     '1 month before'
     dt.diff_for_humans(dt.subtract(months=1))

docs/_docs/fluent_helpers.rst

@@ -14,21 +14,21 @@ setting the timestamp will not set the corresponding timezone to UTC.
 
     dt = pendulum.now()
 
-    dt = dt.year_(1975).month_(5).day_(21).to_datetime_string()
+    dt = dt.set(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()
+    dt.set(hour=22, minute=32, second=5).to_datetime_string()
     '2016-11-16 22:32:05'
 
     dt.on(1975, 5, 21).at(22, 32, 5).to_datetime_string()
     '1975-05-21 22:32:05'
 
-    dt.timestamp_(169957925).timezone_('Europe/London')
+    dt.set(tz='Europe/London')
 
-    dt.tz_('America/Toronto').in_timezone('America/Vancouver')
+    dt.set(tz='America/Toronto').in_timezone('America/Vancouver')
 
 .. note::
 
-    ``timezone_()`` and ``tz_()`` just modify the timezone information without
+    ``set(tz=...)`` just modify the timezone information without
     making any conversion while ``in_timezone()`` converts the time in the
     appropriate timezone.

docs/_docs/instantiation.rst

@@ -2,22 +2,19 @@ Instantiation
 =============
 
 There are several different methods available to create a new instance of Pendulum.
-First there is a constructor. It accepts the same parameters as the standard class.
+First there is a the `datetime()` helper.
 
 .. code-block:: python
 
-    from pendulum import Pendulum
+    import pendulum
 
-    dt = Pendulum(2015, 2, 5, tzinfo='America/Vancouver')
+    dt = pendulum.datetime(2015, 2, 5, tz='America/Vancouver')
     isinstance(dt, datetime)
     True
 
-    dt = Pendulum.now(-5)
-
-You'll notice above that the timezone (2nd) parameter was passed as a string and an integer
-rather than a ``tzinfo`` instance. All timezone parameters have been augmented
-so you can pass a ``tzinfo`` instance, string or integer offset to GMT
-and the timezone will be created for you.
+`datetime()` sets the time to `00:00:00` if it's not specified,
+and the timezone (the `tz` keyword argument) to `UTC`.
+It otherwise can be a `Timezone` instance or simply a string timezone value.
 
 .. note::
 
@@ -44,7 +41,7 @@ and the timezone will be created for you.
          'US/Pacific-New',
          'US/Samoa')
 
-This is again shown in the next example which also introduces the ``now()`` function.
+There is also the ``now()`` helper.
 
 .. code-block:: python
 
@@ -87,7 +84,7 @@ besides behaving as expected, all accept a timezone parameter and each has their
     print(yesterday)
     '2016-06-27T00:00:00-05:00'
 
-The next helper is ``create()`` which allows you to provide
+The next helper is ``datetime()`` which allows you to provide
 as many or as few arguments as you want and will provide default values for all others.
 
 .. code-block:: python
@@ -129,7 +126,7 @@ The difference being the addition the ``tz`` argument that can be a ``tzinfo`` i
 
     Note that it will be the only one supported in the next major version.
 
-The final ``create`` function is for working with unix timestamps.
+The final helper is for working with unix timestamps.
 ``from_timestamp()`` will create a ``Pendulum`` instance equal to the given timestamp
 and will set the timezone as well or default it to ``UTC``.
 
@@ -141,21 +138,6 @@ and will set the timezone as well or default it to ``UTC``.
     pendulum.from_timestamp(-1, 'Europe/London').to_datetime_string()
     '1970-01-01 00:59:59'
 
-    # Using the standard fromtimestamp is also possible
-    pendulum.fromtimestamp(-1).to_datetime_string()
-    '1969-12-31 23:59:59'
-
-You can also create a ``copy()`` of an existing ``Pendulum`` instance.
-As expected the date, time and timezone values are all copied to the new instance.
-
-.. code-block:: python
-
-    dt = pendulum.now()
-    print(dt.diff(dt.copy().add(years=1)).in_years())
-    1
-
-    # dt was unchanged and still holds the value of pendulum.now()
-
 Finally, if you find yourself inheriting a ``datetime`` instance,
 you can create a ``Pendulum`` instance via the ``instance()`` function.
 

docs/_docs/interval.rst

@@ -12,6 +12,8 @@ It has many improvements over the base class.
 
     .. code-block:: python
 
+        import pendulum
+
         d1 = datetime(2012, 1, 1, 1, 2, 3, tzinfo=pytz.UTC)
         d2 = datetime(2011, 12, 31, 22, 2, 3, tzinfo=pytz.UTC)
         delta = d2 - d1
@@ -20,8 +22,8 @@ It has many improvements over the base class.
         delta.seconds
         75600
 
-        d1 = Pendulum(2012, 1, 1, 1, 2, 3)
-        d2 = Pendulum(2011, 12, 31, 22, 2, 3)
+        d1 = pendulum.datetime(2012, 1, 1, 1, 2, 3)
+        d2 = pendulum.datetime(2011, 12, 31, 22, 2, 3)
         delta = d2 - d1
         delta.days
         0
@@ -37,7 +39,6 @@ You can create an instance in the following ways:
 
     import pendulum
 
-    it = pendulum.Interval(days=1177, seconds=7284, microseconds=1234)
     it = pendulum.interval(days=1177, seconds=7284, microseconds=1234)
 
     # You can use an existing timedelta instance
@@ -63,7 +64,7 @@ The ``Interval`` class brings more properties than the default ``days``, ``secon
     1117
 
     # If you want the remaining days not included in full weeks
-    it.remaning_days
+    it.remaining_days
     1
 
     # The remaining number in each unit

docs/_docs/introduction.rst

@@ -16,8 +16,8 @@ For example all comparisons are done in UTC or in the timezone of the datetime b
 
     import pendulum
 
-    dt_toronto = pendulum.create(2012, 1, 1, tz='America/Toronto')
-    dt_vancouver = pendulum.create(2012, 1, 1, tz='America/Vancouver')
+    dt_toronto = pendulum.datetime(2012, 1, 1, tz='America/Toronto')
+    dt_vancouver = pendulum.datetime(2012, 1, 1, tz='America/Vancouver')
 
     print(dt_vancouver.diff(dt_toronto).in_hours())
     3

docs/_docs/localization.rst

@@ -5,9 +5,9 @@ Localization occurs when using the ``format()`` method which accepts a ``locale`
 
 .. code-block:: python
 
-    from pendulum import Pendulum
+    import pendulum
 
-    dt = Pendulum(1975, 5, 21)
+    dt = pendulum.datetime(1975, 5, 21)
 
     dt.format('%A %d %B %Y', locale='de')
     'Mittwoch 21 Mai 1975'
@@ -22,9 +22,10 @@ Localization occurs when using the ``format()`` method which accepts a ``locale`
     .. code-block:: python
 
         import locale
-        from pendulum import Pendulum
 
-        dt = Pendulum(1975, 5, 21)
+        import pendulum
+
+        dt = pendulum.datetime(1975, 5, 21)
 
         locale.setlocale(locale.setlocale(locale.LC_ALL, 'de_DE.UTF-8'))
         dt.format('%A %d %B %Y')