[Twisted-Python] Running twisted app in a different thread

[Devraj Mukherjee]

Hi all,

I am new to Twisted, please be gentle :)

The Twisted application I am dealing with is python-vnc-viewer
(http://python-vnc.viewer.googlecode.com). We are attempting the RFB
library implemented using Twisted in our application, to bring up a
customer viewer. Our  uses a threading model that is quite centric to
our application.

Is it possible to ask the Twisted application to run in a sea prate thread?

Thanks.

-- 
"The secret impresses no-one, the trick you use it for is everything"
- Alfred Borden (The Prestiege)

___
Twisted-Python mailing list
Twisted-Python@twistedmatrix.com
http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python

Re: [Twisted-Python] A pseudo-deferred class that can be canceled

[Andrew Bennetts]

Terry Jones wrote:
> I just wrote the below for fun.  It's untested :-)
> 
> It's a class that you initialize with a callable (f), and which gives you
> back a deferred (d) that will fire when f fires. Alternately, you can fire
> d yourself by calling 'callback' or 'errback' on the class instance and
> passing a value.  That value is returned via d.
> 
> The reason this is useful is that normally when you call a function that
> returns a deferred, you can't easily "cancel" the deferred because it is
> made and controlled by the function you called. The callback or errback on

I think the key thing is to remember there are two distinct parts:

  1) an operation (which eventually will have a result or failure)
  2) a result 
  
A Deferred takes care of managing 2.  It's a placeholder for that
result, and it can track callbacks that need to be called when it
arrives, etc.

We currently don't have any formal idioms for 1.  I think this is what
you're trying to address.  After all, it's not the result that times out
or that you might want to cancel, it's the operation that is expected to
generate it.

I don't think it's wise to conflate the two concepts, so I think
CancellableDeferred is a poor name.

In an ideal world perhaps every Deferred would have a .operation
attribute, so maybe “d.operation.cancel()” and even
“d.operation.getProgressReport()” would be possible, but I doubt that
every piece of code that creates a Deferred would want to pay the cost
of that bookkeepping.  But hopefully you see my point that it's a
connected but distinct concept to the very simple, single-purpose
callback managing object that a Deferred is.

[...]
> I post this partly because it seems cute, but more because it seems like
> issue that's probably been solved by many people. Is there a general
> utility in Twisted for doing this? A better way?

It feels like there should be, but so far people have basically been
managing the logic that fires Deferreds ad hoc.  I don't think this is
an ideal state of affairs, but it seems it's Good Enough most of the
time.

If I were to try improve the situation, I'd be trying to make an
Operation object or something like that, I think.  I think you'd want to
make it support cancellation (and timeouts) when the underlying code
supports it (network requests are often easy to cancel — just close the
socket), and I'm not sure what would be best when the underlying code is
not cancellable (deferToThread is in general impossible to cancel, etc).

So currently your class isn't something I'd use, because I don't think
it helps with any of this.

-Andrew.


___
Twisted-Python mailing list
Twisted-Python@twistedmatrix.com
http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python

Re: [Twisted-Python] lore2sphinx themeing

[Kevin Horn]

On Mon, Jan 4, 2010 at 8:46 PM, Glyph Lefkowitz wrote:

>
> On Jan 4, 2010, at 7:18 PM, Kevin Horn wrote:
>
> > Thanks to a quick patch from Michael Thompson, the current output of the
> Sphinx conversion [1] now matches the color scheme and typographic style of
> the main twisted site.  It's using the layout of the 'default' sphinx theme
> (previously was using the 'sphinxdoc' theme).
>
> This is an improvement, but it looks like a very rough cut to me.


Like I said, this is the default sphinx theme with some different colors and
text styling.  Yes, very rough.


> The link colors are wrong, it's missing the subtle top/bottom gradients,
> there's no Twisted logo anywhere, etc etc.
>

I'm not sure I understand what you mean about the link colors being
wrong...unless you mean the hover/active/visited colors?  The colors for
links both in the text and in the navigation areas are identical to that in
Trac...

Logo, gradients, etc. were put off until there was a clear understanding of
what exactly was desired.

