jiuyuan
/
test_ok1
2
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

update and fix docs for installation 

- rework installation
- add a new FAQ entry related to issue58 Windows/setuptools/multiprocess
- strike api/source references

--HG--
branch : trunk
This commit is contained in:
holger krekel 2009-11-02 13:00:48 +01:00
parent 6a82cdb37f
commit e584892c12
12 changed files with 116 additions and 96 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
.hgignore
View File

@ -17,3 +17,4 @@ syntax:glob
build/
dist/
py.egg-info
issue/

2
bin-for-dist/makepluginlist.py
View File

@ -217,7 +217,7 @@ class PluginDoc(RestWriter):
self.links.append(('plugins', 'index.html'))
self.links.append(('get in contact', '../../contact.html'))
self.links.append(('checkout the py.test development version',
'../../download.html#checkout'))
'../../install.html#checkout'))
if 0: # this breaks the page layout and makes large doc files
#self.h2("plugin source code")

37
doc/code.txt
View File

@ -2,35 +2,33 @@
py.code: higher level python code and introspection objects
================================================================================
The :api:`py.code` part of the pylib contains some functionality to help
The ``py.code`` part of the pylib contains some functionality to help
dealing with Python code objects. Even though working with Python's internal
code objects (as found on frames and callables) can be very powerful, it's
usually also quite cumbersome, because the API provided by core Python is
relatively low level and not very accessible.
The :api:`py.code` library tries to simplify accessing the code objects as well
The ``py.code`` library tries to simplify accessing the code objects as well
as creating them. There is a small set of interfaces a user needs to deal with,
all nicely bundled together, and with a rich set of 'Pythonic' functionality.
source: :source:`py/code/`
Contents of the library
=======================
Every object in the :api:`py.code` library wraps a code Python object related
to code objects, source code, frames and tracebacks: the :api:`py.code.Code`
class wraps code objects, :api:`py.code.Source` source snippets,
:api:`py.code.Traceback` exception tracebacks, :api:`py.code.Frame` frame
objects (as found in e.g. tracebacks) and :api:`py.code.ExceptionInfo` the
Every object in the ``py.code`` library wraps a code Python object related
to code objects, source code, frames and tracebacks: the ``py.code.Code``
class wraps code objects, ``py.code.Source`` source snippets,
``py.code.Traceback` exception tracebacks, :api:`py.code.Frame`` frame
objects (as found in e.g. tracebacks) and ``py.code.ExceptionInfo`` the
tuple provided by sys.exc_info() (containing exception and traceback
information when an exception occurs). Also in the library is a helper function
:api:`py.code.compile()` that provides the same functionality as Python's
``py.code.compile()`` that provides the same functionality as Python's
built-in 'compile()' function, but returns a wrapped code object.
The wrappers
============
:api:`py.code.Code`
``py.code.Code``
-------------------
Code objects are instantiated with a code object or a callable as argument,
@ -48,9 +46,7 @@ A quick example::
>>> str(c.source()).split('\n')[0]
"def read(self, mode='r'):"
source: :source:`py/code/code.py`
:api:`py.code.Source`
``py.code.Source``
---------------------
Source objects wrap snippets of Python source code, providing a simple yet
@ -71,9 +67,8 @@ Example::
>>> str(sub).strip() # XXX why is the strip() required?!?
'print "foo"'
source: :source:`py/code/source.py`
:api:`py.code.Traceback`
``py.code.Traceback``
------------------------
Tracebacks are usually not very easy to examine, you need to access certain
@ -97,15 +92,13 @@ Example::
>>> str(first.statement).strip().startswith('raise ValueError')
True
source: :source:`py/code/code.py`
:api:`py.code.Frame`
``py.code.Frame``
--------------------
Frame wrappers are used in :api:`py.code.Traceback` items, and will usually not
Frame wrappers are used in ``py.code.Traceback`` items, and will usually not
directly be instantiated. They provide some nice methods to evaluate code
'inside' the frame (using the frame's local variables), get to the underlying
code (frames have a code attribute that points to a :api:`py.code.Code` object)
code (frames have a code attribute that points to a ``py.code.Code`` object)
and examine the arguments.
Example (using the 'first' TracebackItem instance created above)::
@ -118,7 +111,7 @@ Example (using the 'first' TracebackItem instance created above)::
>>> [namevalue[0] for namevalue in frame.getargs()]
['cls', 'path']
:api:`py.code.ExceptionInfo`
``py.code.ExceptionInfo``
----------------------------
A wrapper around the tuple returned by sys.exc_info() (will call sys.exc_info()

2
doc/confrest.py
View File

@ -57,7 +57,7 @@ pageTracker._trackPageview();
def fill_menubar(self):
items = [
self.a_docref("install", "download.html"),
self.a_docref("install", "install.html"),
self.a_docref("contact", "contact.html"),
self.a_docref("changelog", "changelog.html"),
self.a_docref("faq", "faq.html"),

18
doc/download.html Normal file
View File

@ -0,0 +1,18 @@
<html>
<head>
<meta http-equiv="refresh" content=" 1 ; URL=install.html" />
</head>
<body>
<script type="text/javascript">
var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");
document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
</script>
<script type="text/javascript">
try {
var pageTracker = _gat._getTracker("UA-7597274-3");
pageTracker._trackPageview();
} catch(err) {}</script>
</body>
</html>

26
doc/faq.txt
View File

@ -120,3 +120,29 @@ and implement the `parametrization scheme of your choice`_.
.. _`pytest_generate_tests`: test/funcargs.html#parametrizing-tests
.. _`parametrization scheme of your choice`: http://tetamap.wordpress.com/2009/05/13/parametrizing-python-tests-generalized/
py.test interaction with other packages
===============================================
What's up with multiprocess on Windows?
------------------------------------------------------------
On windows the multiprocess package will instantiate sub processes
by pickling and thus implicitely re-import a lot of local modules.
Unfortuantely, setuptools-0.6.11 does not ``if __name__=='__main__'``
protect its generated command line script. This leads to infinite
recursion when running a test that instantiates Processes.
There are two workarounds:
* `install Distribute`_ as a drop-in replacement for setuptools
and re-install py.test
* `directly use a checkout`_ which avoids all setuptools/Distribute
installation
.. _`directly use a checkout`: install.html#directly-use-a-checkout
.. _`install distribute`: http://pypi.python.org/pypi/distribute#installation-instructions

47
doc/download.txt → doc/install.txt
View File

@ -7,23 +7,29 @@
Latest Release, see `PyPI project page`_
using easy_install
using easy_install (via Distribute or setuptools)
===================================================
With a working `setuptools installation`_ or `distribute installation`_
It is recommended to use `Distribute for installation`_ as a drop-in
replacement for setuptools_. While setuptools should work well on
Python2 versions, `Distribute`_ allows to install py.test on Python3
and it avoids issue on Windows. With either packaging system
you can type::
easy_install -U py
to get the latest release of the py lib. The ``-U`` switch
to get the latest release of the py lib and py.test. The ``-U`` switch
will trigger an upgrade if you already have an older version installed.
On Linux systems you may need to execute the command as superuser and
on Windows you might need to write down the full path to ``easy_install``.
The py lib and its tools are expected to work well on Linux,
Windows and OSX, Python versions 2.4, 2.5, 2.6 through to
the Python3 versions 3.0 and 3.1.
the Python3 versions 3.0 and 3.1. Jython
.. _mercurial: http://mercurial.selenic.com/wiki/
.. _`Distribute`:
.. _`Distribute for installation`: http://pypi.python.org/pypi/distribute#installation-instructions
.. _`distribute installation`: http://pypi.python.org/pypi/distribute
.. _checkout:
.. _tarball:
@ -39,20 +45,22 @@ and documentation source with mercurial_::
This currrently contains a 1.0.x branch and the
default 'trunk' branch where mainline development
takes place. There also is a readonly subversion
checkout available::
takes place.
svn co https://codespeak.net/svn/py/dist
.. There also is a readonly subversion
checkout available which contains the latest release::
svn co https://codespeak.net/svn/py/dist
You can also go to the python package index and
You can go to the python package index and
download and unpack a TAR file::
http://pypi.python.org/pypi/py/
activating checkout with setuptools
activating a checkout with setuptools
--------------------------------------------
With a working `setuptools installation`_ you can issue::
With a working `Distribute`_ or setuptools_ installation you can type::
python setup.py develop
@ -60,14 +68,13 @@ in order to work with the tools and the lib of your checkout.
.. _`no-setuptools`:
activating a checkout or tarball without setuptools
.. _`directly use a checkout`:
directly use a checkout or tarball
-------------------------------------------------------------
To import the py lib the ``py`` package directory needs to
be on the ``$PYTHONPATH``. If you exexute scripts directly
from ``py/bin/`` or ``py\bin\win32`` they will find their
containing py lib automatically.
Once you got yourself a checkout_ or tarball_ you only need to
set ``PYTHONPATH`` and ``PATH`` environment variables.
It is usually a good idea to add the parent directory of the ``py`` package
directory to your ``PYTHONPATH`` and ``py/bin`` or ``py\bin\win32`` to your
system wide ``PATH`` settings. There are helper scripts that set ``PYTHONPATH`` and ``PATH`` on your system:
@ -75,12 +82,12 @@ system wide ``PATH`` settings. There are helper scripts that set ``PYTHONPATH``
on windows execute::
# inside autoexec.bat or shell startup
c:\\path\to\checkout\py\bin\env.cmd
c:\\path\to\checkout\bin\env.cmd
on linux/OSX add this to your shell initialization::
# inside .bashrc
eval `python ~/path/to/checkout/py/bin/env.py`
eval `python ~/path/to/checkout/bin/env.py`
both of which which will get you good settings
for ``PYTHONPATH`` and ``PATH``.
@ -89,7 +96,7 @@ for ``PYTHONPATH`` and ``PATH``.
note: scripts look for "nearby" py-lib
-----------------------------------------------------
Note that the `command line scripts`_ will look
Note that all `command line scripts`_ will look
for "nearby" py libs, so if you have a layout like this::
mypkg/
@ -119,5 +126,5 @@ of questions or need for changes.
.. _`RPM`: http://translate.sourceforge.net/releases/testing/fedora/pylib-0.9.2-1.fc9.noarch.rpm
.. _`setuptools installation`: http://pypi.python.org/pypi/setuptools
.. _`setuptools`: http://pypi.python.org/pypi/setuptools

12
doc/io.txt
View File

@ -9,10 +9,10 @@ execution of a program.
IO Capturing examples
===============================================
:api:`py.io.StdCapture`
``py.io.StdCapture``
---------------------------
Basic Example:
Basic Example::
>>> import py
>>> capture = py.io.StdCapture()
@ -21,7 +21,7 @@ Basic Example:
>>> out.strip() == "hello"
True
For calling functions you may use a shortcut:
For calling functions you may use a shortcut::
>>> import py
>>> def f(): print "hello"
@ -29,14 +29,14 @@ For calling functions you may use a shortcut:
>>> out.strip() == "hello"
True
:api:`py.io.StdCaptureFD`
``py.io.StdCaptureFD``
---------------------------
If you also want to capture writes to the stdout/stderr
filedescriptors you may invoke:
filedescriptors you may invoke::
>>> import py, sys
>>> capture = py.io.StdCaptureFD()
>>> capture = py.io.StdCaptureFD(out=False, in_=False)
>>> sys.stderr.write("world")
>>> out,err = capture.reset()
>>> err

29
doc/misc.txt
View File

@ -5,7 +5,7 @@ Miscellaneous features of the py lib
Mapping the standard python library into py
===========================================
The :api:`py.std` object allows lazy access to
The ``py.std`` object allows lazy access to
standard library modules. For example, to get to the print-exception
functionality of the standard library you can write::
@ -21,9 +21,9 @@ Support for interaction with system utilities/binaries
======================================================
Currently, the py lib offers two ways to interact with
system executables. :api:`py.process.cmdexec()` invokes
system executables. ``py.process.cmdexec()`` invokes
the shell in order to execute a string. The other
one, :api:`py.path.local`'s 'sysexec()' method lets you
one, ``py.path.local``'s 'sysexec()' method lets you
directly execute a binary.
Both approaches will raise an exception in case of a return-
@ -87,28 +87,7 @@ right version::
binsvn = py.path.local.sysfind('svn', checker=mysvn)
Cross-Python Version compatibility helpers
=============================================
sources:
* :source:`py/builtin/`
The compat and builtin namespaces help to write code using newer python features on older python interpreters.
:api:`py.builtin`
-----------------
:api:`py.builtin` provides builtin functions/types that were added in later Python
versions. If the used Python version used does not provide these builtins the
py lib provides some reimplementations. These currently are:
* enumerate
* reversed
* sorted
* BaseException
* set and frozenset (using either the builtin, if available, or the sets
module)
:api:`py.builtin.BaseException` is just ``Exception`` before Python 2.5.
The ``py.builtin`` namespace provides a number of helpers that help to write python code compatible across Python interpreters, mainly Python2 and Python3. Type ``help(py.builtin)`` on a Python prompt for a the selection of builtins.

26
doc/path.txt
View File

@ -3,17 +3,17 @@ py.path
=======
The 'py' lib provides a uniform high-level api to deal with filesystems
and filesystem-like interfaces: :api:`py.path`. It aims to offer a central
and filesystem-like interfaces: ``py.path``. It aims to offer a central
object to fs-like object trees (reading from and writing to files, adding
files/directories, examining the types and structure, etc.), and out-of-the-box
provides a number of implementations of this API.
Path implementations provided by :api:`py.path`
Path implementations provided by ``py.path``
===============================================
.. _`local`:
:api:`py.path.local`
``py.path.local``
--------------------
The first and most obvious of the implementations is a wrapper around a local
@ -21,8 +21,8 @@ filesystem. It's just a bit nicer in usage than the regular Python APIs, and
of course all the functionality is bundled together rather than spread over a
number of modules.
Example usage, here we use the :api:`py.test.ensuretemp()` function to create
a :api:`py.path.local` object for us (which wraps a directory):
Example usage, here we use the ``py.test.ensuretemp()`` function to create
a ``py.path.local`` object for us (which wraps a directory):
.. sourcecode:: pycon
@ -40,17 +40,17 @@ a :api:`py.path.local` object for us (which wraps a directory):
>>> foofile.read(1)
'b'
:api:`py.path.svnurl` and :api:`py.path.svnwc`
``py.path.svnurl` and :api:`py.path.svnwc``
----------------------------------------------
Two other :api:`py.path` implementations that the py lib provides wrap the
Two other ``py.path`` implementations that the py lib provides wrap the
popular `Subversion`_ revision control system: the first (called 'svnurl')
by interfacing with a remote server, the second by wrapping a local checkout.
Both allow you to access relatively advanced features such as metadata and
versioning, and both in a way more user-friendly manner than existing other
solutions.
Some example usage of :api:`py.path.svnurl`:
Some example usage of ``py.path.svnurl``:
.. sourcecode:: pycon
@ -65,7 +65,7 @@ Some example usage of :api:`py.path.svnurl`:
>>> time.strftime('%Y-%m-%d', time.gmtime(firstentry.date))
'2004-10-02'
Example usage of :api:`py.path.svnwc`:
Example usage of ``py.path.svnwc``:
.. sourcecode:: pycon
@ -125,7 +125,7 @@ specific directory.
Working with Paths
.......................
This example shows the :api:`py.path` features to deal with
This example shows the ``py.path`` features to deal with
filesystem paths Note that the filesystem is never touched,
all operations are performed on a string level (so the paths
don't have to exist, either):
@ -154,7 +154,7 @@ don't have to exist, either):
>>> p4.purebasename == "bar"
True
This should be possible on every implementation of :api:`py.path`, so
This should be possible on every implementation of ``py.path``, so
regardless of whether the implementation wraps a UNIX filesystem, a Windows
one, or a database or object tree, these functions should be available (each
with their own notion of path seperators and dealing with conversions, etc.).
@ -189,7 +189,7 @@ Setting svn-properties
.......................
As an example of 'uncommon' methods, we'll show how to read and write
properties in an :api:`py.path.svnwc` instance:
properties in an ``py.path.svnwc`` instance:
.. sourcecode:: pycon
@ -254,7 +254,7 @@ to provide this choice (and getting rid
of platform-dependencies as much as possible).
There is some experimental small approach
(:source:`py/path/gateway/`) aiming at having
(``py/path/gateway/``) aiming at having
a convenient Remote Path implementation.
There are various hacks out there to have

2
doc/test/plugin/links.txt
View File

@ -16,7 +16,7 @@
.. _`pytest_figleaf.py`: http://bitbucket.org/hpk42/py-trunk/raw/trunk/_py/test/plugin/pytest_figleaf.py
.. _`pytest_hooklog.py`: http://bitbucket.org/hpk42/py-trunk/raw/trunk/_py/test/plugin/pytest_hooklog.py
.. _`pytest_skipping.py`: http://bitbucket.org/hpk42/py-trunk/raw/trunk/_py/test/plugin/pytest_skipping.py
.. _`checkout the py.test development version`: ../../download.html#checkout
.. _`checkout the py.test development version`: ../../install.html#checkout
.. _`pytest_helpconfig.py`: http://bitbucket.org/hpk42/py-trunk/raw/trunk/_py/test/plugin/pytest_helpconfig.py
.. _`oejskit`: oejskit.html
.. _`doctest`: doctest.html

10
doc/test/quickstart.txt
View File

@ -5,16 +5,12 @@
Quickstart
==================
.. _here: ../download.html#no-setuptools
.. _here: ../install.html
With a `setuptools installation`_ (otherwise see here_) you can type::
If you have a version of ``easy_install`` (otherwise see here_) just type::
easy_install -U py
On Linux systems you may need to execute this as the superuser and
on Windows you might need to write down the full path to ``easy_install``.
Now create a file ``test_sample.py`` with the following content:
.. sourcecode:: python
@ -63,7 +59,7 @@ a progress report and important details of the failure.
.. _`contact`: ../contact.html
.. _`automatically collected`: features.html#autocollect
.. _download: ../download.html
.. _install: ../install.html
.. _features: features.html
.. _tutorials: talks.html