IPolicyForHTTPS.createForNetloc incorrectly documents its hostname parameter's type

[habnabit]

IPolicyForHTTPS.createForNetloc states that the hostname parameter should be of type unicode. However, both of its implementors seem to disagree. BrowserLikePolicyForHTTPS documents that its hostname parameters is bytes and attempts hostname.decode('ascii'). _DeprecatedToCurrentPolicyForHTTPS similarly documents its hostname parameter is bytes. The current primary user of the interface, Agent, does not explicitly document that it passes bytes, but regardless only ever passes bytes to createForNetloc. One test does document the parameter as unicode, but then passes bytes anyway.

Based on the above, it's my opinion that the action to be taken is to change the documentation to be consistent with the implementation.

[habnabit]

(In [42612]) Branching to 'fix-IPolicyForHTTPS-documentation-7302'

[habnabit]

(In [42613]) Update 'unicode' -> 'bytes'.

refs #7302

[habnabit]

​Forced a build.

[Jeremy Thurgood]

Related to this, BrowserLikePolicyForHTTPS.createForNetloc documents a tls parameter which isn't present.

[Jean-Paul Calderone]

Related to this, BrowserLikePolicyForHTTPS.createForNetloc documents a tls parameter which isn't present.

Please file a ticket for it instead of commenting on an already-up-for-review ticket which a different scope. Thanks!

[Adi Roiban]

This looks good. Thanks for the fix.

Since BrowserLikePolicyForHTTPS implements IPolicyForHTTPS, does it need to duplicate docstring for methods which are already documented in the interface? Maybe a See iweb.BrowserLikePolicyForHTTPS.createForNetloc can help with reducing code duplication.

Thanks!

[Glyph]

Replying to adiroiban:

This looks good. Thanks for the fix.

Since BrowserLikePolicyForHTTPS implements IPolicyForHTTPS, does it need to duplicate docstring for methods which are already documented in the interface? Maybe a See iweb.BrowserLikePolicyForHTTPS.createForNetloc can help with reducing code duplication.

Nope. pydoctor will copy the interface docstring if it implements the interface, so it's actually better to leave it blank.

[Glyph]

Sigh. URLs are weird. I think maybe this was a mistake? But you're right in that it's a mistake that was already made, and we should fix the documentation to reflect reality. Fixing the mistake for real might involve IRIs or something.

Make it so.

[Glyph]

Ahem. Ping. Please land within 24 hours or I will.

[Glyph]

(In [42954]) Merge fix-IPolicyForHTTPS-documentation-7302: fix interface type documentation

Author: habnabit

Reviewer: glyph

Fixes: #7302

IPolicyForHTTPS.createForNetloc states that the hostname parameter should be of type unicode. However, both of its implementors seem to disagree. This change adjusts the interface documentation to reflect the reality of the implementation.

[hawkowl]

Ticket retargeted after milestone deleted