[Twisted-Python] incompatible change - need revert before release

[Adi Roiban]

On 20 November 2015 at 12:25, Glyph Lefkowitz <glyph at twistedmatrix.com>
wrote:

>
> On Nov 20, 2015, at 1:42 AM, Adi Roiban <adi at roiban.ro> wrote:
>
>
> On 20 November 2015 at 10:32, Glyph Lefkowitz <glyph at twistedmatrix.com>
> wrote:
>
>> > On Nov 20, 2015, at 12:08 AM, Adi Roiban <adi at roiban.ro> wrote:
>> >
>> > It was released before 15.4
>> >
>> > Twisted Web 15.2.0 (2015-05-18)
>> > ===============================
>> >
>> > Features
>> > --------
>> >  - twisted.web.server.Site accepts requestFactory as constructor
>> >    argument. (#7016)
>> >
>> > ----------
>> >
>> > Not sure if rollback is the right thing to do... but I have no idea how
>> to proceed as any change will back the compatibility.
>> >
>> > I guess that we should just create a normal bug ticket and fix this
>> issue
>>
>> Thanks for finding the changelog entry; sorry for the false alarm.
>>
>> If it's been in a release, then there's probably nothing to do.  It's a
>> shame that this went out, but once a breakage like this has happened we
>> have to live with it because otherwise, as you say, we'd be breaking
>> compatibility for the people that already upgraded.  For those that need to
>> support both versions, keyword arguments are the way to go.
>
>
> Well, in public interfaces we could just stop mixing *args and **kwargs
> with other arguments.
>
> It is more work for maintainers, but as a library user I find it much
> easier to see the exact args in the docs, rather than seeing  *args  /
> **kwargs and then navigating the inheritance path to find out all supported
> arguments.
>
>
> I'm not quite sure what you're referring to in this case; but generally, I
> agree.  If you pass a parameter, you should document it with @param even if
> your arg list says *args / **kwargs.  This is how I tried to document, for
> example, optionsForClientTLS.
>

Instead of

def __init__(self, resource, requestFactory=None, *args, **kwargs):
    http.HTTPFactory.__init__(self, *args, **kwargs)

you can have

def __init__(self, resource, logFile=None, requestFactory=None):
    http.HTTPFactory.__init__(self, logFile=logFile)


Duplicating documentation is ugly... maybe we can "improve" pydoctor to
support something like this. Like @see but instead of creating a link, the
code is duplicated... but maybe a link is enough


def __init__(self, resource, logFile=None, requestFactory=None):
    """"
    Some description.

    @include http.HTTPFactory.__init__.logFile
    """"
    http.HTTPFactory.__init__(self, logFile=logFile)

-- 
Adi Roiban
-------------- next part --------------
An HTML attachment was scrubbed...
URL: </pipermail/twisted-python/attachments/20151120/6a077c7f/attachment-0002.html>