Skip to content

Commit 3c5a6dc

Browse files
sdispatersdispater
committed
Adds support for setting formatter locally
1 parent 1ad952e commit 3c5a6dc

File tree

5 files changed

+228
-20
lines changed

5 files changed

+228
-20
lines changed

‎docs/index.rst‎

Lines changed: 166 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -399,6 +399,28 @@ setting the timestamp will not set the corresponding timezone to UTC.
399399
String Formatting
400400
=================
401401

402+
.. versionadded:: 0.6
403+
404+
Pendulum now supports an alternative formatter. It can either be set locally
405+
when calling the ``format()`` method or set globally by using ``pendulum.set_formatter()``.
406+
407+
.. code-block:: python
408+
409+
import pendulum
410+
411+
dt = pendulum.Pendulum(1975, 12, 25, 14, 15, 16)
412+
dt.format('YYYY-MM-DD HH:mm:ss', formatter='alternative')
413+
'1975-12-25 14:15:16'
414+
415+
pendulum.set_formatter('alternative')
416+
dt.format('YYYY-MM-DD HH:mm:ss')
417+
'1975-12-25 14:15:16'
418+
419+
# Reset to default formatter
420+
pendulum.set_formatter()
421+
422+
See `Alternative Formatter`_ for more information
423+
402424
All the ``to_xxx_string()`` methods rely on the native ``datetime.strftime()`` with additional
403425
directives available.
404426
The ``__str__`` magic method is defined which allows ``Pendulum`` instances to be printed
@@ -456,6 +478,11 @@ You can also set the default ``__str__`` format.
456478

457479
For localization support see the `Localization`_ section.
458480

481+
.. warning::
482+
483+
Even if you have set the default formatter to the alternative one (See `Alternative Formatter`_),
484+
the ``__str__`` format must still be in the default format (ie the standard Python format).
485+
459486
Custom Directives
460487
-----------------
461488

