linkcheck: constrain status code types to `LiteralString`

sphinx-doc / sphinx

The Sphinx documentation generator

https://www.sphinx-doc.org/

Other

6.61k stars 2.13k forks source link

linkcheck: constrain status code types to `LiteralString` #13039

Closed jayaddison closed 1 month ago

jayaddison commented 1 month ago

Feature or Bugfix

Refactoring

Purpose

Begin adding some code-symbol safety measures around the use of status codes in the linkcheck builder.
Prepares for a subsequent refactor to use a StrEnum (Py3.11+) to declare the available status codes.

Detail

Add LiteralString typing to status code variables.

Relates

Branched-from #13036.

AA-Turner commented 1 month ago

Why LiteralString over Literal[...]?

jayaddison commented 1 month ago

Ah; to be honest, I'd forgotten about Literal and didn't notice it despite double-checking some usage details for LiteralString (which is what I misread your suggestion to be..).

Assuming that I had opened a PR with the intended change instead, using Literal[...]: that would be a nice low-overhead type safety mechanism, but wouldn't provide much runtime assurance, if I understand it correctly. Additionally, the diff from here to StrEnum introduction might be slightly unusual -- it would involve complete replacement of the Literal-based type alias approach with a StrEnum alternative (that does provide runtime safety).

jayaddison commented 1 month ago

Note: from a readability point of view, I do find the dotted-attribute format (for example, LinkStatus.WORKING) an improvement, so I would like to migrate to StrEnum.

(the reason I mention this is because Literal[...] almost seems like it could solve my refactoring goals entirely, without using StrEnum at all.. except that I don't think standalone constants are ideal; grouping them logically within a parent container is helpful, I think)

jayaddison commented 1 month ago

Superseded by #13040.