On Dec 28, 2024, at 12:28 PM, km@krot.org wrote:
• Glyph [2024-12-28 07:12]:
Yep, that's definitely wrong, thank you for spotting it! I suspect you may find other type-confusion problems in the docs, which don't really have type-checking or testing applied to them. -g
It wasn't just spotting it, it was wondering for quite a while _why_ it didn't work.
Actually, I was slightly surprised that child names are using bytes and not strings: I am used to decode() as early as possible, deal with strings, and then encode() as late as possible. So URL parts being bytes felt kind of weird, and certainly a surprise that could bite a novice.
Actually, the howto page needs a review, as it's rather consistently saying "strings" where bytes are expected:
Sadly, a lot of the documentation is like this. And the resource model itself needs a revisit; these were bytes because bytes were strings 20 years ago. Twisted's HTTP server was originally built on HTTP/0.9, and it really shows sometimes :). We need an overhaul that can do things like handle incremental uploads as well. See <https://github.com/twisted/twisted/issues/4688> and the cluster of related issues.
* ":ref:`Resource rendering <web-howto-using-twistedweb-rendering>` occurs when Twisted Web locates a leaf Resource object. A Resource can either return an html [STRING] or write to the request object."
* "A Resource can know where it is in the URL tree by looking at request.prepath , a list of URL segment [STRINGS]."
* "If the URL ends in a slash, for example http://example.com/foo/bar/ , the final URL segment will be an empty [STRING]."
* "Resource rendering occurs when Twisted Web locates a leaf Resource object to handle a web request. A Resource's render method may do various things to produce output which will be sent back to the browser:
- Return a [STRING]"
I've made an issue on github, so it's not forgotten: https://github.com/twisted/twisted/issues/12409. I could probably as well suggest some changes to the wordings, but I have to figure out how github works -- apparently sending patches is now how it's done nowadays.
Not sure if by "sending patches" you mean "making pull requests" :). Thanks! -g