[Twisted-Python] INCOMPATIBLE CHANGE: twisted.python.dist renamed to twisted.python._setup

[Christopher Armstrong]

The reason this module never had an underscore (and instead has the "don't
use this outside of Twisted" line in the docstring) is because it
originated in a time when Twisted was ostensibly split up into multiple
projects, and I ill-advisedly decided that it technically needed to be
"public" in order for the non-Twisted-core subprojects to use it. That was
a silly decision, and given that the docstring has always told people not
to use it, please feel free to rename it.

-Chris

On Mon, Aug 8, 2016, 1:56 AM Craig Rodrigues <rodrigc at crodrigues.org> wrote:

> On Sun, Aug 7, 2016 at 11:01 PM, Glyph Lefkowitz <glyph at twistedmatrix.com>
> wrote:
>
>>
>> This is also addressing a real problem.  One of the *major* issues with
>> Twisted is *documentation noise*.  Developers trying to use Twisted to
>> build things frequently complain about this: they look for an API to do
>> XYZ, and they search the reference documentation, which produces dozens of
>> confusing, irrelevant hits.  There are multiple issues that interact here
>> (see, for example, <https://github.com/twisted/pydoctor/issues/49> which
>> is a big part of the problem) but one significant one is that our
>> apparently-public API surface is just too big.  Removing things like this,
>> which are really _totally_ useless to anyone, is useful in and of itself
>> and also amplifies the benefit of any other work on docs and tooling to
>> properly segregate public and private API documentation.
>>
>>
>
> Making dist.py private seems to fall under the category of "code
> cleanliness", and doesn't
> seem to solve any specific pressing issue that I see.  Reducing
> documentation noise is a good goal,
> but if dist.py was left the way it is, things would probably be OK with
> Twisted, and I think people
> could figure things out in Twisted with respect to the documentation.
>
> Since you mention pydoctor, I will mention two issues, that I feel are
> more important to the project
> that moving around dist.py:
>
>
>    - pydoctor produces false errors, specifically in h2 code:
>    https://buildbot.twistedmatrix.com/builders/documentation/builds/1291/steps/api-documentation/logs/pydoctor%20errors
>    - pydoctor doesn't work on Python 3:
>    https://github.com/twisted/pydoctor/issues/96
>
> I understand that Twisted is a volunteer project, and people can work on
> whatever they want.
> I also see on this list, that a few people support the dist.py change, so
> as long as
> Adi's change meets the Twisted coding standards, gets code review
> approval, and can pass all the buildbots,
> it can move forward, despite my objections.
>
> --
> Craig
>
>
>
> _______________________________________________
> Twisted-Python mailing list
> Twisted-Python at twistedmatrix.com
> http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: </pipermail/twisted-python/attachments/20160808/1b9b0e83/attachment-0002.html>