Skip to content
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

Jump to bottom

bpo-35183: Add typical examples to os.path.splitext docs #27286

Merged
merged 6 commits into from
Aug 2, 2021
Merged

bpo-35183: Add typical examples to os.path.splitext docs #27286

Changes from 1 commit
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
116040e
bpo-35183: Add typical examples to os.path.splitext docs
jstockwin Jul 22, 2021
9c906b6
📜🤖 Added by blurb_it.
blurb-it[bot] Jul 22, 2021
cd772f9
bpo-35183: Improve example layout in os.path.splitext docs
jstockwin Jul 22, 2021
a4f13d8
bpo-35183: Make ext italic in os.path.splitext docs
jstockwin Jul 23, 2021
06c0cae
bpo-35183: Change os.path doc examples to be repr
jstockwin Jul 23, 2021
3156838
bpo-35183: Explicitly name the extension argument in os.path.splitext…
jstockwin Jul 23, 2021
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
Prev Previous commit
Next Next commit
bpo-35183: Improve example layout in os.path.splitext docs
  • Loading branch information
@jstockwin
jstockwin committed Jul 22, 2021
commit cd772f992d5e69ad4d826b2d2b5fe369694b3cd0
14 changes: 11 additions & 3 deletions Doc/library/os.path.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -485,9 +485,17 @@ the :mod:`glob` module.)

Split the pathname *path* into a pair ``(root, ext)`` such that ``root + ext ==
path``, and *ext* is empty or begins with a period and contains at most one
Copy link
Contributor

Choose a reason for hiding this comment

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

This is nitpicky (sorry). Note that up here in the prior docs, "ext" is italicized, then you switch to monospace. In general, throughout python documentation, you'll see italics used when referencing arguments or variable names in the midst of prose. I suggest changing "ext" on lines 490 and 493 to italics to match the style from the first paragraph.

period, e.g. ``splitext('bar')`` returns ``('bar', '')`` and
``splitext('foo.bar.exe')`` returns ``('foo.bar', '.exe')``. Leading periods on the
basename are ignored; ``splitext('.cshrc')`` returns ``('.cshrc', '')``.
period.

If the path contains no extension, ``ext`` will be ``''``.
e.g. ``splitext('bar')`` returns ``('bar', '')``

If the path contains an extension, then ``ext`` will be set to this extension,
including the leading period. Note that previous periods will be ignored.
e.g. ``splitext('foo.bar.exe')`` returns ``('foo.bar', '.exe')``.
Copy link
Contributor

Choose a reason for hiding this comment

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

What you've done absolutely does accurately follow the style and patterns seen in this documentation thus far. I think it would be nice to do repr examples like this, though:

If the path contains no extension, *ext* will be an empty string::

    >>> splitpath('bar')
    ('bar', '')

If the path contains an extension, then *ext* will be set to this extension,
including the leading period. Note that previous periods will be ignored::

    >>> splittext('foo.bar.exe')
    ('foo.bar', 'ext')

Leading periods on the basename are also ignored::

    >>> splitext('.cshrc')
    ('.cshrc', '')

BUT

  1. That's just me
  2. It breaks from the style of other in lined examples throughout this doc

So, I'd recommend just wait and see if / how others react to this comment, and only go ahead and restructure it like this if others agree with me, because might not!


Leading periods on the basename are ignored.
e.g. ``splitext('.cshrc')`` returns ``('.cshrc', '')``.

.. versionchanged:: 3.6
Accepts a :term:`path-like object`.
Expand Down