Merge branch 'develop'

Author: sdispater

CHANGELOG.md

@@ -2,9 +2,21 @@
 
 ## [Unreleased]
 
-### Fixed
+### Added
+
+- Added `on()` and `at()` methods which replace `with_date()` and `with_time()`.
+- Added a `strict` keyword argument to `parse()` to get the type matching the parsed string.
+- Added the ability to pass an amount to the `range()` method to control the length of the gap.
+- Added a `datetime()` helper method to the `Timezone` class.
+
+### Changed
+
+- Improved parsing of ISO 8601 strings.
+
+### Deprecated
 
-- Fixed parsing of some ISO 8601 strings.
+- `with_date()` and `with_time()` are deprecated. Use `on()` and `at()` instead.
+- `create_from_date()` and `create_from_time()` are deprecated. Use `create()` instead.
 
 
 ## [0.7.0] - 2016-12-07

README.rst

@@ -120,6 +120,53 @@ Those are a few examples showing that Arrow cannot always be trusted to have a c
 behavior with the data you are passing to it.
 
 
+Limitations
+===========
+
+Even though the ``Pendulum`` class is a subclass of ``datetime`` there are some rare cases where
+it can't replace the native class directly. Here is a list (non-exhaustive) of the reported cases with
+a possible solution, if any:
+
+* ``sqlite3`` will use the the ``type()`` function to determine the type of the object by default. To work around it you can register a new adapter:
+
+.. code-block:: python
+
+    from pendulum import Pendulum
+    from sqlite3 import register_adapter
+
+    register_adapter(Pendulum, lambda val: val.isoformat(' '))
+
+* ``mysqlclient`` (former ``MySQLdb``) and ``PyMySQL`` will use the the ``type()`` function to determine the type of the object by default. To work around it you can register a new adapter:
+
+.. code-block:: python
+
+    import MySQLdb.converters
+    import pymysql.converters
+
+    from pendulum import Pendulum
+
+    MySQLdb.converters.conversions[Pendulum] = MySQLdb.converters.DateTime2literal
+    pymysql.converters.conversions[Pendulum] = pymysql.converters.escape_datetime
+
+* ``django`` will use the ``isoformat()`` method to store datetimes in the database. However since ``pendulum`` is always timezone aware the offset information will always be returned by ``isoformat()`` raising an error, at least for MySQL databases. To work around it you can either create your own ``DateTimeField`` or use the previous workaround for ``MySQLdb``:
+
+.. code-block:: python
+
+    from django.db.models import DateTimeField as BaseDateTimeField
+    from pendulum import Pendulum
+
+
+    class DateTimeField(BaseDateTimeField):
+
+        def value_to_string(self, obj):
+            val = self.value_from_object(obj)
+
+            if isinstance(value, Pendulum):
+                return value.to_datetime_string()
+
+            return '' if val is None else val.isoformat()
+
+
 Resources
 =========
 

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.from_date(1975, 5, 21).age
+    pendulum.create(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.from_date(2012, 1, 1, 'America/Toronto').is_dst
+    pendulum.create(2012, 1, 1, tz='America/Toronto').is_dst
     False
-    pendulum.from_date(2012, 9, 1, 'America/Toronto').is_dst
+    pendulum.create(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

@@ -114,9 +114,9 @@ the ``now()`` is created in the same timezone as the instance.
     dt.is_leap_year()
     dt.is_same_day(Pendulum.now())
 
-    born = pendulum.from_date(1987, 4, 23)
-    not_birthday = pendulum.from_date(2014, 9, 26)
-    birthday = pendulum.from_date(2014, 2, 23)
+    born = pendulum.create(1987, 4, 23)
+    not_birthday = pendulum.create(2014, 9, 26)
+    birthday = pendulum.create(2014, 2, 23)
     past_birthday = pendulum.now().subtract(years=50)
 
     born.is_birthday(not_birthday)

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.from_date(2000, 1, 1, 'America/Toronto')
-    dt_vancouver = pendulum.from_date(200, 1, 1, 'America/Vancouver')
+    dt_ottawa = pendulum.create(2000, 1, 1, tz='America/Toronto')
+    dt_vancouver = pendulum.create(2000, 1, 1, tz='America/Vancouver')
 
     dt_ottawa.diff(dt_vancouver).in_hours()
     3
@@ -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.from_date(2011, 8, 1)
+    dt = pendulum.create(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

@@ -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')

docs/_docs/instantiation.rst

@@ -61,29 +61,17 @@ besides behaving as expected, all accept a timezone parameter and each has their
     print(yesterday)
     '2016-06-27T00:00:00-05:00'
 
-The next group of static helpers are the ``from_xxx()`` and ``create()`` helpers.
-Most of the static ``create`` functions allow you to provide
+The next helper is ``create()`` which allows you to provide
 as many or as few arguments as you want and will provide default values for all others.
-Generally default values are the current date, time set to ``00:00:00`` and ``UTC`` timezone.
 
 .. code-block:: python
 
-    pendulum.from_date(year, month, day, tz)
-    pendulum.from_time(hour, minute, second, microsecond, tz)
     pendulum.create(year, month, day, hour, minute, second, microsecond, tz)
 
-``from_date()`` will default the time to ``00:00:00``. ``from_time()`` will default the date to today.
 ``create()`` will default any null parameter to the current date for the date part and to ``00:00:00`` for time.
-As before, the ``tz`` defaults to the ``UTC`` timezone and otherwise can be a ``TimezoneInfo`` instance
+As before, the ``tz`` defaults to the ``UTC`` timezone and otherwise can be a ``Timezone`` instance
 or simply a string timezone value.
 
-.. code-block:: python
-
-    xmas_this_year = pendulum.from_date(None, 12, 25)
-    # Year defaults to current year
-    y2k = pendulum.create(2000, 1, 1, 0, 0, 0)
-    noon_london_tz = pendulum.from_time(12, 0, 0, tz='Europe/London')
-
 .. code-block:: python
 
     pendulum.from_format(time, format, tz)
@@ -138,3 +126,118 @@ you can create a ``Pendulum`` instance via the ``instance()`` function.
     p = pendulum.instance(dt)
     print(p.to_datetime_string())
     '2008-01-01 00:00:00'
+
+Parsing
+-------
+
+You can also instantiate ``Pendulum`` instances by passing a string to the ``parse()`` method.
+
+.. code-block:: python
+
+    import pendulum
+
+    dt = pendulum.parse('1975-05-21 22:00:00')
+    print(dt)
+    '1975-05-21T22:00:00+00:00
+
+The library natively supports the RFC 3339 format, most ISO 8601 formats and some other common formats. If you pass a non-standard or more complicated
+string, the library will fallback on the `dateutil <https://dateutil.readthedocs.io>`_ parser.
+
+RFC 3339
+~~~~~~~~
+
++-----------------------------------+-------------------------------------------+
+|String                             |Output                                     |
++===================================+===========================================+
+|1996-12-19T16:39:57-08:00          |1996-12-19T16:39:57-08:00                  |
++-----------------------------------+-------------------------------------------+
+|1990-12-31T23:59:59Z               |1990-12-31T23:59:59+00:00                  |
++-----------------------------------+-------------------------------------------+
+
+ISO 8601
+~~~~~~~~
+
+Datetime
+++++++++
+
++-----------------------------------+-------------------------------------------+
+|String                             |Output                                     |
++===================================+===========================================+
+|20161001T143028+0530               |2016-10-01T14:30:28+05:30                  |
++-----------------------------------+-------------------------------------------+
+|20161001T14                        |2016-10-01T14:00:00+00:00                  |
++-----------------------------------+-------------------------------------------+
+
+Date
+++++
+
++-----------------------------------+-------------------------------------------+
+|String                             |Output                                     |
++===================================+===========================================+
+|2012                               |2012-01-01T00:00:00+00:00                  |
++-----------------------------------+-------------------------------------------+
+|2012-05-03                         |2012-05-03T00:00:00+00:00                  |
++-----------------------------------+-------------------------------------------+
+|20120503                           |2012-05-03T00:00:00+00:00                  |
++-----------------------------------+-------------------------------------------+
+|2012-05                            |2016-10-01T14:00:00+00:00                  |
++-----------------------------------+-------------------------------------------+
+
+Ordinal day
++++++++++++
+
++-----------------------------------+-------------------------------------------+
+|String                             |Output                                     |
++===================================+===========================================+
+|2012-007                           |2012-01-07T00:00:00+00:00                  |
++-----------------------------------+-------------------------------------------+
+|2012007                            |2012-01-07T00:00:00+00:00                  |
++-----------------------------------+-------------------------------------------+
+
+Week number
++++++++++++
+
++-----------------------------------+-------------------------------------------+
+|String                             |Output                                     |
++===================================+===========================================+
+|2012-W05                           |2012-01-30T00:00:00+00:00                  |
++-----------------------------------+-------------------------------------------+
+|2012W05                            |2012-01-30T00:00:00+00:00                  |
++-----------------------------------+-------------------------------------------+
+|2012-W05-5                         |2012-02-03T00:00:00+00:00                  |
++-----------------------------------+-------------------------------------------+
+|2012W055                           |2012-02-03T00:00:00+00:00                  |
++-----------------------------------+-------------------------------------------+
+
+Time
+++++
+
+When passing only time information the date will default to today.
+
++-----------------------------------+-------------------------------------------+
+|String                             |Output                                     |
++===================================+===========================================+
+|00:00                              |2016-12-17T00:00:00+00:00                  |
++-----------------------------------+-------------------------------------------+
+|12:04:23                           |2016-12-17T12:04:23+00:00                  |
++-----------------------------------+-------------------------------------------+
+|120423                             |2016-12-17T12:04:23+00:00                  |
++-----------------------------------+-------------------------------------------+
+|12:04:23.45                        |2016-12-17T12:04:23.450000+00:00           |
++-----------------------------------+-------------------------------------------+
+
+
+.. note::
+
+    You can pass the ``strict`` keyword argument to ``parse()`` to get the exact type
+    that the string represents:
+
+    .. code-block:: python
+
+        import pendulum
+
+        pendulum.parse('2012-05-03', strict=True)
+        # <Date [2012-05-03]>
+
+        pendulum.parse('12:04:23', strict=True)
+        # <Time [12:04:23]>

docs/_docs/introduction.rst

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

docs/_docs/limitations.rst

@@ -0,0 +1,45 @@
+Limitations
+===========
+
+Even though the ``Pendulum`` class is a subclass of ``datetime`` there are some rare cases where
+it can't replace the native class directly. Here is a list (non-exhaustive) of the reported cases with
+a possible solution, if any:
+
+* ``sqlite3`` will use the the ``type()`` function to determine the type of the object by default. To work around it you can register a new adapter:
+
+.. code-block:: python
+
+    from pendulum import Pendulum
+    from sqlite3 import register_adapter
+
+    register_adapter(Pendulum, lambda val: val.isoformat(' '))
+
+* ``mysqlclient`` (former ``MySQLdb``) and ``PyMySQL`` will use the the ``type()`` function to determine the type of the object by default. To work around it you can register a new adapter:
+
+.. code-block:: python
+
+    import MySQLdb.converters
+    import pymysql.converters
+
+    from pendulum import Pendulum
+
+    MySQLdb.converters.conversions[Pendulum] = MySQLdb.converters.DateTime2literal
+    pymysql.converters.conversions[Pendulum] = pymysql.converters.escape_datetime
+
+* ``django`` will use the ``isoformat()`` method to store datetimes in the database. However since ``pendulum`` is always timezone aware the offset information will always be returned by ``isoformat()`` raising an error, at least for MySQL databases. To work around it you can either create your own ``DateTimeField`` or use the previous workaround for ``MySQLdb``:
+
+.. code-block:: python
+
+    from django.db.models import DateTimeField as BaseDateTimeField
+    from pendulum import Pendulum
+
+
+    class DateTimeField(BaseDateTimeField):
+
+        def value_to_string(self, obj):
+            val = self.value_from_object(obj)
+
+            if isinstance(value, Pendulum):
+                return value.to_datetime_string()
+
+            return '' if val is None else val.isoformat()

docs/_docs/period.rst

@@ -133,6 +133,19 @@ If you want to iterate over a period, you can use the ``range()`` method:
 
     If you just want a generator you can use the ``xrange()`` method.
 
+You can pass an amount for the passed unit to control the length of the gap:
+
+.. code-block:: python
+
+    for dt in period.range('days', 2):
+        print(dt)
+
+    '2000-01-01T00:00:00+00:00'
+    '2000-01-03T00:00:00+00:00'
+    '2000-01-05T00:00:00+00:00'
+    '2000-01-07T00:00:00+00:00'
+    '2000-01-09T00:00:00+00:00'
+
 You can also directly iterate over the ``Period`` instance, the unit will be ``days`` in this case:
 
 .. code-block:: python