Opened 15 years ago

Last modified 11 years ago

#1148 enhancement new

Replace current finger examples with lifeless's and radix's work on a TDD finger example

Reported by: hypatia Owned by:
Priority: normal Milestone:
Component: core Keywords: documentation
Cc: radix, Jean-Paul Calderone, robertc, Thijs Triemstra, Glyph Branch:
Author:

Description


Change History (10)

comment:1 Changed 15 years ago by hypatia

Robert Collins reported that his staff (who are experienced programmers) found
it difficult to use the finger tutorial in the sense of deriving best practices
from it and working out how to test their code. He and radix did some
substantial work over the weekend in Sydney on re-writing the code with a test
driven approach and making sure that it followed best practices as the Twisted
developers define them.

You can find the work at http://www.robertcollins.net/twisted_sprint (that's a
bzr repository as well) -- it's code and no docs so far.

I understand that the current state of the code is as follows:
 - it works and is well tested
 - new examples need to be added (eg HTTP)
 - someone needs to break it up into chewy pedagogically sound
Twisted-for-beginners pieces

It will then be ready for prose around it, which is probably where I come in.

comment:2 Changed 15 years ago by Jean-Paul Calderone

I don't understand the reason for using `self.deferred' in protocols.py.  It
doesn't seem like there's any reason to keep a reference to that deferred, and
there are good reasons not to (garbage collection, etc).

comment:3 Changed 15 years ago by hypatia

IIRC, for test reasons. radix may enlighten you further though. Or bug lifeless
on IRC he will be all to happy to explain if it doesn't require that he gets a
bugtracking login.

comment:4 Changed 14 years ago by hypatia

Cc: robertc added; hypatia removed
Component: core
Owner: changed from hypatia to edsuom

comment:5 Changed 11 years ago by rotund

Another thing to look at is Moshe's Deferred Tutorial from PyCon 2009.

http://moshez.files.wordpress.com/2009/03/deferred-pres.pdf

comment:6 Changed 11 years ago by rotund

From Issue #2720:

itamarst: Let me be more specific then - I am proposing a single document with following structure, starting from simple to more complex, the idea being to ease people into it:

  1. Handwaving: "Deferreds are a promise" 2. Using Deferreds the easy way - inlineCallbacks/deferredGenerator. The need for yield gets across some of implications of deferred result. 3. Using Deferreds without layer of abstraction. 4. Creating Deferreds.

And then maybe other howto for more "expert" or possibly utility stuff like gatherResults, DeferredQueue?, etc..

comment:7 Changed 11 years ago by rotund

Issue #1138 had more suggestions on this.

comment:8 Changed 11 years ago by Thijs Triemstra

Cc: Thijs Triemstra added

comment:9 Changed 11 years ago by Glyph

Cc: Glyph added

On #3735, exarkun referred me to this ticket as the ticket to deal with the testability problems with the current finger tutorial. I can see that #2720 has been closed as a duplicate of this as well.

I'd like to update this ticket, and perhaps file some new ones, to give a clearer picture of what's actually desired, rather than how we're going to go about addressing what's desired (i.e. using radix and lifeless's work).

I think there are several discrete problems actually being raised by this ticket:

  1. the finger tutorial does not cover how to test a twisted application.
  2. the finger tutorial proposes development idioms which are hostile to testing, such as cramming all of one's code into a .tac file, hard-coding pathnames, creating lots of objects at the top level of scope, etc.
  3. the finger tutorial does not cover "best practices"; for example, keeping .tac files small, putting different subsystems into separate modules, not duplicating code... although it's not entirely clear to me what "best practices" actually refers to here.
  4. the closure of #2720 piles on an additional requirement, which does not appear to be addressed at all by the work that radix and lifeless have done, which is to write a better Deferred tutorial and include it within the finger tutorial.
  5. as an almost implicit corollary to the first and second points here, the finger tutorial is itself untested, and therefore changing it is difficult.

I feel like I'm missing something, too, since "best practices" is kind of a vague term, and could easily encompass something that I didn't catch in my shallow reading of the fingerd branch that I made here.

So, for starters, let's rewrite the summary of this ticket to describe what this new tutorial would actually accomplish. Before I do that though I'd like to hear some thoughts on how we should be approaching this.

My personal opinion is that #2720 should just be reopened, because we can address the somewhat smaller and more pressing issue of consolidating our documentation of Deferreds into a single tutorial just for Deferreds would be a lot easier than addressing the larger tutorial situation as a whole.

Also, I think that testing of documentation should be addressed in a completely separate ticket. The code referenced above doesn't touch on the issues involved at all: a tutorial will often want to show a few different snapshots of a piece of code in development (although the current finger tutorial way overdoes this, since it doesn't ever use modules, but I digress...). The tutorial code lives in doc/.../listings, not in the main library, so it's not easy to make sure it's on sys.path properly. Although the current finger tutorial itself is a testing nightmare due to its substantial duplication of code, the aforementioned issues are the ones that prevent us from writing code for new documentation, and I think it would be easy to address those separately. Duncan McGreggor and I did some work on a tutorial for Athena a while ago that might serve as a good basis for some work in this direction.

My general inclination would actually be to file tickets for each of the above items, maybe even more than one apiece. But I'm open to the argument that documentation would be better served by a comprehensive overhaul and a consistent narrative voice, so it is more suitable for radical overhauls than code, where we would normally insist on incremental improvement. In the case of both the Deferred stuff and the documentation-test infrastructure, I think smaller changes would be better though.

Finally, if somebody is to replace the tutorial from scratch, I think that finger is a fairly unusual protocol to produce a demonstration with. For example, the stock finger(1) client shipped by the various free unices does not provide a command-line option to customize the port number. Even telnet(1) can do better. But, better than address it from the perspective of a single protocol, address it from the perspective of an application. Calling it a "user directory" tutorial would make more sense than the "finger" tutorial, IMHO.

comment:10 Changed 9 years ago by <automation>

Owner: edsuom deleted
Note: See TracTickets for help on using tickets.