Stefan Ram wrote:
Ethan Carter <[email protected]> wrote or quoted:
def copy(s, d):
"""Copies text file named S to text file named D."""
with open(s) as src:
with open(d, "w") as dst:
try:
dst.write(src.read())
except Exception:
os.remove(d)
raise
In Python there are several ways to format docstrings.
One possibility is to use conventions from "Sphinx" and to use
"reStructuredText". Then, it might look as follows, giving some
prominence to the names of parameters, though some find that
this is already too much markup in the source code:
"""
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``.
:param s: Path to the source text file to copy from.
:type s: str
:param d: Path to the destination text file to copy to.
:type d: str
:raises OSError: If an I/O error occurs during writing. On error,
the destination file will be removed if it was
partially written.
"""
Sphinx can then extract such documentation from your source code
and generate webpages or PDF books from it.
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``.
: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", but type checkers would
flag that as a possible bug - it should be `copy("1", "2")` if that's
really what you intend.
Maybe type hints are considered a bit advanced for just starting out, it
would seem a good idea to learn about type hints along with the rest of
Python rather than something bolted on afterwards (even if "bolted on
afterwards" is how they came into the Python language!)
--
Mark.
--
https://mail.python.org/mailman3//lists/python-list.python.org
