By using this site, you agree to our updated Privacy Policy and our Terms of Use. Manage your Cookies Settings.
440,621 Members | 1,074 Online
Bytes IT Community
+ Ask a Question
Need help? Post your question and get tips & solutions from a community of 440,621 IT Pros & Developers. It's quick & easy.

omissions in python docs?

P: n/a
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?

May 17 '07 #1
Share this Question
Share on Google+
12 Replies


P: n/a
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
May 17 '07 #2

P: n/a
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.

May 17 '07 #3

P: n/a
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
May 17 '07 #4

P: n/a
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 +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 ----------------

May 17 '07 #5

P: n/a
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

May 17 '07 #6

P: n/a
On May 18, 9:24 am, "Gabriel Genellina" <gagsl-...@yahoo.com.ar>
wrote:
En Thu, 17 May 2007 13:39:43 -0300, 7stud <bbxx789_0...@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...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

May 18 '07 #7

P: n/a
On May 17, 5:24 pm, "Gabriel Genellina" <gagsl-...@yahoo.com.ar>
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!

May 18 '07 #8

P: n/a
On May 17, 7:23 pm, 7stud <bbxx789_0...@yahoo.comwrote:
On May 17, 5:24 pm, "Gabriel Genellina" <gagsl-...@yahoo.com.ar>
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.

May 18 '07 #9

P: n/a
En Thu, 17 May 2007 21:13:49 -0300, John Machin <sj******@lexicon.net>
escribió:
On May 18, 9:24 am, "Gabriel Genellina" <gagsl-...@yahoo.com.ar>
wrote:
>En Thu, 17 May 2007 13:39:43 -0300, 7stud <bbxx789_0...@yahoo.com>
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

May 18 '07 #10

P: n/a
7stud wrote:
On May 17, 7:23 pm, 7stud <bbxx789_0...@yahoo.comwrote:

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.
May 18 '07 #11

P: n/a

"Anthony Irwin" <no****@noemailhere.nowherewrote in message
news:f2**********@news-01.bur.connect.com.au...
| 7stud wrote:
| On May 17, 7:23 pm, 7stud <bbxx789_0...@yahoo.comwrote:
| >
| 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

May 18 '07 #12

P: n/a
Anthony Irwin wrote:
7stud wrote:
>On May 17, 7:23 pm, 7stud <bbxx789_0...@yahoo.comwrote:

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
May 18 '07 #13

This discussion thread is closed

Replies have been disabled for this discussion.