PEP for new modules (I read PEP 2)

[Christoph Becker-Freyseng]

Hello,

recently there was a lot discussion about a new Path-class. So Gerrit
Holl started to write a pre-PEP
http://people.nl.linux.org/~gerrit/c.../pep-xxxx.html

We tried to summarize the good ideas and suggestions. Some are still
missing and concepts of already existing modules have to be
added/thought over. Furthermore it turns out that not a new class is
needed but a module. The pre-PEP is already quite big --- Gerrit Holl
figured out that are bigger ones [1] but I think (and Gerrit Holl
agrees) that we should write the PEP a bit different.

In PEP 002 about adding a module to the standard library it isn't clear
(at least I didn't get it) what exactly should be in the pre-PEP for a
new module.
There's another difference because the Path module does not exist right
now. However I think it's not wrong first to figure out how a good
Path-module should look like and then start implementing and continue
discussion.

I think it would be a good idea to start with a dummy implementation
that has docstrings. Then we could build the documentation for the
module automatically and it wouldn't be neccessary to put everything
into the pre-PEP.
I'd like to keep in the prePEP: Abstract, Motivation, a shortened
Specification (mostly global structure, definitions, ...), Rationale
(especially this one seems important to me), BDFL Pronouncement,
References, Copyright.

So basically I want to relocate the real Specification, because the more
specific it gets the more it looks like a documentation and the prePEP
grows and grows ...
Is this a valid option for a PEP?
Better suggestions?
Thank You,
Christoph Becker-Freyseng
[1]

Some statistics about number of words in different peps:
$ wc -w *.txt | sort -rn | head -20 | nl
1 6356 pep-0253.txt # subtyping built-in types
2 5273 pep-0100.txt # python unicode integration
3 4985 pep-0307.txt # extension to pickle protocol
4 4985 pep-0249.txt # python database api spec
5 4694 pep-0258.txt # docutils design spec
6 4604 pep-0252.txt # types/classes
7 4551 pep-0101.txt # python releases
8 4457 pep-0287.txt # reST
9 4144 pep-0209.txt # multidim. arrays
10 3968 pep-0225.txt # elementwise operators
11 3916 pep-0302.txt # new import hooks
12 3882 pep-xxxx.txt

[Martin v. Löwis]

Christoph Becker-Freyseng wrote:

So basically I want to relocate the real Specification, because the more
specific it gets the more it looks like a documentation and the prePEP
grows and grows ...
Is this a valid option for a PEP?

If you are asking: "Can we have an implementation before we write the
PEP?", the answer is "Certainly, yes".

The PEP procedure is designed to avoid wasting efforts in implementing
ideas that have no chance to ever get accepted to the Python core.
If this is no concern for you (i.e. you are willing to accept the risk
of wasting efforts), you can certainly implement the thing, wait for
user feedback, and then write the PEP.

Regards,
Martin

[Christoph Becker-Freyseng]

Martin v. Löwis wrote:

Christoph Becker-Freyseng wrote:

So basically I want to relocate the real Specification, because the
more specific it gets the more it looks like a documentation and the
prePEP grows and grows ...
Is this a valid option for a PEP?

If you are asking: "Can we have an implementation before we write the
PEP?", the answer is "Certainly, yes".

The PEP procedure is designed to avoid wasting efforts in implementing
ideas that have no chance to ever get accepted to the Python core.
If this is no concern for you (i.e. you are willing to accept the risk
of wasting efforts), you can certainly implement the thing, wait for
user feedback, and then write the PEP.

So if I do it this way, the PEP will not have to contain all the
features of such a module but just a link to the documentation, which
will describe all the classes, functions etc.?

Thank You,
Christoph Becker-Freyseng

[Gerrit Holl]

"Martin v. Löwis" wrote:

Christoph Becker-Freyseng wrote:

So basically I want to relocate the real Specification, because the more
specific it gets the more it looks like a documentation and the prePEP
grows and grows ...
Is this a valid option for a PEP?
If you are asking: "Can we have an implementation before we write the
PEP?", the answer is "Certainly, yes".

I don't think that's what we're asking. The question is: what level of
detail should the "Specification" part of the PEP have? The highest
level of detail is the full documentation - but that would mean the PEP
would be to large. Is it allowed to link the documentation - even if it
is docuemntation for a not-yet-existing module - as the specification?
The PEP procedure is designed to avoid wasting efforts in implementing
ideas that have no chance to ever get accepted to the Python core.
If this is no concern for you (i.e. you are willing to accept the risk
of wasting efforts), you can certainly implement the thing, wait for
user feedback, and then write the PEP.

Hmm, the earlier discussion did show there certainly is a chance it will
ever get accepted, so that's not really the problem. But there are a lot
of ways to do a Path class, and we don't want to spend too much effort
into way A if way B has a lot more chance to be accepted.

yours,
Gerrit.

P.S.
Even a rejected PEP is not a waste of time: one can learn a lot from
writing a PEP, and gets one name on the PEP-list ;-)

--
124. If any one deliver silver, gold, or anything else to another for
safe keeping, before a witness, but he deny it, he shall be brought before
a judge, and all that he has denied he shall pay in full.
-- 1780 BC, Hammurabi, Code of Law
--
PrePEP: Builtin path type
http://people.nl.linux.org/~gerrit/c.../pep-xxxx.html
Asperger's Syndrome - a personal approach:
http://people.nl.linux.org/~gerrit/english/