Spihnx has three "levels" of theme customization.
1. theme options - themes can be set up to take options, which are basically
configurable variables in the templates and css.  This is what's been done
so far.  Just set some colors and fonts.
2. user templates/static files - here you can override templates from the
theme you are using and put things like your own image files, javascript,
css, etc.
3. user themes - a directory or zip file of user templates and static files,
basically as (2), except packaged up nicely to be reusable.


>
> > I'd like to know what people out there want/expect the final theme of the
> Sphinx version of the Twisted docs to look like.
>
> Well, if it ended up looking more or less like it does now, but with a bit
> more attention to detail (at a minimum: some gradients, matching colors, a
> little global navigation to get you back to some Trac pages) I'd be happy,
> and it would be an upgrade.
>
> However, ideally, the page would include links to <
> http://twistedmatrix.com/trac/chrome/common/css/trac.css> and <
> http://twistedmatrix.com/trac/chrome/common/css/wiki.css>, and use the CSS
> classes defined there in its own HTML templates.
>
> While this isn't the cleanest CSS in the world, using it would have two
> significant benefits:
>
>  1. lots of little details, like fonts, colors, sizes, etc, which would be
> exhausting for anyone to investigate and enumerate completely, would line up
> correctly and make it look more polished, and
>  2. if we changed the CSS to adjust the look of the trac site, the docs
> would adjust with it.
>
> I don't mind if this means that some HTML needs to be copied and pasted
> directly from either Trac's templates or Trac's output, as long as it is a
> quick 2-minute cut/paste/edit job that can be quickly explained in a comment
> for someone wanting to update it to a new theme.  I'd much rather have a
> still-slightly-inconsistent documentation theme than burn weeks copy/pasting
> hundreds of little things out of the trac HTML and pain-stakingly
> re-creating every minor effect on the Trac site.
>
>
Groovy, this is exactly the kind of feedback I was looking for.

As far as the CSS goes, I think the best way to handle this would be to
create a stylesheet for the theme, that uses @import to pull in the trac.css
and wiki.css files, and the add or override whatever is necessary.
Templates might be a bit harder to reuse, but we still might be able to do
it.

Thanks for all the good work!
>
>
It's like an addiction. :)

Kevin Horn
___
Twisted-Python mailing list
Twisted-Python@twistedmatrix.com
http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python

Re: [Twisted-Python] lore2sphinx table handling?

[Tim Allen]

On Mon, Jan 04, 2010 at 11:23:37PM -0500, James Y Knight wrote:
> On Jan 4, 2010, at 8:32 PM, Tim Allen wrote:
> > while Grid Tables look pretty, actually editing them requires an Emacs
> > mode, or a lot of patience.
> 
> But when you *do* have an emacs mode (and, really, doesn't everynoe?)  

Well, no, no I don't. Does that mean I don't have to supply
documentation changes with any patches I supply in future? ;)

___
Twisted-Python mailing list
Twisted-Python@twistedmatrix.com
http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python

Re: [Twisted-Python] A pseudo-deferred class that can be canceled

[Terry Jones]

As a final followup before bed...

I chose not to have a 'cancel' method on my class because that seemed
misleading. You're not really canceling anything. You're just asking that a
deferred that you got earlier be fired right now with a value of your
choosing. So I made 2 methods, and named them 'callback' and 'errback'.
The Subject above is reasonably accurate, it's like a pseudo-Deferred
class. Everyone works with regular deferreds, as usual, but if you know you
might want to "cancel" a deferred by firing it early, you can call the
call/errback methods on an instance of CancellableDeferred. Because the
deferred you're holding is not the one that was obtained by calling
self._f, it will fire immediately, which is surely part of the point of
cancellation.  In other words, using the word "cancel" is just a convenient
short / casual description of what's actually being done.

I hope all these words are making things more clear, not less...

Terry

___
Twisted-Python mailing list
Twisted-Python@twistedmatrix.com
http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python

Re: [Twisted-Python] A pseudo-deferred class that can be canceled

[Terry Jones]

Hi Glyph

I read through  without trying to
get all the details (some are not relevant to me, see below).

I'll make a few comments here, then continue in the ticket, supposing
there's interest.

- It would simplify things to separate discussion of canceling deferreds
from discussion of timeouts, which I think you were saying too. The timeout
issue seemed to fade in that ticket, which is good.  The stuff I posted is
just about cancelation, nothing to do with timeouts.

