[Python-Dev] RE: [Python-checkins] CVS: python/dist/src/Doc/lib libmmap.tex,NONE,1.1
Mark Hammond
mhammond@skippinet.com.au
Sun, 18 Jun 2000 13:35:00 +1000
> Documentation for the mmap module: proofreaders welcomed
OK :-)
> the file handle \var{fileno}, and returns a mmap object. If you have
> a Python file object, its
> \method{fileno()} method returns the file's handle, which is
> just an integer.
This could be a little clearer - on first reading, I thought you were
talking about the return value. Maybe something like: "if you wish to pass
an existing Python file object for this parameter, use its
\method{fileno()} method to obtain the fileno."
> \var{tagname}, if specified, is a string giving a tag name for
> the mapping. XXX what is the purpose of the tag name?
Something like: Windows allows you to have many different mappings against
the same file. If you specify the name of an existing tag, that tag is
opened, otherwise a new tag of this name is created. If this parameter is
None, the mapping is created without a name. Avoiding the use of the tag
parameter will assist in keeping your code portable between Unix and
Windows.
> \begin{funcdesc}{mmap}{file, size \optional{, flags, prot}}
> (Unix version) Maps \var{length} bytes from the file specified by the
> file handle \var{fileno}, and returns a mmap object. If you have a
> Python file object, its \method{fileno()} method returns the file's
> handle, which is just an integer.
I believe you mean the signature to say "fileno" instead of "file" - this
makes it consistent with the Windows signature, and reinforces that this
param is indeed identical.
As a meta-comment, the structure of this implies that the param signatures
are more different than they are - eg, it should be possible to write
portable mmap code in most cases, without concern for the platform. the
platform only becomes relevant when you use the optional params for each
platform?
> \begin{methoddesc}{read}{\var{num}}
> Return a string containing up to \var{num} bytes taken from the
"taken from" -> "starting from" ??
> \begin{methoddesc}{write_byte}{\var{byte}}
> Write \var{byte} into memory at the current position of
> the file pointer; the file position is advanced by 1.
> \end{methoddesc}
The type of "byte" should be explained - its never clear to me if a "byte"
should be an int or a string of size 1. In this case, it is the latter.
Looks good!
Mark.