New PEP: Quality Guidelines For Standard Modules
Carlos Ribeiro
issues associated with PEP 2, namely:
- the definition of the "Standard Library";
- some considerations about OS independency and its relation to the
Standard Library;
- and finally, some fairly broad guidelines for standard modules.
I've decided to submit it to the group before sending it Barry Warsaw. I
think that this subject still deserves some public discussion before fixing
the PEP format. I also believe that the main issue with PEP 2 is that it is
too big to be tackled as a single PEP; it is better for us to have a
"framework" for the Standard Library and modules in general, comprised of
several PEPs. Too many cats for a single bag.
p.s. That's probably my first formal document in English. I'm not used to
write such documents in English, and I don't think that I'm going to win a
Pulitzer on it anytime soon :-) Critics are welcome.
Carlos Ribeiro
----
PEP: Unnumbered
Title: Quality Guidelines For Standard Modules
Version: $Revision: 0.1$
Author: crib...@mail.inet.com.br (Carlos Ribeiro)
Status: Draft
Type: Informational
Created: 01-Jul-2001
Post-History:
Abstract
This PEP describes the minimum quality guidelines for modules
to be included as part of the Standard Library. The main
focus is to define a minimum quality level, making the use
of the module as easy, consistent and predictable as possible.
These recommendations are not meant to be enforced as absolute
rules, and should not prevent non-compliant modules from being
included in any Python Distribution.
This proposal does not try to enforce rigid rules on
controversial issues such as source code style and attribute
names. There are no absolute rules for these issues. However,
we feel that some general advice is applicable to most
instances, and so included some guidelines on this topic.
Last but not least, this proposal must be understood as a
broad set of recommendations. It is not meant to be read as
a set of rules to be enforced. Non-compliant modules may be
still be accepted as part of the standard library for several
reasons. Common sense and community acceptance are still the
best judges on this.
What is the Standard Library?
The Standard Library is comprised of the modules that are
referenced in the Python Library Reference manual. Standard
Python Distributions MUST support all modules from the
Standard Library, with the exception of OS-dependant ones.
What is "quality"?
This question is as old as philosophy, and as such, there are
no absolute answers. Our definition of quality, as applied to
the modules in the Standard Library, is based on the folowing
atributes:
- Consistence. All modules in the Standard Library follow
similar structure. Similar objects or attributes always lead
to similar results.
- Predictability. By means of a consistent interface, all
the modules provide highly predictable behavior. Subtle
surprises must be avoided.
- Readability. Both the documentation and the code must be
easy to read, making the learning process much easier.
Documentation and naming guidelines
1. By definition, Standard Library modules MUST be documented
in the main Python Library Reference.
2. The module author SHALL supply the documentation as part
of the process for module acceptance in the Standard
Library, as covered in PEP-2.
3. All the classes and functions exported by the module MUST
have PEP-256 compliant docstrings.
4. Class names SHOULD be written in mixed case.
5. Attributes whose value is expected to be constant SHOULD
have their names written in uppercase.
Module structure guidelines
1. Standard Modules MUST not rely on global variables to keep
state information, except when it is absolutely required.
Whenever it does need to save state information, the use
of a instance object is suggested.
2. In the case that the module is expected to support only a
single instance, a singleton MUST be used, instead of
global variables.
3. Python source code MUST be written using only spaces. Tabs
are not allowed on source code files.
OS-dependency guidelines
1. There are three main categories of modules regarding the
dependency on some particular OS or hardware platform:
* OS-DEPENDENT modules are, for intrinsec reasons, supported
only on some particular platforms and/or hardware
platforms. They may not be ported to other platforms
without substantial investment or changes to the
underlying environment.
* OS-LIMITED modules are supported only on some particular
platforms. They are not inherently limited to the
supported platforms, but for some reason the code cannot
be easily ported (or supported) on other platforms.
* OS-INDEPENDENT modules are supported on many platforms.
Some particular platforms may not support the module,
because of severe limitations on the platform itself.
These limitations are easily recognizable, specially if
the module is already supported on all major platforms.
2. OS-LIMITED modules SHOULD NOT be included in the Standard
Library. The module author MUST rewrite the module in such
a way to make possible to port it to other platforms as a
OS-INDEPENDENT module.
3. OS-DEPENDENT modules SHOULD only be included to support
functionality required to use Python in the target platform.
4. OS-INDEPENDENT modules that rely on specific code in Python
for every platform supported MUST import a separate module
that implements the platform specific code. This (sub)module
SHOULD preferably be part of the main package. In this case
the module name should reflect the platform it supports.
Remarks
This draft was inspired by the discussions regarding Python
development, and PEPs in particular. After following the
discussion it became clear that one of the main topics of the
debate was the need to improve the library. However, we did
lack some definitions on this, and this PEP is being addressed
at this particular problem.
We did chose to use the Python Library Reference documentation
as the basis for our definition, because we felt that no other
definition would as clearly embrace the set of modules that
the community regards as the standard one.
References
(still incomplete; please help me!)
[1] PEP 2 - Procedure for Adding New Modules
[2] PEP 256 - Docstring Processing System Framework
[3] (...there a more to come, please be patient...)
Copyright
This document has been placed in the public domain.
Acknowledgements
This PEP would be impossible without the help of the Python
community. In special, Martijn Faassen and Paul Prescod helped
a lot to bring the issue to our attention.
(please help me here also; I dont want to step on anybody's
toes, but I'm having a terrible time to find all the past
references on my mailbox)
Local Variables:
mode: indented-text
indent-tabs-mode: nil
End:
Malcolm Tredinnick
won't degenerate into a repeat of some previous threads).
Mostly, these are critical comments, but that's not because I'm a
negative bastard (well, I am, but...). Rather, some resolution would be
nice to these discussions, so if somebody throws out a PEP like this,
let's hammer it out and then it either survives and becomes policy or it
becomes clear that we don't really need.
I'm glad some people have taken the time to write down come conclusions
from the earlier discussions.
On Sun, Jul 01, 2001 at 09:45:23PM -0300, Carlos Ribeiro wrote:
> Last but not least, this proposal must be understood as a
> broad set of recommendations. It is not meant to be read as
> a set of rules to be enforced. Non-compliant modules may be
> still be accepted as part of the standard library for several
> reasons. Common sense and community acceptance are still the
> best judges on this.
This last bit pretty much guarantees that everytime somebody proposes a
slightly border-line case, we will revisit the same tired old arguments
again and again. In fact, it's a bit worse than that: since there are a
whole bunch of modules in the current distribution which fail to meet
you recommendations, there's scope for "discussion" aplenty without
further delay. :-)
More seriously, this caveat is useful, since it is a response to all of
my complaints below: anything that falls between the cracks becomes a
source of discussion and then something like a BDFL pronouncement to
settle it.
> What is the Standard Library?
>
> The Standard Library is comprised of the modules that are
> referenced in the Python Library Reference manual. Standard
> Python Distributions MUST support all modules from the
> Standard Library, with the exception of OS-dependant ones.
This seems loosely phrased. What do you mean by "support all modules"?
Do they have to compile? Do they have to return sensible answers when
they run? Can they just say "Not supported on this platform"?
It may be tempting to change this to "must include all modules from the
standard library". However, this is tricky for a couple of reasons: this
PEP hasn't really discussed why the concept of a Standard Library is
required, and I'm not convinced it's a good idea to keep making the
Python "distribution" larger and larger. My modem already starts to
complain if I have to do a full download (thank heavens for CVS
updates).
That last paragraph possibly sows the seed for a whole discussion on the
merits of including every standard component under the sun, or just
having a system for saying "component ZZ is required" and having a place
to download it (a la CPAN in that other world). I'm also not sure this
PEP is necessarily the place for also defining things like "what is a
distribution" (I don't even think that's a useful concept to formalise).
[...]
> OS-dependency guidelines
>
> 1. There are three main categories of modules regarding the
> dependency on some particular OS or hardware platform:
>
> * OS-DEPENDENT modules are, for intrinsec reasons, supported
> only on some particular platforms and/or hardware
> platforms. They may not be ported to other platforms
> without substantial investment or changes to the
> underlying environment.
>
> * OS-LIMITED modules are supported only on some particular
> platforms. They are not inherently limited to the
> supported platforms, but for some reason the code cannot
> be easily ported (or supported) on other platforms.
>
> * OS-INDEPENDENT modules are supported on many platforms.
> Some particular platforms may not support the module,
> because of severe limitations on the platform itself.
> These limitations are easily recognizable, specially if
> the module is already supported on all major platforms.
>
> 2. OS-LIMITED modules SHOULD NOT be included in the Standard
> Library. The module author MUST rewrite the module in such
> a way to make possible to port it to other platforms as a
> OS-INDEPENDENT module.
The OS-LIMITED concept was a bit confusing to me the first couple of
times I read this. Basically, you are saying "write portable code", as
far as I can tell. If there were other obstacles, wouldn't that make the
module OS-DEPENDENT? If I'm missing something here, perhaps you can give
an example of something that is portable code, but OS-LIMITED and not
OS-DEPENDENT.
> 3. OS-DEPENDENT modules SHOULD only be included to support
> functionality required to use Python in the target platform.
This is again a little loosely phrased. I can "use" Python with only a
handful of modules. Of course, it becomes reasonably functionality-free
at that point and I'd probably prefer C or Perl or shell scripting
instead. :-(
It is quite reasonable to have modules in the "standard library" that
are only supported on a wide range of platforms (not all platforms). For
example, there are already various things that are Unix specific and are
awkward at best on Redmond-based operating systems. The set of
Unix-like systems is quite large and if module X runs well on those, why
should it not be included just because Windows is broken (to pick but
one example)?
Similarly, the current stuff for supporting the Macintosh finder tools
and the like are fairly narrowly targeted, but they touch a large user
base.
> 4. OS-INDEPENDENT modules that rely on specific code in Python
> for every platform supported MUST import a separate module
> that implements the platform specific code. This (sub)module
> SHOULD preferably be part of the main package. In this case
> the module name should reflect the platform it supports.
Lest I sound too negative above, I think this categorisation scheme is
somewhat useful (it also exists already, since the library reference
already identifies the platform availability). Particularly for module
writers, who should be thinking about where their target is (does the
module really have to be platform dependent, or can they design it so
that somebody else can come along and add the bits to make it run on a
Palm Pilot and a Cray and a Space Shuttle, etc).
Cheers,
Malcolm
--
A clear conscience is usually the sign of a bad memory.
Carlos Ribeiro
after a busy Sunday :-) You raised several interesting points. I believe
that some problems are caused by my limited knowledge of english. Sometimes
I'm not able to make myself clear. I'll try to reply only one of your
comments; I'll leave the rest of them for tomorrow.
At 10:50 02/07/01 +0800, Malcolm Tredinnick wrote:
>The OS-LIMITED concept was a bit confusing to me the first couple of
>times I read this. Basically, you are saying "write portable code", as
>far as I can tell. If there were other obstacles, wouldn't that make the
>module OS-DEPENDENT? If I'm missing something here, perhaps you can give
>an example of something that is portable code, but OS-LIMITED and not
>OS-DEPENDENT.
Let me try to explain what I meant: some modules are not as portable as
they should. There is nothing inherently non portable on the module code,
but the author may have used (maybe inadvertently) some non portable
feature of some particular platform. This is the what I meant as
OS-LIMITED. It was my way to define modules that deserve to be "fixed". By
removing unneeded dependency these modules may become portable, and so
OS-INDEPENDENT.
Many modules that are available on the net suffer from this problem. Let us
talk about something simple: some advanced data structure, for example a
tree. Some implementations available on the net compile only for some
particular platforms, sometimes because the author used particular features
of that platform's compiler. In such case, it should be relatively easy to
remove the dependency in order to make the code OS-INDEPENDENT, as by my
definition.
As for the rest of your comments, they were all very helpful. I'll try to
think on them a little bit harder Monday morning after a good sleep
<wink-and-snore>
Carlos Ribeiro
Carlos Ribeiro
come up with a revision for this key paragraph:
What is the Standard Library?
The Standard Library is comprised of the modules that are
documented in the Python Library Reference manual. Standard
Python Distributions MUST implement all modules from the
Standard Library, with the possible exception of OS-dependant
ones.
That's a little clearer, I think. However it does still suffer from some
problems:
- Python != CPython. This should not be an issue, though;
standard modules should be supported on different Python
implementations also.
- The problem was moved from the definition of the "Python
Standard Library" to the concept of a "Python Distribution".
It is not clear what a Python Distribution is. However, I
feel that the existence of the Python Library Reference
manual is already one step on this direction, because it
does define a lot of things as part of the "official"
Python Distribution.
Again, a disclaimer: English is not my first language, and sometimes it is
hard for me to make myself clear. I hope to get better with a few more
attempts :-)
Carlos Ribeiro
Courageous
Seems like a good start. I only have one objection:
> 1. Standard Modules MUST not rely on global variables to keep
> state information, except when it is absolutely required.
When writing language requirements, one MUST not use the
term "MUST" in conjunction with an "except". And in any case,
I disagree. Emphatically.
The use of a singleton pattern changes nothing unless every
call to the module has the singleton as its first argument. And
if you're envisioning storing the singleton as a global, nothing
has been accomplished. There's a global.
Perhaps you could make a better case for why you think this
is even important.
C//
Dinu Gherman
>
> PEP: Unnumbered
> Title: Quality Guidelines For Standard Modules
> Version: $Revision: 0.1$
> Author: crib...@mail.inet.com.br (Carlos Ribeiro)
> Status: Draft
> Type: Informational
> Created: 01-Jul-2001
> Post-History:
Ola, Carlos,
In general, that makes pretty much sense to me, although
some statements are likely too vague to go without every-
body interpreting them at will. And, quite likely, under
the term "quality criteria" might be hiding another hot
PEPper...
Still, I'll add two points that I'd like to see covered as
well in a PEP like this:
1. whereever possible the set of features labeled loosely
as "desired qualities" of a standard module must be
detectable by an automated test tool using PyUnit, and
2. the PEP's scope should at least address the possibili-
ties for making existing modules of the standard library
more compliant with those desired qualities.
Number 1 is not to enforce anything (hard anyway), but
simply to be able to run compliance tests to avoid silly
disputes about a given module's compliance with the listed
features. Using Python 2.1 this should be much easier than
before.
Number 2 is a heretic one, yes, but nevertheless important
for achieving true consistency and ease of use for new mem-
bers of the Python community. This kind of thing is unfor-
tunately often underestimated.
Best regards,
Dinu
--
Dinu C. Gherman
ReportLab Consultant - http://www.reportlab.com
................................................................
"The only possible values [for quality] are 'excellent' and 'in-
sanely excellent', depending on whether lives are at stake or
not. Otherwise you don't enjoy your work, you don't work well,
and the project goes down the drain."
(Kent Beck, "Extreme Programming Explained")
Carlos Ribeiro
>When writing language requirements, one MUST not use the
>term "MUST" in conjunction with an "except". And in any case,
>I disagree. Emphatically.
Point taken.
>The use of a singleton pattern changes nothing unless every
>call to the module has the singleton as its first argument. And
>if you're envisioning storing the singleton as a global, nothing
>has been accomplished. There's a global.
>
>Perhaps you could make a better case for why you think this
>is even important.
One example that comes to mind is the fileinput standard module. It stores
global state:
input([files[, inplace[, backup]]])
Create an instance of the FileInput class. The instance will be used as
global state for the functions of this module, and is also returned to use
during iteration.
Let us say that you are iterating over the lines in the main loop of a
filter, and then, depending on the line read, have to iterate over several
other files. The global state prevents you from using the same instance of
the fileinput module. The workaround is to import the module a second time,
binding it by a different name. Please note that I haven't done any *real*
test on this myself. Also, if the state variable is declared as a global,
even reimporting the module will fail.
Carlos Ribeiro
Carlos Ribeiro
words this time:
1. Standard Modules MUST not rely on global variables to keep
state information, EXCEPT when it is ABSOLUTELY required.
Standard modules should not rely on global variables to store state. It
makes more difficult to use the library functionality on different
instances at the same time. It breaks the consistence rule, because you
need to take extra care to avoid some constructs if the module uses
globals. For instance, you can open as many files at you want at the same
time (within the practical limits of your platform), but you aren't
supposed to use more than one instance of the fileinput module. This
limitation can and should be fixed - it's possible to do it using
iterators, but I'm not still into 2.2, so I don't know for sure.
However, in some particular cases, it may be impossible to remove all
global state information from the module. Some examples may include the use
of specific features of the OS or the platform, that is global in its
nature (path information is a good example). Then you have two choices: you
either expose the global objects as part of the module interface (as it is
the case with sys.path), or you expose it using a singleton class. I
believe that using singletons makes it easier to use the module
functionality in a flexible OO way.
Anyway, we can discuss why singletons are good and globals are not until
the end of the universe. I just feel that using singletons will make things
much more consistent with the OO paradigm that is used on most of the library.
Carlos Ribeiro
Steve Holden
news:mailman.994074843...@python.org...
> Let me try explain this topic a little bit better. I've highlighted more
> words this time:
>
> 1. Standard Modules MUST not rely on global variables to keep
> state information, EXCEPT when it is ABSOLUTELY required.
>
I don't think anyone is disagreeing with the sentiments you express. It's
simply that the word SHOULD is better (since it expresses your intended
meaning) than MUST ... EXCEPT.
MUST is usually used in standards and the like to indicate an absolute
requirement, without which an implementation would not be conformant.
Change MUST to SHOULD in the above and there would probably be no
dissenters.
Oh, sorry, this is c.l.py, there'll be some ;-)
Good effort, byt the way. I think we ("ordinary" Python users) have to put
some work in to underpin the foundations...
regards
STeve
Skip Montanaro
Good start on the PEP. A couple comments.
In the final PEP I think you will need to have code examples or point to
specific compliant modules as examples. That will make it easier for people
who won't bother to read and understand the entire PEP to write compliant
code the first time. For example, you wrote:
4. Class names SHOULD be written in mixed case.
This could be either missed or interpreted by lazy programmers as any of
mixedCaseClass
MixedCaseClass
mIxEdCaseCLASS
Mixed_Case_Class
or any of a zillion other possibilities. I suspect you only meant the
second case.
Also, in the References section you should refer to Guido's style guide:
http://www.python.org/doc/essays/styleguide.html
In fact, you may want to pilfer some content...
--
Skip Montanaro (sk...@pobox.com)
(847)971-7098
Gordon McMillan
[snip example of module global being misused]
>... Also, if the state variable
>is declared as a global, even reimporting the module will fail.
This is untrue. I'm guessing you mean that given:
from module import module_global
reload(module)
doesn't do what you want, but that's the fault of using
"from ... import", not module's use of a global.
- Gordon
Roman Suzi
> PEP: Unnumbered
> Title: Quality Guidelines For Standard Modules
> Version: $Revision: 0.1$
> Author: crib...@mail.inet.com.br (Carlos Ribeiro)
> Status: Draft
> Type: Informational
> Created: 01-Jul-2001
> Post-History:
>
>
> Abstract
>
> This PEP describes the minimum quality guidelines for modules
> to be included as part of the Standard Library. The main
> focus is to define a minimum quality level, making the use
> of the module as easy, consistent and predictable as possible.
> These recommendations are not meant to be enforced as absolute
> rules, and should not prevent non-compliant modules from being
> included in any Python Distribution.
>
> This proposal does not try to enforce rigid rules on
> controversial issues such as source code style and attribute
> names. There are no absolute rules for these issues. However,
> we feel that some general advice is applicable to most
> instances, and so included some guidelines on this topic.
>
> Last but not least, this proposal must be understood as a
> broad set of recommendations. It is not meant to be read as
> a set of rules to be enforced. Non-compliant modules may be
> still be accepted as part of the standard library for several
> reasons. Common sense and community acceptance are still the
> best judges on this.
>
>
> What is the Standard Library?
>
> The Standard Library is comprised of the modules that are
> referenced in the Python Library Reference manual. Standard
> Python Distributions MUST support all modules from the
> Standard Library, with the exception of OS-dependant ones.
> What is "quality"?
>
> This question is as old as philosophy, and as such, there are
> no absolute answers. Our definition of quality, as applied to
> the modules in the Standard Library, is based on the folowing
> atributes:
>
> - Consistence. All modules in the Standard Library follow
> similar structure. Similar objects or attributes always lead
> to similar results.
Maybe there could be 2-3 different structures, because modules are so
different and to force similar behaviour from them could be
coounter-productive.
> - Predictability. By means of a consistent interface, all
> the modules provide highly predictable behavior. Subtle
> surprises must be avoided.
realistically surprises are always present because they
depend on the knowledge of the user.
> - Readability. Both the documentation and the code must be
> easy to read, making the learning process much easier.
>
>
> Documentation and naming guidelines
>
> 1. By definition, Standard Library modules MUST be documented
> in the main Python Library Reference.
>
> 2. The module author SHALL supply the documentation as part
> of the process for module acceptance in the Standard
> Library, as covered in PEP-2.
>
> 3. All the classes and functions exported by the module MUST
> have PEP-256 compliant docstrings.
>
> 4. Class names SHOULD be written in mixed case.
Why? Again, in some situation class names are dictated by
the problem domain...
> 5. Attributes whose value is expected to be constant SHOULD
> have their names written in uppercase.
So, I will need to rewrite my programs to use
math.PI instead of math.pi ?
Something about compatibility must be said here...
I am sure there are other examples where constants need to
be used "as is" to avoid "surprises".
Maybe, better define cases when these rules could be broken?
I think, that it's enough to be near the Style Guide when writing a
standard library module. But not to take it dogmatically, of course.
> Module structure guidelines
>
> 1. Standard Modules MUST not rely on global variables to keep
> state information, except when it is absolutely required.
> Whenever it does need to save state information, the use
> of a instance object is suggested.
>
> 2. In the case that the module is expected to support only a
> single instance, a singleton MUST be used, instead of
> global variables.
>
> 3. Python source code MUST be written using only spaces. Tabs
> are not allowed on source code files.
>
>
> OS-dependency guidelines
>
> 1. There are three main categories of modules regarding the
> dependency on some particular OS or hardware platform:
>
> * OS-DEPENDENT modules are, for intrinsec reasons, supported
> only on some particular platforms and/or hardware
> platforms. They may not be ported to other platforms
> without substantial investment or changes to the
> underlying environment.
>
> * OS-LIMITED modules are supported only on some particular
> platforms. They are not inherently limited to the
> supported platforms, but for some reason the code cannot
> be easily ported (or supported) on other platforms.
>
> * OS-INDEPENDENT modules are supported on many platforms.
> Some particular platforms may not support the module,
> because of severe limitations on the platform itself.
> These limitations are easily recognizable, specially if
> the module is already supported on all major platforms.
>
> 2. OS-LIMITED modules SHOULD NOT be included in the Standard
> Library. The module author MUST rewrite the module in such
> a way to make possible to port it to other platforms as a
> OS-INDEPENDENT module.
>
> 3. OS-DEPENDENT modules SHOULD only be included to support
> functionality required to use Python in the target platform.
>
> 4. OS-INDEPENDENT modules that rely on specific code in Python
> for every platform supported MUST import a separate module
> that implements the platform specific code. This (sub)module
> SHOULD preferably be part of the main package. In this case
> the module name should reflect the platform it supports.
>
>
> Remarks
>
> This draft was inspired by the discussions regarding Python
> development, and PEPs in particular. After following the
> discussion it became clear that one of the main topics of the
> debate was the need to improve the library. However, we did
> lack some definitions on this, and this PEP is being addressed
> at this particular problem.
>
> We did chose to use the Python Library Reference documentation
> as the basis for our definition, because we felt that no other
> definition would as clearly embrace the set of modules that
> the community regards as the standard one.
>
>
> References
>
> (still incomplete; please help me!)
>
> [1] PEP 2 - Procedure for Adding New Modules
>
> [2] PEP 256 - Docstring Processing System Framework
>
> [3] (...there a more to come, please be patient...)
Style Guide?
> Copyright
>
> This document has been placed in the public domain.
>
Probably this PEP also need to mention directory structure
of standard library?
Anyway, it seems that probably you need to submit it as PEP
and let wide discussion to make this doc nearly perfect.
Sincerely yours, Roman A.Suzi
--
- Petrozavodsk - Karelia - Russia - mailto:r...@onego.ru -
Alex
> Perhaps you could make a better case for why you think this is even
> important.
If you want to subclass a class whose behaviour depends on a global in
its module, getting the behaviour you want can become a bit messier.
Alex.
Courageous
>Let us say that you are iterating over the lines in the main loop of a
>filter, and then, depending on the line read, have to iterate over several
>other files. The global state prevents you from using the same instance of
>the fileinput module.
This is inarguably and obviously bad design. The author's choice of
an implicit singleton in this case was a great error and lacked even
small amounts of foresight. The error here, however, was not the global
variable. It was the implicit global singleton attached to contextually-
dependent state.
There are many situations in which global state is appropriately stored
at the module level. sys.__stderr__ for example.
I'm not sure how to improve the language of what it is that you are asking
for, however. How about: "please don't expect the standard library committee
to accept shitty code into the standard library." :-)
C//
Skip Montanaro
C//> This is inarguably and obviously bad design. The author's choice of
C//> an implicit singleton in this case was a great error and lacked
C//> even small amounts of foresight. The error here, however, was not
C//> the global variable. It was the implicit global singleton attached
C//> to contextually-dependent state.
Let's not be too hasty here. Version 1.1 of fileinput.py is dated
21-Nov-97, well before threading was widespread in Python (which is where
this stray global stuff tends to really bite you in the butt, the original
author's example notwithstanding). Also, until a year or so ago, the
fileinput module was not widely used, so any design problems it harbors were
likely to bite relatively few butts. The original design probably worked
well for the original author.
The now deprecated regex module suffered from the same problem. It was
heavily used for several years nonetheless before being replaced by two revs
of Perl-compatible regular expressions.
If the current implementation of the fileinput module creates problems for
you, rework it and submit a patch. ;-)
Tim Peters
> This is inarguably and obviously bad design. The author's choice of
[Skip Montanaro]
> Let's not be too hasty here. Version 1.1 of fileinput.py is dated
> 21-Nov-97, well before threading was widespread in Python (which is
> where this stray global stuff tends to really bite you in the butt,
> the original author's example notwithstanding). ...
If you want a threadsafe fileinput reader, create an instance of the
fileinput.FileInput class explicitly. The module global is a default
instance, catering to approximately 99.999% of expected uses: "the main
loop" exclusively chugs over sys.argv -- which is also a shared global. If
you use that from multiple threads simultaneously, it's not fileinput that's
nuts <0.9 wink>.
functioning-as-designed-ly y'rs - tim
David Goodger
> Also, until a year or so ago, the fileinput module was not widely used
Speak for yourself :-). I use it all the time. There must be more like me
out there.
Well, maybe not.
--
David Goodger dgoo...@bigfoot.com Open-source projects:
- Python Docstring Processing System: http://docstring.sf.net
- reStructuredText: http://structuredtext.sf.net
- The Go Tools Project: http://gotools.sf.net
Paul Prescod
guidelines. It occurs to me that the way to minimize violations without
being totally heavy handed is to require violations to be documented and
justified (inline, or in the module documentation, or in some kind of
PEP, or whatever.)
So for FileInput there would be a paragraph somewhere that says: "The
fileinput module violates the restriction on global variables in order
to simplify the common case of doing X Y Z. If you want to use it in a
threaded (or otherwise sophisticated) context, you can use the FileInput
class instead of the global functions."
Documenting the deviation from the spec allows us all to read and
determine whether the deviation is justified and, more important,
demonstrates that the author understood the spec and took it into
account. Like a PEP, it also (in theory) will reduce the likelihood of
repeated arguments because the arguments will be captured in a document.
--
Take a recipe. Leave a recipe.
Python Cookbook! http://www.ActiveState.com/pythoncookbook
Chris Tavares
lack of requirements for a test suite/regression testing is somewhat
disturbing. Test suites are essential for maintaining software quality over
time.
-Chris
Carlos Ribeiro
- we need to reference the style guide
- the use of tools such as PyCheck should be encouraged
- and yes, my english needs some quality checking also :-)
I'm going to work on it tonight. Too bad I have a day job <wink>. As of
now, I'm still waiting for Martin's proposed PEP2 text - it seems that he
still needs to get either Barry Warsaw or ESR approval on this, mainly
because he's taking over an existing but unfinished PEP. I feel that we're
talking about complementary issues, and it would be very important to be
working together.
Carlos Ribeiro
Steve Holden
news:ySe07.262$xp1....@newsread1.prod.itd.earthlink.net...
represents invaluable documentation for portability.
regards
STeve
--
http://www.holdenweb.com/
Thomas Wouters
> now, I'm still waiting for Martin's proposed PEP2 text - it seems that he
That's Martijn, not Martin :) 'Martijn' has the emphasis on the 'ij', which
is pronounced not unlike the 'ai' in "aiieeeee! *splat*"
I-wont-go-into-how-Thomas-is-supposed-to-be-pronounced-ly y'rs ;)
--
Thomas Wouters <tho...@xs4all.net>
Hi! I'm a .signature virus! copy me into your .signature file to help me spread!
Roman Suzi
There could be even use of some special __-word to
stress that the module is standard:
__distribution__
or
__belongs__
And probably standard modules need to clean-up unused
names after they done, so there will be no other
standard modules in the module namespace like in this situation:
>>> import uu
>>> uu.
uu.Error uu.__doc__ uu.__name__ uu.decode uu.os uu.test
uu.__all__ uu.__file__ uu.binascii uu.encode uu.sys
uu.sys is the same sys here!
Also maybe standard modules need to have __all__ to explicitely
mention their interface (or we'll wait for interface PEP
to be adopted?)
Sincerely yours, Roman Suzi
--
_/ Russia _/ Karelia _/ Petrozavodsk _/ r...@onego.ru _/
_/ Wednesday, July 04, 2001 _/ Powered by Linux RedHat 6.2 _/
_/ "Mediocrity requires aloofness to preserve it's dignity" _/
Martijn Faassen
> I've got some very good comments on my PEP-to-be. The main concerns are:
> - we need to reference the style guide
> - the use of tools such as PyCheck should be encouraged
> - and yes, my english needs some quality checking also :-)
Did you add stuff like '(unit) tests are good'? Very important in my
opinion.
> I'm going to work on it tonight. Too bad I have a day job <wink>. As of
> now, I'm still waiting for Martin's proposed PEP2 text - it seems that he
> still needs to get either Barry Warsaw or ESR approval on this, mainly
> because he's taking over an existing but unfinished PEP. I feel that we're
> talking about complementary issues, and it would be very important to be
> working together.
Definitely. I've just posted my version of PEP 2 after getting an okay from
ERS.
You also should have received a copy by mail, did it not arrive? I sent it
to you earlier, I think monday.
And yes, I feel the two are pretty complementary, so that's good.
Regards,
Martijn
--
History of the 20th Century: WW1, WW2, WW3?
No, WWW -- Could we be going in the right direction?