- Deferreds are fairly simple, would be good to keep them that way (i.e.,
  not add to the class). Deferreds are very general, you can use them as
  building blocks to do more complex things, which is what my class does -
  it's just a deferred in the middle.

- Once someone has made a function call, gotten a deferred, added
  call/errbacks to it, etc., it's gone. It's in flight. Forget about it.
  Relax and let it happen, etc. It's too complicated to try to stop things
  from happening that someone else set up to happen in some potentially
  complex manner. Other code, that the Deferred class itself can't possibly
  be aware of, may be relying on the deferred firing and at least part of
  its callback chain being run, etc. The simplest thing to do is to just
  provide a mechanism whereby the eventual holder of the deferred can opt
  to trigger their deferred immediately and ignore the final result of the
  original call (supposing there ever is one).

- My class seems a bit like the Operation class proposed by Peaker. But
  it's simpler because you still only work with normal deferreds. You just
  get to fire a deferred any time you want to, with any value you want, and
  to ignore what would have been the result had you not preempively fired
  it.

Those are some reactions to the thread. I'm happy to continue there.

Terry

___
Twisted-Python mailing list
Twisted-Python@twistedmatrix.com
http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python

Re: [Twisted-Python] lore2sphinx table handling?

[James Y Knight]

On Jan 4, 2010, at 8:32 PM, Tim Allen wrote:

> I think the List Table format is probably the easiest to maintain in
> a simple text editor, followed by the Simple Table format. CSV mode
> looks like it's really designed for you to keep the table in an  
> external
> file and edit it in a spreadsheet, or regenerate it from a database,  
> and
> while Grid Tables look pretty, actually editing them requires an Emacs
> mode, or a lot of patience.

But when you *do* have an emacs mode (and, really, doesn't everynoe?)  
it's the easiest to use.

James

___
Twisted-Python mailing list
Twisted-Python@twistedmatrix.com
http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python

Re: [Twisted-Python] A pseudo-deferred class that can be canceled

[Terry Jones]

> "Glyph" == Glyph Lefkowitz  writes:
Glyph> I already lost you at the first sentence.

:-)  Sorry.

Glyph> The class below never appears to use 'self._f'

Oops, that should have been a self._f in the call method.

Glyph> and ... Deferreds are things that fire, I don't see how the callable
Glyph> (f) can fire.  Can you rephrase your intent?

Yes.

I wanted a way to be able to call something (anything) that returns a
deferred and then, at some later point, to be able to decide that I no
longer want the deferred to fire in the way the original function would
have done it. Instead I want to fire it myself, to in some sense cancel the
outstanding call (by ignoring its result and instead returning a result of
my choosing, right now).

E.g., I call twisted.web.client.getPage and get a deferred (d) back. I add
a callback to d. If sometime later (perhaps just due to too much time
elapsing, but perhaps for another reason - e.g., maybe I'm shutting down a
service, who knows) I want to effectively cancel that deferred, what choice
do I have?  The deferred was made elsewhere (in HTTPClientFactory in this
case), which is presumably going to fire it at some point. Somewhere else
in my code I've now got a callback function that's going to get the result,
though I now don't want that to happen.  I could set a flag somewhere to
indicate to my own callback(s) that it(they) should ignore any incoming
result and/or fail, but that's pretty messy.  Instead I'd like to just
manually cancel the deferred myself - where by "cancel" I mean fire it with
a value of my choosing. Most convenient, probably, is to call its errback
with a TimeoutError of some kind (just as defer.timeout does) which I can
just absorb or log etc.  I can't do this though with the deferred I got
back from getPage.

So the (untested) class I posted sits in the middle. If the original
deferred (from getPage, in our example) fires first, it passes (via
chainDeferred) the result along to the deferred it gave me. If instead I
trigger the deferred myself (by calling 'callback' or 'errback' *on the
CancellableDeferred instance*) then it fires the deferred it gave me back
and will later ignore the result from getPage (if any).

Glyph> I'm glad you're thinking about this, because it is an *extremely*
Glyph> thorny issue which I would really like to address one day.  Many of
Glyph> the issues you're talking about were brought up, and various
Glyph> solutions suggested, then found problematic, then modified ad
Glyph> nauseam on .  If you can
Glyph> read that discussion and make some sense of it, perhaps you can post
Glyph> a recommendation there, or at least a summary of the discussion so
Glyph> far so that I don't have to read the whole discussion again to
Glyph> remember what I think should happen next? :)

