[py-svn] r38455 - in py/trunk/py/doc: . future
hpk at codespeak.net
hpk at codespeak.net
Sun Feb 11 14:26:05 CET 2007
Author: hpk
Date: Sun Feb 11 14:26:03 2007
New Revision: 38455
Added:
py/trunk/py/doc/download.txt
- copied, changed from r38451, py/trunk/py/doc/getting-started.txt
Removed:
py/trunk/py/doc/api.txt
py/trunk/py/doc/getting-started.txt
py/trunk/py/doc/releasescheme.txt
Modified:
py/trunk/py/doc/TODO.txt
py/trunk/py/doc/contact.txt
py/trunk/py/doc/execnet.txt
py/trunk/py/doc/future/future.txt
py/trunk/py/doc/index.txt
py/trunk/py/doc/test.txt
py/trunk/py/doc/why_py.txt
Log:
various merging of startup documentation
and rewriting/refactoring information and
references. clarifying release-structure
a bit.
Modified: py/trunk/py/doc/TODO.txt
==============================================================================
--- py/trunk/py/doc/TODO.txt (original)
+++ py/trunk/py/doc/TODO.txt Sun Feb 11 14:26:03 2007
@@ -59,9 +59,8 @@
* (DONE/c-modules don't) see if things work on Win32 (partially done)
-* refine and implement `releasescheme`_
+* (partly DONE) refine and implement releasescheme/download
-.. _releasescheme: releasescheme.html
APIGEN / source viewer
-------------------------------------
Deleted: /py/trunk/py/doc/api.txt
==============================================================================
--- /py/trunk/py/doc/api.txt Sun Feb 11 14:26:03 2007
+++ (empty file)
@@ -1,19 +0,0 @@
-The py lib API
-==============
-
-This is a placeholder for upcoming API documentation. We
-intend to mostly generate this API description from the py
-lib's entry points, their docstrings and cross-reference it
-with its tests and examples that are already available
-at our little `getting started`_ chapter.
-
-Your tests are your API insurance
-=================================
-
-Tests are the primary assurance of API compatilibity. If you
-would like to ensure some behaviour gets preserved across major
-releases you have to write a test. Note though, that the
-documentation may state additional restrictions which
-take precedence.
-
-.. _`getting started`: getting-started.html
Modified: py/trunk/py/doc/contact.txt
==============================================================================
--- py/trunk/py/doc/contact.txt (original)
+++ py/trunk/py/doc/contact.txt Sun Feb 11 14:26:03 2007
@@ -1,15 +1,81 @@
py lib contact and communication
===================================
-* `development mailing list`_ for conceptual and coding discussions (low to medium traffic).
+.. contents::
+.. sectnum::
-* `subversion commit mailing list`_ all updates to the trunk/branch source and documentation tree.
+IRC Channel #pylib on irc.freenode.net
+--------------------------------------------
-* `development bug/feature tracker`_ for filing bugs and feature requests.
+The #pylib channel on freenode displays all commits to the py lib
+and you are welcome to lurk or to ask questions there!
-* IRC Channel #pylib on irc.freenode.net
+`py-dev`_ developers mailing list
+-----------------------------------
-.. _`subversion commit mailing list`: http://codespeak.net/mailman/listinfo/py-svn
-.. _`development mailing list`: http://codespeak.net/mailman/listinfo/py-dev
+If you see bugs and/or can provide patches, please
+subscribe to the `py-dev developers list`_.
+As of Febrary 2007 it has medium to low traffic.
+
+
+`py-svn`_ commit mailing list
+-----------------------------------
+
+If you'd like to see ongoing development commits,
+please subscribe to:
+
+ `py-svn general commit mailing list`_
+
+This list (as of February 2007) has medium to high traffic.
+
+
+`development bug/feature tracker`_
+---------------------------------------------
+
+This (somewhat old) roundup instance still serves
+to file bugs and track issues. However, we also
+keep a list of "TODOs" in various directories.
+
+
+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 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
+.. _us: http://codespeak.net/mailman/listinfo/py-dev
+.. _codespeak: http://codespeak.net/
+.. _`py-dev`:
+.. _`development mailing list`:
+.. _`py-dev developers list`: http://codespeak.net/mailman/listinfo/py-dev
+.. _`subversion commit mailing list`:
+.. _`py-svn`:
+.. _`py-svn general commit mailing list`: http://codespeak.net/mailman/listinfo/py-svn
.. _`development bug/feature tracker`: https://codespeak.net/issue/py-dev/
Copied: py/trunk/py/doc/download.txt (from r38451, py/trunk/py/doc/getting-started.txt)
==============================================================================
--- py/trunk/py/doc/getting-started.txt (original)
+++ py/trunk/py/doc/download.txt Sun Feb 11 14:26:03 2007
@@ -1,31 +1,32 @@
-Getting started with the py lib
-===============================
+Download and Installation of the py lib
+===============================================
.. contents::
.. sectnum::
-Obtaining the current py lib
-============================
+Downloading a tar/zip file and installing it
+===================================================
-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 latest stable public release:
-.. _`the py lib`: index.html
+ `download py-0.9.0.tgz`_
+ `download py-0.9.0.zip`_
-getting it via subversion
--------------------------
+.. _`download py-0.9.0.tgz`: http://codespeak.net/download/py/py-0.9.0.tgz
+.. _`download py-0.9.0.zip`: http://codespeak.net/download/py/py-0.9.0.zip
-Checkout the py lib distribution tree with subversion, e.g. use::
+The py lib can be `globally installed via setup.py`_
+or `used locally`_.
- 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.
+Getting (and updating) via subversion
+--------------------------------------------
+
+Use Subversion to checkout the latest 0.9.x stable release:
+
+ svn co http://codespeak.net/svn/py/release/0.9.x py-0.9.x
+
+to obtain the complete code and documentation tree.
If you experience problems with the subversion checkout e.g.
because you have a http-proxy in between that doesn't proxy
@@ -33,14 +34,34 @@
of just "codespeak.net". Alternatively, you may tweak
your local subversion installation.
-setting it up
--------------
+If you want to follow stable snapshots
+then you may use the equivalent of this invocation:
+
+ svn co http://codespeak.net/svn/py/dist py-dist
+
+
+.. _`globally installed via setup.py`:
+
+Installation via setup.py
+------------------------------
+
+Go to your unpacked/checked out directory
+and issue:
+
+ python setup.py install
+
+
+.. _`used locally`:
+
+Local Installation/Usage
+------------------------------
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.
+your (unixish) system path, which lets you execute test files
+and directories.
-There already is a convenient way for Bash/Shell based systems
+There 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`
@@ -48,80 +69,45 @@
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-external scenario`:
- svn up
+The py lib as an svn external
+-------------------------------------------------------
-have fun and `get an account`_ :-)
+Add the py lib as an external to your project `DIRECTORY`
+which contains your svn-controlled root package::
+ svn propedit 'svn:externals' DIRECTORY
-Participating in development
-============================
+which will open an editor where you can add
+the following line:
-The py-dev and py-svn mailing lists
------------------------------------
+ py http://codespeak.net/svn/py/dist
-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:
+This will make your projcet automatically use the
+most recent stable snapshot of the py lib.
- `py-dev developers list`_
+Alternatively you may use this url for
+integrating the development version:
-and our
+ http://codespeak.net/svn/py/trunk
- `py-svn general commit mailing list`_
+or the next one for following the e.g. the 0.9 release branch
-Coding and communication
-------------------------
+ http://codespeak.net/svn/py/release/py-0.9.x
-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.
+py subversion directory structure
+=================================
-.. _`zope3`: http://zope3.zwiki.org/
-.. _twisted: http://www.twistedmatrix.org
-.. _future: future/future.html
+The directory release layout of the repository is
+going to follow this scheme::
-.. _`get an account`:
+ http://codespeak.net/
+ svn/py/dist # latest stable (may or may not be a release)
+ svn/py/release/X.Y.Z # release tags and branches
+ svn/py/trunk # head development / merge point
-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
Modified: py/trunk/py/doc/execnet.txt
==============================================================================
--- py/trunk/py/doc/execnet.txt (original)
+++ py/trunk/py/doc/execnet.txt Sun Feb 11 14:26:03 2007
@@ -218,8 +218,6 @@
gw = py.execnet.SocketGateway('localhost', cls.port)
print "initialized socket gateway to port", cls.port
-.. _`py API`: api.html
-
.. [#] There is an interesting emerging `Jail`_ linux technology
as well as a host of others, of course.
Modified: py/trunk/py/doc/future/future.txt
==============================================================================
--- py/trunk/py/doc/future/future.txt (original)
+++ py/trunk/py/doc/future/future.txt Sun Feb 11 14:26:03 2007
@@ -327,7 +327,6 @@
.. _`CPython's distutils`: http://www.python.org/dev/doc/devel/lib/module-distutils.html
-.. _`getting started`: ../getting-started.html
.. _`restructured text`: http://docutils.sourceforge.net/docs/user/rst/quickref.html
.. _`python standard library`: http://www.python.org/doc/2.3.4/lib/lib.html
.. _`xpython EuroPython 2004 talk`: http://codespeak.net/svn/user/hpk/talks/xpython-talk.txt
Deleted: /py/trunk/py/doc/getting-started.txt
==============================================================================
--- /py/trunk/py/doc/getting-started.txt Sun Feb 11 14:26:03 2007
+++ (empty file)
@@ -1,127 +0,0 @@
-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
Modified: py/trunk/py/doc/index.txt
==============================================================================
--- py/trunk/py/doc/index.txt (original)
+++ py/trunk/py/doc/index.txt Sun Feb 11 14:26:03 2007
@@ -1,13 +1,25 @@
-py.test and the py lib - documentation
-----------------------------------------
+py lib documentation
+=================================================
+
+`Download and Installation`_
+
+Main tools and API
+----------------------
`py.test`_ introduces to the **py.test** testing utility
-`py.execnet`_ an innovative way to distribute programs across the net (not stable on win32 yet)
+`py.execnet`_ distribute programs across the net
+
+`py.magic.greenlet`_: micro-threads (lightweight in-process concurrent programming)
-`py.magic.greenlet`_: Lightweight in-process concurrent programming (aka Stackless)
+`py.path`_: local and subversion Path and Filesystem access
+
+`py lib scripts`_ describe the scripts contained in the ``py/bin`` directory.
-`py.path`_: Path and Filesystem access and manipulation for local and svn based trees
+`apigen`_: a new way to generate rich Python API documentation
+
+support functionality
+---------------------------------
`py.code`_: High-level access/manipulation of Python code and traceback objects.
@@ -17,23 +29,20 @@
`py.log`_ an alpha document about the ad-hoc logging facilities
-`py lib scripts`_ describe the scripts contained in the ``py/bin`` directory.
+`miscellaneous features`_ describes some small but nice py lib features
-`miscellaneous features`_ describes some more py lib features
+Background and Motivation information
+-------------------------------------------
`future`_ handles development visions and plans for the near future.
`why what how py?`_, describing motivation and background of the py lib
-Note that some parts of these texts refer to future development and
-do not reflect the current state. **Welcome to documentation and
-test driven development** :-)
-
-
-.. _`getting started`: getting-started.html
+.. _`download and installation`: download.txt
.. _`py-dev at codespeak net`: http://codespeak.net/mailman/listinfo/py-dev
.. _`py.execnet`: execnet.html
.. _`py.magic.greenlet`: greenlet.html
+.. _`apigen`: apigen.html
.. _`py.log`: log.html
.. _`py.io`: io.html
.. _`py.path`: path.html
@@ -43,6 +52,5 @@
.. _`py.xml`: xml.html
.. _`Why What how py?`: why_py.html
.. _`future`: future/future.html
-.. _`getting started`: getting-started.html
.. _`miscellaneous features`: misc.html
Deleted: /py/trunk/py/doc/releasescheme.txt
==============================================================================
--- /py/trunk/py/doc/releasescheme.txt Sun Feb 11 14:26:03 2007
+++ (empty file)
@@ -1,113 +0,0 @@
-
-py subversion directory structure
-=================================
-
-The directory release layout of the repository is
-going to follow this scheme::
-
- svn/py/dist # latest stable code base (may or may not be a release)
- svn/py/release/X.Y.Z # tagged releases
- svn/py/branch/X.Y # contains release branch development
- svn/py/trunk # head development
-
-Scenario "no svn and just let me play, please"
-==============================================
-
-If you don't have a subversion client you can download
-specific versions by going to
-
- http://codespeak.net/download/py
-
-and pick a suitable archive file. You need to
-unpack it and may want to run `setup.py` to install
-it in a system-wide manner.
-
-Installation Scenario "svn + stay close to released versions"
--------------------------------------------------------------
-
-If you have a subversion client (you can easily install
-one, look at PyPy's `svn help document`_) it is recommended that you choose the following
-method to install, irrespective if you want to install
-things via distutils. Start by issueing the following
-shell command (or a graphical equivalent)::
-
- svn co http://codespeak.net/svn/py/dist py-dist
-
-Now we want to make sure that the `py-dist/py/bin` directory
-gets on your shell search path in order to have "py.test"
-directly available. You basically have two choices:
-
-1) include in your local shell environment startup the equivalent
- of ``eval `python .../py-dist/py/env.py```.
- XXX describe this in more detail (rip out from `getting started`_).
-
-2) go to the `py-dist` directory and run `python setup.py install`.
-
-.. _`getting started`: getting-started.html
-.. _`svn help document`: http://codespeak.net/pypy/index.cgi?doc/getting_started.html#subversion
-
-If you later want to upgrade your version of the py lib
-to the newest release you simply issue::
-
- svn up
-
-or to switch to the development trunk via::
-
- svn switch http://codespeak.net/svn/py/trunk
-
-or to a specific version via::
-
- svn switch http://codespeak.net/svn/py/tag/py-X.Y.Z
-
-or to a specific release branch::
-
- svn switch http://codespeak.net/svn/py/branch/py-X.Y
-
-If you choose the option No. 2) above you have to repeat
-the distutils install after each checkout/switch.
-
-.. _`svn-external scenario`:
-
-
-Installation Scenario "svn + include py lib as an external"
-===========================================================
-
-OK, so you want to have the py lib supporting your
-application and are using subversion? Great because
-things are quite easy and flexible for this scenario.
-
-Tying the py lib into your subversion controled project
--------------------------------------------------------
-
-On the `DIRECTORY` which contains your root package issue::
-
- svn pe 'svn:externals' DIRECTORY
-
-and add the following line to your (possibly empty) list
-of svn-externals::
-
- py http://codespeak.net/svn/py/dist
-
-This will make your projcet follow the most recent
-release of the py lib. (please substitute `dist` for `trunk`
-if you want to follow py lib development, this will let
-you catch interaction problems early on ...).
-If you now issue an `svn up` on your `DIRECTORY` you
-will retrieve the external into your application.
-
-If you want to follow a minor release branch seamlessly
-then use the following line::
-
- py http://codespeak.net/svn/py/branch/py-X.Y
-
-where `X.Y` indicate the branch you want to follow.
-
-If you want to use a very fixed version of the py lib
-you can tie to a specific release::
-
- py http://codespeak.net/svn/py/tag/py-X.Y.Z
-
-Integrating the py lib into your distribution
-----------------------------------------------
-
-XXX
Modified: py/trunk/py/doc/test.txt
==============================================================================
--- py/trunk/py/doc/test.txt (original)
+++ py/trunk/py/doc/test.txt Sun Feb 11 14:26:03 2007
@@ -14,11 +14,12 @@
starting point: ``py.test`` command line tool
=============================================
-First, see `getting started`_ for how to install the 'py.test' tool
-on your system.
+We presume you have done an installation as per the
+download_ page after which you should be able to execute the
+'py.test' tool from a command line shell.
``py.test`` is the command line tool to run tests. You can supply it
-with any Python module by passing it as an argument::
+with a Python test file (or directory) by passing it as an argument::
py.test test_sample.py
@@ -32,11 +33,9 @@
def test_answer():
assert 42 == 43
-As you can see, you can have test functions as well as test
-methods. This in contrast to the Python standard library's
-``unittest.py``.
-
-You can use ``py.test`` to run all tests in a directory structure by
+You may have test functions and test methods, there is no
+need to subclass or to put tests into a class.
+You can also use ``py.test`` to run all tests in a directory structure by
invoking it without any arguments::
py.test
@@ -46,9 +45,7 @@
subdirectories, starting with the current directory, and run them. Each
Python test module is inspected for test methods starting with ``test_``.
-.. _`getting started`: getting-started.html
-
-
+.. _download: download.html
.. _features:
Basic Features of ``py.test``
Modified: py/trunk/py/doc/why_py.txt
==============================================================================
--- py/trunk/py/doc/why_py.txt (original)
+++ py/trunk/py/doc/why_py.txt Sun Feb 11 14:26:03 2007
@@ -127,7 +127,7 @@
completly change the implementation but the public API
tests will continue to run.
-- No **tested feature** of the exported `py API`_ is to vanish
+- No **tested feature** of the exported py API is to vanish
across minor releases until it is marked deprecated.
For example, pure API tests of a future version 1.0 are to
@@ -269,7 +269,6 @@
.. _`envisioned import/export system`: future/future.html#importexport
.. _future: future/future.html
.. _`py.test tool and library`: test.html
-.. _`py API`: api.html
.. _`great work that Fred L. Drake, Jr. is doing`: http://www.python.org/doc/2.3.4/lib/lib.html
--
More information about the pytest-commit
mailing list