150 lines
5.1 KiB
Plaintext
150 lines
5.1 KiB
Plaintext
====================================
|
|
Miscellaneous features of the py lib
|
|
====================================
|
|
|
|
|
|
Mapping the standard python library into py
|
|
===========================================
|
|
|
|
The :api:`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::
|
|
|
|
py.std.traceback.print_exc()
|
|
|
|
without having to do anything else than the usual ``import py``
|
|
at the beginning. You can access any other top-level standard
|
|
library module this way. This means that you will only trigger
|
|
imports of modules that are actually needed. Note that no attempt
|
|
is made to import submodules.
|
|
|
|
Support for interaction with system utilities/binaries
|
|
======================================================
|
|
|
|
Currently, the py lib offers two ways to interact with
|
|
system executables. :api:`py.process.cmdexec()` invokes
|
|
the shell in order to execute a string. The other
|
|
one, :api:`py.path.local`'s 'sysexec()' method lets you
|
|
directly execute a binary.
|
|
|
|
Both approaches will raise an exception in case of a return-
|
|
code other than 0 and otherwise return the stdout-output
|
|
of the child process.
|
|
|
|
The shell based approach
|
|
------------------------
|
|
|
|
You can execute a command via your system shell
|
|
by doing something like::
|
|
|
|
out = py.process.cmdexec('ls -v')
|
|
|
|
However, the ``cmdexec`` approach has a few shortcomings:
|
|
|
|
- it relies on the underlying system shell
|
|
- it neccessitates shell-escaping for expressing arguments
|
|
- it does not easily allow to "fix" the binary you want to run.
|
|
- it only allows to execute executables from the local
|
|
filesystem
|
|
|
|
.. _sysexec:
|
|
|
|
local paths have ``sysexec``
|
|
----------------------------
|
|
|
|
The py lib currently offers a stripped down functionality of what
|
|
the new `PEP-324 subprocess module`_ offers. The main functionality
|
|
of synchronously executing a system executable has a straightforward API::
|
|
|
|
binsvn.sysexec('ls', 'http://codespeak.net/svn')
|
|
|
|
where ``binsvn`` is a path that points to the ``svn`` commandline
|
|
binary. Note that this function would not offer any shell-escaping
|
|
so you really have to pass in separated arguments. This idea
|
|
fits nicely into `a more general view on path objects`_.
|
|
|
|
For a first go, we are just reusing the existing `subprocess
|
|
implementation`_ but don't expose any of its API apart
|
|
from the above ``sysexec()`` method.
|
|
|
|
Note, however, that currently the support for the ``sysexec`` interface on
|
|
win32 is not thoroughly tested. If you run into problems with it, we are
|
|
interested to hear about them. If you are running a Python older than 2.4 you
|
|
will have to install the `pywin32 package`_.
|
|
|
|
|
|
.. _`future book`: future.html
|
|
.. _`PEP-324 subprocess module`: http://www.python.org/peps/pep-0324.html
|
|
.. _`subprocess implementation`: http://www.lysator.liu.se/~astrand/popen5/
|
|
.. _`a more general view on path objects`: future.html#general-path
|
|
.. _`pywin32 package`: http://pywin32.sourceforge.net/
|
|
|
|
finding an executable local path
|
|
--------------------------------
|
|
|
|
Finding an executable is quite different on multiple platforms.
|
|
Currently, the ``PATH`` environment variable based search on
|
|
unix platforms is supported::
|
|
|
|
py.path.local.sysfind('svn')
|
|
|
|
which returns the first path whose ``basename`` matches ``svn``.
|
|
In principle, `sysfind` deploys platform specific algorithms
|
|
to perform the search. On Windows, for example, it may look
|
|
at the registry (XXX).
|
|
|
|
To make the story complete, we allow to pass in a second ``checker``
|
|
argument that is called for each found executable. For example, if
|
|
you have multiple binaries available you may want to select the
|
|
right version::
|
|
|
|
def mysvn(p):
|
|
""" check that the given svn binary has version 1.1. """
|
|
line = p.execute('--version'').readlines()[0]
|
|
if line.find('version 1.1'):
|
|
return p
|
|
binsvn = py.path.local.sysfind('svn', checker=mysvn)
|
|
|
|
|
|
|
|
Cross-Python Version compatibility helpers
|
|
=============================================
|
|
|
|
sources:
|
|
|
|
* :source:`py/compat/`
|
|
* :source:`py/builtin/`
|
|
|
|
The compat and builtin namespaces help to write code using newer python features on older python interpreters.
|
|
|
|
:api:`py.compat`
|
|
----------------
|
|
|
|
:api:`py.compat` provides fixed versions (currently taken from Python 2.4.4) of
|
|
a few selected modules to be able to use them across python versions. Currently these are:
|
|
|
|
* doctest
|
|
* optparse
|
|
* subprocess
|
|
* textwrap
|
|
|
|
Note that for example ``import doctest`` and ``from py.compat import doctest`` result
|
|
into two different module objects no matter what Python version you are using.
|
|
So you should only use exactly one of these to avoid confusion in your program.
|
|
|
|
: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.
|