OK, I'll take a look (in my copious spare time, etc).

>> I don't know why defer.Deferred.setTimeout is deprecated, but I guess
>> it's partly to do with this control issue.

Glyph> This is one of the reasons, but another major reason is that
Glyph> 'setTimeout' does not belong as a method of Deferred.  If we did
Glyph> support cancellation somehow, the way to set a timeout would be to
Glyph> do 'reactor.callLater(5.0, myDeferred.cancel)'.  Deferred was
Glyph> originally in twisted.python and it really should have remained
Glyph> there, decoupled from twisted.internet.

OK, I agree with that aim.  Cancelation (if you want to call it that) using
my class is, IMO, decoupled from normal deferreds.  Under normal
circumstances you don't want to cancel a deferred you've asked for. But if
you might, you can get yourself an instance of CancellableDeferred and use
it instead. It provides you with a way to cancel the deferred (by which I
mean: manually trigger it yourself with a value of your choosing, and
thereafter ignore anything that might eventually come back from whatever it
was you originally called (and which it is presumably now too late to
undo)).  You can do the canceling via reactor.callLater, just as you
describe, but you call a method on the CancellableDeferred instance, not on
the deferred.  That keeps the canceling functionality out of the deferred
class.

Is that any clearer?  Sorry the code was untested - it was meant to be so
simple that it couldn't possibly be wrong :-)

Terry

___
Twisted-Python mailing list
Twisted-Python@twistedmatrix.com
http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python

Re: [Twisted-Python] A pseudo-deferred class that can be canceled

[Glyph Lefkowitz]

On Jan 4, 2010, at 9:22 PM, Terry Jones wrote:

> I just wrote the below for fun.  It's untested :-)


> It's a class that you initialize with a callable (f), and which gives you
> back a deferred (d) that will fire when f fires. Alternately, you can fire
> d yourself by calling 'callback' or 'errback' on the class instance and
> passing a value.  That value is returned via d.

I already lost you at the first sentence.  The class below never appears to use 
'self._f', and ... Deferreds are things that fire, I don't see how the callable 
(f) can fire.  Can you rephrase your intent?

> The reason this is useful is that normally when you call a function that
> returns a deferred, you can't easily "cancel" the deferred because it is
> made and controlled by the function you called. The callback or errback on
> the deferred is (very likely) going to be called at some point.  OTOH, in
> the class below you get to "cancel" the deferred by triggering it yourself.
> If you fire d in this way, then when the original deferred fires (if ever),
> its result is ignored.

I'm glad you're thinking about this, because it is an *extremely* thorny issue 
which I would really like to address one day.  Many of the issues you're 
talking about were brought up, and various solutions suggested, then found 
problematic, then modified ad nauseam on 
.  If you can read that discussion 
and make some sense of it, perhaps you can post a recommendation there, or at 
least a summary of the discussion so far so that I don't have to read the whole 
discussion again to remember what I think should happen next? :)

> I don't know why defer.Deferred.setTimeout is deprecated, but I guess it's
> partly to do with this control issue.

This is one of the reasons, but another major reason is that 'setTimeout' does 
not belong as a method of Deferred.  If we did support cancellation somehow, 
the way to set a timeout would be to do 'reactor.callLater(5.0, 
myDeferred.cancel)'.  Deferred was originally in twisted.python and it really 
should have remained there, decoupled from twisted.internet.


___
Twisted-Python mailing list
Twisted-Python@twistedmatrix.com
http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python

Re: [Twisted-Python] lore2sphinx themeing

[Glyph Lefkowitz]

On Jan 4, 2010, at 7:18 PM, Kevin Horn wrote:

> Thanks to a quick patch from Michael Thompson, the current output of the 
> Sphinx conversion [1] now matches the color scheme and typographic style of 
> the main twisted site.  It's using the layout of the 'default' sphinx theme 
> (previously was using the 'sphinxdoc' theme).

This is an improvement, but it looks like a very rough cut to me.  The link 
colors are wrong, it's missing the subtle top/bottom gradients, there's no 
Twisted logo anywhere, etc etc.  

