On 2025-08-28 21:15:11 +0100, Mark Bourne wrote: > I don't know if Sphinx can extract types from type hints but, at least if > the docstring is just for humans reading the code, using those can reduce > the markup in the docstring: > ``` > def copy(s: int, d: int) -> None: > """ > Copy the contents of the text file whose path is given by the > parameter ``s`` to the text file whose path is given by ``d``.
I'm almost sure that you didn't intend the paths to be of type int.
>
> :param s: Path to the source text file to copy from.
> :param d: Path to the destination text file to copy to.
> :raises OSError: If an I/O error occurs during writing. On error,
> the destination file will be removed if it was
> partially written.
> """
> ```
>
> Aside from acting as documentation of the expected argument and return
> types, type hints can also be read by type checkers to help find places
> where objects of the wrong types might be passed. Type hints don't make any
> difference at runtime, so you could still call `copy(1, 2)` and it'll copy a
> file named "1" to a file named "2",
No, it would try to copy from file descriptor 1 to file descriptor 2.
Given that file descriptor 1 is normally stdout and file descriptor 2 is
stderr, this doesn't make much sense but it would work (fsvo) in a Linux
terminal.
> but type checkers would flag that as a
> possible bug - it should be `copy("1", "2")` if that's really what you
> intend.
Actually, the way you wrote it, the checker would flag the correct usage
as incorrect (and the incorrect one, too, since os.remove doesn't accept
an int).
hjp
--
_ | Peter J. Holzer | Story must make more sense than reality.
|_|_) | |
| | | [email protected] | -- Charles Stross, "Creative writing
__/ | http://www.hjp.at/ | challenge!"
signature.asc
Description: PGP signature
-- https://mail.python.org/mailman3//lists/python-list.python.org
