From Newsgroup: comp.lang.python

The program below only copies text files on purpose---because we haven't learned about binary files in this course yet. (So I could catch a UnicodeDecodeError while writing.) If an exception is raised while
writing, I need to delete the file that was created. Can you think of
anything I'm missing? I'm sure you can improve it by making it more
efficient for not reading the entire file into memory---I'm aware of
that, but also not going in that direction right now. (I will worry
about that when I write a new version that does binary reading.) In
summary, don't demand too much of a Python beginner here. Thanks!

# -*- mode: python; python-indent-offset: 2 -*-
import os
import sys

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

def usage(program):
return f"""usage: python {program} source.txt destination.txt"""

def main(argc, argv):
if argc != 3:
raise SystemExit(usage(argv[0]))
copy(argv[1], argv[2])

if __name__ == "__main__":
main(len(sys.argv), sys.argv)
--- Synchronet 3.21a-Linux NewsLink 1.2

From Newsgroup: comp.lang.python

Ethan Carter <ec1828@somewhere.edu> wrote or quoted:

Can you think of anything I'm missing?

The correctness of a program as a solution to an assignment
depends on the exact wording of the assignment, so it's a
bit difficult to say without seeing it.

"""Copies text file named S to text file named D."""

This is not entirely clear, since case is significant in Python
("S" is not the same as "s"), and it is ambiguous whether it refers
to a file actually named "S" or to a file whose name is provided as
a str object bound to the name "s" in the function's source code.


--- Synchronet 3.21a-Linux NewsLink 1.2

From Newsgroup: comp.lang.python

ram@zedat.fu-berlin.de (Stefan Ram) writes:

Ethan Carter <ec1828@somewhere.edu> wrote or quoted:

Can you think of anything I'm missing?

The correctness of a program as a solution to an assignment
depends on the exact wording of the assignment, so it's a
bit difficult to say without seeing it.

You're right. There's no written statement. The exercise was suggested
by the teacher while in class. It was something like ``write a program
that copies text files by getting source and destination via the command-line.''

"""Copies text file named S to text file named D."""

This is not entirely clear, since case is significant in Python
("S" is not the same as "s"), and it is ambiguous whether it refers
to a file actually named "S" or to a file whose name is provided as
a str object bound to the name "s" in the function's source code.

This is how docstrings are traditionally written in GNU EMACS ELISP
code---they upcase argument names of the procedure being documented. I
can't recall who taught me this, but I believe it was Robert Chassel in
his book ``An Introduction to Emacs Lisp'' that's included in the GNU
EMACS itself.

But, yeah, if the Python community doesn't do that, it's all what you
say.

Thanks for your attention!

PS. Is it just me or there's just us in this used-to-be-very-active
group? Thanks for being my teacher here. Have a good day!
--- Synchronet 3.21a-Linux NewsLink 1.2

From Newsgroup: comp.lang.python

Ethan Carter <ec1828@somewhere.edu> wrote or quoted:

You're right. There's no written statement. The exercise was suggested
by the teacher while in class. It was something like ``write a program
that copies text files by getting source and destination via the >command-line.''

Well then, I'd think about using "shutil", e.g., "shutil.copy".
Check it out in "The Python Library Reference"; it's 11.10.1 in
release 3.13.0a0.

But, yeah, if the Python community doesn't do that, it's all what you
say.

Community or no community, in Python, you can have:

def f( s, S ):
return 2*s+S

. Should the docs then say, "returns 2*S+S"?

PS. Is it just me or there's just us in this used-to-be-very-active
group? Thanks for being my teacher here. Have a good day!

Thanks, you too!

On one hand, many people seem to prefer websites for discussions
nowadays. On the other hand, if I had not responded, probably
someone else would have.


--- Synchronet 3.21a-Linux NewsLink 1.2

From Newsgroup: comp.lang.python

On 27/08/2025 18.57, Ethan Carter wrote:
[...]