> I'd like to know what people out there want/expect the final theme of the 
> Sphinx version of the Twisted docs to look like.

Well, if it ended up looking more or less like it does now, but with a bit more 
attention to detail (at a minimum: some gradients, matching colors, a little 
global navigation to get you back to some Trac pages) I'd be happy, and it 
would be an upgrade.

However, ideally, the page would include links to 
 and 
, and use the CSS 
classes defined there in its own HTML templates.

While this isn't the cleanest CSS in the world, using it would have two 
significant benefits:

  1. lots of little details, like fonts, colors, sizes, etc, which would be 
exhausting for anyone to investigate and enumerate completely, would line up 
correctly and make it look more polished, and
  2. if we changed the CSS to adjust the look of the trac site, the docs would 
adjust with it.

I don't mind if this means that some HTML needs to be copied and pasted 
directly from either Trac's templates or Trac's output, as long as it is a 
quick 2-minute cut/paste/edit job that can be quickly explained in a comment 
for someone wanting to update it to a new theme.  I'd much rather have a 
still-slightly-inconsistent documentation theme than burn weeks copy/pasting 
hundreds of little things out of the trac HTML and pain-stakingly re-creating 
every minor effect on the Trac site.

Thanks for all the good work!


___
Twisted-Python mailing list
Twisted-Python@twistedmatrix.com
http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python

[Twisted-Python] A pseudo-deferred class that can be canceled

[Terry Jones]

I just wrote the below for fun.  It's untested :-)

It's a class that you initialize with a callable (f), and which gives you
back a deferred (d) that will fire when f fires. Alternately, you can fire
d yourself by calling 'callback' or 'errback' on the class instance and
passing a value.  That value is returned via d.

The reason this is useful is that normally when you call a function that
returns a deferred, you can't easily "cancel" the deferred because it is
made and controlled by the function you called. The callback or errback on
the deferred is (very likely) going to be called at some point.  OTOH, in
the class below you get to "cancel" the deferred by triggering it yourself.
If you fire d in this way, then when the original deferred fires (if ever),
its result is ignored.

I don't know why defer.Deferred.setTimeout is deprecated, but I guess it's
partly to do with this control issue. If a timeout function you add to a
deferred calls its errback (the default behavior), the deferred is still
nevertheless going to be called by the code that created it. That code
doesn't know and shouldn't have to check if a timeout happened from the POV
of its caller. The setTimeout approach also only allows one timeout. With
the below, any code can call the callback/errback function at any time. If
you do want to cancel the deferred based simply on a timeout, you can do
this (with as many different timeouts as you like - only the earliest will
have any effect, supposing the original deferred still hasn't fired):

   cd = CancellableDeferred(func)
   deferred = cd.call()
   reactor.callLater(5, cd.errback, None)

I post this partly because it seems cute, but more because it seems like
issue that's probably been solved by many people. Is there a general
utility in Twisted for doing this? A better way?

Terry



from twisted.internet import defer


class CancellableDeferred(object):
def __init__(self, f, *args, **kw):
self._f = f
self._args = args
self._kw = kw
self._calld = None
self.called = False

def _fire(self, result):
if not self.called:
self.called = True
self._calld.chainDeferred(self._resultd)

def call(self):
if self._calld:
raise Exception('Already called.')
self._resultd = defer.Deferred()
self._calld = defer.maybeDeferred(self.f, *self._args, **self._kw)
self._calld.addBoth(self._fire)
return self._resultd

def callback(self, value=None):
if not self.called:
self.called = True
self._resultd.callback(value)

def errback(self, value=None):
if not self.called:
self.called = True
self._resultd.errback(value)

___
Twisted-Python mailing list
Twisted-Python@twistedmatrix.com
http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python

Re: [Twisted-Python] lore2sphinx table handling?

[Tim Allen]

On Mon, Jan 04, 2010 at 06:08:17PM -0600, Kevin Horn wrote:
> Any of these formats should work fine, but I'm curious as to what people (in
> particular the core devs) think as to which should be the preferred method
> in the Sphinx documentation.

I'm not a core dev, but I'll chime in so that at least you'll have some
feedback if nobody else does. :) 

