Skip to content

Clarify documentation of positional-only default values #67926

Closed as duplicate
Closed as duplicate
Clarify documentation of positional-only default values#67926
Labels
docsDocumentation in the Doc dirpendingThe issue will be closed if no feedback is providedtype-featureA feature request or enhancement

Description

@vadmium
vadmium
opened on 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']

    Activity

    1. vadmium commented on Mar 22, 2015

      @vadmium
      vadmium
      on Mar 22, 2015
      MemberAuthor

      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
    2. vadmium
      assigned
      docspython
      on Mar 22, 2015
    3. vadmium
      added
      docsDocumentation in the Doc dir
      on Mar 22, 2015

    4. vadmium commented on Mar 22, 2015

      @vadmium
      vadmium
      on Mar 22, 2015
      MemberAuthor

      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?

    5. serhiy-storchaka commented on Mar 22, 2015

      @serhiy-storchaka
      serhiy-storchaka
      on Mar 22, 2015
      Member

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

      or just

      make clinic
    6. ezio-melotti
      added
      type-featureA feature request or enhancement
      on Mar 22, 2015

    7. bitdancer commented on Mar 22, 2015

      @bitdancer
      bitdancer
      on Mar 22, 2015
      Member

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

    8. brettcannon commented on Mar 23, 2015

      @brettcannon
      brettcannon
      on Mar 23, 2015
      Member

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

    9. bitdancer commented on Mar 24, 2015

      @bitdancer
      bitdancer
      on Mar 24, 2015
      Member

      That's a good point.

    10. vadmium commented on Apr 2, 2015

      @vadmium
      vadmium
      on Apr 2, 2015
      MemberAuthor

      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.

    11. vadmium commented on Apr 20, 2015

      @vadmium
      vadmium
      on Apr 20, 2015
      MemberAuthor

      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.

    12. python-dev commented on Sep 9, 2015

      @python-dev
      python-devmannequin
      on Sep 9, 2015
      Mannequin

      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

    13. vadmium commented on Sep 9, 2015

      @vadmium
      vadmium
      on Sep 9, 2015
      MemberAuthor

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

    14. vadmium commented on Dec 6, 2015

      @vadmium
      vadmium
      on Dec 6, 2015
      MemberAuthor

      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.

    15. ezio-melotti commented on Dec 30, 2015

      @ezio-melotti
      ezio-melotti
      on Dec 30, 2015
      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).

    16. ezio-melotti
      transferred this issue fromon Apr 10, 2022

    17. StanFromIreland commented on Aug 14, 2025

      @StanFromIreland
      StanFromIreland
      on Aug 14, 2025
      Member

      I believe that this is a duplicate of the recent issue: #131885

    18. vadmium commented on Aug 15, 2025

      @vadmium
      vadmium
      on Aug 15, 2025
      MemberAuthor

      Looks like it. The main change left from my patches is the FileIO parameter name fix and test in https://bugs.python.org/file41253/square-brackets.patch.

      -.. class:: FileIO(name, mode='r', closefd=True, opener=None)
+.. class:: FileIO(file, mode='r', closefd=True, opener=None)

      All of my v3 patch is now redundant, and the other signatures identified in square-brackets.patch have adopted the slash notation:

    19. StanFromIreland commented on Aug 15, 2025

      @StanFromIreland
      StanFromIreland
      on Aug 15, 2025
      Member

      Do you wish to apply the patch?

    20. StanFromIreland
      added
      pendingThe issue will be closed if no feedback is provided
      on Aug 18, 2025
    21. github-project-automation
      added this to docs issueson Aug 18, 2025
    22. github-project-automation
      moved this to Todo in docs issueson Aug 18, 2025
    23. StanFromIreland
      closed this as a duplicateof Update function signatures to use * and / as needed #131885 on Oct 30, 2025
    Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

    Metadata

    Metadata

    Assignees

    No one assigned

      Labels

      docsDocumentation in the Doc dirpendingThe issue will be closed if no feedback is providedtype-featureA feature request or enhancement

      Projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions