omissions in python docs?

[7stud]

Hi,

1) The shelve module doesn't list close() as a method.

2) The fnmatch module does not even mention translate().

I have a hard time believing I am the first one to notice those
omissions. Are the docs just old and poorly maintained? Or, is there
some reason those methods were omitted?

[=?ISO-8859-1?Q?=22Martin_v=2E_L=F6wis=22?=]

7stud schrieb:

I have a hard time believing I am the first one to notice those
omissions. Are the docs just old and poorly maintained? Or, is there
some reason those methods were omitted?

You are likely the first one to notice, and then talk about that.

It often happened in the past that patches were admitted which don't
simultaneously update the documentation, hence they diverge. These
days, patches are regularly rejected for not providing proper
documentation changes.

As you now found a difference, please write a patch and submit it
to sf.net/projects/python.

Regards,
Martin

[memracom]

It often happened in the past that patches were admitted which don't
simultaneously update the documentation, hence they diverge. These
days, patches are regularly rejected for not providing proper
documentation changes.

Nevertheless, the docs *ARE* old and poorly maintained. Sometimes you
find the info that you need in the docs, and other times Google is a
better source of information. I find that the weakest part of many
module docs are the examples.

[=?ISO-8859-1?Q?=22Martin_v=2E_L=F6wis=22?=]

me******@yahoo.com schrieb:

>It often happened in the past that patches were admitted which don't
simultaneously update the documentation, hence they diverge. These
days, patches are regularly rejected for not providing proper
documentation changes.

Nevertheless, the docs *ARE* old and poorly maintained.

I agree they are old, but they are *not* poorly maintained.
There is a strict policy that changes to the code *must*
be accompanied by documentation updates, and contributed
documentation patches are quickly integrated (more quickly
than code changes). So from a maintenance point of view,
the documentation is at a better standing than the code.

Regards,
Martin

[Steve Holden]

Martin v. Löwis wrote:

7stud schrieb:

>I have a hard time believing I am the first one to notice those
omissions. Are the docs just old and poorly maintained? Or, is there
some reason those methods were omitted?

You are likely the first one to notice, and then talk about that.

It often happened in the past that patches were admitted which don't
simultaneously update the documentation, hence they diverge. These
days, patches are regularly rejected for not providing proper
documentation changes.

As you now found a difference, please write a patch and submit it
to sf.net/projects/python.

Please note that the documentation patch doesn't need to be in the Latex
source format used to produce the docs - editors will add any necessary
markup.

regards
Steve
--
Steve Holden [phone] [phone]
Holden Web LLC/Ltd http://www.holdenweb.com
Skype: holdenweb http://del.icio.us/steve.holden
------------------ Asciimercial ---------------------
Get on the web: Blog, lens and tag your way to fame!!
holdenweb.blogspot.com squidoo.com/pythonology
tagged items: del.icio.us/steve.holden/python
All these services currently offer free registration!
-------------- Thank You for Reading ----------------

[Gabriel Genellina]

En Thu, 17 May 2007 13:39:43 -0300, 7stud <bb**********@yahoo.com>
escribió:

2) The fnmatch module does not even mention translate().

I have a hard time believing I am the first one to notice those
omissions.

At least for 2) you're late. It's already documented on 2.5.1:
http://sourceforge.net/tracker/index...70&atid=105470

--
Gabriel Genellina

[John Machin]

On May 18, 9:24 am, "Gabriel Genellina" <[e-mail]>
wrote:

En Thu, 17 May 2007 13:39:43 -0300, 7stud <[e-mail]>
escribió:

2) The fnmatch module does not even mention translate().

I have a hard time believing I am the first one to notice those
omissions.

At least for 2) you're late. It's already documented on 2.5.1:http://sourceforge.net/tracker/index...d=1630844&grou...

Not quite. All that says is that you raised the problem and that
somebody else's patch was accepted.

It's not in 2.5.1 AFAICT: not in "current docs" on Python website, not
in CHM file distributed with Windows version of Python 2.5.1

It is in "development docs'" (2.6a0) on Python website.

Nit-pickingly yours,
John

[7stud]

On May 17, 5:24 pm, "Gabriel Genellina" <[e-mail]>
wrote:

At least for 2) you're late. It's already documented on 2.5.1:http://sourceforge.net/tracker/index...d=1630844&grou...

Darn. I could have been somebody!

>Nit-pickingly yours,
John

No so. I checked the downloaded docs on my computer and the supposedly
up to date docs here:

http://docs.python.org/lib/module-fnmatch.html

before posting. I rechecked them after reading Gabriel Genellina's
post, and I couldn't find translate() in the fnmatch module.

There's still time!

[7stud]

On May 17, 7:23 pm, 7stud <[e-mail]:

On May 17, 5:24 pm, "Gabriel Genellina" <[e-mail]>
wrote:

At least for 2) you're late. It's already documented on 2.5.1:http://sourceforge.net/tracker/index...d=1630844&grou...

Darn. I could have been somebody!

Nit-pickingly yours,
John

No so. I checked the downloaded docs on my computer and the supposedly
up to date docs here:

http://docs.python.org/lib/module-fnmatch.html

before posting. I rechecked them after reading Gabriel Genellina's
post, and I couldn't find translate() in the fnmatch module.

There's still time!

By the way, have the python doc keepers ever visited the php docs? In
my opinion, they are the best docs of any language I've encountered
because users can add posts to any page in the docs to correct them or
post code showing how to get around various idiosyncrasies when using
the functions.

[Gabriel Genellina]

En Thu, 17 May 2007 21:13:49 -0300, John Machin <sj******@lexicon.net>
escribió:

On May 18, 9:24 am, "Gabriel Genellina" <[e-mail]>
wrote:

>En Thu, 17 May 2007 13:39:43 -0300, 7stud <[e-mail]>
escribió:

2) The fnmatch module does not even mention translate().

At least for 2) you're late. It's already documented on
2.5.1:http://sourceforge.net/tracker/index...d=1630844&grou...

Not quite. All that says is that you raised the problem and that
somebody else's patch was accepted.
It's not in 2.5.1 AFAICT: not in "current docs" on Python website, not
in CHM file distributed with Windows version of Python 2.5.1

But it *is* corrected on the CHM file from Release 2.5.1c1 (5th April,
2007), and also in the source distribution for 2.5.1 final
(libfnmatch.tex). I don't have the 2.5.1-final Windows binaries to check,
but if it's not updated there, perhaps there was a hiccup on the release
process.
And the docs on python.org aren't updated either. Hiccups comes in
sequence...

--
Gabriel Genellina

[Anthony Irwin]

7stud wrote:

On May 17, 7:23 pm, 7stud <[e-mail]:

By the way, have the python doc keepers ever visited the php docs? In
my opinion, they are the best docs of any language I've encountered
because users can add posts to any page in the docs to correct them or
post code showing how to get around various idiosyncrasies when using
the functions.

Hi,

I also like the php docs and love that you can type any function into
the search at php.net and the documentation just comes up and there is
example code and then user comments also.

--
Kind Regards,
Anthony Irwin

http://www.irwinresources.com
http://www.makehomebusiness.com
email: anthony at above domains, - www.

[Terry Reedy]

"Anthony Irwin" <no****@noemailhere.nowherewrote in message
news:f2**********@news-01.bur.connect.com.au...
| 7stud wrote:
| On May 17, 7:23 pm, 7stud <[e-mail]:
| >
| By the way, have the python doc keepers ever visited the php docs? In
| my opinion, they are the best docs of any language I've encountered
| because users can add posts to any page in the docs to correct them or
| post code showing how to get around various idiosyncrasies when using
| the functions.
| >
| I also like the php docs and love that you can type any function into
| the search at php.net and the documentation just comes up and there is
| example code and then user comments also.

Reactions to php docs are rather idiosyncratic. I did visit in response to
such positive recommendations and and consider them to be pretty bad, and
posted why at the time.

tjr

[Stargaming]

Anthony Irwin wrote:

7stud wrote:

>On May 17, 7:23 pm, 7stud <[e-mail]:

By the way, have the python doc keepers ever visited the php docs? In
my opinion, they are the best docs of any language I've encountered
because users can add posts to any page in the docs to correct them or
post code showing how to get around various idiosyncrasies when using
the functions.

Hi,

I also like the php docs and love that you can type any function into
the search at php.net and the documentation just comes up and there is
example code and then user comments also.

For searching, we got at least pyhelp.cgi_.

HTH,
Stargaming

... _pyhelp.cgi: http://starship.python.net/crew/theller/pyhelp.cgi