[Twisted-Python] twisted.protocols.telnet or twisted.conch.telnet?

[Jean-Paul Calderone]

On Sun, 19 Mar 2006 10:08:47 -0800, James Schend <blakeyrat at gmail.com> wrote:
>I'm still not convinced.  If you look at the API reference under Conch:
>
>http://twistedmatrix.com/documents/current/api/twisted.conch.telnet.html
>
>And the API refrerence under Protocols:
>
>http://twistedmatrix.com/documents/current/api/twisted.protocols.telnet.Telnet.html
>
>There's a HUGE difference in the amount of documentation available.

Yes.  There seems to be much more documentation for twisted.conch.telnet.

>Just learning this stuff for the first time, I need as much
>documentation as I can get... all the examples, and all the API docs,
>seem to be in twisted.protocols.telnet.  And of course I'd much rather
>use something that's at version 2.2 than something that's at version
>0.6.

Don't attach too much significance to these numbers.  It would be great if versioning actually conveyed some information, but it hardly does.  The only thing you can reliably take away from a version number is whether or not it is larger or smaller than another version /for the same piece of software/.  This loosely correlates with whether it is newer or older than another release of that software, little else.  In particular, you cannot compare version numbers of different pieces of software meaningfully.

>If conch is still unstable and hasn't hit 1.0, why is the old
>interface deprecated?

Because the old interface is quirky and incomplete and the implementation is unmaintained (and basically unfixable without breaking backwards compatibility).

>It seems silly to deprecate the old interface
>if the new one, being unstable, might change and require being
>deprecated again.  I'm sorry, I just don't understand.

The deprecation is an indication of our future plans.  If you are more worried about the twisted.conch.telnet API changing than you are about the incompleteness and unmaintainedness of twisted.protocols.telnet, by all means, use twisted.protocols.telnet.  It's not a "warning" for nothing.

>
>(FYI, I did download the entire tarball, but I only installed the
>"core" because I figured that that was all I needed.  I didn't
>anticipate that "correct" telnet interface had moved because, again,
>this isn't documented in the API reference, which I looked at before
>installing.)
>
>You say that Conch is better... how is it better?  Is
>twisted.protocol.telnet going away in the near future?

As soon as reasonably possible.

>What the heck should I be using?

twisted.conch.telnet.

>Other than the deprecated warning, I'm inclined to use the "old" 
>twisted.protocols.telnet interface which at least has examples 
>and documented functions.

I'm confused by your repeated claims of the absense of documentation for twisted.conch.telnet.  <http://twistedmatrix.com/documents/current/api/twisted.conch.telnet.html> lists two interfaces, six exception classes, and five protocol classes.  The API documentation pages for the two interfaces alone document the eleven public methods of twisted.conch.telnet completely, and <http://twistedmatrix.com/projects/conch/documentation/examples/> gives numerous examples of both custom telnet and ssh servers.

>
>Thanks again for your help.  It looks like I found your toolset in the
>midst of some huge confusing rewrite or something.  :)  Just my luck.

Things are pretty much always like this.  The only possible hope for perfect documentation is to have a dead project.  I much prefer an active one.

Jean-Paul