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

correct docstring for builtin compile #57886

Open
jimjjewett mannequin opened this issue Dec 29, 2011 · 5 comments
Open

correct docstring for builtin compile #57886

jimjjewett mannequin opened this issue Dec 29, 2011 · 5 comments
Labels
3.7 (EOL) end of life 3.8 only security fixes docs Documentation in the Doc dir type-bug An unexpected behavior, bug, or error

Comments

@jimjjewett
Copy link
Mannequin

jimjjewett mannequin commented Dec 29, 2011

BPO 13677
Nosy @terryjreedy, @merwok, @JimJJewett
Files
  • bltinmodule.c.patch: Change to compile_doc
  • 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 2011-12-29.17:49:22.427>
    labels = ['3.8', 'type-bug', '3.7', 'docs']
    title = 'correct docstring for builtin compile'
    updated_at = <Date 2018-03-22.08:38:26.312>
    user = 'https://github.com/JimJJewett'

    bugs.python.org fields:

    activity = <Date 2018-03-22.08:38:26.312>
    actor = 'serhiy.storchaka'
    assignee = 'docs@python'
    closed = False
    closed_date = None
    closer = None
    components = ['Documentation']
    creation = <Date 2011-12-29.17:49:22.427>
    creator = 'Jim.Jewett'
    dependencies = []
    files = ['24105']
    hgrepos = []
    issue_num = 13677
    keywords = ['patch']
    message_count = 5.0
    messages = ['150337', '150400', '150407', '150408', '150947']
    nosy_count = 4.0
    nosy_names = ['terry.reedy', 'eric.araujo', 'docs@python', 'Jim.Jewett']
    pr_nums = []
    priority = 'normal'
    resolution = None
    stage = None
    status = 'open'
    superseder = None
    type = 'behavior'
    url = 'https://bugs.python.org/issue13677'
    versions = ['Python 2.7', 'Python 3.6', 'Python 3.7', 'Python 3.8']

    @jimjjewett
    Copy link
    Mannequin Author

    jimjjewett mannequin commented Dec 29, 2011

    The current docstring for compile suggests that the flags are strictly for selecting future statements. These are not the only flags.

    It also suggests that the source must be source code and the result will be bytecode, which isn't quite true.

    I suggest changing:

    "The flags argument, if present, controls which future statements influence the compilation of the code."

    to:

    "The flags argument, if present, largely controls which future
    statements influence the compilation of the code. (Additional
    flags are documented in the AST module.)"

    @jimjjewett jimjjewett mannequin assigned docspython Dec 29, 2011
    @jimjjewett jimjjewett mannequin added docs Documentation in the Doc dir type-bug An unexpected behavior, bug, or error labels Dec 29, 2011
    @terryjreedy
    Copy link
    Member

    Flags comment applies to 3.2.2 docs and 2.7.2 docs. There is only one additional flag: ast.PyCF_ONLY_AST, so 'flags' should be singular.

    As for src and dst, doc has been updated to say 'Compile the source into a code or AST object. ... source can either be a string or an AST object.

    'source' should be capitalized.

    @jimjjewett
    Copy link
    Mannequin Author

    jimjjewett mannequin commented Dec 31, 2011

    I'm not sure we're looking at the same thing.  I was talking about the docstring that shows up at the interactive prompt in response to 
    >>> help(compile)

    Going to hg.python.org/cpython and selecting branches, then default, then browse, got me to
    http://hg.python.org/cpython/file/7010fa9bd190/Python/bltinmodule.c
    which still doesn't mention AST. I also don't see any reference to "src" or "dst", or any "source" that looks like it should be capitalized.

    I agree that there is (to my knowledge, at this time) only one additional flag. I figured ast or future was needed to get the compilation constants, so it made sense to delegate -- but you seem to be reading something newer than I am.

    @terryjreedy
    Copy link
    Member

    I am aware that the docstring, shown at help(compile), is what you were talking about. The docstring and manuals should say the same thing, or at least not contradict each other, so it is common for both to be out of date and both to be updated at the same time. So I went and looked at the current py2 and py3 docs to see if they also need change. And they do, though not quite as much. src and dst were unofficial abbreviations for source and output, in reference to what you said. Sorry for the confusion.

    @merwok
    Copy link
    Member

    merwok commented Jan 9, 2012

    The compiler flags are not really documented in the ast module doc or anywhere: see bpo-12207 and bpo-1612012.

    @serhiy-storchaka serhiy-storchaka added 3.7 (EOL) end of life 3.8 only security fixes labels Mar 22, 2018
    @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
    3.7 (EOL) end of life 3.8 only security fixes docs Documentation in the Doc dir type-bug An unexpected behavior, bug, or error
    Projects
    None yet
    Development

    No branches or pull requests

    3 participants