• 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: * ":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.

...

On Dec 26, 2024, at 2:04 PM, Kirill Miazine <km@krot.org> wrote:

While browsing through the twisted.web docs, I noticed following:

Hello's getChild() method on https://docs.twisted.org/en/stable/web/howto/using-twistedweb.html#resource-... has a typo. It says

if name == '':

where it should have said:

if name == b'':

• Glyph [2024-12-29 01:48]: [...]>> 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 :).

Uh-oh.

We need an overhaul that can do things like handle incremental uploads as well.  See <https://github.com/twisted/twisted/issues/4688 <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" :).

I'd really prefer to send a good old patch, but here you go: https://github.com/twisted/twisted/pull/12410