PEX API Reference¶
Module contents¶
pex.crawler module¶
Support for webpage parsing and crawling.
-
class
pex.crawler.
Crawler
(context=None, threads=1)[source]¶ Bases:
object
A multi-threaded crawler that supports local (disk) and remote (web) crawling.
pex.environment module¶
pex.fetcher module¶
pex.finders module¶
The finders we wish we had in setuptools.
As of setuptools 3.3, the only finder for zip-based distributions is for eggs. The path-based finder only searches paths ending in .egg and not in .whl (zipped or unzipped.)
pex.finders augments pkg_resources with additional finders to achieve functional parity between wheels and eggs in terms of findability with find_distributions.
- To use:
>>> from pex.finders import register_finders >>> register_finders()
-
class
pex.finders.
ChainedFinder
(finders)[source]¶ Bases:
object
A utility to chain together multiple pkg_resources finders.
-
class
pex.finders.
FixedEggMetadata
(importer)[source]¶ Bases:
pkg_resources.EggMetadata
An EggMetadata provider that has functional parity with the disk-based provider.
-
class
pex.finders.
WheelMetadata
(importer)[source]¶ Bases:
pkg_resources.EggMetadata
Metadata provider for zipped wheels.
pex.http module¶
-
class
pex.http.
CachedRequestsContext
(cache=None, **kw)[source]¶ Bases:
pex.http.RequestsContext
A requests-based Context with CacheControl support.
-
class
pex.http.
Context
[source]¶ Bases:
abc.AbstractClass
Encapsulate the networking necessary to do requirement resolution.
At a minimum, the Context must implement
open(link)
by returning a file-like object. Reference implementations ofread(link)
andfetch(link)
are provided based uponopen(link)
but may be further specialized by individual implementations.-
exception
Error
[source]¶ Bases:
exceptions.Exception
Error base class for Contexts to wrap application-specific exceptions.
-
Context.
content
(link)[source]¶ Return the encoded content associated with the link.
Parameters: link – The Link
to read.
-
Context.
fetch
(link, into=None)[source]¶ Fetch the binary content associated with the link and write to a file.
Parameters: - link – The
Link
to fetch. - into – If specified, write into the directory
into
. IfNone
, creates a new temporary directory that persists for the duration of the interpreter.
- link – The
-
Context.
open
(link)[source]¶ Return an open file-like object to the link.
Parameters: link – The Link
to open.
-
exception
-
class
pex.http.
RequestsContext
(session=None, verify=True, env=<pex.variables.Variables object>)[source]¶ Bases:
pex.http.Context
A requests-based Context.
-
class
pex.http.
StreamFilelike
(request, link, chunk_size=16384)[source]¶ Bases:
object
A file-like object wrapper around requests streams that performs hash validation.
-
class
pex.http.
UrllibContext
(*args, **kw)[source]¶ Bases:
pex.http.Context
Default Python standard library Context.
pex.installer module¶
pex.interpreter module¶
pex support for interacting with interpreters.
pex.iterator module¶
The glue between fetchers, crawlers and requirements.
pex.link module¶
-
class
pex.link.
Link
(url)[source]¶ Bases:
object
Wrapper around a URL.
-
filename
¶ The basename of this url.
-
fragment
¶ The url fragment following ‘#’ if any.
-
join
(href)[source]¶ Given a href relative to this link, return the
Link
of the absolute url.Parameters: href – A string-like path relative to this link.
-
local
¶ Is the url a local file?
-
path
¶ The full path of this url with any hostname and scheme components removed.
-
remote
¶ Is the url a remote file?
-
scheme
¶ The URI scheme used by this Link.
-
url
¶ The url string to which this link points.
-
pex.package module¶
-
pex.package.
EGG_NAME
()¶ match(string[, pos[, endpos]]) –> match object or None. Matches zero or more characters at the beginning of the string
-
class
pex.package.
EggPackage
(url, **kw)[source]¶ Bases:
pex.package.Package
A Package representing a built egg.
-
class
pex.package.
Package
(url)[source]¶ Bases:
pex.link.Link
Base class for named Python binary packages (e.g. source, egg, wheel).
-
compatible
(identity, platform='linux-x86_64')[source]¶ Is this link compatible with the given
PythonIdentity
identity and platform?Parameters: - identity (
PythonIdentity
) – The Python identity (e.g. CPython 2.7.5) against which compatibility should be checked. - platform (string or None) – The platform against which compatibility should be checked. If None, do not check platform compatibility.
- identity (
-
classmethod
from_href
(href, **kw)[source]¶ Convert from a url to Package.
Parameters: href (string) – The url to parse Returns: A Package object if a valid concrete implementation exists, otherwise None.
-
-
class
pex.package.
SourcePackage
(url, **kw)[source]¶ Bases:
pex.package.Package
A Package representing an uncompiled/unbuilt source distribution.
-
classmethod
split_fragment
(fragment)[source]¶ A heuristic used to split a string into version name/fragment:
>>> SourcePackage.split_fragment('pysolr-2.1.0-beta') ('pysolr', '2.1.0-beta') >>> SourcePackage.split_fragment('cElementTree-1.0.5-20051216') ('cElementTree', '1.0.5-20051216') >>> SourcePackage.split_fragment('pil-1.1.7b1-20090412') ('pil', '1.1.7b1-20090412') >>> SourcePackage.split_fragment('django-plugin-2-2.3') ('django-plugin-2', '2.3')
-
classmethod
-
class
pex.package.
WheelPackage
(url, **kw)[source]¶ Bases:
pex.package.Package
A Package representing a built wheel.
-
pex.package.
distribution_compatible
(dist, interpreter=None, platform=None)[source]¶ Is this distribution compatible with the given interpreter/platform combination?
Parameters: interpreter – The Python interpreter against which compatibility should be checked. If None specified, the current interpreter is used. :type identity:
PythonInterpreter
or None :param platform: The platform against which compatibility should be checked. If None, the current platform will be used :type platform: string or None :returns: True if the distribution is compatible, False if it is unrecognized or incompatible.
pex.pep425 module¶
PEP425 handling for pex
PEP425 (http://legacy.python.org/dev/peps/pep-0425/) describes a tagging system used to determine whether or not a distribution’s platform is compatible with the current platform. It is the tagging system used to describe platform compatibility for wheel files.
pex.pex module¶
-
class
pex.pex.
PEX
(pex='/home/docs/checkouts/readthedocs.org/user_builds/pex/envs/stable/bin/sphinx-build', interpreter=None, env=<pex.variables.Variables object>)[source]¶ Bases:
object
PEX, n. A self-contained python environment.
-
cmdline
(args=())[source]¶ The commandline to run this environment.
Parameters: args – Additional arguments to be passed to the application being invoked by the environment.
-
execute
()[source]¶ Execute the PEX.
This function makes assumptions that it is the last function called by the interpreter.
-
classmethod
minimum_sys
()[source]¶ Return the minimum sys necessary to run this interpreter, a la python -S.
Returns: (sys.path, sys.path_importer_cache, sys.modules) tuple of a bare python installation.
-
classmethod
minimum_sys_modules
(site_libs, modules=None)[source]¶ Given a set of site-packages paths, return a “clean” sys.modules.
When importing site, modules within sys.modules have their __path__’s populated with additional paths as defined by *-nspkg.pth in site-packages, or alternately by distribution metadata such as *.dist-info/namespace_packages.txt. This can possibly cause namespace packages to leak into imports despite being scrubbed from sys.path.
NOTE: This method mutates modules’ __path__ attributes in sys.module, so this is currently an irreversible operation.
-
classmethod
patch_pkg_resources
(*args, **kwds)[source]¶ Patch pkg_resources given a new working set.
-
run
(args=(), with_chroot=False, blocking=True, setsid=False, **kw)[source]¶ Run the PythonEnvironment in an interpreter in a subprocess.
Parameters: - args – Additional arguments to be passed to the application being invoked by the environment.
- with_chroot – Run with cwd set to the environment’s working directory.
- blocking – If true, return the return code of the subprocess. If false, return the Popen object of the invoked subprocess.
- setsid – If true, run the PEX in a separate operating system session.
Remaining keyword arguments are passed directly to subprocess.Popen.
-
pex.pex_builder module¶
-
class
pex.pex_builder.
PEXBuilder
(path=None, interpreter=None, chroot=None, pex_info=None, preamble=None, copy=False)[source]¶ Bases:
object
Helper for building PEX environments.
-
add_dist_location
(dist, name=None)[source]¶ Add a distribution by its location on disk.
Parameters: - dist – The path to the distribution to add.
- name – (optional) The name of the distribution, should the dist directory alone be
ambiguous. Packages contained within site-packages directories may require specifying
name
.
Raises PEXBuilder.InvalidDistribution: When the path does not contain a matching distribution.
PEX supports packed and unpacked .whl and .egg distributions, as well as any distribution supported by setuptools/pkg_resources.
-
add_distribution
(dist, dist_name=None)[source]¶ Add a
pkg_resources.Distribution
from its handle.Parameters: - dist (
pkg_resources.Distribution
) – The distribution to add to this environment. - dist_name – (optional) The name of the distribution e.g. ‘Flask-0.10.0’. By default this will be inferred from the distribution itself should it be formatted in a standard way.
- dist (
-
add_requirement
(req)[source]¶ Add a requirement to the PEX environment.
Parameters: req – A requirement that should be resolved in this environment. Changed in version 0.8: Removed
dynamic
andrepo
keyword arguments as they were unused.
-
add_resource
(filename, env_filename)[source]¶ Add a resource to the PEX environment.
Parameters: - filename – The source filename to add to the PEX.
- env_filename – The destination filename in the PEX. This path must be a relative path.
-
add_source
(filename, env_filename)[source]¶ Add a source to the PEX environment.
Parameters: - filename – The source filename to add to the PEX.
- env_filename – The destination filename in the PEX. This path must be a relative path.
-
build
(filename, bytecode_compile=True)[source]¶ Package the PEX into a zipfile.
Parameters: - filename – The filename where the PEX should be stored.
- bytecode_compile – If True, precompile .py files into .pyc files.
If the PEXBuilder is not yet frozen, it will be frozen by
build
. This renders the PEXBuilder immutable.
-
clone
(into=None)[source]¶ Clone this PEX environment into a new PEXBuilder.
Parameters: into – (optional) An optional destination directory to clone this PEXBuilder into. If not specified, a temporary directory will be created. Clones PEXBuilder into a new location. This is useful if the PEXBuilder has been frozen and rendered immutable.
Changed in version 0.8: The temporary directory created when
into
is not specified is now garbage collected on interpreter exit.
-
freeze
(bytecode_compile=True)[source]¶ Freeze the PEX.
Parameters: bytecode_compile – If True, precompile .py files into .pyc files when freezing code. Freezing the PEX writes all the necessary metadata and environment bootstrapping code. It may only be called once and renders the PEXBuilder immutable.
-
set_entry_point
(entry_point)[source]¶ Set the entry point of this PEX environment.
Parameters: entry_point (string or None) – The entry point of the PEX in the form of module
ormodule:symbol
, orNone
.By default the entry point is None. The behavior of a
None
entry point is dropping into an interpreter. Ifmodule
, it will be executed viarunpy.run_module
. Ifmodule:symbol
, it is equivalent tofrom module import symbol; symbol()
.The entry point may also be specified via
PEXBuilder.set_executable
.
-
set_executable
(filename, env_filename=None)[source]¶ Set the executable for this environment.
Parameters: - filename – The file that should be executed within the PEX environment when the PEX is invoked.
- env_filename – (optional) The name that the executable file should be stored as within the PEX. By default this will be the base name of the given filename.
The entry point of the PEX may also be specified via
PEXBuilder.set_entry_point
.
-
set_script
(script)[source]¶ Set the entry point of this PEX environment based upon a distribution script.
Parameters: script – The script name as defined either by a console script or ordinary script within the setup.py of one of the distributions added to the PEX. Raises: PEXBuilder.InvalidExecutableSpecification
if the script is not found in any distribution added to the PEX.
-
set_shebang
(shebang)[source]¶ Set the exact shebang line for the PEX file.
For example, pex_builder.set_shebang(‘/home/wickman/Local/bin/python3.4’). This is used to override the default behavior which is to have a #!/usr/bin/env line referencing an interpreter compatible with the one used to build the PEX.
Parameters: shebang (str) – The shebang line minus the #!.
-
pex.pex_info module¶
-
class
pex.pex_info.
PexInfo
(info=None)[source]¶ Bases:
object
PEX metadata.
# Build metadata: build_properties: BuildProperties # (key-value information about the build system) code_hash: str # sha1 hash of all names/code in the archive distributions: {dist_name: str} # map from distribution name (i.e. path in
# the internal cache) to its cache key (sha1)requirements: list # list of requirements for this environment
# Environment options pex_root: ~/.pex # root of all pex-related files entry_point: string # entry point into this pex script: string # script to execute in this pex environment
# at most one of script/entry_point can be specifiedzip_safe: True, default False # is this pex zip safe? inherit_path: True, default False # should this pex inherit site-packages + PYTHONPATH? ignore_errors: True, default False # should we ignore inability to resolve dependencies? always_write_cache: False # should we always write the internal cache to disk first?
# this is useful if you have very large dependencies that # do not fit in RAM constrained environmentsChanged in version 0.8: Removed the
repositories
andindices
information, as they were never implemented.-
build_properties
¶ Information about the system on which this PEX was generated.
Returns: A dictionary containing metadata about the environment used to build this PEX.
-
inherit_path
¶ Whether or not this PEX should be allowed to inherit system dependencies.
By default, PEX environments are scrubbed of all system distributions prior to execution. This means that PEX files cannot rely upon preexisting system libraries.
By default inherit_path is False. This may be overridden at runtime by the $PEX_INHERIT_PATH environment variable.
-
zip_safe
¶ Whether or not this PEX should be treated as zip-safe.
If set to false and the PEX is zipped, the contents of the PEX will be unpacked into a directory within the PEX_ROOT prior to execution. This allows code and frameworks depending upon __file__ existing on disk to operate normally.
By default zip_safe is True. May be overridden at runtime by the $PEX_FORCE_LOCAL environment variable.
-
pex.platforms module¶
pex.resolver module¶
-
class
pex.resolver.
CachingResolver
(cache, cache_ttl, *args, **kw)[source]¶ Bases:
pex.resolver.Resolver
A package resolver implementing a package cache.
-
class
pex.resolver.
Resolver
(interpreter=None, platform=None)[source]¶ Bases:
object
Interface for resolving resolvable entities into python packages.
-
class
pex.resolver.
StaticIterator
(packages)[source]¶ Bases:
pex.iterator.IteratorInterface
An iterator that iterates over a static list of packages.
-
pex.resolver.
resolve
(requirements, fetchers=None, interpreter=None, platform=None, context=None, precedence=None, cache=None, cache_ttl=None)[source]¶ Produce all distributions needed to (recursively) meet requirements
Parameters: - requirements – An iterator of Requirement-like things, either
pkg_resources.Requirement
objects or requirement strings. - fetchers – (optional) A list of
Fetcher
objects for locating packages. If unspecified, the default is to look for packages on PyPI. - interpreter – (optional) A
PythonInterpreter
object to use for building distributions and for testing distribution compatibility. - platform – (optional) A PEP425-compatible platform string to use for filtering compatible distributions. If unspecified, the current platform is used, as determined by Platform.current().
- context – (optional) A
Context
object to use for network access. If unspecified, the resolver will attempt to use the best available network context. - precedence – (optional) An ordered list of allowable
Package
classes to be used for producing distributions. For example, if precedence is supplied as(WheelPackage, SourcePackage)
, wheels will be preferred over building from source, and eggs will not be used at all. If(WheelPackage, EggPackage)
is suppplied, both wheels and eggs will be used, but the resolver will not resort to building anything from source. - cache – (optional) A directory to use to cache distributions locally.
- cache_ttl – (optional integer in seconds) If specified, consider non-exact matches when
resolving requirements. For example, if
setuptools==2.2
is specified and setuptools 2.2 is available in the cache, it will always be used. However, if a non-exact requirement such assetuptools>=2,<3
is specified and there exists a setuptools distribution newer than cache_ttl seconds that satisfies the requirement, then it will be used. If the distribution is older than cache_ttl seconds, it will be ignored. Ifcache_ttl
is not specified, resolving inexact requirements will always result in making network calls through thecontext
.
Returns: List of
pkg_resources.Distribution
instances meetingrequirements
.Raises: - Unsatisfiable – If
requirements
is not transitively satisfiable. - Untranslateable – If no compatible distributions could be acquired for a particular requirement.
This method improves upon the setuptools dependency resolution algorithm by maintaining sets of all compatible distributions encountered for each requirement rather than the single best distribution encountered for each requirement. This prevents situations where
tornado
andtornado==2.0
could be treated as incompatible with each other because the “best distribution” when encounteringtornado
was tornado 3.0. Instead,resolve
maintains the set of compatible distributions for each requirement as it is encountered, and iteratively filters the set. If the set of distributions ever becomes empty, thenUnsatisfiable
is raised.Changed in version 0.8: A number of keywords were added to make requirement resolution slightly easier to configure. The optional
obtainer
keyword was replaced byfetchers
,translator
,context
,threads
,precedence
,cache
andcache_ttl
, also all optional keywords.Changed in version 1.0: The
translator
andthreads
keywords have been removed. The choice of threading policy is now implicit. The choice of translation policy is dictated byprecedence
directly.Changed in version 1.0:
resolver
is now just a wrapper around theResolver
andCachingResolver
classes.- requirements – An iterator of Requirement-like things, either
pex.testing module¶
-
pex.testing.
temporary_content
(*args, **kwds)[source]¶ Write content to disk where content is map from string => (int, string).
If target is int, write int random bytes. Otherwise write contents of string.
-
pex.testing.
write_simple_pex
(td, exe_contents, dists=None, coverage=False)[source]¶ Write a pex file that contains an executable entry point
Parameters: - td – temporary directory path
- exe_contents (string) – entry point python file
- dists – distributions to include, typically sdists or bdists
- coverage – include coverage header
pex.tracer module¶
pex.translator module¶
-
class
pex.translator.
ChainedTranslator
(*translators)[source]¶ Bases:
pex.translator.TranslatorBase
Glue a sequence of Translators together in priority order. The first Translator to resolve a requirement wins.
pex.util module¶
pex.variables module¶
-
class
pex.variables.
Variables
(environ=None, use_defaults=True)[source]¶ Bases:
object
Environment variables supported by the PEX runtime.
-
PEX_ALWAYS_CACHE
¶ Boolean
Always write PEX dependencies to disk prior to invoking regardless whether or not the dependencies are zip-safe. For certain dependencies that are very large such as numpy, this can reduce the RAM necessary to launch the PEX. The data will be written into $PEX_ROOT, which by default is $HOME/.pex. Default: false.
-
PEX_COVERAGE
¶ Boolean
Enable coverage reporting for this PEX file. This requires that the “coverage” module is available in the PEX environment. Default: false.
-
PEX_COVERAGE_FILENAME
¶ Filename
Write the coverage data to the specified filename. If PEX_COVERAGE_FILENAME is not specified but PEX_COVERAGE is, coverage information will be printed to stdout and not saved.
-
PEX_FORCE_LOCAL
¶ Boolean
Force this PEX to be not-zip-safe. This forces all code and dependencies to be written into $PEX_ROOT prior to invocation. This is an option for applications with static assets that refer to paths relative to __file__ instead of using pkgutil/pkg_resources. Default: false.
-
PEX_HTTP_RETRIES
¶ Integer
The number of HTTP retries when performing dependency resolution when building a PEX file. Default: 5.
-
PEX_IGNORE_ERRORS
¶ Boolean
Ignore any errors resolving dependencies when invoking the PEX file. This can be useful if you know that a particular failing dependency is not necessary to run the application. Default: false.
-
PEX_INHERIT_PATH
¶ Boolean
Allow inheriting packages from site-packages. By default, PEX scrubs any packages and namespace packages from sys.path prior to invoking the application. This is generally not advised, but can be used in situations when certain dependencies do not conform to standard packaging practices and thus cannot be bundled into PEX files. Default: false.
-
PEX_INTERPRETER
¶ Boolean
Drop into a REPL instead of invoking the predefined entry point of this PEX. This can be useful for inspecting the PEX environment interactively. It can also be used to treat the PEX file as an interpreter in order to execute other scripts in the context of the PEX file, e.g. “PEX_INTERPRETER=1 ./app.pex my_script.py”. Equivalent to setting PEX_MODULE to empty. Default: false.
-
PEX_MODULE
¶ String
Override the entry point into the PEX file. Can either be a module, e.g. ‘SimpleHTTPServer’, or a specific entry point in module:symbol form, e.g. “myapp.bin:main”.
-
PEX_PATH
¶ A set of one or more PEX files
Merge the packages from other PEX files into the current environment. This allows you to do things such as create a PEX file containing the “coverage” module or create PEX files containing plugin entry points to be consumed by a main application. Paths should be specified in the same manner as $PATH, e.g. PEX_PATH=/path/to/pex1.pex:/path/to/pex2.pex and so forth.
-
PEX_PROFILE
¶ Boolean
Enable application profiling. If specified and PEX_PROFILE_FILENAME is not specified, PEX will print profiling information to stdout.
-
PEX_PROFILE_FILENAME
¶ Filename
Profile the application and dump a profile into the specified filename in the standard “profile” module format.
-
PEX_PROFILE_SORT
¶ String
Toggle the profile sorting algorithm used to print out profile columns. Default: ‘cumulative’.
-
PEX_PYTHON
¶ String
Override the Python interpreter used to invoke this PEX. Can be either an absolute path to an interpreter or a base name e.g. “python3.3”. If a base name is provided, the $PATH will be searched for an appropriate match.
-
PEX_ROOT
¶ Directory
The directory location for PEX to cache any dependencies and code. PEX must write not-zip-safe eggs and all wheels to disk in order to activate them. Default: ~/.pex
-
PEX_SCRIPT
¶ String
The script name within the PEX environment to execute. This must either be an entry point as defined in a distribution’s console_scripts, or a script as defined in a distribution’s scripts section. While Python supports any script including shell scripts, PEX only supports invocation of Python scripts in this fashion.
-
PEX_TEARDOWN_VERBOSE
¶ Boolean
Enable verbosity for when the interpreter shuts down. This is mostly only useful for debugging PEX itself. Default: false.
-
PEX_VERBOSE
¶ Integer
Set the verbosity level of PEX debug logging. The higher the number, the more logging, with 0 being disabled. This environment variable can be extremely useful in debugging PEX environment issues. Default: 0
-