Inconsistent docstrings in struct module

[abalkin]

BPO	8973
Nosy	@birkenfeld, @mdickinson, @abalkin
Files	issue8973.patch issue8973-Struct.diff: Expanded Struct.doc struct.py.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 = 'https://github.com/abalkin'
closed_at = <Date 2011-01-31.17:23:54.870>
created_at = <Date 2010-06-11.15:32:36.870>
labels = ['extension-modules', 'type-bug']
title = 'Inconsistent docstrings in struct module'
updated_at = <Date 2011-01-31.17:23:54.869>
user = 'https://github.com/abalkin'

bugs.python.org fields:

activity = <Date 2011-01-31.17:23:54.869>
actor = 'SilentGhost'
assignee = 'belopolsky'
closed = True
closed_date = <Date 2011-01-31.17:23:54.870>
closer = 'SilentGhost'
components = ['Extension Modules']
creation = <Date 2010-06-11.15:32:36.870>
creator = 'belopolsky'
dependencies = []
files = ['17643', '17649', '20625']
hgrepos = []
issue_num = 8973
keywords = ['patch']
message_count = 19.0
messages = ['107556', '107557', '107558', '107655', '107656', '107657', '107658', '107659', '107660', '107663', '107664', '107666', '107686', '107687', '107688', '127593', '127606', '127609', '127626']
nosy_count = 4.0
nosy_names = ['georg.brandl', 'mark.dickinson', 'belopolsky', 'SilentGhost']
pr_nums = []
priority = 'normal'
resolution = 'accepted'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue8973'
versions = ['Python 3.2']

[abalkin]

Module level pack, unpack etc. methods have similar functionality with Struct instance methods, but docs are different. The immediate issue is the lack of signature in the module level methods' docstrings.

$ ./python.exe -m pydoc struct.Struct.pack
Help on method_descriptor in struct.Struct:

struct.Struct.pack = pack(...)
    S.pack(v1, v2, ...) -> bytes
    
    Return a bytes containing values v1, v2, ... packed according to this
    Struct's format. See struct.__doc__ for more on format strings.

and

$ ./python.exe -m pydoc struct.pack
Help on built-in function pack in struct:

struct.pack = pack(...)
    Return bytes containing values v1, v2, ... packed according to fmt.

[abalkin]

Two more bits:

1. "See struct.__doc__", while technically correct, is not user friendly.  If you copy struct.__doc__ to >>> prompt, you get an ugly repr of a multiline string.  I suggest s/struct.__doc__/help(struct)/.

2. For some reason struct.Struct does not show up in help(struct).

[mdickinson]

Thanks for the reports; I'll look at this a little later.

[mdickinson]

Here's a patch. Alexander, do you want to check it for sanity?

[mdickinson]

N.B. The patch doesn't fix the missing struct.Struct documentation issue; I'll look at that separately.

[mdickinson]

The docstrings need to be rewrapped to 72 characters; I'll do this once the wording is settled.

[abalkin]

calcsize() still does not have signature in docstring.

A nit: maybe follow calcsize() lead and say "format string fmt" rather than just "fmt".

One more __doc__ mention: in Struct docstring,

| __init__(...)
| x.__init__(...) initializes x; see x.__class__.__doc__ for signature

I think this is inherited, but quite confusing here because help(Struct) does not have signature. Maybe just add signature to help(Struct).

[mdickinson]

r81947 fixes the missing struct.Struct entry in struct.help. (pydoc was relying on the inspect module to correctly guess the module for struct.Struct, and inspect was getting it wrong. Adding __all__ to the struct module saves inspect from having to guess.)

[mdickinson]

I also accidentally included the docstring changes in r81947; those were reverted in r81948.

[mdickinson]

Committed patch (with additional changes suggested by Alexander) in r81949. Only the __init__ doc issue remains.

[abalkin]

See issue bpo-8983 for the the __init__ doc discussion since it is not specific to the struct module.

[mdickinson]

Apart from the pydoc __init__ issue, the Struct class documentation should probably be expanded a bit. At the moment, it's just:

PyDoc_STRVAR(s__doc__, "Compiled struct object");

Alexander, interested in producing a patch?