Changes custom directives.

Author: sdispater

docs/index.rst

@@ -227,24 +227,39 @@ you can create a ``Pendulum`` instance via the ``instance()`` function.
 Localization
 ============
 
-Localization occurs naturally when using the ``format()`` method since it relies on the
-native ``strftime`` datetime function.
+Localization occurs when using the ``format()`` method which accepts a ``locale`` keyword.
 
 .. code-block:: python
 
-    import locale
     from pendulum import Pendulum
 
     dt = Pendulum(1975, 5, 21)
 
-    locale.setlocale(locale.setlocale(locale.LC_ALL, 'de_DE.UTF-8'))
-    dt.format('%A %d %B %Y')
+    dt.format('%A %d %B %Y', locale='de')
     'Mittwoch 21 Mai 1975'
 
-    locale.setlocale(locale.LC_ALL, locale.getdefaultlocale())
     dt.format('%A %d %B %Y')
     'Wednesday 21 May 1975'
 
+.. note::
+
+    You can also use the ``strftime()`` method, which behaves exactly like the native one.
+
+    .. code-block:: python
+
+        import locale
+        from pendulum import Pendulum
+
+        dt = Pendulum(1975, 5, 21)
+
+        locale.setlocale(locale.setlocale(locale.LC_ALL, 'de_DE.UTF-8'))
+        dt.format('%A %d %B %Y')
+        'Mittwoch 21 Mai 1975'
+
+        locale.setlocale(locale.LC_ALL, locale.getdefaultlocale())
+        dt.format('%A %d %B %Y')
+        'Wednesday 21 May 1975'
+
 ``diff_for_humans()`` is also localized, you can set the Pendulum locale
 by using the class method ``pendulum.set_locale()``.
 
@@ -448,13 +463,13 @@ Custom Directives
 -----------------
 
 Apart from the `default directives <For localization support see the Localization section.>`_,
-Pendulum comes with its own:
+Pendulum comes with its own (each custom directive is in the form ``%_{directive}``):
 
 ===========  ======================================================================== =================================
 Directive    Meaning                                                                  Example
 ===========  ======================================================================== =================================
-``%P``       Difference to Greenwich time (GMT) with colon between hours and minutes  ``+02:00``
-``%t``       English ordinal suffix for the day of the month, 2 characters            ``st``, ``nd``, ``rd`` or ``th``
+``%_z``      Difference to Greenwich time (GMT) with colon between hours and minutes  ``+02:00``
+``%_t``      Ordinal suffix for the day of the month, 2 characters                    ``st``, ``nd``, ``rd`` or ``th``
 ===========  ======================================================================== =================================
 
 Common Formats

pendulum/pendulum.py

@@ -56,19 +56,19 @@ class Pendulum(datetime.datetime, TranslatableMixin):
     SECONDS_PER_MINUTE = 60
 
     # Formats
-    ATOM = '%Y-%m-%dT%H:%M:%S%P'
+    ATOM = '%Y-%m-%dT%H:%M:%S%_z'
     COOKIE = '%A, %d-%b-%Y %H:%M:%S %Z'
-    ISO8601 = '%Y-%m-%dT%H:%M:%S%P'
-    ISO8601_EXTENDED = '%Y-%m-%dT%H:%M:%S.%f%P'
+    ISO8601 = '%Y-%m-%dT%H:%M:%S%_z'
+    ISO8601_EXTENDED = '%Y-%m-%dT%H:%M:%S.%f%_z'
     RFC822 = '%a, %d %b %y %H:%M:%S %z'
     RFC850 = '%A, %d-%b-%y %H:%M:%S %Z'
     RFC1036 = '%a, %d %b %y %H:%M:%S %z'
     RFC1123 = '%a, %d %b %Y %H:%M:%S %z'
     RFC2822 = '%a, %d %b %Y %H:%M:%S %z'
-    RFC3339 = '%Y-%m-%dT%H:%M:%S%P'
-    RFC3339_EXTENDED = '%Y-%m-%dT%H:%M:%S.%f%P'
+    RFC3339 = '%Y-%m-%dT%H:%M:%S%_z'
+    RFC3339_EXTENDED = '%Y-%m-%dT%H:%M:%S.%f%_z'
     RSS = '%a, %d %b %Y %H:%M:%S %z'
-    W3C = '%Y-%m-%dT%H:%M:%S%P'
+    W3C = '%Y-%m-%dT%H:%M:%S%_z'
 
     # Default format to use for __str__ method when type juggling occurs.
     DEFAULT_TO_STRING_FORMAT = None
@@ -92,7 +92,7 @@ class Pendulum(datetime.datetime, TranslatableMixin):
 
     _EPOCH = datetime.datetime(1970, 1, 1, tzinfo=pytz.UTC)
 
-    _CUSTOM_FORMATTERS = ['P', 't']
+    _CUSTOM_FORMATTERS = ['_z', '_t']
     _FORMATTERS_REGEX = re.compile('%%(%s)' % '|'.join(_CUSTOM_FORMATTERS))
 
     _MODIFIERS_VALID_UNITS = ['day', 'week', 'month', 'year', 'decade', 'century']
@@ -924,7 +924,7 @@ def _strftime(self, m, locale=None):
 
         fmt = m.group(1)
 
-        if fmt == 'P':
+        if fmt == '_z':
             offset = self._datetime.utcoffset() or datetime.timedelta()
             minutes = offset.total_seconds() / 60
 
@@ -936,7 +936,7 @@ def _strftime(self, m, locale=None):
             hour, minute = divmod(abs(int(minutes)), 60)
 
             return '{0}{1:02d}:{2:02d}'.format(sign, hour, minute)
-        elif fmt == 't':
+        elif fmt == '_t':
             translation = self.translator().transchoice('ordinal', self.day, locale=locale)
             if translation == 'ordinal':
                 translation = ''

tests/localization_tests/test_fr.py

@@ -73,5 +73,5 @@ def format(self):
         self.assertEqual('janvier', d.format('%B'))
         self.assertEqual('janv', d.format('%b'))
         self.assertEqual('', d.format('%p'))
-        self.assertEqual('er', d.format('%t'))
-        self.assertEqual('e', d.add(days=1).format('%t'))
+        self.assertEqual('er', d.format('%_t'))
+        self.assertEqual('e', d.add(days=1).format('%_t'))

tests/pendulum_tests/test_strings.py

@@ -101,7 +101,7 @@ def test_to_w3c_string(self):
 
     def test_custom_formatters(self):
         d = Pendulum(1975, 12, 25, 14, 15, 16, tzinfo='local')
-        self.assertEqual('Thursday 25th of December 1975 02:15:16 PM -05:00', d.format('%A %-d%t of %B %Y %I:%M:%S %p %P'))
+        self.assertEqual('Thursday 25th of December 1975 02:15:16 PM -05:00', d.format('%A %-d%_t of %B %Y %I:%M:%S %p %_z'))
 
     def test_repr(self):
         d = Pendulum(1975, 12, 25, 14, 15, 16, tzinfo='local')
@@ -110,4 +110,4 @@ def test_repr(self):
     def test_format_with_locale(self):
         d = Pendulum(1975, 12, 25, 14, 15, 16, tzinfo='local')
         self.assertEqual('jeudi 25e jour de décembre 1975 02:15:16  -05:00',
-                         d.format('%A %-d%t jour de %B %Y %I:%M:%S %p %P', locale='fr'))
+                         d.format('%A %-d%_t jour de %B %Y %I:%M:%S %p %_z', locale='fr'))