Path: csiph.com!fu-berlin.de!uni-berlin.de!not-for-mail
From: ram@zedat.fu-berlin.de (Stefan Ram)
Newsgroups: comp.lang.python
Subject: Re: can you improve this text-only beginner copy program?
Date: 27 Aug 2025 21:09:56 GMT
Organization: Stefan Ram
Lines: 35
Expires: 1 Jun 2026 11:59:58 GMT
Message-ID: <Sphinx-20250827220833@ram.dialup.fu-berlin.de>
References: <87a53kdfpx.fsf@somewhere.edu>
Mime-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
X-Trace: news.uni-berlin.de SSIPmVEvYkIP8ctlLClGrQ/0oyMe/k1oz+iqXIKnpUiiTF
Cancel-Lock: sha1:B2MtMc3gdt7w9KKDq3BbGXipZxI= sha256:0bMDv8zd8rPC/PpxUd6V3sStqwFBYnpyKWTGa2K+bnU=
X-Copyright: (C) Copyright 2025 Stefan Ram. All rights reserved. Distribution through any means other than regular usenet channels is forbidden. It is forbidden to publish this article in the Web, to change URIs of this article into links, and to transfer the body without this notice, but quotations of parts in other Usenet posts are allowed.
X-No-Archive: Yes
Archive: no
X-No-Archive-Readme: "X-No-Archive" is set, because this prevents some services to mirror the article in the web. But the article may be kept on a Usenet archive server with only NNTP access.
X-No-Html: yes
Content-Language: en-US
Xref: csiph.com comp.lang.python:197545

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.