Velocity Reviews

Velocity Reviews (http://www.velocityreviews.com/forums/index.php)
-   Python (http://www.velocityreviews.com/forums/f43-python.html)
-   -   RE: Python evolution: Unease (http://www.velocityreviews.com/forums/t339932-re-python-evolution-unease.html)

Roman Suzi 01-04-2005 02:06 PM

RE: Python evolution: Unease
 
On Tue, 4 Jan 2005, Batista, Facundo wrote:

Maybe OP doesn't yet fully comprehend the ways of Python universe?

As for his claims, I am quite surprised that Python lacks
something in the docs.

Concerning better hierarchy in the standard library, it is interesting
that there are some movements in this direction: xml package,
email package, etc. Probably Iwan thinks that letting more
"hierachiesness" into std lib Python will be "cleaner".
Yes, it will probably look "more organized" this way, but
I do not like the idea:

import time.time
import time.calendar
...
import web.url.openers
import net.http
...
import datatypes.string
import textprocessing.re

etc.


> [Iwan van der Kleyn]
>
> #- need: a better standard ide, an integrated db interface with
> #- a proper
> #- set of db drivers (!!), a better debugger, a standard widget/windows
> #- toolkit, something akin to a standard for web programming, better
> #- documentation, a standard lib which is better organized, a
> #- formalized
> #- set of protocols and patterns for program construction. And an
> #- interpreter which is fast enough to avoid using C or Pyrex in most
> #- obvious cases.
>
> Let's take one by one:
>
> - IDE: Better than what? Than IDLE? Than Eclipse? Than SPE? Than Pythonwin?
>
> - Integrated DB interface with a proper set of db drivers (what means the
> "!!"?): What do you mean with an integrated db interface? An standard API to
> access different DB engines? Something like the Database API specification
> (http://www.python.org/topics/databas...API-2.0.html)? There's a SIG
> on DB at http://www.python.org/sigs/db-sig/ you may want to look at.
> Regarding drivers, to what DB do you miss one?
>
> - Debugger: Again, better than what? I use the debugger in IDLE and it's
> pretty ok.
>
> - Standard widget/windows toolkit: More standard than Tk?
>
> - Something akin to a standard for web programming: specifically?
>
> - Better documentation: Did you find *any* issue in the docs? And why you
> didn't post a bug on that?
>
> - Better organization of the std lib: What do you propose (specifically)?
> Please, in your proposal, take in consideration migration plans and how the
> migration affect actual systems. And of course, why the new organization is
> better than the old one. BTW, I also think that it should be better
> organized, but don't know how.
>
> - a formalized set of protocols and patterns for program construction: a
> what?
>
> - an interpreter which is fast enough to avoid using C or Pyrex in most
> obvious cases: CPython is More Than Fast Enough. In which obvious cases it's
> not enough for you?
>
> Don't misinterpret this response. I know it was a rambling. But *maybe* you
> have something to contribute to Python development, even good ideas only and
> no work.
>
> . Facundo


Sincerely yours, Roman A.Suzi
--
- Petrozavodsk - Karelia - Russia - mailto:rnd@onego.ru -


Paul Rubin 01-04-2005 03:19 PM

Re: Python evolution: Unease
 
Roman Suzi <rnd@onego.ru> writes:
> As for his claims, I am quite surprised that Python lacks
> something in the docs.


Python is lacking plenty in the docs. Care to figure out from the
docs how tkinter works? That's not explained anywhere at all, except
in some off-site resources and in some printed books. Even some
language features like class methods and slots are explained only in
PEP's and release notes, instead of in the language manual where you'd
expect to find them since they're part of the language.

Skip Montanaro 01-04-2005 03:43 PM

Re: Python evolution: Unease
 

Paul> Care to figure out from the docs how tkinter works? That's not
Paul> explained anywhere at all, except in some off-site resources and
Paul> in some printed books. Even some language features like class
Paul> methods and slots are explained only in PEP's and release notes,
Paul> instead of in the language manual where you'd expect to find them
Paul> since they're part of the language.

Start writing (or reorganizing). Folks, this is open source. I'm sure by
the traffic on the list most people here know how to write. In the case of
Tkinter, you should probably get the okay of the authors of various external
docs before incorporating them into the Python docs, but note that several
Tkinter-related documents are referenced directly from the Tkinter module
docs:

Python Tkinter Resources
The Python Tkinter Topic Guide provides a great deal of information
on using Tk from Python and links to other sources of information on
Tk.

An Introduction to Tkinter
Fredrik Lundh's on-line reference material.

Tkinter reference: a GUI for Python
On-line reference material.

Tkinter for JPython
The Jython interface to Tkinter.

Python and Tkinter Programming
The book by John Grayson (ISBN 1-884777-81-3).

This being the Internet and all, it's not clear that referencing external
documentation is somehow worse than incorporating it directly into the
distribution.

As for stuff that exists in PEPs and release notes, they should already all
have the necessary copyright (either they were placed in the public domain
or they are already part of the Python distribution) to allow you do just
check out a CVS tree, make the necessary edits and either check the files
back in or submit a patch to SourceForge.

In the documentation arena, I think more thought should probably be given to
producing online docs that can be directly annotated, thus further reducing
the barrier to more complete documentation (and more updates). Take a look
at latex2html, propose or implement changes, or just rewrite the damn thing
in Python. I think latex2html is probably a recurring nightmare for Fred
Drake.

Skip

Paul Rubin 01-05-2005 01:12 AM

Re: Python evolution: Unease
 
Skip Montanaro <skip@pobox.com> writes:
> Start writing (or reorganizing). Folks, this is open source. I'm
> sure by the traffic on the list most people here know how to write.


Irrelevant, the issue isn't what docs can be written if someone
wants to do it, it's what docs are actually already there. I mean
every shortcoming anyone could raise about Python or anything else
could have the same answer, "it's open source, go fix it". The
question is what does the existing stuff do.

> In the case of Tkinter, you should probably get the okay of the
> authors of various external docs before incorporating them into the
> Python docs,


If such permission is available then the external docs should just
be dropped into the distro.

> but note that several Tkinter-related documents are referenced
> directly from the Tkinter module docs:


Irrelevant, the Python docs mean the ones that are included, not the
ones that are merely referenced.

> This being the Internet and all, it's not clear that referencing external
> documentation is somehow worse than incorporating it directly into the
> distribution.


The same thing could be said for software. So why not eliminate the
Python library and let everyone download each module separately?
Because it's bogus is why. It really does matter whether something is
included or just referenced. That's what "batteries included" is
supposed to be about--you get ONE package and it's supposed to have
everything you need without having to go forage for additional
components. It matters because most users shouldn't need to care
about the Python distro at all, since they got Python through its
inclusion in some bigger distro. E.g., I'm now running the Python
that was included in Fedora Core 3 GNU/Linux, a complete OS distro on
a DVD-ROM, containing about 3 gigabytes not including sources. And
when a user installs 3 gigabytes of software from a DVD, they can
reasonably expect that they've installed a complete system and
shouldn't need to download anything additional to use all the features
of the programs on the DVD. Now the Fedora maintainers aren't Python
gurus--people ask for Python so they did the obvious thing: downloaded
it, ran its installer, put the output into their distro, and said "ok,
Fedora has Python". That's all they should need to do to incorporate
Python into Fedora. So it's up to the Python maintainers, not the
Fedora maintainers or the user, to make sure that the Python distro
has everything that users need, without further downloading.

And that was just about Tkinter, for which good docs exist but just
don't happen to be in the distro. How about something like
SocketServer, for which no reasonable docs exist at all? There's no
way to figure out how to use it without reading the source. Or the
socket library, whose docs say to go buy a book by W. Richard Stevens.
The book is very good, but having to go buy a proprietary book is the
opposite of what self-contained free software documentation is
supposed to mean.

I'm not trying to bash Python, which is excellent in many ways, or I
wouldn't be using it. I just see various other free software projects
as trying to live up to higher standards and I think Python should
aspire to the same thing.

> As for stuff that exists in PEPs and release notes, they should
> already all have the necessary copyright (either they were placed in
> the public domain or they are already part of the Python
> distribution) to allow you do just check out a CVS tree, make the
> necessary edits and either check the files back in or submit a patch
> to SourceForge.


And about that full featured Python web browser and native-code Python
compiler, all you have to do is go write it. Come on.

Having to piece together info from a dozen obscure and inconsistent
PEP's and stuff in the CVS tree and source comments is not what most
people think of as "documentation". Documentation means I can look in
the manual and the info is right there, properly referenced in the
table of contents and in the proper section for that type of language
feature, unified with the rest of the docs.

> In the documentation arena, I think more thought should probably be
> given to producing online docs that can be directly annotated, thus
> further reducing the barrier to more complete documentation (and
> more updates). Take a look at latex2html, propose or implement
> changes, or just rewrite the damn thing in Python. I think
> latex2html is probably a recurring nightmare for Fred Drake.


I've personally been happy with Texinfo for other kinds of docs and
would consider it easier to deal with than latex2html. It might even
be feasible to edit it in a wiki, so anyone could improve it easily.
Another idea is web-based doc comments like PHP and MySQL have, so the
doc editors can incorporate the info from the comments in subsequent
doc releases.

Skip Montanaro 01-05-2005 01:54 AM

Re: Python evolution: Unease
 

Paul> Skip Montanaro <skip@pobox.com> writes:
>> Start writing (or reorganizing). Folks, this is open source. I'm
>> sure by the traffic on the list most people here know how to write.


Paul> Irrelevant, the issue isn't what docs can be written if someone
Paul> wants to do it, it's what docs are actually already there.

How do you think we got the docs we already have? Somebody wrote them. If
there aren't enough docs or if they have mistakes, then somebody has to
correct them. I'm just suggesting that more people put their money where
they mouths are so-to-speak.

>> This being the Internet and all, it's not clear that referencing
>> external documentation is somehow worse than incorporating it
>> directly into the distribution.


Paul> The same thing could be said for software. So why not eliminate
Paul> the Python library and let everyone download each module
Paul> separately? Because it's bogus is why.
Paul> It really does matter whether something is included or just
Paul> referenced.

Okay, then start doing the work necessary to incorporate that stuff into the
core. Get Fredrik to say "okay" to including his Tkinter docs, then do what
it takes to incorporate it. The fact that Fredrik can check those docs in
himself but hasn't after several years suggests that he prefers the status
quo for one or more reasons.

I'm not saying references are perfect. I'm saying that given the time
constraints of the existing developer crowd and the relative priority of
various open tasks that folding in external documentation hasn't risen to
the top of the queue yet. The best way to make that happen is for it to be
your highest priority and then for you to make it happen. That's a
longer-winded way to say what I meant with "this is open source".

Paul> And that was just about Tkinter, for which good docs exist but
Paul> just don't happen to be in the distro. How about something like
Paul> SocketServer, for which no reasonable docs exist at all?

I'm at a loss. Is there something about this quote taken directly from the
section of the library reference manual entitled "Undocumented Modules" that
is unclear?

Here's a quick listing of modules that are currently undocumented, but
that should be documented. Feel free to contribute documentation for
them! (Send via email to docs@python.org.)

The list there is itself incomplete.

There is a reference manual section for SocketServer, btw:

http://www.python.org/doc/current/li...ketServer.html

If that needs examples or corrections or is incomplete, feel free to submit
a patch to either SourceForge or by email to docs@python.org.

Paul> I'm not trying to bash Python, which is excellent in many ways, or
Paul> I wouldn't be using it. I just see various other free software
Paul> projects as trying to live up to higher standards and I think
Paul> Python should aspire to the same thing.

I'm sorry, I don't know quite how to respond to that. Sure, I imagine there
are other communities that do it better. I've seen PHP mentioned here
recently, and have direct experience with CPAN (and actually like it pretty
well).

Look, I don't have much free time, and what free time I do have I mostly
spend moonlighting on other software (much to my wife's chagrin). I imagine
most of the other people who contribute to the Python distribution are
similarly time-afflicted. Here are a couple ideas:

1. Do you have more money than time? Donate a few bucks to the PSF:

http://www.python.org/psf/

Someone will probably do #2.

2. Do you have more time than money? Write a proposal to the PSF to
implement/improve/polish off some aspect of the distribution:

http://www.python.org/psf/

3. Got some free time and don't care about a few extra bucks? Check
out how to contribute to Python:

http://www.python.org/dev/

>> As for stuff that exists in PEPs and release notes, they should
>> already all have the necessary copyright (either they were placed in
>> the public domain or they are already part of the Python
>> distribution) to allow you do just check out a CVS tree, make the
>> necessary edits and either check the files back in or submit a patch
>> to SourceForge.


Paul> And about that full featured Python web browser and native-code
Paul> Python compiler, all you have to do is go write it. Come on.

Where did I say to go write a browser or a native-code Python compiler? If
that's your bag you can try resurrecting something Grail-like (browser) or
contribute time top PyPy or Psyco. When I said "write", I literally meant
write, as in English text.

Paul> Having to piece together info from a dozen obscure and
Paul> inconsistent PEP's and stuff in the CVS tree and source comments
Paul> is not what most people think of as "documentation".
Paul> Documentation means I can look in the manual and the info is right
Paul> there, properly referenced in the table of contents and in the
Paul> proper section for that type of language feature, unified with the
Paul> rest of the docs.

I was suggesting that maybe you might like to take the pieces and make them
something coherent. If it was trivial it would have probably been done by
now.

>> In the documentation arena, I think more thought should probably be
>> given to producing online docs that can be directly annotated, thus
>> further reducing the barrier to more complete documentation (and more
>> updates). Take a look at latex2html, propose or implement changes,
>> or just rewrite the damn thing in Python. I think latex2html is
>> probably a recurring nightmare for Fred Drake.


Paul> I've personally been happy with Texinfo for other kinds of docs
Paul> and would consider it easier to deal with than latex2html. It
Paul> might even be feasible to edit it in a wiki, so anyone could
Paul> improve it easily. Another idea is web-based doc comments like
Paul> PHP and MySQL have, so the doc editors can incorporate the info
Paul> from the comments in subsequent doc releases.

I rather like reST (much of www.python.org is being reimplemented in reST),
but that's just me. The key point I was trying to make is that an
annotation capability would probably help. With such a feature you could
add examples or links to the online Python Cookbook, whatever. Need some
ideas? Look here:

http://www.amk.ca/diary/archives/003336.html

As Andrew indicated, it's a "half-hour hack", but it might give someone
something to think about.

Skip

Jeremy Bowers 01-05-2005 02:12 AM

Re: Python evolution: Unease
 
On Tue, 04 Jan 2005 17:12:04 -0800, Paul Rubin wrote:
> Irrelevant, the issue isn't what docs can be written if someone wants to
> do it, it's what docs are actually already there....


> I just see various other free software projects as
> trying to live up to higher standards and I think Python should aspire to
> the same thing.


So, nobody should have to write the docs because they should already be
there, but "somebody" should have to write the docs?

You need to think more clearly about the pronouns you are slinging around.
Who is this "they" that should write the docs? (Yes, I know you didn't use
that exact word but the concept is clearly there.) And what right do you
have to demand this action from "they"? Are you willing to pay me to do it?




Paul Rubin 01-05-2005 02:28 AM

Re: Python evolution: Unease
 
Jeremy Bowers <jerf@jerf.org> writes:
> So, nobody should have to write the docs because they should already be
> there, but "somebody" should have to write the docs?
>
> You need to think more clearly about the pronouns you are slinging around.
> Who is this "they" that should write the docs?


The Python advocates who claim that Python is well-documented and take
exception to when someone say it isn't. Their idea of "it's
well-documented" seems to be "if there's parts that you think are
poorly documented, feel free to document it". What kind of nonsense
is that? "Python code runs just as fast as C code. If you think it's
slower, feel free to speed it up". "Python's standard library
includes a database module. If it isn't there, feel free to add one".
"Programming in Python cures cancer. If your cancer doesn't clear up
when you code in Python, feel free to submit a patch".

Software advocacy, which Python has an awful lot of, involves
extolling the virtues of a program as it exists in the present. Not
as it could potentially exist if someone hypothetically added a bunch
of work that hasn't yet been done. Python is good software, but its
advocates are making claims that Python itself doesnt live up to.

And no, I don't feel a responsibility to do the missing work, since
I'm not the one making those advocacy claims.

Peter Hansen 01-05-2005 03:16 AM

Re: Python evolution: Unease
 
Paul Rubin wrote:
> Jeremy Bowers <jerf@jerf.org> writes:
>>So, nobody should have to write the docs because they should already be
>>there, but "somebody" should have to write the docs?
>>
>>You need to think more clearly about the pronouns you are slinging around.
>>Who is this "they" that should write the docs?

>
> The Python advocates who claim that Python is well-documented and take
> exception to when someone say it isn't. Their idea of "it's
> well-documented" seems to be "if there's parts that you think are
> poorly documented, feel free to document it". What kind of nonsense
> is that? "Python code runs just as fast as C code. If you think it's
> slower, feel free to speed it up". "Python's standard library
> includes a database module. If it isn't there, feel free to add one".
> "Programming in Python cures cancer. If your cancer doesn't clear up
> when you code in Python, feel free to submit a patch".


I think you're throwing out strawman arguments here.

The key distinction is that "well-documented" is clearly
a judgment call, a personal opinion, while the others
are all measurable absolutes. (The "as fast as C" one borders
on being an opinion, since most people actually say things that
mean something more like "as fast as I need it to, so C has no
advantage".)

Saying, in effect, as they are, "Python's docs are well enough
documented for my purposes and, I believe, for those of many
other people" certainly isn't nonsense, and saying "and if you
don't agree you should consider improving them yourself
instead of asking me or others who feel as I do" is certainly
not nonsense.

> And no, I don't feel a responsibility to do the missing work, since
> I'm not the one making those advocacy claims.


So those who claim Python is well-documented are the ones who
should improve the documentation, but those claiming that
the documentation is poor should feel no responsibility to
make the improvements?

Does this make any sense to you? To me, *this* is the nonsense.

-Peter

alex23 01-05-2005 03:30 AM

Re: Python evolution: Unease
 
Paul Rubin wrote:
> The Python advocates who claim that Python is well-documented and

take
> exception to when someone say it isn't. Their idea of "it's
> well-documented" seems to be "if there's parts that you think are
> poorly documented, feel free to document it". What kind of nonsense
> is that?


It's called "having an opinion". "Good" documentation does its job, if
noone else thought it was poorly documented then to them it wasn't.

The only person who knows how the current documentation is
unsatisfactory to you is *you*.

The mistake being made here by the OS community is the assumption,
based on their own personal experiences, that others will take the
absence of something as a challenge to fill it themselves, serving the
dual role of obtaining what they need for their own purposes AND
providing it for the purposes of others. It's a mistaken assumption
because for most people it's easier to gripe that someone else, oh
let's say "advocates", should be doing it for you.

> "Python code runs just as fast as C code. If you think it's
> slower, feel free to speed it up".


The objective, qualifiable speed of Python has *what* exactly to do
with the subjective, interprative assessment of the Python
documentation?

> "Python's standard library includes a database module. If it isn't

there,
> feel free to add one".


Which part of the open source movement do you just not get?

> "Programming in Python cures cancer. If your cancer doesn't clear up
> when you code in Python, feel free to submit a patch".


Wow, you quickly ran out of points of blind Pythonic advocation, didn't
you?

> Software advocacy, which Python has an awful lot of, [...]


Unjustifiable claims, which your postings have an awful lot of...see
how easy it is to characterise someones position in the negative? See
how pointless it is for useful dialogue?

You've done nothing but kvetch about how others aren't providing you
with what you need. Let's face it, people like you are never going to
take the initiative and actually contribute something when you're
already quite comfortable sponging off the efforts of others and hiding
behind claims of advocacy whenever anyone questions your own
motivations.
In short: grow up and just write the damn documentation.

- alex23 -


Paul Rubin 01-05-2005 03:49 AM

Re: Python evolution: Unease
 
Peter Hansen <peter@engcorp.com> writes:
> The key distinction is that "well-documented" is clearly
> a judgment call, a personal opinion,


No it's not. If a program has significant modules with complicated
public API's and no documentation, it's poorly documented in an
absolute sense. A well-documented program includes docs for all
the public API's.

> So those who claim Python is well-documented are the ones who
> should improve the documentation, but those claiming that
> the documentation is poor should feel no responsibility to
> make the improvements?


Yes, precisely so. Like if someone says "I've written this fantastic
math package, it's fast and accurate and solves every problem
perfectly, let's start a newsgroup about how to convince our PHB's to
use it and why it's so much better than every other math package
that's ever been written", and I try the package and it says that
2+2=5 and I report that bug, I've made a constructive comment and have
no further responsibility. I've also shown that the program doesn't
live up to its claims and people wanting to do real work with it
should watch out. If the developers want to keep making the grand
claims, they should fix the bug. If they want to say "this package is
technically cool but gets some answers wrong, maybe you don't want to
do anything serious with it but it's fun to play with", that's
different. But there's a constant current in clpy of "Python is great
for everything, our PHB's should all embrace it, it supports protocols
X, Y, and Z and is great for that kind of application" when those
protocols turn out to be only half-implemented, or "it's
well-documented" when the manual turns out to be only half-complete.
And the responses I see sound almost like "2+2=5 is an accurate
answer, and if you think it's not close enough, it's open source, so
fix it".

If you want to see a really well-done (at least in parts, and also
poorly documented but not making claims to the contrary) Python
program, take a look at Twisted Matrix. It reimplements any number of
features that are already in Python. An early version of the docs
explained the reason. It said something like "it may look like we're
re-inventing the wheel, but we have no choice, since the existing
wheel is square and made of glue".

> Does this make any sense to you? To me, *this* is the nonsense.


I don't see any nonsense. People who make claims about a program are
the ones responsible for the truth of the claims. Saying anyone else
is responsible is bizarre.


All times are GMT. The time now is 11:47 AM.

Powered by vBulletin®. Copyright ©2000 - 2014, vBulletin Solutions, Inc.
SEO by vBSEO ©2010, Crawlability, Inc.