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

[Jean-Paul Calderone]

On Sun, 19 Mar 2006 10:54:27 -0800, James Schend <blakeyrat at gmail.com> wrote:
>http://twistedmatrix.com/documents/current/api/twisted.conch.telnet.html
>
>It lists the classes, and then right next to (almost all of) them it
>says "undocumented."
>
>How can the two interfaces document the public method completely if
>they're undocumented?

Did you try clicking on any links on that page?

>
>Thanks for your second link, however, I hadn't found that page during
>my surfing of your site.  It looks useful.

It should probably be displayed somewhere more prominently on the site.  For some reason, someone has added a link to the conch howtos to the front page, which may leave readers with the incorrect impression that is all of the conch documentation.

>
>I still don't understand why you'd deprecate a stable interface in
>preference to an *unstable* one.

Because I have no interest in maintaining the stable interface since it is so narrowly useful.


>What happens if conch changes in
>some way and needs to be deprecated again?  It seems to me like it's a
>"damned if you do or damned if you don't"... if you use
>twisted.protocols.telnet it'll be removed and your code won't work,
>but if you use twisted.conch.telnet it could be changed and your code
>won't work.

That's life when you're depending on the volunteer efforts of others. :)  That said, nothing is stopping you from using twisted.protocols.telnet: if it is someday removed, you can always distribute a copy of it with your software.

>
>I'm not nearly concerned, BTW, about the <1.0 version number as I am
>about the "unstable" warning.
>
>If twisted.conch is what people are supposed to be using, wouldn't it
>make sense to put that in the core install?

No, because the "core install" is a very special-purpose thing that most people aren't interested in.  It's part of the "Twisted install" already, and that's what most people should install.

>
>Sorry for being such a griper and for hammering a dead horse with this
>one.  I guess I'd just like some assurance that my project, written
>using twisted.conch, will still work as the conch library gets
>upgraded to 1.0

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

To look at this problem another way, how would you feel if you started to use twisted.conch.telnet and found that it satisfied 90% of your use-case, but that due to one critical oversight, you couldn't supply the remaining 10% yourself but instead had to write your own telnet library from scratch, because we had given up the freedom of making changes to twisted.conch.telnet?  That wouldn't be any more useful to you than the current situation.

What you can do is use it and provide feedback on what it does and does not do well and work with us to improve it to the point where we _are_ confident that it is good enough to abandon the hope of making further incompatible changes to it later on.

> (at which point, I presume, it would become stable?)

Maybe or maybe not.  Generally we mark APIs as stable or unstable with finer granularity than this.  It is unlikely that all of conch will become stable at the same time.

Jean-Paul