I think the List Table format is probably the easiest to maintain in
a simple text editor, followed by the Simple Table format. CSV mode
looks like it's really designed for you to keep the table in an external
file and edit it in a spreadsheet, or regenerate it from a database, and
while Grid Tables look pretty, actually editing them requires an Emacs
mode, or a lot of patience.

___
Twisted-Python mailing list
Twisted-Python@twistedmatrix.com
http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python

Re: [Twisted-Python] lore2sphinx table handling?

[Glyph Lefkowitz]

On Jan 4, 2010, at 8:21 PM, Michael Hudson-Doyle wrote:

> 2010/1/5 Kevin Horn :
>> Sphinx uses plain ReST tables, and from what I can tell, ReST has 4 (yes,
>> 4!) ways of marking up tables:
>> 
>> Grid tables
>> http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#grid-tables
>> - ASCII-art style tables
> 
> I tend to use these, because they're what emacs' table-mode supports.
> But my opinion probably shouldn't count for all that much :-)

That's what I was going to say as well.  I'm assuming that docutils has support 
for building and emitting grid tables already, though.  If it's difficult to 
format them in the output, or the output looks weird, then I would recommend 
just going with CSV tables for now instead.


___
Twisted-Python mailing list
Twisted-Python@twistedmatrix.com
http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python

Re: [Twisted-Python] lore2sphinx table handling?

[Michael Hudson-Doyle]

2010/1/5 Kevin Horn :
> Sphinx uses plain ReST tables, and from what I can tell, ReST has 4 (yes,
> 4!) ways of marking up tables:
>
> Grid tables
> http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#grid-tables
> - ASCII-art style tables

I tend to use these, because they're what emacs' table-mode supports.
But my opinion probably shouldn't count for all that much :-)

Cheers,
mwh

___
Twisted-Python mailing list
Twisted-Python@twistedmatrix.com
http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python

Re: [Twisted-Python] lore2sphinx themeing

[Reza Lotun]

Hi Kevin,

> Thanks to a quick patch from Michael Thompson, the current output of  
> the Sphinx conversion [1] now matches the color scheme and  
> typographic style of the main twisted site.  It's using the layout  
> of the 'default' sphinx theme (previously was using the 'sphinxdoc'  
> theme).
>
> I'd like to know what people out there want/expect the final theme  
> of the Sphinx version of the Twisted docs to look like.
>
> The floor is open...please offer your

No suggestions really. Just wanted to say this is looking really  
fantastic. Great work so far! Keep it up.

Cheers,
Reza

___
Twisted-Python mailing list
Twisted-Python@twistedmatrix.com
http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python

[Twisted-Python] lore2sphinx themeing

[Kevin Horn]

Thanks to a quick patch from Michael Thompson, the current output of the
Sphinx conversion [1] now matches the color scheme and typographic style of
the main twisted site.  It's using the layout of the 'default' sphinx theme
(previously was using the 'sphinxdoc' theme).

I'd like to know what people out there want/expect the final theme of the
Sphinx version of the Twisted docs to look like.

The floor is open...please offer your suggestions!

[1] http://twistedsphinx.funsize.net/
___
Twisted-Python mailing list
Twisted-Python@twistedmatrix.com
http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python

[Twisted-Python] lore2sphinx table handling?

[Kevin Horn]

Sphinx uses plain ReST tables, and from what I can tell, ReST has 4 (yes,
4!) ways of marking up tables:

Grid tables
http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#grid-tables
- ASCII-art style tables

Simple Tables
http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#simple-tables
- A different style of ASCII-art table, simpler but less powerful than Grid
Tables

CSV Tables
http://docutils.sourceforge.net/docs/ref/rst/directives.html#csv-table
- data is provided in CSV format in the body of a ReST directive

List Tables
http://docutils.sourceforge.net/docs/ref/rst/directives.html#list-table
- data is provided as nested lists in the body of a ReST directive

My question is, what format should the lore2sphinx tool target?

Any of these formats should work fine, but I'm curious as to what people (in
particular the core devs) think as to which should be the preferred method
in the Sphinx documentation.

Keep in mind that there are only 2 tables in all of the Twisted docs, and
one of them is in the documentation for Lore, which (hopefully!) should be
going away once this project is completed.  So it's not like it would be a
whole lot of work to change the preferred format later.

Kevin Horn
___
Twisted-Python mailing list
Twisted-Python@twistedmatrix.com
http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python