Hello,
I just noticed that #7098 expanded the meaning of the objects Twisted
typically refers to as "context factories".
Prior to #7098, these were things that implemented a `getContext` method
that returned an `OpenSSL.SSL.Context` instance.
Subsequent to #7098, these are now *either* that or an object that
provides `IOpenSSLClientConnectionCreator`.
It seems that parts of Twisted itself were updated to reflect this
change. For example, the very bottom of the TLS implementation stack in
Twisted, `twisted.protocols.tls`, acknowledges this change (I imagine
this was unavoidable). Also, way on the other side of Twisted,
`twisted.web.client.Agent` takes advantage of this change to implement
the great new certificate and hostname validation features introduced in
14.0.0.
However, other parts of Twisted itself were not updated. For example,
the layers that sit in between `twisted.protocols.tls` and
`twisted.web.client.Agent` weren't touched much. `SSL4ClientEndpoint`,
for example, still documents its `sslContextFactory` as "SSL
Configuration information as an instance of
L{twisted.internet.ssl.ContextFactory}.". And, somewhat insanely I
think, `IReactorSSL.connectSSL` still says "@param contextFactory: a
L{twisted.internet.ssl.ClientContextFactory} object.".
Merely from a documentation standpoint, this seems suboptimal. From a
compatibility standpoint... Well, it seems incompatible to me. Perhaps
this is an instance where the compatibility policy can be broken (though
really that's academic since 14.0.0 has already been released, the
policy has been broken already) but I don't recall any explicit
discussion about a decision to do this.
I *hope* and suspect there won't be much fall-out from this change
considering it's hard to implement TLS and as far as I know there are no
third-party implementations of `IReactorSSL` (GNUTLS came to mind but
they have their own incompatible interface afaict). In other words,
maybe we'll get lucky this time.
I wrote this email instead of filing tickets about the documentation
problems because doing the latter was implicit acknowledgement that this
incompatible change is okay. Having written the email now, I see
there's probably no going back, regardless. Maybe we can learn
something from this incident and avoid repeating it with a more popular
interface, though.
We could probably add a description of this particular kind of
incompatible change to the `CompatibilityPolicy` wiki page. If
reviewers read that page, then they'll know to watch out for it.
And of course (assuming we're committed to this direction, which we seem
to be) we need to fix the rest of the "contextFactory" documentation
throughout Twisted. I'll go file one ticket related to that now...
Jean-Paul
_______________________________________________
Twisted-Python mailing list
Twisted-Python@twistedmatrix.com
http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python
