omissions in python docs?

7

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 said:
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
 
M

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?=

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
 
S

Steve Holden

Martin said:
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 +1 571 484 6266 +1 800 494 3119
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 ----------------
 
J

John Machin

At least for 2) you're late. It's already documented on 2.5.1:http://sourceforge.net/tracker/index.php?func=detail&aid=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
 
7

7stud

At least for 2) you're late. It's already documented on 2.5.1:http://sourceforge.net/tracker/index.php?func=detail&aid=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!
 
7

7stud

Darn. I could have been somebody!


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.
 
G

Gabriel Genellina

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...
 
A

Anthony Irwin

7stud said:
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.
 
T

Terry Reedy

| 7stud wrote:
| >
| > 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
 

Ask a Question

Want to reply to this thread or ask your own question?

You'll need to choose a username for the site, which only take a couple of moments. After that, you can post your question and our members will help you out.

Ask a Question

Members online

Forum statistics

Threads
473,744
Messages
2,569,484
Members
44,903
Latest member
orderPeak8CBDGummies

Latest Threads

Top