[Twisted-Python] HTTPClientFactory's deferred never finishing download on .vcf (vcard file) link

Steve Steiner (listsin) listsin at integrateddevcorp.com
Sun Oct 11 11:07:56 EDT 2009


On Oct 10, 2009, at 9:07 PM, Glyph Lefkowitz wrote:

> Much of the other code I'm using follows PEP-8 naming_conventions  
> for methods and such whereas Twisted follows the Twisted Coding  
> Standard which is a more javaCamelCase style convention.
>
> For what it's worth, the Twisted coding standard pre-dates PEP-8 (In  
> fact, I think it might even predate the whole PEP process).

> Also, Java did not invent the convention of camel-case names.  My  
> use of the convention in the early Twisted coding standard was a  
> deliberate aping of Smalltalk's coding convention.  I realize a lot  
> more people have seen Java written this way than ST, but  
> nevertheless ST was my inspiration for many of Twisted's  
> conventions, coding-standard and otherwise.

I understand.  I refer to it as "Java" since that's more current.  I  
think of it more as ST as well; I was there "back then."  It's one of  
the things I really like about Twisted.  I just kind of "get" it  
'cause it makes sense from for a long time <sic>.

I don't particularly agree with, or like some things in PEP-8.

For example, I like to line things up "right" when organization can be  
indicated by spacing like (which will be mutilated by e-mail, but you  
know what I mean):

foo = (
		("this value is long",	"default"),
		("short",			"other"),
	)

If it's a table, it should be laid out like a table, not all crooked  
and stuff.  CamelCase is another issue.  Why it should be OK in  
ClassNames but not OK in variable_names, since you have to hit the  
shift key to get the flippin' underscore anyway, has 'logic' that  
escapes me. "Inserting an extra, meaningless extra character, which  
requires using the Shift key, instead of the next letter, also with  
the shift key saves *thing*."

> That particular documentation refers to 'backwards compatible'  
> functions using PEP-8 style attribute names while preferring the  
> newer Twisted Coding Standard flavoured names.
>
> Yes, before code review was consistently applied throughout the  
> codebase, we did have a few inconsistent names slip through.  Since  
> then we've tried to update them where we've found them so everything  
> is consistently in one style.

Also understood.  That's the thing about writing stuff other people  
use; you've got to keep it working even when you're slapping your  
forehead about something you decided then that's now so _obviously_  
better done another way.

> Making the right things show up in the right order in our API  
> documentation is a constant challenge.  If you have any ideas for  
> emphasizing the correct (i.e. non-"backwards-compatibility") names,  
> you might want to submit a patch to pydoctor and/or Twisted's  
> docstrings.

I actually took a quick look at pydoctor for the first time tonight.   
I'm wrestling with getting a doc set together from some code that's  
EpyDoc, some that's Sphinx, and some that's not there at all.

What I'd like is to use Sphinx, using all of EpyDoc's nice extensions  
to reStructuredText (e.g. the nice :Parameters: block stuff) so I'm  
looking to see if anyone's already done that work for Sphinx.

Meanwhile, vis-à-vis the Twisted docs, has there been any recent  
discussion about moving the Twisted docs to Sphinx?  I found some doc  
discussions way back to 2002, nothing later than 2007/8-ish, but, as  
far as I know, there's not particular effort underway.

If Twisted could get documented with Sphinx, while adding anything  
Twisted needs that Sphinx doesn't have already, it would sure be  
nice...and would remove one more Twisted specific tool to maintain in  
the Twisted toolchain, while enhancing Sphinx at the same time.

I'm having to do the pydoctor vs. Sphinx vs. EpyDoc research  
anyway...I'll post it somewhere public and send a link/message to the  
list.

S






-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://twistedmatrix.com/pipermail/twisted-python/attachments/20091011/887948a9/attachment.htm 


More information about the Twisted-Python mailing list