Repository: crsmithdev/arrow
Pull request #614 (2019-07-14 18:45:30)

Added escaping to docs
I also removed the version locks from `requirements.txt` to force the latest versions of the packages to be installed.

Related to the discussion here: https://github.com/crsmithdev/arrow/issues/35


Patch:
diff --git a/arrow/factory.py b/arrow/factory.py
index 437fe44..ba705d3 100644
--- a/arrow/factory.py
+++ b/arrow/factory.py
@@ -153,6 +153,13 @@ class ArrowFactory(object):
         locale = kwargs.get("locale", "en_us")
         tz = kwargs.get("tzinfo", None)
 
+        # if kwargs given, send to constructor unless only tzinfo provided.
+        if len(kwargs) > 1:
+            arg_count = 3
+        if len(kwargs) == 1:
+            if not isinstance(tz, tzinfo):
+                arg_count = 3
+
         # () -> now, @ utc.
         if arg_count == 0:
             if isinstance(tz, tzinfo):
diff --git a/docs/index.rst b/docs/index.rst
index f359331..1f9cd1a 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -307,8 +307,8 @@ Then get and use a factory for it:
     >>> custom.days_till_xmas()
     >>> 211
 
-Tokens
-~~~~~~
+Supported Tokens
+~~~~~~~~~~~~~~~~
 
 Use the following tokens in parsing and formatting.  Note that they're not the same as the tokens for `strptime(3) <https://www.gnu.org/software/libc/manual/html_node/Low_002dLevel-Time-String-Parsing.html#index-strptime>`_:
 
@@ -374,13 +374,6 @@ Use the following tokens in parsing and formatting.  Note that they're not the s
 |**Timestamp**                   |X             |1381685817                                 |
 +--------------------------------+--------------+-------------------------------------------+
 
-Any token can be escaped when parsing by enclosing it within square brackets:
-
-.. code-block:: python
-
-    >>> arrow.get("2018-03-09 8 h 40", "YYYY-MM-DD h [h] m")
-    <Arrow [2018-03-09T08:40:00+00:00]>
-
 .. rubric:: Footnotes
 
 .. [#t1] localization support for parsing and formatting
@@ -389,6 +382,49 @@ Any token can be escaped when parsing by enclosing it within square brackets:
 .. [#t4] timezone names from `tz database <https://www.iana.org/time-zones>`_ provided via dateutil package
 .. [#t5] support for the DDD and DDDD tokens will be added in a future release
 
+Escaping Formats
+~~~~~~~~~~~~~~~~
+
+Tokens, phrases, and regular expressions in a format string can be escaped when parsing by enclosing them within square brackets.
+
+Tokens & Phrases
+++++++++++++++++
+
+Any `token <Supported Tokens_>`_ or phrase can be escaped as follows:
+
+.. code-block:: python
+
+    >>> fmt = "YYYY-MM-DD h [h] m"
+    >>> arrow.get("2018-03-09 8 h 40", fmt)
+    <Arrow [2018-03-09T08:40:00+00:00]>
+
+    >>> fmt = "YYYY-MM-DD h [hello] m"
+    >>> arrow.get("2018-03-09 8 hello 40", fmt)
+    <Arrow [2018-03-09T08:40:00+00:00]>
+
+    >>> fmt = "YYYY-MM-DD h [hello world] m"
+    >>> arrow.get("2018-03-09 8 hello world 40", fmt)
+    <Arrow [2018-03-09T08:40:00+00:00]>
+
+This can be useful for parsing dates in different locales such as French, in which it is common to format time strings as "8 h 40" rather than "8:40".
+
+Regular Expressions
++++++++++++++++++++
+
+You can also escape regular expressions by enclosing them within square brackets. In the following example, we are using the regular expression :code:`\s+` to match any number of whitespace characters that separate the tokens. This is useful if you do not know the number of spaces between tokens ahead of time (e.g. in log files).
+
+.. code-block:: python
+
+    >>> fmt = r"ddd[\s+]MMM[\s+]DD[\s+]HH:mm:ss[\s+]YYYY"
+    >>> arrow.get("Mon Sep 08 16:41:45 2014", fmt)
+    <Arrow [2014-09-08T16:41:45+00:00]>
+
+    >>> arrow.get("Mon \tSep 08   16:41:45     2014", fmt)
+    <Arrow [2014-09-08T16:41:45+00:00]>
+
+    >>> arrow.get("Mon Sep 08   16:41:45   2014", fmt)
+    <Arrow [2014-09-08T16:41:45+00:00]>
+
 API Guide
 ---------
 
diff --git a/requirements.txt b/requirements.txt
index d5ca714..ac54277 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -2,9 +2,9 @@ backports.functools_lru_cache==1.5.0
 chai==1.1.2
 nose==1.3.7
 nose-cov==1.6
-pre-commit==1.16.1
+pre-commit==1.17.0
 python-dateutil==2.8.0
 pytz==2019.1
 simplejson==3.16.0
 sphinx==1.8.5; python_version == '2.7'
-sphinx==2.0.1; python_version >= '3.5'
+sphinx==2.1.2; python_version >= '3.5'


Test patch:
diff --git a/tests/factory_tests.py b/tests/factory_tests.py
index 21e5ae4..416530e 100644
--- a/tests/factory_tests.py
+++ b/tests/factory_tests.py
@@ -221,6 +221,46 @@ class GetTests(Chai):
             self.factory.get(2013, 1, 1), datetime(2013, 1, 1, tzinfo=tz.tzutc())
         )
 
+    def test_full_kwargs(self):
+
+        self.assertEqual(
+            self.factory.get(
+                year=2016,
+                month=7,
+                day=14,
+                hour=7,
+                minute=16,
+                second=45,
+                microsecond=631092,
+            ),
+            datetime(2016, 7, 14, 7, 16, 45, 631092, tzinfo=tz.tzutc()),
+        )
+
+    def test_three_kwargs(self):
+
+        self.assertEqual(
+            self.factory.get(year=2016, month=7, day=14),
+            datetime(2016, 7, 14, 0, 0, tzinfo=tz.tzutc()),
+        )
+
+    def test_insufficient_kwargs(self):
+
+        with self.assertRaises(TypeError):
+            self.factory.get(year=2016)
+
+        with self.assertRaises(TypeError):
+            self.factory.get(year=2016, month=7)
+
+    def test_locale_kwarg_only(self):
+
+        with self.assertRaises(TypeError):
+            self.factory.get(locale="ja")
+
+    def test_locale_with_tzinfo(self):
+
+        with self.assertRaises(TypeError):
+            self.factory.get(locale="ja", tzinfo=tz.gettz("Asia/Tokyo"))
+
 
 class UtcNowTests(Chai):
     def setUp(self):