@@ -513,6 +540,145 @@ The following are methods to display a ``Pendulum`` instance as a common format:
513540
dt.to_w3c_string()
514541
'1975-12-25T14:15:16-05:00'
515542
543+
Alternative formatter
544+
---------------------
545+
546+
Pendulum supports an alternative format when using the ``format()`` method.
547+
This format is more intuitive to use than the default one and supports more
548+
directives.
549+
You can use this format either locally when calling the ``format()`` method
550+
or globally by using ``pendulum.set_formatter()``.
551+
552+
.. code-block:: python
553+
554+
import pendulum
555+
556+
dt = pendulum.Pendulum(1975, 12, 25, 14, 15, 16)
557+
dt.format('YYYY-MM-DD HH:mm:ss', formatter='alternative')
558+
'1975-12-25 14:15:16'
559+
560+
pendulum.set_formatter('alternative')
561+
dt.format('YYYY-MM-DD HH:mm:ss')
562+
'1975-12-25 14:15:16'
563+
564+
# Reset to default formatter
565+
pendulum.set_formatter()
566+
567+
Tokens
568+
~~~~~~
569+
570+
The following tokens are currently supported:
571+
572+
573+
+--------------------------------+--------------+-------------------------------------------+
574+
| |Token |Output |
575+
+================================+==============+===========================================+
576+
|**Year** |YYYY |2000, 2001, 2002 ... 2012, 2013 |
577+
+--------------------------------+--------------+-------------------------------------------+
578+
| |YY |00, 01, 02 ... 12, 13 |
579+
+--------------------------------+--------------+-------------------------------------------+
580+
|**Quarter** |Q |1 2 3 4 |
581+
+--------------------------------+--------------+-------------------------------------------+
582+
| |Qo |1st 2nd 3rd 4th |
583+
+--------------------------------+--------------+-------------------------------------------+
584+
|**Month** |MMMM |January, February, March ... |
585+
+--------------------------------+--------------+-------------------------------------------+
586+
| |MMM |Jan, Feb, Mar ... |
587+
+--------------------------------+--------------+-------------------------------------------+
588+
| |MM |01, 02, 03 ... 11, 12 |
589+
+--------------------------------+--------------+-------------------------------------------+
590+
| |M |1, 2, 3 ... 11, 12 |
591+
+--------------------------------+--------------+-------------------------------------------+
592+
| |Mo |1st 2nd ... 11th 12th |
593+
+--------------------------------+--------------+-------------------------------------------+
594+
|**Day of Year** |DDDD |001, 002, 003 ... 364, 365 |
595+
+--------------------------------+--------------+-------------------------------------------+
596+
| |DDD |1, 2, 3 ... 4, 5 |
597+
+--------------------------------+--------------+-------------------------------------------+
598+
|**Day of Month** |DD |01, 02, 03 ... 30, 31 |
599+
+--------------------------------+--------------+-------------------------------------------+
600+
| |D |1, 2, 3 ... 30, 31 |
601+
+--------------------------------+--------------+-------------------------------------------+
602+
| |Do |1st, 2nd, 3rd ... 30th, 31st |
603+
+--------------------------------+--------------+-------------------------------------------+
604+
|**Day of Week** |dddd |Monday, Tuesday, Wednesday ... |
605+
+--------------------------------+--------------+-------------------------------------------+
606+
| |ddd |Mon, Tue, Wed ... |
607+
+--------------------------------+--------------+-------------------------------------------+
608+
| |d |1, 2, 3 ... 6, 7 |
609+
+--------------------------------+--------------+-------------------------------------------+
610+
|**Hour** |HH |00, 01, 02 ... 23, 24 |
611+
+--------------------------------+--------------+-------------------------------------------+
612+
| |H |0, 1, 2 ... 23, 24 |
613+
+--------------------------------+--------------+-------------------------------------------+
614+
| |hh |01, 02, 03 ... 11, 12 |
615+
+--------------------------------+--------------+-------------------------------------------+
616+
| |h |1, 2, 3 ... 11, 12 |
617+
+--------------------------------+--------------+-------------------------------------------+
618+
|**Minute** |mm |00, 01, 02 ... 58, 59 |
619+
+--------------------------------+--------------+-------------------------------------------+
620+
| |m |0, 1, 2 ... 58, 59 |
621+
+--------------------------------+--------------+-------------------------------------------+
622+
|**Second** |ss |00, 01, 02 ... 58, 59 |
623+
+--------------------------------+--------------+-------------------------------------------+
624+
| |s |0, 1, 2 ... 58, 59 |
625+
+--------------------------------+--------------+-------------------------------------------+
626+
|**Fractional Second** |S |0 1 ... 8 9 |
627+
+--------------------------------+--------------+-------------------------------------------+
628+
| |SS |00, 01, 02 ... 98, 99 |
629+
+--------------------------------+--------------+-------------------------------------------+
630+
| |SSS |000 001 ... 998 999 |
631+
+--------------------------------+--------------+-------------------------------------------+
632+
| |SSSS ... |000[0..] 001[0..] ... 998[0..] 999[0..] |
633+
| |SSSSSS | |
634+
+--------------------------------+--------------+-------------------------------------------+
635+
|**AM / PM** |A |AM, PM |
636+
+--------------------------------+--------------+-------------------------------------------+
637+
|**Timezone** |ZZ |-07:00, -06:00 ... +06:00, +07:00 |
638+
+--------------------------------+--------------+-------------------------------------------+
639+
| |Z |-0700, -0600 ... +0600, +0700 |
640+
+--------------------------------+--------------+-------------------------------------------+
641+
| |zz |Asia/Baku, Europe/Warsaw, GMT ... |
642+
+--------------------------------+--------------+-------------------------------------------+
643+
| |z |EST CST ... MST PST |
644+
+--------------------------------+--------------+-------------------------------------------+
645+
|**Timestamp** |X |1381685817 |
646+
+--------------------------------+--------------+-------------------------------------------+
647+
648+
Localized Formats
649+
~~~~~~~~~~~~~~~~~
650+
651+
Because preferred formatting differs based on locale,
652+
there are a few tokens that can be used to format an instance based on its locale.
653+
654+
+--------------------------------------------+--------------+-------------------------------------------+
655+
|**Time** |LT |8:30 PM |
656+
+--------------------------------------------+--------------+-------------------------------------------+
657+
|**Time with seconds** |LTS |8:30:25 PM |
658+
+--------------------------------------------+--------------+-------------------------------------------+
659+
|**Month numeral, day of month, year** |L |09/04/1986 |
660+
+--------------------------------------------+--------------+-------------------------------------------+
661+
|**Month name, day of month, year** |LL |September 4 1986 |
662+
+--------------------------------------------+--------------+-------------------------------------------+
663+
|**Month name, day of month, year, time** |LLL |September 4 1986 8:30 PM |
664+
+--------------------------------------------+--------------+-------------------------------------------+
665+
|**Month name, day of month, day of week,** |LLLL |Thursday, September 4 1986 8:30 PM |
666+
|**year, time** | | |
667+
+--------------------------------------------+--------------+-------------------------------------------+
668+
669+
Escaping Characters
670+
~~~~~~~~~~~~~~~~~~~
671+
672+
To escape characters in format strings, you can wrap the characters in square brackets.
673+
674+
.. code-block:: python
675+
676+
import pendulum
677+
678+
pendulum.now().format('[today] dddd', formatter='alternative')
679+
'today Sunday'
680+
681+
516682
517683
Comparison
518684
==========

‎pendulum/__init__.py‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,8 @@
4646
reset_to_string_format = Pendulum.reset_to_string_format
4747
set_transition_rule = Pendulum.set_transition_rule
4848
get_transition_rule = Pendulum.get_transition_rule
49+
set_formatter = Pendulum.set_formatter
50+
get_formatter = Pendulum.get_formatter
4951

5052
# Standard helpers
5153
min = Pendulum.min

0 commit comments

Comments
 (0)