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

Jump to bottom

longobject: documentation improvements #57174

Closed
skrah mannequin opened this issue Sep 12, 2011 · 11 comments
Closed

longobject: documentation improvements #57174

skrah mannequin opened this issue Sep 12, 2011 · 11 comments
Labels
docs Documentation in the Doc dir type-feature A feature request or enhancement

Comments

@skrah
Copy link
Mannequin

skrah mannequin commented Sep 12, 2011

BPO 12965
Nosy @mdickinson, @skrah
Files
  • longobject-doc.diff
    		•

    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 = <Date 2014-10-14.14:38:34.076>
created_at = <Date 2011-09-12.16:57:49.844>
labels = ['type-feature', 'docs']
title = 'longobject: documentation improvements'
updated_at = <Date 2014-10-14.14:38:34.074>
user = 'https://github.com/skrah'

    bugs.python.org fields:

    activity = <Date 2014-10-14.14:38:34.074>
actor = 'skrah'
assignee = 'none'
closed = True
closed_date = <Date 2014-10-14.14:38:34.076>
closer = 'skrah'
components = ['Documentation']
creation = <Date 2011-09-12.16:57:49.844>
creator = 'skrah'
dependencies = []
files = ['23133']
hgrepos = []
issue_num = 12965
keywords = ['patch']
message_count = 11.0
messages = ['143922', '146251', '146252', '146253', '148797', '163566', '163571', '163578', '163579', '163642', '229293']
nosy_count = 4.0
nosy_names = ['mark.dickinson', 'skrah', 'docs@python', 'python-dev']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue12965'
versions = ['Python 2.7', 'Python 3.2', 'Python 3.3']
    @skrah
    Copy link
    Mannequin Author

    skrah mannequin commented Sep 12, 2011

    I think the integer objects documentation could be clearer on a
    couple of points:

    • Despite being listed under "Concrete Objects Layer", some
      functions implicitly accept anything with an __int__()
      method. Currently only the PyLong_AsLong() documentation
      states this explicitly.

      The patch clearly distinguishes between functions that
      duck type and functions that don't.

    • The patch replaces "is greater than *_MAX" instances with
      "out of bounds" to include the other error condition
      "is less than *_MIN".

    Additionally, the patch fixes comments in longobject.c that
    don't state the duck typing behavior.

    @skrah skrah mannequin assigned docspython Sep 12, 2011
    @skrah skrah mannequin added docs Documentation in the Doc dir type-feature A feature request or enhancement labels Sep 12, 2011
    @skrah skrah mannequin assigned mdickinson and unassigned docspython Sep 12, 2011
    @python-dev
    Copy link
    Mannequin

    python-dev mannequin commented Oct 23, 2011

    New changeset d4839fea4a5a by Mark Dickinson in branch 'default':
    Issue bpo-12965: Fix some inaccurate comments in Objects/longobject.c. Thanks Stefan Krah.
    http://hg.python.org/cpython/rev/d4839fea4a5a

    @mdickinson
    Copy link
    Member

    I've fixed some of the inaccurate comments in Objects/longobject.c, for the default branch; I'm still looking at the Doc update.

    This really is a bit of a mess, especially for cases like PyLong_AsVoidPtr, which can either end up calling PyLong_As(Long)Long (which allows conversion via __int__), or PyLong_AsUnsigned(Long)Long (which doesn't).

    Ultimately, I think it would make sense to remove all __int__ conversions from Objects/longobject.c; this would affect:

    • PyLong_AsLongAndOverflow
    • PyLong_AsLong
    • PyLong_AsUnsignedLongMask

    and the 'LongLong' variants of these. The ramifications of such a change might be quite long-reaching; in particular, I seem to recall that this would affect the 'getargs' machinery.

    It could be fun to remove these conversions and see how much of the test-suite fails. :-)

    @mdickinson
    Copy link
    Member

    It could be fun to remove these conversions and see how much of the
    test-suite fails. :-)

    ... On my machine, just test_ctypes and test_getargs2, as it turns out.

    @skrah
    Copy link
    Mannequin Author

    skrah mannequin commented Dec 3, 2011

    Ultimately, I think it would make sense to remove all __int__
    conversions from Objects/longobject.c;

    +1

    I think this API cleanup is worth some (probably very limited)
    breakage in third party modules.

    @python-dev
    Copy link
    Mannequin

    python-dev mannequin commented Jun 23, 2012

    New changeset 5ca9a51f3d85 by Mark Dickinson in branch '3.2':
    Issue bpo-12965: Clean up C-API docs for PyLong_AsLong(AndOverflow); clarify that __int__ will be called for non-PyLongs
    http://hg.python.org/cpython/rev/5ca9a51f3d85

    New changeset 63fc1552cd36 by Mark Dickinson in branch 'default':
    Issue bpo-12965: Merge from 3.2
    http://hg.python.org/cpython/rev/63fc1552cd36

    @python-dev
    Copy link
    Mannequin

    python-dev mannequin commented Jun 23, 2012

    New changeset 3ace8e17074a by Mark Dickinson in branch '3.2':
    Issue bpo-12965: Clean up C-API docs for PyLong_AsLongLong(AndOverflow); clarify that __int__ will be called for non-PyLongs
    http://hg.python.org/cpython/rev/3ace8e17074a

    New changeset 85683f005fc8 by Mark Dickinson in branch 'default':
    Issue bpo-12965: Merge from 3.2.
    http://hg.python.org/cpython/rev/85683f005fc8

    @python-dev
    Copy link
    Mannequin

    python-dev mannequin commented Jun 23, 2012

    New changeset e1416a4d728a by Mark Dickinson in branch '3.2':
    Issue bpo-12965: More PyLong_As* clarifications. Thanks Stefan Krah.
    http://hg.python.org/cpython/rev/e1416a4d728a

    New changeset 349bc58e8c66 by Mark Dickinson in branch 'default':
    Issue bpo-12965: Merge from 3.2.
    http://hg.python.org/cpython/rev/349bc58e8c66

    @mdickinson
    Copy link
    Member

    Docs mostly fixed now for Python 3.2 and Python 3.3. That leaves 2.7, where there are some additional complications (e.g., __long__ in addition to __int__, when / whether short ints are accepted, etc.).

    While it would be good to fix the 2.7 docs as well, I don't see myself having time for this in the near future, so I'm unassigning for now; Stefan, I think should feel free to take this issue and check in clarifications for 2.7, if you want to.

    @mdickinson mdickinson removed their assignment Jun 23, 2012
    @skrah
    Copy link
    Mannequin Author

    skrah mannequin commented Jun 23, 2012

    OK, I'll see if I find some time for the 2.7 docs.

    @skrah skrah mannequin self-assigned this Jun 23, 2012
    @skrah
    Copy link
    Mannequin Author

    skrah mannequin commented Oct 14, 2014

    This seems like too much trouble for 2.7. Closing, since I was the
    one who opened the issue (just reopen if you think it is still worth
    it).

    @skrah skrah mannequin closed this as completed Oct 14, 2014
    @skrah skrah mannequin removed their assignment Oct 14, 2014
    @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
    No one assigned
    Labels
    docs Documentation in the Doc dir type-feature A feature request or enhancement
    Projects
    None yet
    Milestone
    No milestone
    Development

    No branches or pull requests
    1 participant
    @mdickinson