Xah Lee写道：

Xah Lee wrote:

Python Doc问题示例：gzip

Xah Lee，20050831

今天我需要使用Python来压缩/解压缩gzip文件。因为我已经阅读了8个月之前的官方Python教程，自那以来每周花费30多分钟用Python，拥有14年的计算经验，8年的数学计算经验我在unix管理员和perl工作了4年，我很快找到了官方文档：
http://python.org/doc/2.4.1/lib/module-gzip.html

我会的想象它是一个类似的功能：

fileContent = GzipFile（filePath，压缩/解压缩）

然而，在20秒后扫描文档没有单一的例子
相反，该文档首先提供了一些关于与其他压缩模块和其他软件兼容的神秘信息。然后它以一种非常随意的方式谈论主要功能G / GzipFile。没有任何关于使用它来解决问题的观点
也没有关于如何使用它的具体描述。取而代之的是，类，
构造函数，对象等的术语与读者在Python和gzip压缩中使用IO编程的专业知识的推定相结合。
>在不理解，并且不是Python专家之后，我想阅读关于文件对象的文件，但是没有链接。

找到文件对象的文档页面后：
http：// python。 org / doc / 2.4.1 / lib / bltin-file-objects.html ，但本身是以非常无益的方式编写和组织的。

这里是'其文件问题的细节。它始于：

?? zlib模块提供的数据压缩与GNU压缩程序gzip使用的数据压缩兼容。因此，gzip模块提供了GzipFile类来读取和写入gzip格式的文件，自动压缩或解压缩数据，使其看起来像普通的文件对象。请注意，此模块不支持gzip和gunzip程序可以解压缩的其他文件格式，例如由compress和pack生成的文件格式。??

这个介绍段落大约有3件事：（1）这个gzip
模块的目的。 （2）它与zlib模块的关系。 （3）关于gzip程序'支持压缩和打包的无偿奥秘> Python的gzip模块不支持软件。必然提到因为
本段中的写作是如何表达的。写作本身就是混乱。

在使用gzip模块的人中，绝大多数人只需要解压缩gzip文件。他们不需要在序言中知道（2）和（3）。这里最糟糕的方面是混乱的写作。

类GzipFile（[filename [，mode [，compresslevel [，fileobj]]]]）
GzipFile类的构造函数，它模拟大多数文件对象的方法，除了readinto（）和truncate（）
方法。必须给fileobj和filename中的至少一个赋予非平凡的值。新的类实例基于fileobj，它可以是常规文件，StringIO对象或任何其他模拟文件的对象。它默认为None，在这种情况下打开文件名
以提供文件对象。??

本段假设读者完全熟悉Python的文件对象及其方法。写作是随意的，而且非常混乱。它试图通过副作用来表达其含义，而不是明确和清晰。

a？¢sim ??是两次疯狂的。这些...... Gzipfile类，它模拟了...... a ??更好的说是通过
a ?? Gzipfile是在Python的文件对象类之后建模的.a ??

a？¢意图声明它有所有Python的文件对象方法除了其中两个之外，都是含糊不清的措辞。好像是说所有
方法都存在，除了它们中的两个方法不同。

a？使用的单词a ??非平凡的值a ??是愚蠢的。
非平凡价值在这里意味着什么？是一个非平凡的价值吗？在Python中具有特定的含义？或者，它是否意味着通用的英语解释？
如果是后者，那么它的意思是：a ??至少有一个
fileobj和filename必须给出一个非平凡的值？ ？它是否只是意味着必须给出其中一个参数？

a？这段的其余部分是不可理解的。

??当fileobj不是无，filename参数仅用于包含在gzip文件头中，其中可能包含未压缩文件的原始文件名。它默认为文件名
fileobj，如果可辨别的话;否则，它默认为空字符串，
在这种情况下，原始文件名不包含在标题中。??

a ?? discerniblea ???这篇文章非常混乱，并且它假设读者熟悉Gzip的技术规范。

