[py-svn] r6881 - py/dist/doc
hpk at codespeak.net
hpk at codespeak.net
Sun Oct 10 14:02:12 CEST 2004
Author: hpk
Date: Sun Oct 10 14:02:11 2004
New Revision: 6881
Added:
py/dist/doc/why_py.txt
Modified:
py/dist/doc/execnet.txt
py/dist/doc/test.txt
Log:
M doc/execnet.txt
M doc/test.txt
mostly fixes to rest
A doc/why_py.txt
a new document describing some of the background/history
of the py lib
Modified: py/dist/doc/execnet.txt
==============================================================================
--- py/dist/doc/execnet.txt (original)
+++ py/dist/doc/execnet.txt Sun Oct 10 14:02:11 2004
@@ -56,7 +56,7 @@
execution of source code. This Channel object allows two
program parts to send data to each other.
-Here is the rough idea for the interface:
+Here is the rough idea for the interface::
#
# attributes API
#
@@ -111,7 +111,7 @@
then opens a SocketGateway to the freshly started
socketserver. The "py.execnet.socketserver" is a small script that
basically listens and accepts socket connections, receives one
-liners and executes them.
+liners and executes them. Here is the code::
import py
socketserverbootstrap = py.code.Source(
@@ -164,7 +164,7 @@
Another Example for Channels
----------------------------
-problem: retrieving contents of remote files
+problem: retrieving contents of remote files::
import py
contentserverbootstrap = py.code.Source(
Modified: py/dist/doc/test.txt
==============================================================================
--- py/dist/doc/test.txt (original)
+++ py/dist/doc/test.txt Sun Oct 10 14:02:11 2004
@@ -154,7 +154,7 @@
The ``driver`` invokes the iteration protocol, i.e. the
``__iter__`` method of Collectors. These methods yield more (sub)
-collectors or Test *Items*. They should usually not raise
+*collectors* or Test *Items*. They should usually not raise
exceptions but yield back a specific CollectError. This is to
avoid that a collecting error breaks the whole collection
chain. It is at the drivers discretion to react to errors
Added: py/dist/doc/why_py.txt
==============================================================================
--- (empty file)
+++ py/dist/doc/why_py.txt Sun Oct 10 14:02:11 2004
@@ -0,0 +1,131 @@
+==============================================
+Why, who, what and how do you do *the py lib*?
+==============================================
+
+Why do we do the py lib?
+------------------------
+
+Among the main motivations for writing the py lib is
+frustration at existing python modules and packages,
+among them:
+
+- there is no standard way of testing python applications,
+ scripts or modules. everybody does its own hack around
+ the unittest.py if testing happens at all.
+
+- due to python's "export every name" policy for modules
+ and packages it is hard to refactor them across
+ releases becaue you might break uses of your code
+
+- distributed applications are implemented using
+ 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
+
+- often modules/packages are implemented in java-style
+
+- the python "batteries included" are tied to 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.
+
+The py lib tries to address these problems step by step.
+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.
+
+What is your current focus?
+---------------------------
+
+Currently, the main focus of the py lib is to get a decent
+`test environment`_. Automated tests fit very well to the
+dynamism of Python. Automated tests ease development and
+allow fast refactoring cycles. So we are trying to develop
+the best python `test environment`_ to makes writing
+tests as easy as possible. And fun.
+
+Most importantly, we try to allow test scripts with minimal
+boilerplate code or - mostly - 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.
+
+In order, to allow a fast development pace across versions of
+the py lib there is '''explicit name export control'''. You
+will only see names which make sense to use from the outside
+and which the py lib developers want to guarantee across major
+versions. No '''tested feature''' of this tightly controled API
+will vanish across major releases until it is marked
+deprecated. But if deprecated an API could go with every
+following major release. Much thought is given to reduce the
+exported *name complexity*. This is an area where the python
+"batteries" lack a lot. They expose so many names that it
+becomes very hard to change APIs across releases. This kills
+the fun of refactoring and improving things.
+
+Another focus is a well tested Path implementation that
+supports different backends, currently a local filesystem and
+subversion working copies and subversion remote URLs.
+Moreover, it provides an experimental fspython path to address
+a Python object on the filesystem.
+
+How does py development work?
+-----------------------------
+
+We are discussing things on our `py-dev mailing list`_
+and collaborate via the codespeak subversion repository.
+
+We follow a `coding style`_ which builds on `PEP 8`_, the basic
+python coding style document. It's easy to get commit rights
+especially if you are an experienced python developer
+and share some of the frustrations described above.
+
+Moreover, the world has been granted svn commit rights to all
+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 a good idea to follow
+py-dev at codespeak.net and grasp some of the things that are
+going on. Oh right, and you should also agree to release
+your code under an ``MIT license``. Maybe we can compute
+the individual copyrights from the subversion blame
+command. Would be a fun way to handle it. Basically, nobody
+should have a problem to use the py lib under any OSI approved
+license and also for commercial purposes.
+
+Who is "we"? Some history ...
+-----------------------------
+
+Some of the initial code was written from Jens-Uwe Mager
+and Holger Krekel, after which Holger continued on an
+iteration of the py.test tool (known first as 'utest', then as
+'std.utest', now 'py.test'). Helpful discussions took place
+with Martijn Faassen, and then Armin Rigo who contributed
+important parts. He and Holger came up with a couple of
+iterations of the testing-code that reduced the API to almost
+nothing: just the assert statement and an assert_raises
+method.
+
+Now recently, after Holgers `talk at EP2004`_ more people
+were interested and there were some discussions with Jim Fulton
+and Marius Gedminas and more recently, Ian Bicking. However,
+there is no real core development team as such. 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 continous concern of one of the current developers.
+However, one of the improvements to the testing code 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
+.. _`coding style`: coding-style.html
+.. _`PEP 8`: http://www.python.org/peps/pep-0008.html
+.. _`py-dev mailing list`: http://codespeak.net/mailman/listinfo/py-dev
+.. _`test environment`: test.html
More information about the pytest-commit
mailing list