p53209761
/
test_ok2
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

[svn r38514] rewrite/refactor why_py (it was quite old) 

--HG--
branch : trunk
This commit is contained in:
hpk 2007-02-11 20:31:14 +01:00
parent 00c7ccfaa0
commit 790c9bbb88
1 changed files with 62 additions and 146 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

208
py/doc/why_py.txt
View File

@ -9,59 +9,22 @@ Why, who, what and how do you do *the py lib*?
Why did we start the py lib? Why did we start the py lib?
============================ ============================
.. _frustrations: Among the main motivation for the py lib and its flagship
py.test tool were:
Frustrations and the fun of developing new ways - to test applications with a testing tool that provides
----------------------------------------------- advanced features out of the box, yet allows full customization
per-project.
Among the main motivations for writing the py lib is - distribute applications in an ad-hoc way both for testing
frustration at existing python modules and packages, and for application integration purposes.
among them:
- there is no standard way of testing python applications, - help with neutralizing platform and python version differences
scripts or modules. everybody does its own hack around
the unittest.py if testing happens at all.
- due to python's default *export all names* policy for modules - offer a uniform way to access local and remote file resources
and packages it is hard to refactor code across
releases because you might break usages of your code
- the python "batteries included" standard modules are tied to - offer some unique features like micro-threads (greenlets)
the python release process. You can't easily benefit from
new python module in older python versions which you might
have to use for whatever reason.
- support for richer interactive interaction with command line
utilities or e.g. pygame-based shells is missing.
- modules/packages are often implemented in javaesque -style
- distributed applications are implemented using
a variant of Remote Method Invocation (RMI) which carries
a lot of problems and is often difficult to deploy
with respect to different platforms and versions.
- there is no _automated_ way of installing, maintaining
and upgrading applications
The py lib tries to address these problems. It is thus in
risk of trying to do too many things at once. Of course, we
can't solve them all at once but you will find that the above
points currently drive the development of the py lib.
Experimenting with new days, appreciating the existing ones
-----------------------------------------------------------
First note that we very much appreciate the great work of all
the python developers and the python-dev team in particular.
Criticism of old ways and experimenting with new ways doesn't
imply that the old ways are bad. But we all strive for the
holy development grail at least some of the time, don't we?
And because it happens far too rarely, let us especially emphasize
our appreciation for the `great work that Fred L. Drake, Jr.
is doing`_ with maintaining the core Python documentation.
What is the py libs current focus? What is the py libs current focus?
================================== ==================================
@ -74,17 +37,24 @@ Currently, the main focus of the py lib is to get a decent
Writing, distributing and deploying tests should become Writing, distributing and deploying tests should become
a snap ... and fun! a snap ... and fun!
Automated tests fit very well to the dynamism of Python. On a side note: automated tests fit very well to the dynamism
Automated tests ease development and allow fast refactoring of Python. Automated tests ease development and allow fast
cycles. Automated tests are a means of communication refactoring cycles. Automated tests are a means of
as well. communication as well.
ad-hoc distribution of programs
------------------------------------
The py lib through its `py.execnet`_ namespaces offers
support for ad-hoc distributing programs across
a network and subprocesses. We'd like to generalize
this approach further to instantiate and let whole
ad-hoc networks communicate with each other while
keeping to a simple programming model.
.. _`py.execnet`: execnet.html
We try to allow test scripts with minimal boilerplate code or
no boilerplate at all. With the py lib you can simply use
``assert`` statements in order to - well - assert something
about objects in your code. No ``assertEqual(s)`` and all the
other kinds of funny names which only cover part of what you
want to assert about an expression, anyway.
allowing maximum refactoring in the future ... allowing maximum refactoring in the future ...
---------------------------------------------- ----------------------------------------------
@ -92,42 +62,31 @@ allowing maximum refactoring in the future ...
explicit name export control explicit name export control
............................ ............................
In order, to allow a fast development pace across versions of In order to allow a fast development pace across versions of
the py lib there is **explicit name export control**. You the py lib there is **explicit name export control**. You
will only see names which make sense to use from the outside should only see names which make sense to use from the outside
and which the py lib developers want to guarantee across multiple and which the py lib developers want to guarantee across versions.
revisions. However, you don't need to treat the ``py`` lib as However, you don't need to treat the ``py`` lib as
anything special. You can simply use the usual ``import`` anything special. You can simply use the usual ``import``
statement and will not notice much of a difference - except that statement and will not notice much of a difference - except that
the namespaces you'll see from the ``py`` lib will be extreamly the namespaces you'll see from the ``py`` lib are relatively
clean and have no clutter. clean and have no clutter.
Indeed, much thought is given to reduce the exported *name Release policy & API maintenance
complexity*. This is an area where the python "batteries" and
many python packages unfortunately lack a lot. They expose so
many names that it becomes very hard to change APIs across
releases. People have been adding whole interface systems
because of that but arguably this adds another layer of names
instead of reducing the original problem.
Anyway, exporting to many names kills the fun of refactoring
and improving things. We want to avoid that as much as
possible.
Upcoming Release policy & API guarantees
........................................ ........................................
We'll talk about major, minor and micro numbers as the three We'll talk about major, minor and micro numbers as the three
numbers in "1.2.3" respectively. These are the (draft!) numbers in "1.2.3" respectively. These are the
release policies: the rough release policies:
- Micro-releases are bug fix releases and may not introduce - Micro-releases are bug fix releases and should not introduce
new names to the public API. They may add tests and thus new names to the public API. They may add tests and thus
further define the behaviour of the py lib. They may further define the behaviour of the py lib. They may
completly change the implementation but the public API completly change the implementation but the public API
tests will continue to run. tests should continue to run (unless they needed to
get fixed themselves).
- No **tested feature** of the exported py API is to vanish - No **tested feature** of the exported py API shall vanish
across minor releases until it is marked deprecated. across minor releases until it is marked deprecated.
For example, pure API tests of a future version 1.0 are to For example, pure API tests of a future version 1.0 are to
@ -144,14 +103,10 @@ release policies:
a single leading '_' is generally seen as an implementation a single leading '_' is generally seen as an implementation
level detail. level detail.
- we intend to involve expert developers who give new APIs an
independent review before they go into a minor release
and even more so before they go into a major release.
- major releases *should*, but are not required to, pass - major releases *should*, but are not required to, pass
all API tests of the previous latest major released all API tests of the previous latest major released
version. A full list of changes is to be included in version.
the release notes, including the tests that got abandoned.
the need to find the right *paths* ... the need to find the right *paths* ...
-------------------------------------- --------------------------------------
@ -159,18 +114,12 @@ the need to find the right *paths* ...
Another focus are well tested so called *path* implementations Another focus are well tested so called *path* implementations
that allow you to seemlessly work with different backends, that allow you to seemlessly work with different backends,
currently a local filesystem, subversion working copies and currently a local filesystem, subversion working copies and
subversion remote URLs. Moreover, there is an experimental subversion remote URLs. The `jorendorff path.py`_ implementation
``extpy`` path to address a Python object on the (possibly
remote) filesystem. The `jorendorff path.py`_ implementation
goes somewhat in the same direction but doesn't try to goes somewhat in the same direction but doesn't try to
systematically access local and remote file systems as well as systematically access local and remote file systems as well as
other hierarchic namespaces. The latter is the focus of the other hierarchic namespaces. The latter is the focus of the
``py.path`` API. ``py.path`` API.
If you are ready to grasp more then you may try reading
about future_ coding goals of the py lib, which reflect the
current developers thoughts and discussions.
.. _`jorendorff path.py`: http://www.jorendorff.com/articles/python/path/ .. _`jorendorff path.py`: http://www.jorendorff.com/articles/python/path/
How does py development work? How does py development work?
@ -189,76 +138,42 @@ It's easy to get commit rights especially if you are an
experienced python developer and share some of the experienced python developer and share some of the
frustrations described above. frustrations described above.
Moreover, the world will be granted svn commit rights to all Licensing
py test files so that you can easily add bug-tests or tests
for behaviour to make sure the tested behaviour persists
across releases. If you are itching to actually fix or
refactor any implementation code you can likely get commit
rights to do it. However, it is then (and anyway) a good idea to
follow the `py-dev mailing list`_ and grasp some of the things
that are going on in the `future`_ book.
Licensing, please
----------------- -----------------
Oh right, and you should also agree to release your contributions The Py lib is released under the MIT license and all
under an ``MIT license`` and consequently any other OSI-approved contributors need to release their contributions
license. This is FOSS [#]_ and we want to have the py lib interopable under this license as well.
with whatever license style you prefer. Copyright generally
stays with the contributors. We are following the
linux-kernel dev-model with this one.
Hum, maybe we can also compute the individual copyrights from connections with PyPy_
the subversion blame command. Would be a fun way to handle it.
Basically, nobody should ever have a problem to use the py lib
under any OSI approved license and also for commercial
purposes.
Are there connections with PyPy_?
--------------------------------- ---------------------------------
Some of the motivation for writing the py lib stems from needs A major motivation for writing the py lib stems from needs
during PyPy_ development, most importantly testing and during PyPy_ development, most importantly testing and
file system access issues. PyPy puts a lot of pressure file system access issues. PyPy puts a lot of pressure
on a testing environment and thus is a great **reality test** on a testing environment and thus is a good **reality test**.
kind of thing.
More importantly, the development perspective taken from the Who is "we"?
PyPy developers has some influence. For example, the
`envisioned import/export system`_ clearly has some thought
references to the way PyPy tries to separate different levels
of objects and execution in order to reach a higher level
view of what is going on.
Who is "we"? Some history ...
============================= =============================
Some initial code was written from *Jens-Uwe Mager* and *Holger Some initial code was written from *Jens-Uwe Mager* and *Holger
Krekel*, after which Holger continued on a previous Krekel*, after which Holger continued on a previous
incarnation of the py.test tool (known first as 'utest', then incarnations of the py.test tool (known first as 'utest', then
as 'std.utest', now, finally and at last 'py.test'). as 'std.utest', now for some 2 years 'py.test').
Helpful discussions took place with *Martijn Faassen*, *Stephan Helpful discussions took place with *Martijn Faassen*, *Stephan
Schwarzer* and then *Armin Rigo* who contributed important parts. Schwarzer*, *Brian Dorsey*, *Grigh Gheorghiu* and then
*Armin Rigo* who contributed important parts.
He and Holger came up with a couple of iterations of the He and Holger came up with a couple of iterations of the
testing-code that reduced the API to almost nothing: just the testing-code that reduced the API to basically nothing: just the
plain assert statement and a ``py.test.raises`` method to plain assert statement and a ``py.test.raises`` method to
check for occuring exceptions. check for occuring exceptions within tests.
Now recently, after Holgers `talk at EP2004`_ more people Currently (as of 2007), there are more people involved
were interested and there were discussions with *Jim Fulton*, and also have worked funded through merlinux_ and the
*Marius Gedminas*, *Laura Creighton* and more recently, *Ian Bicking*. PyPy EU project, Carl Friedrich Bolz, Guido Wesdorp
and Maciej Fijalkowski who contributed particularly
However, there is no real core development team as such, yet. in 2006 and 2007 major parts of the py lib.
Also we are somewhat lacking in the win32 area. Every now and
then the py lib is tested on windows but it's currently not a
practical concern of one of the current developers or
contributors.
However, one of the future directions of the `py.test tool and
library`_ is to allow running tests across multiple python
versions and computers. Then we can run tests without having
to walk up or boot up a windows machine :-)
.. _`talk at EP2004`: http://codespeak.net/svn/user/hpk/talks/std-talk.txt .. _`talk at EP2004`: http://codespeak.net/svn/user/hpk/talks/std-talk.txt
.. _`coding style`: coding-style.html .. _`coding style`: coding-style.html
@ -270,6 +185,7 @@ to walk up or boot up a windows machine :-)
.. _future: future/future.html .. _future: future/future.html
.. _`py.test tool and library`: test.html .. _`py.test tool and library`: test.html
.. _`great work that Fred L. Drake, Jr. is doing`: http://www.python.org/doc/2.3.4/lib/lib.html .. _`great work that Fred L. Drake, Jr. is doing`: http://www.python.org/doc/2.3.4/lib/lib.html
.. _merlinux: http://merlinux.de
-- --