??模式参数可以是''r''，'rb中的任何一个''，''''，''ab''，''w''或
''wb''，取决于文件是读还是写。
默认是fileobj的模式，如果可辨别的话;否则，默认
是''rb''。如果没有给出，'b''标志将被添加到模式中以确保文件以二进制模式打开以实现跨平台的可移植性。??

a ??辨别???再次，隐含地假设熟悉Python的文件
对象的工作。对于那些没有使用Python处理文件的专业知识的人来说，必须阅读Python的文件对象文档。

?? compresslevel参数是一个从1到9的整数控制压缩程度; 1是最快的并且产生最小的压缩，而9是最慢的并且产生最大的压缩。
默认为9。??

??调用GzipFile对象的close（）方法不会关闭
fileobj，因为您可能希望在追加更多资料之后
压缩数据。这也允许你传递一个打开的StringIO对象作为fileobj写入，并使用StringIO对象的getvalue（）方法检索生成的内存缓冲区。??

嗯？追加更多材料？传递一个StringIO？和内存缓冲区？

在这里，读者会假设使用IO进行编程的专业知识。
同时，写作并不清楚它究竟是如何尝试的。 close（）方法。
建议
--------------------------
应该有高质量的文档清晰，简洁，准确。并且，至少它假设读者的专业知识来获得这些品质，
更好。

大多数使用这个模块的程序员真的只想
压缩规范。这是Python文档编写者应该做些什么来改进它：

a？¢重写介绍段落。示例：a ??此模块提供了一个简单的界面，使用GNU
压缩格式gzip压缩和解压缩文件。有关使用gzip格式的详细信息，请使用
zlib module.a ??。 a ?? zlib modulea ??短语应该与其文档相关联。

a？¢在文档顶部附近添加一个用法示例。一个值得千言万语的例子：

＃解压缩文件
import gzip
fileObj = gzip.GzipFile（" /Users/joe/war_and_peace.txt .gz"，''rb''）;
fileContent = fileObj.read（）
fileObj.close（）

＃压缩文件
import gzip
fileObj = gzip.GzipFile（" /Users/mary/hamlet.txt.gz&quot ;,''wb''）;
fileObj.write（fileContent）
fileObj.close（）链接。

a？¢重写写作，以免假设读者完全熟悉Python的IO。例如，当谈到
模式''r''，''rb''时，...添加一个关于它们的含义的简短陈述。这样，读者可能不必采取额外的步骤来阅读文件对象上的页面。

a？¢删除关于gzip压缩的神秘技术细节到

写作的一般建议：写这个模块的目的是记录它的行为，并有效地指出如何使用它。 />编写文档时请记住这一点。明确说明您要为每个逐项段落说明的内容。让它精确，但
没有过度。假设您的读者熟悉Python
语言或gzip压缩。例如，什么是Python中的类和对象，以及压缩级别，压缩级别，文件名
后缀约定。但是，不要认为读者是Python IO的专家，或gzip规范或压缩技术和业界的软件。如果需要确切的技术细节或警告，请将其移至脚注。
---------------

Xah
xa*@xahlee.org
http://xahlee.org/

Python Doc Problem Example: gzip

Xah Lee, 20050831

Today i need to use Python to compress/decompress gzip files. Since
i''ve read the official Python tutorial 8 months ago, have spent 30
minutes with Python 3 times a week since, have 14 years of computing
experience, 8 years in mathematical computing and 4 years in unix admin
and perl, i have quickly found the official doc:
http://python.org/doc/2.4.1/lib/module-gzip.html

I''d imagine it being a function something like:

fileContent = GzipFile(filePath, comprress/decompress)

However, scanning the doc after 20 seconds there''s no single example
showing how it is used.

Instead, the doc starts with some arcane info about compatibility with
some other compression module and other software. Then it talks in a
very haphazard way with confused writing about the main function
GzipFile. No perspectives whatsoever about using it to solve a problem
nor a concrete description of how to use it. Instead, jargons of Class,
Constructor, Object etc are thrown together with presumption of
reader''s expertise of IO programing in Python and gzip compression
arcana.

After no understanding, and being not a Python expert, i wanted to read
about file objects but there''s no link.

After locating the file object''s doc page:
http://python.org/doc/2.4.1/lib/bltin-file-objects.html, but itself is
written and organized in a very unhelpful way.

Here''s the detail of the problems of its documentation. It starts with:

??The data compression provided by the zlib module is compatible
with that used by the GNU compression program gzip. Accordingly, the
gzip module provides the GzipFile class to read and write gzip-format
files, automatically compressing or decompressing the data so it looks
like an ordinary file object. Note that additional file formats which
can be decompressed by the gzip and gunzip programs, such as those
produced by compress and pack, are not supported by this module.??

This intro paragraph is about 3 things: (1) the purpose of this gzip
module. (2) its relation with zlib module. (3) A gratuitous arcana
about gzip program''s support of a??compress and packa?? software being
not supported by Python''s gzip module. Necessarily mentioned because
how the writing in this paragraph is phrased. The writing itself is a
jumble.

Of the people using the gzip module, vast majority really just need to
decompress a gzip file. They don''t need to know (2) and (3) in a
preamble. The worst aspect here is the jumbled writing.

??class GzipFile( [filename[, mode[, compresslevel[, fileobj]]]])
Constructor for the GzipFile class, which simulates most of the methods
of a file object, with the exception of the readinto() and truncate()
methods. At least one of fileobj and filename must be given a
non-trivial value. The new class instance is based on fileobj, which
can be a regular file, a StringIO object, or any other object which
simulates a file. It defaults to None, in which case filename is opened
to provide a file object.??

This paragraph assumes that readers are thoroughly familiar with
Python''s File Objects and its methods. The writing is haphazard and
extremely confusive. Instead of explicitness and clarity, it tries to
convey its meanings by side effects.

a?￠ The words a??simulatea?? are usd twice inanely. Thesentence
a??...Gzipfile class, which simulates...a?? is better said by
a??Gzipfile is modeled after Python''s File Objects class.a??

a?￠ The intention to state that it has all Python''s File Object methods
except two of them, is ambiguous phrased. It is as if to say all
methods exists, except that two of them works differently.

a?￠ The used of the word a??non-trivial valuea?? is inane. What does a
non-trivial value mean here? Does a??non-trivial valuea?? have specific
meaning in Python? Or, is it meant with generic English interpretation?
If the latter, then what does it mean to say: a??At least one of
fileobj and filename must be given a non-trivial valuea??? Does it
simply mean one of these parameters must be given?

a?￠ The rest of the paragraph is just incomprehensible.

??When fileobj is not None, the filename argument is only used to
be included in the gzip file header, which may includes the original
filename of the uncompressed file. It defaults to the filename of
fileobj, if discernible; otherwise, it defaults to the empty string,
and in this case the original filename is not included in the header.??

a??discerniblea??? This writing is very confused, and it assumes the
reader is familiar with the technical specification of Gzip.

??The mode argument can be any of ''r'', ''rb'', ''a'', ''ab'', ''w'', or
''wb'', depending on whether the file will be read or written. The
default is the mode of fileobj if discernible; otherwise, the default
is ''rb''. If not given, the ''b'' flag will be added to the mode to ensure
the file is opened in binary mode for cross-platform portability.??

a??discerniblea??? Again, familiarity with the working of Python''s file
object is implicitly assumed. For people who do not have expertise with
working with files using Python, it necessatates the reading of
Python''s file objects documentation.

??The compresslevel argument is an integer from 1 to 9 controlling
the level of compression; 1 is fastest and produces the least
compression, and 9 is slowest and produces the most compression. The
default is 9.??

??Calling a GzipFile object''s close() method does not close
fileobj, since you might wish to append more material after the
compressed data. This also allows you to pass a StringIO object opened
for writing as fileobj, and retrieve the resulting memory buffer using
the StringIO object''s getvalue() method.??

huh? append more material? pass a StringIO? and memory buffer?

Here, expertise in programing with IO is assumed of the reader.
Meanwhile, the writing is not clear about how exactly what it is trying
to say about the close() method.
Suggestions
--------------------------
A quality documentation should be clear, succinct, precise. And, the
least it assumes reader''s expertise to obtain these qualities, the
better it is.

Vast majority of programers using this module really just want to
compress or decompress a file. They do not need to know any more
details about the technicalities of this module nor about the Gzip
compression specification. Here''s what Python documentation writers
should do to improve it:

a?￠ Rewrite the intro paragraph. Example: a??This module provides a
simple interface to compress and decompress files using the GNU
compression format gzip. For detailed working with gzip format, use the
zlib module.a??. The a??zlib modulea?? phrase should belinked to its
documentation.

a?￠ Near the top of the documentation, add a example of usage. A
example is worth a thousand words:

# decompressing a file
import gzip
fileObj = gzip.GzipFile("/Users/joe/war_and_peace.txt.gz", ''rb'');
fileContent = fileObj.read()
fileObj.close()

# compressing a file
import gzip
fileObj = gzip.GzipFile("/Users/mary/hamlet.txt.gz", ''wb'');
fileObj.write(fileContent)
fileObj.close()

a?￠ Add at the beginning of the documentation a explicit statement,
that GzipFile() is modeled after Python''s File Objects, and provide a
link to it.

a?￠ Rephrase the writing so as to not assume that the reader is
thoroughly familiar with Python''s IO. For example, when speaking of the
modes ''r'', ''rb'', ... add a brief statement on what they mean. This way,
readers may not have to take a extra step to read the page on File
Objects.

a?￠ Remove arcane technical details about gzip compression to the
bottom as footnotes.

a?￠ General advice on the writing: The goal of writing on this module
is to document its behavior, and effectively indicate how to use it.
Keep this in mind when writing the documentation. Make it clear on what
you are trying to say for each itemized paragraph. Make it precise, but
without over doing it. Assume your readers are familiar with Python
language or gzip compression. For example, what are classes and objects
in Python, and what compressions are, compression levels, file name
suffix convention. However, do not assume that the readers are expert
of Python IO, or gzip specification or compression technology and
software in the industry. If exact technical details or warnings are
necessary, move them to footnotes.
---------------

Xah
xa*@xahlee.org
a?? http://xahlee.org/

"""

你想创造一个你可以跪下的世界：这是你的最终希望和醉酒。
> br />
还拉扯Zarathustra。


"""


--Friedrich Nietzsche，Thus Spoke Zarathustra， 1885

Gerard

"""
You want to create the world before which you can kneel: this is your
ultimate hope and intoxication.

Also sprach Zarathustra.

"""

--Friedrich Nietzsche, Thus Spoke Zarathustra, 1885
Gerard

Xah Lee写道：

Xah Lee wrote:

我读过8个月之前的官方Python教程，自那以来每周3次用Python花费30分钟，拥有14年的计算经验，8年的数学计算经验和4年的unix管理员工作。
和perl

i''ve read the official Python tutorial 8 months ago, have spent 30
minutes with Python 3 times a week since, have 14 years of computing
experience, 8 years in mathematical computing and 4 years in unix admin
and perl

我可以摆动耳朵。

I can wiggle my ears.

" Gerard Flanagan" < GR ******** @ yahoo.co.uk>写在

新闻：11 ********************** @ g44g2000cwa.googlegr psps.com：

"Gerard Flanagan" <gr********@yahoo.co.uk> wrote in
news:11**********************@g44g2000cwa.googlegr oups.com:

Xah Lee写道：

Xah Lee wrote:

Python Doc问题示例：gzip

[...]质量文档应清晰，简洁，准确。
而且，至少它假定读者获得这些品质的专业知识，就越好。

大多数使用这个模块的程序员真的只想压缩
或解压缩文件。他们不需要知道任何关于该模块技术细节的更多细节，也不需要了解Gzip压缩规范。这是Python
文档编写者应该做些什么来改进它：

a？¢重写介绍段落。示例：a ??此模块提供

Python Doc Problem Example: gzip
[...] A quality documentation should be clear, succinct, precise.
And, the least it assumes reader''s expertise to obtain these
qualities, the better it is.

Vast majority of programers using this module really just want
to compress or decompress a file. They do not need to know any
more details about the technicalities of this module nor about
the Gzip compression specification. Here''s what Python
documentation writers should do to improve it:

a?￠ Rewrite the intro paragraph. Example: a??This module prov

使用GNU
压缩格式gzip来压缩和解压缩文件的

ides a

简单接口。有关使用gzip格式的详细信息，请使用zlib module.a ??。 a ?? zlib modulea ??短语应

simple interface to compress and decompress files using the GNU
compression format gzip. For detailed working with gzip format,
use the zlib module.a??. The a??zlib modulea?? phrase should be

链接到其

linked to its

文档。

a？¢在文档顶部附近添加一个使用示例。一个例子胜过千言万语：

＃解压缩文件
import gzip
fileObj = gzip.GzipFile（" /Users/joe/war_and_peace.txt.gz&quot ;，
''rb''）; fileContent = fileObj.read（）
fileObj.close（）

＃压缩文件
import gzip
fileObj = gzip.GzipFile（" / Users / mary /hamlet.txt.gz&quot ;,''wb''）;
fileObj.write（fileContent）
fileObj.close（）

documentation.

a?￠ Near the top of the documentation, add a example of usage.
A example is worth a thousand words:

# decompressing a file
import gzip
fileObj = gzip.GzipFile("/Users/joe/war_and_peace.txt.gz",
''rb''); fileContent = fileObj.read()
fileObj.close()

# compressing a file
import gzip
fileObj = gzip.GzipFile("/Users/mary/hamlet.txt.gz", ''wb'');
fileObj.write(fileContent)
fileObj.close()

""
你想要创造一个你可以跪下的世界：这是你最终的希望和醉酒。

也拉着Zarathustra。

"""
You want to create the world before which you can kneel: this is
your ultimate hope and intoxication.

Also sprach Zarathustra.

我已经设法避免阅读Xah Lee的dia骂了最多的b
部分。由于你在帖子中包含了* WHOLE THING *，我有一个

机会。看看他要说些什么，而且我曾经同意其中的一些。我们中的一些人以身作则;有时一个例子是

我们需要使用一个特定的功能（特别是我们通常不需要的b $ b）。通过添加一些模型代码来改进文档

的批评对于* all *

文档是有效的，我想，不仅仅是Python的。


通常情况下，当有人建议将文档更改为

开源项目时，其他人会来并提醒

每个人都认为它'这都是志愿者的努力，那么为什么不应该做那个做出改变的人呢？在

文档的情况下，这种方法意味着那些对模块如何工作最不了解的人应该是描述它的人
$对于其他人来说，b $ b，对我来说似乎有些落后。

的例子应该来自那些知道他们在做什么的人。

他们应该解释这个例子在做什么 - 只是那种

一个随意的用户想要快速学习的东西。


有人肯定会跳进去并指向示例代码，这几乎是所有合理的主要代码包裹包括。那是好东西。

有（例如）wxPython，它是唯一有用的文档，或者说是
而是，它是唯一的东西使wxWidgets文档

有用。文档中代码示例的链接可以在

中代替示例调用的片段。但是在大多数文档中都没有足够的

。


我很乐意看到基本上每个函数的例子和

方法。而不只是回应签名的东西，而是一些

上下文来展示它如何有用。这将是在

醉酒中。一类终极希望。但在大多数情况下，

对于

包裹的那个部分的临时用户来说非常有用。


-

rzed

I''ve managed to avoid reading Xah Lee''s diatribes for the most
part. Since you included the *WHOLE THING* in your post, I had an
"opportunity" to see what he had to say, and for once I agree with
some of it. Some of us learn by example; sometimes an example is
all we need to use a particular feature (especially one that we
don''t often have need for). The criticism that the documentation
would be improved by adding some model code is valid for *all*
documentation, I think, not just Python''s.

Typically, when someone proposes changes to documentation to an
open source project, someone else will come along and remind
everyone that it''s all volunteer effort, so why shouldn''t the one
doing the propopsing be the one to make the change? In the case of
documentation, that approach would mean that those who have the
least idea of how a module works should be the ones to describe it
for everyone else, which seems a little backward to me. The
examples should come from those who know what they''re doing and
they should explain what the example is doing -- just the sort of
things a casual user wants to learn quickly.

Someone is sure to jump in now and point to sample code, which
nearly all reasonably major packages include. That''s good stuff.
With (for example) wxPython, it''s the only useful documentation, or
rather, it''s the only thing that makes the wxWidgets documentation
useful. Links to code samples in the documentation would be fine in
lieu of snippets of example calls. But there''s not enough of either
in most documentation.

I would love to see examples for essentially every function and
method. And not just something that echoes the signature, but some
context to show how it might be useful. That would be in the
"intoxication" class of ultimate hopes. In most cases, though, it
would be *extremely* helpful for a casual user of that part of the
package.

--
rzed