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.

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

Clarify documentation of positional-only default values #67926

Open
vadmium opened this issue Mar 22, 2015 · 12 comments
Open

Clarify documentation of positional-only default values #67926

vadmium opened this issue Mar 22, 2015 · 12 comments
Labels
docs Documentation in the Doc dir type-feature A feature request or enhancement

Comments

@vadmium
Copy link
Member

vadmium commented Mar 22, 2015

BPO 23738
Nosy @birkenfeld, @ezio-melotti, @bitdancer, @berkerpeksag, @vadmium, @serhiy-storchaka
Dependencies
  • bpo-14586: TypeError: truncate() takes no keyword arguments
  • bpo-25030: io.[Text]IOBase.seek doesn't take keyword parameter
  • bpo-25810: Python 3 documentation for eval is incorrect
  • Files
  • pos-defaults.patch
  • pos-defaults.v2.patch
  • pos-defaults.v3.patch
  • square-brackets.patch
  • Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.

    Show more details

    GitHub fields:

    assignee = None
    closed_at = None
    created_at = <Date 2015-03-22.10:31:01.273>
    labels = ['type-feature', 'docs']
    title = 'Clarify documentation of positional-only default values'
    updated_at = <Date 2020-05-22.18:24:08.773>
    user = 'https://github.com/vadmium'

    bugs.python.org fields:

    activity = <Date 2020-05-22.18:24:08.773>
    actor = 'brett.cannon'
    assignee = 'docs@python'
    closed = False
    closed_date = None
    closer = None
    components = ['Documentation']
    creation = <Date 2015-03-22.10:31:01.273>
    creator = 'martin.panter'
    dependencies = ['14586', '25030', '25810']
    files = ['38632', '38800', '40417', '41253']
    hgrepos = []
    issue_num = 23738
    keywords = ['patch']
    message_count = 12.0
    messages = ['238890', '238893', '238894', '238922', '239025', '239129', '239869', '241591', '250277', '250278', '255997', '257229']
    nosy_count = 8.0
    nosy_names = ['georg.brandl', 'ezio.melotti', 'r.david.murray', 'docs@python', 'python-dev', 'berker.peksag', 'martin.panter', 'serhiy.storchaka']
    pr_nums = []
    priority = 'normal'
    resolution = None
    stage = 'patch review'
    status = 'open'
    superseder = None
    type = 'enhancement'
    url = 'https://bugs.python.org/issue23738'
    versions = ['Python 3.4', 'Python 3.5', 'Python 3.6']

    @vadmium
    Copy link
    Member Author

    vadmium commented Mar 22, 2015

    This patch adds the PEP-457 positional-only slash “/” indicator to some function signatures in the documentation. I only looked at the the os, builtin, binascii, zlib and fcntl modules, and their functions where the documentation incorrectly suggests that they accept keyword arguments. For example, I changed

    eval(expression, globals=None, locals=None)

    to

    eval(expression, globals=None, locals=None, /)

    References:

    There are many more instances where square brackets are used, or the arguments are mandatory. See the PEP for examples, but I do not think it is so important to “fix” them.

    I also fixed parameter name mismatches that I discovered for a quite a few functions that do take keyword arguments.

    One more thing I noticed, that I do not know how to fix, is the Argument Clinic signatures list invalid default values for zlib.compressobj(zdict=None) and os.utime(ns=None):

    >>> zlib.compressobj(zdict=None)
    Traceback (most recent call last):
      File "<stdin>", line 1, in <module>
    TypeError: 'NoneType' does not support the buffer interface
    >>> os.utime("dummy", ns=None)
    Traceback (most recent call last):
      File "<stdin>", line 1, in <module>
    TypeError: utime: 'ns' must be a tuple of two ints

    @vadmium vadmium added the docs Documentation in the Doc dir label Mar 22, 2015
    @vadmium
    Copy link
    Member Author

    vadmium commented Mar 22, 2015

    Hmm it seems my change for os.utimes() in Modules/posixmodule.c does not automatically get reflected in the doc string. Is there some script I can run to regenerate it, or do I have to do it manually?

    @serhiy-storchaka
    Copy link
    Member

    ./python Tools/clinic/clinic.py --make

    or just

    make clinic
    

    @ezio-melotti ezio-melotti added the type-feature A feature request or enhancement label Mar 22, 2015
    @bitdancer
    Copy link
    Member

    Personally I would rather stick to the [] syntax in the docs, with the default values mentioned in the text.

    @brettcannon
    Copy link
    Member

    I say switch to what Argument Clinic uses, else there's a disconnect syntactically between help() and the docs.

    @bitdancer
    Copy link
    Member

    That's a good point.

    @vadmium
    Copy link
    Member Author

    vadmium commented Apr 2, 2015

    pos-defaults.v2.patch includes the results of “make clinic” to fix the doc strings.

    Is there a consensus to use PEP-457’s slash “/” notation? At one point I think I saw Serhiy was concerned that it might be confusing.

    @vadmium
    Copy link
    Member Author

    vadmium commented Apr 20, 2015

    Of course in a new release, the functions could actually grow support for keywords, sidestepping the problem. bpo-8706 proposes to do this.

    And see bpo-13386 about the conventions for optional arguments more generally.

    @python-dev
    Copy link
    Mannequin

    python-dev mannequin commented Sep 9, 2015

    New changeset fdb5d84f9948 by Martin Panter <vadmium> in branch '3.4':
    Issue bpo-23738: Document and test actual keyword parameter names
    https://hg.python.org/cpython/rev/fdb5d84f9948

    New changeset 40bf1ca3f715 by Martin Panter <vadmium> in branch '3.5':
    Issue bpo-23738: Merge 3.4 into 3.5
    https://hg.python.org/cpython/rev/40bf1ca3f715

    New changeset 6177482ce6a1 by Martin Panter <vadmium> in branch 'default':
    Issue bpo-23738: Merge 3.5 into 3.6
    https://hg.python.org/cpython/rev/6177482ce6a1

    @vadmium
    Copy link
    Member Author

    vadmium commented Sep 9, 2015

    I have committed the obvious keyword argument name fixes from my patch. Now patch v3 contains just the PEP-457 changes to be considered.

    @vadmium
    Copy link
    Member Author

    vadmium commented Dec 6, 2015

    Here is a more conservative patch using square brackets, and documenting the defaults in the text. I updated all the documentation from my previous patch, and added new changes for the “io” module.

    One quirk was that BufferedReader.read1() does not actually support the value −1. Therefore I changed the base class to BufferedIOBase.read1([size]) without mentioning what happens when size is omitted. Related: bpo-23214.

    @ezio-melotti
    Copy link
    Member

    One thought that occurred to me is that we could make the * and / in the signature links that point to a relevant section of the documentation.
    I believe this is doable with Sphinx, even though I'm not sure how complex it is and if it's worth it. If we do this, people will be able to find out easily what they mean (especially considering that it's hard to search for them).

    @ezio-melotti ezio-melotti transferred this issue from another repository Apr 10, 2022
    Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
    Labels
    docs Documentation in the Doc dir type-feature A feature request or enhancement
    Projects
    None yet
    Development

    No branches or pull requests

    5 participants