test_ok1/py/doc/getting-started.txt

Getting started with the py lib 
===============================

.. contents::
.. sectnum::

Obtaining the current py lib 
============================

Due to the nature of its innovative goals `the py lib`_ can't be 
easily released without a certain API consistency.  Nevertheless, 
the API is pretty stable in many respects and very 
well tested.  So we invite you to participate and 
use it - especially if you share `the frustrations with
current python package development`_. 

.. _`the py lib`: index.html 

getting it via subversion 
-------------------------

Checkout the py lib distribution tree with subversion, e.g. use:: 

    svn co http://codespeak.net/svn/py/dist py-dist 

to checkout the code, documentation, tool and example tree 
into a ``py-dist`` checkout directory.  Your naming desire may vary
for your local checkout directory. 

If you experience problems with the subversion checkout e.g. 
because you have a http-proxy in between that doesn't proxy 
DAV requests you can try to use "codespeak.net:8080" instead 
of just "codespeak.net".  Alternatively, you may tweak 
your local subversion installation. 

setting it up
-------------

You need to put the checkout-directory into your ``PYTHONPATH``
and you want to have the ``py-dist/py/bin/py.test`` script in 
your system path, which lets you execute test files and directories.  

There already is a convenient way for Bash/Shell based systems
to setup the ``PYTHONPATH`` as well as the shell ``PATH``, insert:: 

    eval `python ~/path/to/py-dist/py/env.py`

into your ``.bash_profile``.  Of course, you need to
specify your own checkout-directory. 

If you know of a good developer-style way of doing the
equivalent on win32 (non-cygwin) environments, tell us_. 

And no, we don't yet provide a distutils-install until 
we have settled on a convenient way to upgrade seamlessly 
via an `svn up` while at the same time allowing 
installs/upgrades via the distutils `setup.py` way.   
Our `releasescheme document`_ holds some preliminary 
planning on how future releaes of the py lib will 
look like. 

.. _`releasescheme document`: releasescheme.html

upgrading it 
------------

Well, easy. Go to your checkout directory and issue:: 

    svn up 

have fun and `get an account`_ :-) 


Participating in development 
============================

The py-dev and py-svn mailing lists 
----------------------------------- 

If you feel the desire to help tackle bugs and fixes, 
or support resolution of some `frustrations`_ or to
just lurk in then please subscribe to one or both 
of our mailinglists: 

    `py-dev developers list`_ 

and our  

    `py-svn general commit mailing list`_ 

Coding and communication 
------------------------

We are practicing what could be called documentation, 
vision, discussion and automated test driven development. 
In the `future`_ book we try to layout visions and ideas for
the near coding feature to give a means for preliminary
feedback before code hits the ground. 

With our `coding style`_ we are mostly following 
cpython guidance with some additional restrictions
some of which projects like twisted_ or zope3_ have 
adopted in similar ways. 

.. _`zope3`: http://zope3.zwiki.org/
.. _twisted: http://www.twistedmatrix.org 
.. _future: future/future.html 

.. _`get an account`:  

get an account on codespeak  
--------------------------- 

codespeak_ is employing a pretty liberal committing scheme.  If you know 
someone who is active on codespeak already or you are otherwise known in 
the community then you will most probably just get access.  But even if 
you are new to the python developer community you may still get one if 
you want to improve things and can be expected to honour the 
style of coding and communication. 

.. _`coding style`: coding-style.html 
.. _`frustrations`: 
.. _`the frustrations with current python package development`: why_py.html#frustrations
.. _us: http://codespeak.net/mailman/listinfo/py-dev
.. _codespeak: http://codespeak.net/
.. _`py-dev developers list`: http://codespeak.net/mailman/listinfo/py-dev 
.. _`py-svn general commit mailing list`: http://codespeak.net/mailman/listinfo/py-svn