Skip to content

gh-100574: add examples/links to the strptime/strftime docs #100575

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Apr 8, 2023
Merged

gh-100574: add examples/links to the strptime/strftime docs #100575

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
24fd03b
Add links to `.(from)isoformat` to `.str(p|f)time` docs.
ezio-melotti Dec 28, 2022
ac70ccc
Add a `str(f|p)time` format codes example.
ezio-melotti Dec 28, 2022
9c92c53
Remove extra prompt from example.
ezio-melotti Dec 28, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 26 additions & 21 deletions Doc/library/datetime.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -737,18 +737,16 @@ Instance methods:
.. method:: date.strftime(format)

Return a string representing the date, controlled by an explicit format string.
Format codes referring to hours, minutes or seconds will see 0 values. For a
complete list of formatting directives, see
:ref:`strftime-strptime-behavior`.
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This ref is converted to the title of the section: strftime() and strptime() Behavior. The actual list of format codes is actually a subsection. Adding a label to the subsection and updating the ref might result in a more readable sentence.

Format codes referring to hours, minutes or seconds will see 0 values.
See also :ref:`strftime-strptime-behavior` and :meth:`date.isoformat`.


.. method:: date.__format__(format)

Same as :meth:`.date.strftime`. This makes it possible to specify a format
string for a :class:`.date` object in :ref:`formatted string
literals <f-strings>` and when using :meth:`str.format`. For a
complete list of formatting directives, see
:ref:`strftime-strptime-behavior`.
literals <f-strings>` and when using :meth:`str.format`.
See also :ref:`strftime-strptime-behavior` and :meth:`date.isoformat`.

Examples of Usage: :class:`date`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Expand Down Expand Up @@ -1052,8 +1050,8 @@ Other constructors, all class methods:

:exc:`ValueError` is raised if the date_string and format
can't be parsed by :func:`time.strptime` or if it returns a value which isn't a
time tuple. For a complete list of formatting directives, see
:ref:`strftime-strptime-behavior`.
time tuple. See also :ref:`strftime-strptime-behavior` and
:meth:`datetime.fromisoformat`.



Expand Down Expand Up @@ -1511,20 +1509,21 @@ Instance methods:
(which :func:`time.ctime` invokes, but which
:meth:`datetime.ctime` does not invoke) conforms to the C standard.


.. method:: datetime.strftime(format)

Return a string representing the date and time, controlled by an explicit format
string. For a complete list of formatting directives, see
:ref:`strftime-strptime-behavior`.
Return a string representing the date and time,
controlled by an explicit format string.
See also :ref:`strftime-strptime-behavior` and :meth:`datetime.isoformat`.


.. method:: datetime.__format__(format)

Same as :meth:`.datetime.strftime`. This makes it possible to specify a format
string for a :class:`.datetime` object in :ref:`formatted string
literals <f-strings>` and when using :meth:`str.format`. For a
complete list of formatting directives, see
:ref:`strftime-strptime-behavior`.
literals <f-strings>` and when using :meth:`str.format`.
See also :ref:`strftime-strptime-behavior` and :meth:`datetime.isoformat`.


Examples of Usage: :class:`.datetime`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Expand Down Expand Up @@ -1869,17 +1868,15 @@ Instance methods:
.. method:: time.strftime(format)

Return a string representing the time, controlled by an explicit format
string. For a complete list of formatting directives, see
:ref:`strftime-strptime-behavior`.
string. See also :ref:`strftime-strptime-behavior` and :meth:`time.isoformat`.


.. method:: time.__format__(format)

Same as :meth:`.time.strftime`. This makes it possible to specify a format string
for a :class:`.time` object in :ref:`formatted string
literals <f-strings>` and when using :meth:`str.format`. For a
complete list of formatting directives, see
:ref:`strftime-strptime-behavior`.
Same as :meth:`.time.strftime`. This makes it possible to specify
a format string for a :class:`.time` object in :ref:`formatted string
literals <f-strings>` and when using :meth:`str.format`.
See also :ref:`strftime-strptime-behavior` and :meth:`time.isoformat`.


.. method:: time.utcoffset()
Expand Down Expand Up @@ -2321,6 +2318,14 @@ versus :meth:`strptime`:
:meth:`strftime` and :meth:`strptime` Format Codes
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

These methods accept format codes that can be used to parse and format dates::

>>> datetime.strptime('31/01/22 23:59:59.999999',
... '%d/%m/%y %H:%M:%S.%f')
datetime.datetime(2022, 1, 31, 23, 59, 59, 999999)
>>> _.strftime('%a %d %b %Y, %I:%M%p')
'Mon 31 Jan 2022, 11:59PM'
Comment on lines +2323 to +2327
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In this example I tried to capture as many format codes as possible in a way that makes it easy to find which part corresponds to which code.


The following is a list of all the format codes that the 1989 C standard
requires, and these work on all platforms with a standard C implementation.

Expand Down