From e584892c12341ce84716a08174b541928ba66d7e Mon Sep 17 00:00:00 2001 From: holger krekel Date: Mon, 2 Nov 2009 13:00:48 +0100 Subject: [PATCH] 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 --- .hgignore | 1 + bin-for-dist/makepluginlist.py | 2 +- doc/code.txt | 37 ++++++++++-------------- doc/confrest.py | 2 +- doc/download.html | 18 ++++++++++++ doc/faq.txt | 26 +++++++++++++++++ doc/{download.txt => install.txt} | 47 ++++++++++++++++++------------- doc/io.txt | 12 ++++---- doc/misc.txt | 29 +++---------------- doc/path.txt | 26 ++++++++--------- doc/test/plugin/links.txt | 2 +- doc/test/quickstart.txt | 10 ++----- 12 files changed, 116 insertions(+), 96 deletions(-) create mode 100644 doc/download.html rename doc/{download.txt => install.txt} (69%) diff --git a/.hgignore b/.hgignore index 68736d817..237e3feac 100644 --- a/.hgignore +++ b/.hgignore @@ -17,3 +17,4 @@ syntax:glob build/ dist/ py.egg-info +issue/ diff --git a/bin-for-dist/makepluginlist.py b/bin-for-dist/makepluginlist.py index e4d6bb779..0920a0641 100644 --- a/bin-for-dist/makepluginlist.py +++ b/bin-for-dist/makepluginlist.py @@ -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") diff --git a/doc/code.txt b/doc/code.txt index 3af24ed53..61c3e5593 100644 --- a/doc/code.txt +++ b/doc/code.txt @@ -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() diff --git a/doc/confrest.py b/doc/confrest.py index 4e558c062..6fae19128 100644 --- a/doc/confrest.py +++ b/doc/confrest.py @@ -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"), diff --git a/doc/download.html b/doc/download.html new file mode 100644 index 000000000..5f4c46640 --- /dev/null +++ b/doc/download.html @@ -0,0 +1,18 @@ + + + + + + + + + + + diff --git a/doc/faq.txt b/doc/faq.txt index 0bf9dd9b2..0dc878ce3 100644 --- a/doc/faq.txt +++ b/doc/faq.txt @@ -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 + + diff --git a/doc/download.txt b/doc/install.txt similarity index 69% rename from doc/download.txt rename to doc/install.txt index 9ef4abc85..8795c332d 100644 --- a/doc/download.txt +++ b/doc/install.txt @@ -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 diff --git a/doc/io.txt b/doc/io.txt index 3d0bf0a98..6fd686b2d 100644 --- a/doc/io.txt +++ b/doc/io.txt @@ -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 diff --git a/doc/misc.txt b/doc/misc.txt index 7d122bec5..22a35964b 100644 --- a/doc/misc.txt +++ b/doc/misc.txt @@ -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. diff --git a/doc/path.txt b/doc/path.txt index 8b82aaab7..836317e46 100644 --- a/doc/path.txt +++ b/doc/path.txt @@ -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 diff --git a/doc/test/plugin/links.txt b/doc/test/plugin/links.txt index f50095f1b..a4bb73a5f 100644 --- a/doc/test/plugin/links.txt +++ b/doc/test/plugin/links.txt @@ -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 diff --git a/doc/test/quickstart.txt b/doc/test/quickstart.txt index 6ef4f4572..ab35fa02d 100644 --- a/doc/test/quickstart.txt +++ b/doc/test/quickstart.txt @@ -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