Adds a strict keyword argument to parse() to get the type matching the parsed string.

Author: sdispater

CHANGELOG.md

@@ -5,6 +5,7 @@
 ### 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.
 
 ### Changed
 

docs/_docs/instantiation.rst

@@ -138,3 +138,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 time
+    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]>

pendulum/__init__.py

@@ -1,5 +1,6 @@
 # -*- coding: utf-8 -*-
 
+# Types
 from .pendulum import Pendulum
 from .date import Date
 from .time import Time
@@ -44,8 +45,9 @@
 get_formatter = Global.get_formatter
 
 # Helpers
+from .parser import parse
+
 instance = Pendulum.instance
-parse = Pendulum.parse
 now = Pendulum.now
 utcnow = Pendulum.utcnow
 today = Pendulum.today

pendulum/parser.py

@@ -0,0 +1,71 @@
+# -*- coding: utf-8 -*-
+
+from __future__ import division
+
+from .parsing import Parser as BaseParser
+from .tz import UTC
+from .pendulum import Pendulum
+from .date import Date
+from .time import Time
+from ._global import Global
+
+
+class Parser(BaseParser):
+    """
+    Parser that returns known types (Pendulum, Date, Time)
+    """
+
+    def parse(self, text):
+        """
+        Parses a string with the given options.
+
+        :param text: The string to parse.
+        :type text: str
+
+        :rtype: mixed
+        """
+        parsed = super(Parser, self).parse(text)
+
+        if not self.is_strict():
+            return self._create_pendulum_object(parsed)
+
+        # Checking for date
+        if 'year' in parsed:
+            # Checking for time
+            if 'hour' in parsed:
+                return self._create_pendulum_object(parsed)
+            else:
+                return self._create_date_object(parsed)
+
+        return self._create_time_object(parsed)
+
+    def _create_pendulum_object(self, parsed):
+        if parsed['offset'] is None:
+            tz = self._options.get('tz', UTC)
+        else:
+            tz = parsed['offset'] / 3600
+
+        return Pendulum(
+            parsed['year'], parsed['month'], parsed['day'],
+            parsed['hour'], parsed['minute'], parsed['second'],
+            parsed['subsecond'] // 1000,
+            tzinfo=tz
+        )
+
+    def _create_date_object(self, parsed):
+        return Date(
+            parsed['year'], parsed['month'], parsed['day']
+        )
+
+    def _create_time_object(self, parsed):
+        return Time(
+            parsed['hour'], parsed['minute'], parsed['second'],
+            parsed['subsecond'] // 1000
+        )
+
+
+def parse(text, **options):
+    # Use the mock now value if it exists
+    options['now'] = options.get('now', Global.get_test_now())
+
+    return Parser(**options).parse(text)

pendulum/parsing/__init__.py

@@ -13,7 +13,7 @@ def parse(text, **options):
     :param options: The parsing options.
     :type options: dict
 
-    :rtype: Pendulum or Span
+    :rtype: dict
 
     :raises: ParserError
     """