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

Document '/' in signatures #65513

Closed
vedgar mannequin opened this issue Apr 20, 2014 · 22 comments
Closed

Document '/' in signatures #65513

vedgar mannequin opened this issue Apr 20, 2014 · 22 comments
Assignees
@larryhastings
Labels
3.7 (EOL) end of life 3.8 only security fixes docs Documentation in the Doc dir easy topic-argument-clinic type-feature A feature request or enhancement

Comments

@vedgar
Copy link
Mannequin

vedgar mannequin commented Apr 20, 2014

BPO 21314
Nosy @rhettinger, @terryjreedy, @ncoghlan, @larryhastings, @benjaminp, @jwilk, @encukou, @berkerpeksag, @zware, @pradyunsg, @MojoVampire, @vedgar, @csabella, @lysnikolaou, @pablogsal, @noahhaasis
PRs
  • bpo-21314: Add a FAQ entry about positional only parameters #10641
  • bpo-21314: Add a FAQ entry about positional only parameters #10641
  • bpo-21314: Add a FAQ entry about positional only parameters #10641
  • [3.7] bpo-21314: Add a FAQ entry about positional only parameters (GH-10641) #12266
    		•

    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 = 'https://github.com/larryhastings'
closed_at = <Date 2022-04-04.20:43:41.240>
created_at = <Date 2014-04-20.10:07:19.415>
labels = ['easy', '3.7', '3.8', 'type-feature', 'expert-argument-clinic', 'docs']
title = "Document '/' in signatures"
updated_at = <Date 2022-04-04.20:43:41.236>
user = 'https://github.com/vedgar'

    bugs.python.org fields:

    activity = <Date 2022-04-04.20:43:41.236>