"""Copies text file named S to text file named D."""

This is not entirely clear, since case is significant in Python
("S" is not the same as "s"), and it is ambiguous whether it refers
to a file actually named "S" or to a file whose name is provided as
a str object bound to the name "s" in the function's source code.

This is how docstrings are traditionally written in GNU EMACS ELISP code---they upcase argument names of the procedure being documented. I
can't recall who taught me this, but I believe it was Robert Chassel in
his book ``An Introduction to Emacs Lisp'' that's included in the GNU
EMACS itself.

That's because LISP has a difficult relationship
with case (sensitive / insensitive).

In any environment strictly case sensitive, it's
obviously not a good idea to change case at will.

So, don't use LISP docstrings style in Python...

bye,
--

piergiorgio
--- Synchronet 3.21a-Linux NewsLink 1.2

From Newsgroup: comp.lang.python

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.


--- Synchronet 3.21a-Linux NewsLink 1.2

From Newsgroup: comp.lang.python

On Wed, 27 Aug 2025 11:03:22 -0300, Ethan Carter wrote:

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

copy("/proc/sys/kernel/random/uuid", "/dev/full")

--------------------------------------------------------------------------- OSError Traceback (most recent call last) OSError: [Errno 28] No space left on device

During handling of the above exception, another exception occurred:

OSError Traceback (most recent call last) Cell In[5], line 11
8 os.remove(d)
9 raise

11 copy("/proc/sys/kernel/random/uuid", "/dev/full")

Cell In[5], line 4, in copy(s, d)
2 """Copies text file named S to text file named D."""
3 with open(s) as src:
----> 4 with open(d, "w") as dst:
5 try:
6 dst.write(src.read())

OSError: [Errno 28] No space left on device
--- Synchronet 3.21a-Linux NewsLink 1.2

From Newsgroup: comp.lang.python

Ethan Carter wrote:

PS. Is it just me or there's just us in this used-to-be-very-active
group? Thanks for being my teacher here. Have a good day!

Until a few months ago, there was a gateway that forwarded messages both
ways between this newsgroup and a mailing list. It seems to have
stopped working around the time mailing list appears to have been been migrated to a different system. I reported that on the issue tracker a
couple of weeks ago: <https://github.com/python/pythondotorg/issues/2761#issuecomment-3156554668>

Although <https://www.python.org/community/lists/> seems to promote this newsgroup in preference to the mailing list, I guess most of those contributing are actually using the mailing list. That page still says
the mailing list is an alternative way of accessing the newsgroup, so
I'm assuming breaking that connection wasn't intentional. I keep
meaning to sign up to the mailing list in the meantime...
--
Mark.
--- Synchronet 3.21a-Linux NewsLink 1.2

From Newsgroup: comp.lang.python

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.
--- Synchronet 3.21a-Linux NewsLink 1.2

From Newsgroup: comp.lang.python

Mark Bourne <nntp.mbourne@spamgourmet.com> wrote or quoted:

I don't know if Sphinx can extract types from type hints but,

Yes, Sphinx can extract types from type hints, and there are settings
like "autodoc_typehints", "autodoc_typehints_description_target",
"autodoc_typehints_format" since version 2.1 or later.


--- Synchronet 3.21a-Linux NewsLink 1.2

From Newsgroup: comp.lang.python

On Thu, 28 Aug 2025 21:05:06 +0100, Mark Bourne wrote:

Until a few months ago, there was a gateway that forwarded messages
both ways between this newsgroup and a mailing list. It seems to
have stopped working around the time mailing list appears to have
been been migrated to a different system.

Good riddance. They were taking Usenet postings into their list
without permission, and then complaining when some of those postings
didnrCOt conform to their rCLcode of conductrCY -- a rCLcoderCY which nobody on Usenet had agreed to.
--- Synchronet 3.21a-Linux NewsLink 1.2