[Twisted-Python] usage.Options

[Brian Warner]

> I'm looking at warner's manhole doc at
>     http://www.lothar.com/tech/twisted/manhole.xhtml
> (which is excellent, btw)

<blushes>. thanks. Check out the other docs-in-progress at
http://www.lothar.com/tech/twisted/ too, let me know what you think.

> I'm tempted to wonder if this would be better (if it were implemented in
> usage.Options, of course...):
>     # add manhole with username and password
>     from twisted.tap.manhole import Options, updateApplication
>     updateApplication(app, Options(user='boss', password='sekrit'))

I'm also not sure if this is a sufficiently common need to make shorter..
most of the time the Options come from sys.argv, after all. What I would find
handy, however, would be something to specifically make it easier to add a
manhole service into an application. Something that a beginner could use
without understanding anything further about PB. Something, say, like this:

Index: twisted/manhole/service.py
===================================================================
RCS file: /cvs/Twisted/twisted/manhole/service.py,v
retrieving revision 1.31
diff -u -r1.31 service.py
--- twisted/manhole/service.py	1 Sep 2002 09:07:11 -0000	1.31
+++ twisted/manhole/service.py	5 Oct 2002 07:05:33 -0000
@@ -344,3 +344,17 @@
                                             getattr(self.application,
                                                     'name', "???"))
         return s
+
+
+def addManhole(app, username, password, portno=None):
+    """Convenience method to add manhole service to an existing app. Returns
+    the manhole Service so you can get at its .namespace attribute."""
+    from twisted.cred import authorizer
+    auth = authorizer.DefaultAuthorizer(app)
+    svc = Service("twisted.manhole", serviceParent=app, authorizer=auth)
+    p = svc.createPerspective(username)
+    p.makeIdentity(password)
+    if portno == None:
+        portno = pb.portno
+    app.listenTCP(portno, pb.BrokerFactory(pb.AuthRoot(auth)))
+    return svc


That would allow the user to add a manhole service with a nice, clean
two-line addition (as opposed to my mean, ugly 4-line addition):

 from twisted.manhole.service import addManhole
 addManhole(app, "boss", "sekrit")

And then you can pre-fill the namespace with useful variables (like
theApplication, or your Services) like this:

 from twisted.manhole.service import addManhole
 n = addManhole(app, "boss", "sekrit").namespace
 n['app'] = app
 n['svc'] = my_svc
 n['help'] = " app: theApplication\n svc: my_svc\n"


One shortcoming of my patch is that the auth will probably steal pb.portno
from any existing PB services. If there are already PB services listening on
that port, the code should probably raise an exception and tell the user to
make it listen on a different one (rather than silently insert it's user/pass
into the user's Authorizer). I don't know how to check for that.. any ideas?

thanks,
 -Brian