actor = 'petr.viktorin'
assignee = 'larry'
closed = True
closed_date = <Date 2022-04-04.20:43:41.240>
closer = 'petr.viktorin'
components = ['Documentation', 'Argument Clinic']
creation = <Date 2014-04-20.10:07:19.415>
creator = 'veky'
dependencies = []
files = []
hgrepos = []
issue_num = 21314
keywords = ['patch', 'patch', 'patch', 'easy']
message_count = 22.0
messages = ['216899', '216900', '216901', '219979', '219983', '219987', '223893', '323436', '324982', '325005', '328982', '330193', '330209', '337017', '337611', '337612', '337613', '337708', '337881', '343595', '344047', '416695']
nosy_count = 18.0
nosy_names = ['rhettinger', 'terry.reedy', 'ncoghlan', 'larry', 'benjamin.peterson', 'jwilk', 'petr.viktorin', 'docs@python', 'berker.peksag', 'zach.ware', 'pradyunsg', 'josh.r', 'veky', 'emily.zhao', 'cheryl.sabella', 'lys.nikolaou', 'pablogsal', 'noah.haasis']
pr_nums = ['10641', '10641', '10641', '12266']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue21314'
versions = ['Python 3.6', 'Python 3.7', 'Python 3.8']
    @vedgar
    Copy link
    Mannequin Author

    vedgar mannequin commented Apr 20, 2014

    Please look at the output of help(object.__ge__).

    1. What's that $ in front of self? lt and gt don't have it.

    2. What's that / as a third argument? Many wrapper functions have it (for example, see help(tuple.__len__).

    3. What's that -- as the first line of doc? Similar methods don't have it.

    @vedgar vedgar mannequin assigned docspython Apr 20, 2014
    @vedgar vedgar mannequin added the docs Documentation in the Doc dir label Apr 20, 2014
    @MojoVampire
    Copy link
    Mannequin

    MojoVampire mannequin commented Apr 20, 2014

    I don't know about the other bits, but that trailing '/' is how Argument Clinic (which makes full featured inspection available to built-in functions) notes that the parameters are positional only, and cannot be passed by keyword. See PEP-436.

    @zware
    Copy link
    Member

    zware commented Apr 20, 2014

    1. This was due to a typo. The release of Python 3.4 saw the introduction of new introspection information on many C-implemented functions thanks to Argument Clinic (see PEP-436, I think it is). As part of that (still ongoing) transition, the default doctrings for type slots like __ge__ were given Argument Clinic-style signatures, and __ge__ had a typo.

    I fixed that typo on Friday (actually prompted by your previous issue about len's bad signature).

    1. That marker now shows that all proceeding arguments are positional-only. We should probably make sure that is well documented somewhere, possibly in the tutorial.

    2. This was also due to the typo I fixed.

    @terryjreedy terryjreedy changed the title Bizarre help Document '/' in signatures Apr 25, 2014
    @zware zware added easy type-feature A feature request or enhancement labels Apr 29, 2014
    @emilyzhao
    Copy link
    Mannequin

    emilyzhao mannequin commented Jun 7, 2014

    Can someone close this? I think it's fixed.

    @benjaminp
    Copy link
    Contributor

    The original bug (junk in various doc strings) has been fixed, but I think the positional argument "/" syntax still needs docs. It's a little tricky because "/" is not actually valid syntax; it's just for documentation signatures.

    @emilyzhao
    Copy link
    Mannequin

    emilyzhao mannequin commented Jun 7, 2014

    where's the best place for that documentation to live?

    @zware
    Copy link
    Member

    zware commented Jul 24, 2014

    Apologies for the delay in answering, Emily. And, unfortunately, I don't have a good answer. If you would like to write a patch, I would suggest just sticking the documentation wherever you think is best and make sure there is a link to it from the Symbols index page. Whoever commits your patch will either agree with your placement or have a better idea of where to put it, and will either move it themselves or work with you to move it.

    Here are a few possible places it could go, off the top of my head and without really looking:

    • in the pydoc docs
    • in the help() builtin docs
    • in or near the inspect.Signature docs
    • in the Clinic HOWTO
    • somewhere in the tutorial (though I'm not sure where would be good)

    @berkerpeksag
    Copy link
    Member

    I'd suggest adding a FAQ entry to the "Core Language" section at https://docs.python.org/3/faq/programming.html#core-language then we can link to it from the places (except pydoc docs) Zachary listed in msg223893.

    @noahhaasis
    Copy link
    Mannequin

    noahhaasis mannequin commented Sep 11, 2018

    Can I work on this?

    @berkerpeksag
    Copy link
    Member

    Welcome, Noah! Feel free to work on this issue, but please note that there is no consensus on the best place to document / signatures, so you may need to move your changes between locations (e.g. from Doc/faq/programming.rst to Doc/gloassary.rst) before we merge your work.

    @berkerpeksag berkerpeksag added 3.7 (EOL) end of life 3.8 only security fixes labels Sep 11, 2018
    @pradyunsg
    Copy link
    Member

    We now have a PEP for this; just noting this here since I don't see a cross reference between them.

    https://www.python.org/dev/peps/pep-0570/

    @lysnikolaou
    Copy link
    Contributor

    Noah, are you working on this?

    @noahhaasis
    Copy link
    Mannequin

    noahhaasis mannequin commented Nov 21, 2018

    I don‘t have the time right now. Feel free to work on it!

    @lysnikolaou
    Copy link
    Contributor

    Ping for review.

    @ncoghlan
    Copy link
    Contributor

    New changeset 1aeeaeb by Nick Coghlan (Lysandros Nikolaou) in branch 'master':
    bpo-21314: Add a FAQ entry about positional only parameters (GH-10641)
    1aeeaeb

    @miss-islington
    Copy link
    Contributor

    New changeset 87f5255 by Miss Islington (bot) in branch '3.7':
    bpo-21314: Add a FAQ entry about positional only parameters (GH-10641)
    87f5255

    @ncoghlan
    Copy link
    Contributor

    I went ahead and merged Lysandros's new FAQ entry (Thank you Lysandros!), as having some level of documentation for this notation is markedly better than the previous "none at all", and the PR added cross-references from the builtins and inspect module docs in addition to adding the FAQ itself.

    However, I'm not closing the issue yet as:

    • the exact wording could likely stand to be tweaked a bit (in particular, I'm not sure it's a good idea to reference PEP-570 from the FAQ entry)

    • we may want to enhance pydoc itself to explain the notation inline (e.g. by appending a footer saying "Note: parameters to the left of / entries are positional only and cannot be passed by name" after the docstring being displayed when positional only parameters are found, and "Note: parameters to the right of * and *name entries are keyword only and can only be passed by name" when keyword only parameters are found)

    • we may want to file a follow-up issue proposing that pydoc go back to either not marking positional-only parameters at all, or marking them differently (e.g. with "Note: x, y, and z are positional only parameters that cannot be passed by name" after the individual callable docstrings)

    @csabella
    Copy link
    Contributor

    There are a few other open issues about positional-only keywords (for example, bpo-10789 and bpo-8350). I wasn't sure what, if anything, could be done with those now that the '/' is available and documented.

    @lysnikolaou
    Copy link
    Contributor

    I agree with Nick, that pydoc should somehow be updated to mark positional-only parameters as such. I believe that the third approach proposed by Nick is the most sensible one, as it makes the life of new developers easier by explicitly listing all the positional-only parameters. I could open a new issue and work on a PR, if you all agree that that is the way to go.

    @pablogsal
    Copy link
    Member

    I think we can revisit this now that PEP-570 is accepted

    @terryjreedy
    Copy link
    Member

    Hooray! Now that PEP-570 is implemented in 3.8:

    >>> def f(a, /, *, b): return 3
...
>>> f(0, b=2)
3
# other combinations raise

    and somewhat documented, ('/' in grammar of '8.6 Function definitions', though not explained, should its status become final and listing moved?

    @encukou
    Copy link
    Member

    encukou commented Apr 4, 2022

    • PEP-570 (Python Positional-Only Parameters) is final
    • The language spec was updated to mention it
    • the FAQ entry was revised to not link to the PEP and be a self-contained explanation

    IMO the only thing left is to make searching for / yield the right results, but that is bpo-15871.
    Closing this issue.

    @encukou encukou closed this as completed Apr 4, 2022
    @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
    Assignees

    @larryhastings larryhastings

    Labels
    3.7 (EOL) end of life 3.8 only security fixes docs Documentation in the Doc dir easy topic-argument-clinic type-feature A feature request or enhancement
    Projects
    None yet
    Milestone
    No milestone
    Development

    No branches or pull requests