Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > comp.lang.python > #197548

Re: can you improve this text-only beginner copy program?

Show all headers | View raw

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.

Back to comp.lang.python | Previous | Next — Previous in thread | Next in thread | Find similar

Thread

can you improve this text-only beginner copy program? Ethan Carter <ec1828@somewhere.edu> - 2025-08-27 11:03 -0300
  Re: can you improve this text-only beginner copy program? ram@zedat.fu-berlin.de (Stefan Ram) - 2025-08-27 15:12 +0000
    Re: can you improve this text-only beginner copy program? Ethan Carter <ec1828@somewhere.edu> - 2025-08-27 13:57 -0300
      Re: can you improve this text-only beginner copy program? ram@zedat.fu-berlin.de (Stefan Ram) - 2025-08-27 17:45 +0000
      Re: can you improve this text-only beginner copy program? Piergiorgio Sartor <piergiorgio.sartor.this.should.not.be.used@nexgo.REMOVETHIS.de> - 2025-08-27 22:21 +0200
      Re: can you improve this text-only beginner copy program? Mark Bourne <nntp.mbourne@spamgourmet.com> - 2025-08-28 21:05 +0100
        Re: can you improve this text-only beginner copy program? (Posting On Python-List Prohibited) Lawrence D’Oliveiro <ldo@nz.invalid> - 2025-08-28 22:17 +0000
  Re: can you improve this text-only beginner copy program? ram@zedat.fu-berlin.de (Stefan Ram) - 2025-08-27 21:09 +0000
    Re: can you improve this text-only beginner copy program? Mark Bourne <nntp.mbourne@spamgourmet.com> - 2025-08-28 21:15 +0100
      Re: can you improve this text-only beginner copy program? ram@zedat.fu-berlin.de (Stefan Ram) - 2025-08-28 20:50 +0000
  Re: can you improve this text-only beginner copy program? (Posting On Python-List Prohibited) Lawrence D’Oliveiro <ldo@nz.invalid> - 2025-08-28 01:36 +0000

csiph-web