From 790c9bbb88950d9eaac394f3424999140dde641b Mon Sep 17 00:00:00 2001 From: hpk Date: Sun, 11 Feb 2007 20:31:14 +0100 Subject: [PATCH] [svn r38514] rewrite/refactor why_py (it was quite old) --HG-- branch : trunk --- py/doc/why_py.txt | 208 ++++++++++++++-------------------------------- 1 file changed, 62 insertions(+), 146 deletions(-) diff --git a/py/doc/why_py.txt b/py/doc/why_py.txt index 137f5824e..402482257 100644 --- a/py/doc/why_py.txt +++ b/py/doc/why_py.txt @@ -9,59 +9,22 @@ Why, who, what and how do you do *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 -frustration at existing python modules and packages, -among them: +- distribute applications in an ad-hoc way both for testing + and for application integration purposes. -- 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. +- help with neutralizing platform and python version differences -- due to python's default *export all names* policy for modules - and packages it is hard to refactor code across - releases because you might break usages of your code +- offer a uniform way to access local and remote file resources -- the python "batteries included" standard modules 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. +- offer some unique features like micro-threads (greenlets) -- 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? ================================== @@ -74,17 +37,24 @@ Currently, the main focus of the py lib is to get a decent Writing, distributing and deploying tests should become a snap ... and fun! -Automated tests fit very well to the dynamism of Python. -Automated tests ease development and allow fast refactoring -cycles. Automated tests are a means of communication -as well. +On a side note: automated tests fit very well to the dynamism +of Python. Automated tests ease development and allow fast +refactoring cycles. Automated tests are a means of +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 ... ---------------------------------------------- @@ -92,42 +62,31 @@ allowing maximum refactoring in the future ... 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 -will only see names which make sense to use from the outside -and which the py lib developers want to guarantee across multiple -revisions. However, you don't need to treat the ``py`` lib as +should only see names which make sense to use from the outside +and which the py lib developers want to guarantee across versions. +However, you don't need to treat the ``py`` lib as anything special. You can simply use the usual ``import`` 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. -Indeed, much thought is given to reduce the exported *name -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 +Release policy & API maintenance ........................................ We'll talk about major, minor and micro numbers as the three -numbers in "1.2.3" respectively. These are the (draft!) -release policies: +numbers in "1.2.3" respectively. These are the +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 further define the behaviour of the py lib. They may 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. 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 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 all API tests of the previous latest major released - version. A full list of changes is to be included in - the release notes, including the tests that got abandoned. + version. + 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 that allow you to seemlessly work with different backends, currently a local filesystem, subversion working copies and -subversion remote URLs. Moreover, there is an experimental -``extpy`` path to address a Python object on the (possibly -remote) filesystem. The `jorendorff path.py`_ implementation +subversion remote URLs. The `jorendorff path.py`_ implementation goes somewhat in the same direction but doesn't try to systematically access local and remote file systems as well as other hierarchic namespaces. The latter is the focus of the ``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/ 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 frustrations described above. -Moreover, the world will be 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 (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 +Licensing ----------------- -Oh right, and you should also agree to release your contributions -under an ``MIT license`` and consequently any other OSI-approved -license. This is FOSS [#]_ and we want to have the py lib interopable -with whatever license style you prefer. Copyright generally -stays with the contributors. We are following the -linux-kernel dev-model with this one. +The Py lib is released under the MIT license and all +contributors need to release their contributions +under this license as well. -Hum, maybe we can also compute the individual copyrights from -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_? +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 file system access issues. PyPy puts a lot of pressure -on a testing environment and thus is a great **reality test** -kind of thing. +on a testing environment and thus is a good **reality test**. -More importantly, the development perspective taken from the -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 ... +Who is "we"? ============================= Some initial code was written from *Jens-Uwe Mager* and *Holger Krekel*, after which Holger continued on a previous -incarnation of the py.test tool (known first as 'utest', then -as 'std.utest', now, finally and at last 'py.test'). +incarnations of the py.test tool (known first as 'utest', then +as 'std.utest', now for some 2 years 'py.test'). 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 -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 -check for occuring exceptions. +check for occuring exceptions within tests. -Now recently, after Holgers `talk at EP2004`_ more people -were interested and there were discussions with *Jim Fulton*, -*Marius Gedminas*, *Laura Creighton* and more recently, *Ian Bicking*. - -However, there is no real core development team as such, yet. -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 :-) +Currently (as of 2007), there are more people involved +and also have worked funded through merlinux_ and the +PyPy EU project, Carl Friedrich Bolz, Guido Wesdorp +and Maciej Fijalkowski who contributed particularly +in 2006 and 2007 major parts of the py lib. .. _`talk at EP2004`: http://codespeak.net/svn/user/hpk/talks/std-talk.txt .. _`coding style`: coding-style.html @@ -270,6 +185,7 @@ to walk up or boot up a windows machine :-) .. _future: future/future.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 +.. _merlinux: http://merlinux.de --