[Python-Dev] API and process questions (sparked by Claudiu Popa on 16104

[Brett Cannon]

On Mon Apr 28 2014 at 11:32:58 AM, Jim J. Jewett <jimjjewett at gmail.com>
wrote:

> (1)  Should fixes to a docstring go in with a patch, even if they
> aren't related to the changing functionality?
>

It should probably be its own commit.


>
> Bytestring compilation has several orthogonal parameters.  Most -- but
> not all -- are documented in the docstring.  (Specifically, there is
> no explanation of the rx parameter which acts as a filter, and no
> mention that symbolic links to directories are ignored.)
>
> It is best if a commit changes one small thing at a time.
> On the other hand, Nick recently posted that the minimal overhead of a
> patch commit is about half an hour.
>
> Is that overhead enough to override the one-issue-per-patch guideline?
>

That's typical for backported patches, not if something is only going into
default. That being said, if the change is truly small and you "sneak" it
in I don't think anyone is going to make you revert the patch to do it as
more atomic commits.


>
> (2)  The patch adds new functionality to use multiple processes in
> parallel.  The normal parameter values are integers indicating how
> many processes to use.  The parameter also needs two special values --
> one to indicate "use os.cpu_count", and the other to indicate "don't
> use multiprocessing at all".
>
> (A)  Is there a Best Practices for this situation, with two odd cases?
>

No. In this situation I would consider 0 or -1 for "use os.cpu_count' and
None for "don't use multi-processing".


>
> (B)  Claudiu originally copied the API from a similar APU for
> regrtest.  What is the barrier for "do it sensibly" vs "stick with
> precedent elsewhere"?  (Apparently regrtest treats any negative number
> as a request for the cpu_count calculation;  I suspect that "-5" is
> more likely to be an escaping error for "5" than it is to be a real
> request for auto-calculation that just happened to choose -5 instead
> of -1.)
>

Regrtest doesn't count as an API to stick to. =)


>
> (C)  How important is it to keep the API consistent between a
> top-level CLI command and the internal implementation?  At the the
> moment, the request for cpu_count is handled in the CLI wrapper, and
> not available to interactive callers.  On the other hand, interactive
> callers could just call cpu_count themselves...
>

It doesn't hurt, but we typically don't promote CLIs for stdlib modules so
there isn't much precedent.


>
> (D)  How important is it to maintain consistency with other uses of
> the same tool -- multiprocessing has its own was of requesting
> auto-calculation.  (So someone used to multiprocessing might assume
> that "None" meant to auto-calculate, as opposed to "don't use
> multiprocessing at all.")
>

That's a judgment call. If there is already no consistency go with the one
that makes the most sense. If consistency exists across the stdlib then
stay consistent.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-dev/attachments/20140428/8e99fa5b/attachment.html>