compileall functions do not document or test return values

[nchammas]

BPO	25768
Nosy	@brettcannon, @nchammas
Files	compileall-doc.patch compileall.patch compileall.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 = 'https://github.com/brettcannon'
closed_at = <Date 2015-12-27.21:18:49.653>
created_at = <Date 2015-11-29.22:44:15.622>
labels = ['type-bug', 'docs']
title = 'compileall functions do not document or test return values'
updated_at = <Date 2015-12-27.21:18:49.652>
user = 'https://github.com/nchammas'

bugs.python.org fields:

activity = <Date 2015-12-27.21:18:49.652>
actor = 'brett.cannon'
assignee = 'brett.cannon'
closed = True
closed_date = <Date 2015-12-27.21:18:49.653>
closer = 'brett.cannon'
components = ['Documentation']
creation = <Date 2015-11-29.22:44:15.622>
creator = 'nchammas'
dependencies = []
files = ['41201', '41277', '41364']
hgrepos = []
issue_num = 25768
keywords = ['patch']
message_count = 19.0
messages = ['255600', '255653', '255658', '255665', '255666', '255670', '255675', '255677', '255678', '255897', '255984', '256076', '256162', '256248', '256742', '256777', '256778', '257100', '257101']
nosy_count = 4.0
nosy_names = ['brett.cannon', 'docs@python', 'python-dev', 'nchammas']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue25768'
versions = ['Python 3.6']

[nchammas]

I'm using the public functions of Python's built-in compileall module.

https://docs.python.org/3/library/compileall.html#public-functions

There doesn't appear to be documentation of what each of these functions returns.

I figured out, for example, that compileall.compile_file() returns 1 when the file compiles successfully, and 0 if not.

If this is "official" behavior, it would be good to see it documented so that we can rely on it.

I'd be happy to submit a patch to fix this if a committer is willing to shepherd a new contributor (me) through the process. Otherwise, this is probably a quick fix for experienced contributors.

[brettcannon]

At this point the return values are probably as official as they are going to be since these are such old functions.

If you want to write a patch, Nicholas, please see https://docs.python.org/devguide/ for instructions on how to do that.

[nchammas]

Exciting! I'm on it.

[nchammas]

OK, here's a patch.

I reviewed the doc style guide [0] but I'm not 100% sure if I'm using the appropriate tense. There are also a couple of lines that go a bit over 80 characters, but the file already had a few of those.

Am happy to make any adjustments, if necessary.

[0] https://docs.python.org/devguide/documenting.html#style-guide

[nchammas]

And I just signed the contributor agreement. (Some banner showed up when I attached the patch to this issue asking me to do so.)

[brettcannon]

Thanks, Nicholas! I'll have a look when I have a chance (hopefully no later than Friday).

[nchammas]

👍 Take your time.

[nchammas]

Oh derp. It appears this is dup of bpo-24386. Apologies.

[nchammas]

Whoops, wrong issue. Reopening.