Path: csiph.com!eternal-september.org!feeder.eternal-september.org!.POSTED!not-for-mail
From: Mark Bourne <nntp.mbourne@spamgourmet.com>
Newsgroups: comp.lang.python
Subject: Re: can you improve this text-only beginner copy program?
Date: Thu, 28 Aug 2025 21:15:11 +0100
Organization: A noiseless patient Spider
Lines: 67
Message-ID: <108qdd0$1jcfd$1@dont-email.me>
References: <87a53kdfpx.fsf@somewhere.edu> <Sphinx-20250827220833@ram.dialup.fu-berlin.de>
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8; format=flowed
Content-Transfer-Encoding: 7bit
Injection-Date: Thu, 28 Aug 2025 20:15:29 +0000 (UTC)
Injection-Info: dont-email.me; posting-host="e20cd3cdca54d69c8d306f2d464c04b1"; logging-data="1683949"; mail-complaints-to="abuse@eternal-september.org";	posting-account="U2FsdGVkX1+uW1OWEAxJHb8k9S5d3gVK"
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:128.0) Gecko/20100101 SeaMonkey/2.53.21
Cancel-Lock: sha1:25UjIW+Xb/9P6vc/WBNlQ2ZKc0c=
In-Reply-To: <Sphinx-20250827220833@ram.dialup.fu-berlin.de>
Xref: csiph.com comp.lang.python:197548

Stefan Ram wrote:
> Ethan Carter <ec1828@somewhere.edu> 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.