============================================== Why, who, what and how do you do *the py lib*? ============================================== .. contents:: .. sectnum:: Why did we start the py lib? ============================ Among the main motivation for the py lib and its flagship py.test tool were: - to test applications with a testing tool that provides advanced features out of the box, yet allows full customization per-project. - distribute applications in an ad-hoc way both for testing and for application integration purposes. - help with neutralizing platform and python version differences - offer a uniform way to access local and remote file resources - offer some unique features like micro-threads (greenlets) What is the py libs current focus? ================================== testing testing testing ----------------------- Currently, the main focus of the py lib is to get a decent `test environment`_, indeed to produce the best one out there. Writing, distributing and deploying tests should become a snap ... and fun! 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 allowing maximum refactoring in the future ... ---------------------------------------------- explicit name export control ............................ In order to allow a fast development pace across versions of the py lib there is **explicit name export control**. You 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 are relatively clean and have no clutter. 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 the rough release policies: - 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 should continue to run (unless they needed to get fixed themselves). - 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 continue to fully run on 1.1 and so on. If an API gets deprecated with a minor release it goes with the next minor release. Thus if you don't use deprecated APIs you should be able to use the next two minor releases. However, if you relied on some untested implementation behaviour, you may still get screwed. Solution: add API tests to the py lib :-) It's really the tests that make the difference. - Pure API tests are not allowed to access any implementation level details. For example, accessing names starting with a single leading '_' is generally seen as an implementation level detail. - major releases *should*, but are not required to, pass all API tests of the previous latest major released version. 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. 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. .. _`jorendorff path.py`: http://www.jorendorff.com/articles/python/path/ How does py development work? ============================= Communication and coding style ------------------------------ We are discussing things on our `py-dev mailing list`_ and collaborate via the codespeak subversion repository. We follow a `coding style`_ which strongly 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. Licensing ----------------- The Py lib is released under the MIT license and all contributors need to release their contributions under this license as well. connections with PyPy_ --------------------------------- 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 good **reality test**. Who is "we"? ============================= Some initial code was written from *Jens-Uwe Mager* and *Holger Krekel*, after which Holger continued on a previous 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*, *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 basically nothing: just the plain assert statement and a ``py.test.raises`` method to check for occuring exceptions within tests. 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 .. _`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 .. _`PyPy`: http://codespeak.net/pypy .. _future: future.html .. _`py.test tool and library`: test.html .. _merlinux: http://merlinux.de -- .. [#] FOSS is an evolving acronym for Free and Open Source Software