# PEX API Reference

## Module contents

## pex.crawler module

Support for webpage parsing and crawling.

class pex.crawler.Crawler(context=None, threads=1)

  Bases: `object`

  A multi-threaded crawler that supports local (disk) and remote (web) crawling.

  classmethod reset_cache()

    Reset the internal crawl cache. This is intended primarily for tests.

class pex.crawler.PageParser

  Bases: `object`

  A helper class to extract and differentiate ordinary and download links from webpages.

  classmethod links(page)

    return all links on a page, including potentially rel= links.

  classmethod rel_links(page)

    return rel= links that should be scraped, skipping obviously data links.

pex.crawler.unescape(s)

  Unescapes html. Taken from https://wiki.python.org/moin/EscapingHtml

## pex.environment module

class pex.environment.PEXEnvironment(pex, pex_info, interpreter=None, **kw)

  Bases: `pkg_resources.Environment`

  can_add(dist)

    Is distribution dist acceptable for this environment?

    The distribution must match the platform and python version requirements specified when this environment was created, or False is returned.

  classmethod load_internal_cache(pex, pex_info)

    Possibly cache out the internal cache.

## pex.fetcher module

class pex.fetcher.Fetcher(urls)

  Bases: `pex.fetcher.FetcherBase`

class pex.fetcher.FetcherBase

  Bases: `abc.AbstractClass`

  A fetcher takes a Requirement and tells us where to crawl to find it.

class pex.fetcher.PyPIFetcher(pypi_base='https://pypi.org/simple/', use_mirrors=False)

  Bases: `pex.fetcher.FetcherBase`

pex.fetcher.normalize_name(name)

  Normalize package name according to PEP-503

## 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)

  Bases: `object`

  A utility to chain together multiple pkg_resources finders.

class pex.finders.FixedEggMetadata(importer)

  Bases: `pkg_resources.EggMetadata`

  An EggMetadata provider that has functional parity with the disk-based provider.

class pex.finders.WheelMetadata(importer)

  Bases: `pkg_resources.EggMetadata`

  Metadata provider for zipped wheels.

  classmethod data_dir(wheel_path)

    Returns the internal path of the data dir for the given wheel.

    As defined https://www.python.org/dev/peps/pep-0427/#the-data-directory

    Return type

      str

  classmethod dist_info_dir(wheel_path)

    Returns the internal path of the dist-info dir for the given wheel.

    As defined here: https://www.python.org/dev/peps/pep-0427/#the-dist-info-directory

    Return type

      str

pex.finders.get_script_from_egg(name, dist)

  Returns location, content of script in distribution or (None, None) if not there.

pex.finders.register_finders()

  Register finders necessary for PEX to function properly.

pex.finders.unregister_finders()

  Unregister finders necessary for PEX to function properly.

## pex.glibc module

pex.glibc.glibc_version_string()

  Returns glibc version string, or None if not using glibc.

## pex.http module

class pex.http.CachedRequestsContext(cache=None, **kw)

  Bases: `pex.http.RequestsContext`

  A requests-based Context with CacheControl support.

class pex.http.Context

  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 of `read(link)` and `fetch(link)` are provided based upon `open(link)` but may be further specialized by individual implementations.

  exception Error

    Bases: `Exception`

    Error base class for Contexts to wrap application-specific exceptions.

  content(link)

    Return the encoded content associated with the link.

    Parameters

      link – The `Link` to read.

  fetch(link, into=None)

    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`. If `None`, creates a new temporary directory that persists for the duration of the interpreter.

  abstract open(link)

    Return an open file-like object to the link.

    Parameters

      link – The `Link` to open.

  read(link)

    Return the binary content associated with the link.

    Parameters

      link – The `Link` to read.

  classmethod register(context_impl)

    Register a concrete implementation of a `Context` to be recognized.

  resolve(link)

    Resolves final link throught all the redirections.

    Parameters

      link – The `Link` to open.

class pex.http.RequestsContext(session=None, verify=True, env=<pex.variables.Variables object>)

  Bases: `pex.http.Context`

  A requests-based Context.

  content(link)

    Return the encoded content associated with the link.

    Parameters

      link – The `Link` to read.

  open(link)

    Return an open file-like object to the link.

    Parameters

      link – The `Link` to open.

  resolve(link)

    Resolves final link throught all the redirections.

    Parameters

      link – The `Link` to open.

class pex.http.StreamFilelike(request, link, chunk_size=16384)

  Bases: `object`

  A file-like object wrapper around requests streams that performs hash validation.

  classmethod detect_algorithm(link)

    Detect the hashing algorithm from the fragment in the link, if any.

class pex.http.UrllibContext(*args, **kw)

  Bases: `pex.http.Context`

  Default Python standard library Context.

  content(link)

    Return the encoded content associated with the link.

    Parameters

      link – The `Link` to read.

  open(link)

    Return an open file-like object to the link.

    Parameters

      link – The `Link` to open.

  resolve(link)

    Resolves final link throught all the redirections.

    Parameters

      link – The `Link` to open.

## pex.installer module

class pex.installer.Installer(source_dir, strict=True, interpreter=None)

  Bases: `pex.installer.InstallerBase`

  Install an unpacked distribution with a setup.py.

class pex.installer.Packager(source_dir, strict=True, interpreter=None, install_dir=None)

  Bases: `pex.installer.DistributionPackager`

  Create a source distribution from an unpacked setup.py-based project.

## pex.interpreter module

pex support for interacting with interpreters.

## pex.iterator module

The glue between fetchers, crawlers and requirements.

class pex.iterator.Iterator(fetchers=None, crawler=None, follow_links=False, allow_prereleases=None)

  Bases: `pex.iterator.IteratorInterface`

  A requirement iterator, the glue between fetchers, crawlers and requirements.

  iter(req)

    Return a list of packages that satisfy the requirement.

## pex.link module

class pex.link.Link(url)

  Bases: `object`

  Wrapper around a URL.

  property filename

    The basename of this url.

  property fragment

    The url fragment following ‘#’ if any.

  classmethod from_filename(filename)

    Return a `Link` wrapping the local filename.

  join(href)

    Given a href relative to this link, return the `Link` of the absolute url.

    Parameters

      href – A string-like path relative to this link.

  property local

    Is the url a local file?

  property local_path

    Returns the local filesystem path (only works for file:// urls).

  property path

    The full path of this url with any hostname and scheme components removed.

  property remote

    Is the url a remote file?

  property scheme

    The URI scheme used by this Link.

  property url

    The url string to which this link points.

  classmethod wrap(url)

    Given a url that is either a string or `Link`, return a `Link`.

    Parameters

      url – A string-like or `Link` object to wrap.

    Returns

      A `Link` object wrapping the url.

  classmethod wrap_iterable(url_or_urls)

    Given a string or `Link` or iterable, return an iterable of `Link` objects.

    Parameters

      url_or_urls – A string or `Link` object, or iterable of string or `Link` objects.

    Returns

      A list of `Link` objects.

## pex.package module

class pex.package.BinaryPackage(*args, **kwargs)

  Bases: `pex.package.Package`

  A Package representing a binary distribution which can be e.g. platform specific.

  compatible(supported_tags)

    Is this package compatible with the given tag set?

    Parameters

      supported_tags (list of 3-tuples) – A list of tags that is supported by the target interpeter, as generated by `pex.pep425tags.get_supported()`.

pex.package.EGG_NAME(string, pos=0, endpos=9223372036854775807)

  Matches zero or more characters at the beginning of the string.

class pex.package.EggPackage(url, **kw)

  Bases: `pex.package.BinaryPackage`

  A Package representing a built egg.

class pex.package.Package(url)

  Bases: `pex.link.Link`

  Base class for named Python binary packages (e.g. source, egg, wheel).

  exception Error

    Bases: `Exception`

  exception InvalidPackage

    Bases: `pex.package.Package.Error`

  compatible(supported_tags)

    Is this package compatible with the given tag set?

    Parameters

      supported_tags (list of 3-tuples) – A list of tags that is supported by the target interpeter, as generated by `pex.pep425tags.get_supported()`.

  classmethod from_href(href, **kw)

    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.

  classmethod register(package_type)

    Register a concrete implementation of a Package to be recognized by pex.

  satisfies(requirement, allow_prereleases=None)

    Determine whether this package matches the requirement.

    Parameters

      - requirement (string or `pkg_resources.Requirement`) – The requirement to compare this Package against

      - allow_prereleases (Optional[bool]) – Whether to allow prereleases to satisfy the requirement.

    Returns

      True if the package matches the requirement, otherwise False

class pex.package.SourcePackage(url, **kw)

  Bases: `pex.package.Package`

  A Package representing an uncompiled/unbuilt source distribution.

  compatible(supported_tags)

    Is this package compatible with the given tag set?

    Parameters

      supported_tags (list of 3-tuples) – A list of tags that is supported by the target interpeter, as generated by `pex.pep425tags.get_supported()`.

  classmethod split_fragment(fragment)

    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')

class pex.package.WheelPackage(url, **kw)

  Bases: `pex.package.BinaryPackage`

  A Package representing a built wheel.

pex.package.distribution_compatible(dist, supported_tags=None)

  Is this distribution compatible with the given interpreter/platform combination?

  Parameters

    supported_tags – A list of tag tuples specifying which tags are supported by the platform in question.

  Returns

    True if the distribution is compatible, False if it is unrecognized or incompatible.

## pex.pep425tags module

Generate and work with PEP 425 Compatibility Tags.

pex.pep425tags.get_abbr_impl()

  Return abbreviated implementation name.

pex.pep425tags.get_abi_tag()

  Return the ABI tag based on SOABI (if available) or emulate SOABI (CPython 2, PyPy).

pex.pep425tags.get_darwin_arches(major, minor, machine)

  Return a list of supported arches (including group arches) for the given major, minor and machine architecture of an macOS machine.

pex.pep425tags.get_flag(var, fallback, expected=True, warn=True)

  Use a fallback method for determining SOABI flags if the needed config var is unset or unavailable.

pex.pep425tags.get_impl_tag()

  Returns the Tag for this specific implementation.

pex.pep425tags.get_impl_ver()

  Return implementation version.

pex.pep425tags.get_impl_version_info()

  Return sys.version_info-like tuple for use in decrementing the minor version.

pex.pep425tags.get_platform()

  Return our platform name ‘win32’, ‘linux_x86_64’

pex.pep425tags.get_supported(version=None, noarch=False, platform=None, impl=None, abi=None, force_manylinux=False)

  Return a list of supported tags for each version specified in version.

  Parameters

    - version – string version (e.g., “33”, “32”) or None. If None, use local system Python version.

    - platform – specify the exact platform you want valid tags for, or None. If None, use the local system platform.

    - impl – specify the exact implementation you want valid tags for, or None. If None, use the local interpreter impl.

    - abi – specify the exact abi you want valid tags for, or None. If None, use the local interpreter abi.

    - force_manylinux – Whether or not to force manylinux support. This is useful when resolving for different target platform than current.

pex.pep425tags.get_supported_for_any_abi(version=None, noarch=False, platform=None, impl=None, force_manylinux=False)

  Generates supported tags for unspecified ABI types to support more intuitive cross-platform resolution.

## pex.pex module

class pex.pex.PEX(pex='/usr/lib/python3/dist-packages/sphinx/__main__.py', interpreter=None, env=<pex.variables.Variables object>, verify_entry_point=False)

  Bases: `object`

  PEX, n. A self-contained python environment.

  exception Error

    Bases: `Exception`

  exception InvalidEntryPoint

    Bases: `pex.pex.PEX.Error`

  exception NotFound

    Bases: `pex.pex.PEX.Error`

  cmdline(args=())

    The commandline to run this environment.

    Parameters

      args – Additional arguments to be passed to the application being invoked by the environment.

  execute()

    Execute the PEX.

    This function makes assumptions that it is the last function called by the interpreter.

  classmethod minimum_sys(inherit_path)

    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)

    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(working_set)

    Patch pkg_resources given a new working set.

  patch_sys(inherit_path)

    Patch sys with all site scrubbed.

  path()

    Return the path this PEX was built at.

  run(args=(), with_chroot=False, blocking=True, setsid=False, **kwargs)

    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)

  Bases: `object`

  Helper for building PEX environments.

  exception Error

    Bases: `Exception`

  exception ImmutablePEX

    Bases: `pex.pex_builder.PEXBuilder.Error`

  exception InvalidDependency

    Bases: `pex.pex_builder.PEXBuilder.Error`

  exception InvalidDistribution

    Bases: `pex.pex_builder.PEXBuilder.Error`

  exception InvalidExecutableSpecification

    Bases: `pex.pex_builder.PEXBuilder.Error`

  add_dist_location(dist, name=None)

    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)

    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.

  add_egg(egg)

    Alias for add_dist_location.

  add_interpreter_constraint(ic)

    Add an interpreter constraint to the PEX environment.

    Parameters

      ic – A version constraint on the interpreter used to build and run this PEX environment.

  add_requirement(req)

    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` and `repo` keyword arguments as they were unused.

  add_resource(filename, env_filename)

    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)

    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)

    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)

    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)

    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)

    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` or `module:symbol`, or `None`.

    By default the entry point is None. The behavior of a `None` entry point is dropping into an interpreter. If `module`, it will be executed via `runpy.run_module`. If `module:symbol`, it is equivalent to `from module import symbol; symbol()`.

    The entry point may also be specified via `PEXBuilder.set_executable`.

  set_executable(filename, env_filename=None)

    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)

    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)

    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. If it does not include the leading ‘#!’ it will be added.

## pex.pex_info module

class pex.pex_info.PexInfo(info=None)

  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: string # root of all pex-related files eg: ~/.pex 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 specified

  zip_safe: True, default False # is this pex zip safe? inherit_path: false/fallback/prefer # 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 environments

  Changed in version 0.8: Removed the `repositories` and `indices` information, as they were never implemented.

  property 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.

  property 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.

  property interpreter_constraints

    A list of constraints that determine the interpreter compatibility for this pex, using the Requirement-style format, e.g. `'CPython>=3', or just '>=2.7,<3'` for requirements agnostic to interpreter class.

    This property will be used at exec time when bootstrapping a pex to search PEX_PYTHON_PATH for a list of compatible interpreters.

  merge_pex_path(pex_path)

    Merges a new PEX_PATH definition into the existing one (if any). :param string pex_path: The PEX_PATH to merge.

  property pex_path

    A colon separated list of other pex files to merge into the runtime environment.

    This pex info property is used to persist the PEX_PATH environment variable into the pex info metadata for reuse within a built pex.

  property 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

class pex.platforms.Platform(platform, impl=None, version=None, abi=None)

  Bases: `pex.platforms.Platform`

  Represents a target platform and it’s extended interpreter compatibility tags (e.g. implementation, version and ABI).

  supported_tags(interpreter=None, force_manylinux=True)

    Returns a list of supported PEP425 tags for the current platform.

## pex.resolver module

class pex.resolver.CachingResolver(cache, cache_ttl, *args, **kw)

  Bases: `pex.resolver.Resolver`

  A package resolver implementing a package cache.

class pex.resolver.ResolvedDistribution(requirement, distribution)

  Bases: `pex.resolver.ResolvedDistribution`

  A requirement and the resolved distribution that satisfies it.

class pex.resolver.Resolver(allow_prereleases=None, interpreter=None, platform=None, use_manylinux=None)

  Bases: `object`

  Interface for resolving resolvable entities into python packages.

  exception Error

    Bases: `Exception`

class pex.resolver.StaticIterator(packages, allow_prereleases=None)

  Bases: `pex.iterator.IteratorInterface`

  An iterator that iterates over a static list of packages.

  iter(req)

    Return a list of packages that satisfy the requirement.

exception pex.resolver.Unsatisfiable

  Bases: `Exception`

exception pex.resolver.Untranslateable

  Bases: `Exception`

pex.resolver.patched_packing_env(env)

  Monkey patch packaging.markers.default_environment

pex.resolver.platform_to_tags(platform, interpreter)

  Splits a “platform” like linux_x86_64-36-cp-cp36m into its components.

  If a simple platform without hyphens is specified, we will fall back to using the current interpreter’s tags.

pex.resolver.resolve(requirements, fetchers=None, interpreter=None, platform=None, context=None, precedence=None, cache=None, cache_ttl=None, allow_prereleases=None, use_manylinux=None)

  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.

    - versions – (optional) a list of string versions, of the form [“33”, “32”], or None. The first version will be assumed to support our ABI.

    - platform – (optional) specify the exact platform you want valid tags for, or None. If None, use the local system platform.

    - impl – (optional) specify the exact implementation you want valid tags for, or None. If None, use the local interpreter impl.

    - abi – (optional) specify the exact abi you want valid tags for, or None. If None, use the local interpreter abi.

    - 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 as `setuptools>=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. If `cache_ttl` is not specified, resolving inexact requirements will always result in making network calls through the `context`.

    - allow_prereleases – (optional) Include pre-release and development versions. If unspecified only stable versions will be resolved, unless explicitly included.

    - use_manylinux – (optional) Whether or not to use manylinux for linux resolves.

  Returns

    List of `ResolvedDistribution` instances meeting `requirements`.

  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` and `tornado==2.0` could be treated as incompatible with each other because the “best distribution” when encountering `tornado` 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, then `Unsatisfiable` 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 by `fetchers`, `translator`, `context`, `threads`, `precedence`, `cache` and `cache_ttl`, also all optional keywords.

  Changed in version 1.0: The `translator` and `threads` keywords have been removed. The choice of threading policy is now implicit. The choice of translation policy is dictated by `precedence` directly.

  Changed in version 1.0: `resolver` is now just a wrapper around the `Resolver` and `CachingResolver` classes.

  Changed in version 1.5.0: The `pkg_blacklist` has been removed and the return type changed to a list of `ResolvedDistribution`.

pex.resolver.resolve_multi(requirements, fetchers=None, interpreters=None, platforms=None, context=None, precedence=None, cache=None, cache_ttl=None, allow_prereleases=None, use_manylinux=None)

  A generator function that produces all distributions needed to meet requirements for multiple interpreters and/or platforms.

  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.

    - interpreters – (optional) An iterable of `PythonInterpreter` objects to use for building distributions and for testing distribution compatibility.

    - platforms – (optional) An iterable of PEP425-compatible platform strings 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 as `setuptools>=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. If `cache_ttl` is not specified, resolving inexact requirements will always result in making network calls through the `context`.

    - allow_prereleases – (optional) Include pre-release and development versions. If unspecified only stable versions will be resolved, unless explicitly included.

  Yields

    All `ResolvedDistribution` instances meeting `requirements`.

  Raises

    - Unsatisfiable – If `requirements` is not transitively satisfiable.

    - Untranslateable – If no compatible distributions could be acquired for a particular requirement.

## pex.testing module

class pex.testing.IntegResults(output, return_code, exception, traceback)

  Bases: `pex.testing.results`

  Convenience object to return integration run results.

pex.testing.get_dep_dist_names_from_pex(pex_path, match_prefix='')

  Given an on-disk pex, extract all of the unique first-level paths under .deps.

pex.testing.run_pex_command(args, env=None)

  Simulate running pex command for integration testing.

  This is different from run_simple_pex in that it calls the pex command rather than running a generated pex. This is useful for testing end to end runs with specific command line arguments or env options.

pex.testing.temporary_content(content_map, interp=None, seed=31337, perms=420)

  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.temporary_filename()

  Creates a temporary filename.

  This is useful when you need to pass a filename to an API. Windows requires all handles to a file be closed before deleting/renaming it, so this makes it a bit simpler.

pex.testing.write_simple_pex(td, exe_contents, dists=None, sources=None, coverage=False, interpreter=None)

  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

    - sources – sources to include, as a list of pairs (env_filename, contents)

    - coverage – include coverage header

    - interpreter – a custom interpreter to use to build the pex

## pex.tracer module

class pex.tracer.TraceLogger(predicate=None, output=<_io.TextIOWrapper name='<stderr>' mode='w' encoding='utf-8'>, clock=<module 'time' (built-in)>, prefix='')

  Bases: `object`

  A multi-threaded tracer.

## pex.translator module

class pex.translator.BinaryTranslator(package_type, supported_tags=None)

  Bases: `pex.translator.TranslatorBase`

  translate(package, into=None)

    From a binary package, translate to a local binary distribution.

class pex.translator.ChainedTranslator(*translators)

  Bases: `pex.translator.TranslatorBase`

  Glue a sequence of Translators together in priority order. The first Translator to resolve a requirement wins.

class pex.translator.EggTranslator(**kw)

  Bases: `pex.translator.BinaryTranslator`

class pex.translator.SourceTranslator(interpreter=PythonInterpreter('/usr/bin/python3.10', PythonIdentity('cp', 'cp310', '310', 3, 10, 5), {('pex', '1.5.3'): '/build/python-pex-vFWbht/python-pex-1.5.3', ('pytz', '2022.1'): '/usr/lib/python3/dist-packages', ('certifi', '2020.6.20'): '/usr/lib/python3/dist-packages', ('setuptools', '59.6.0'): '/usr/lib/python3/dist-packages', ('packaging', '21.3'): '/usr/lib/python3/dist-packages', ('more-itertools', '8.10.0'): '/usr/lib/python3/dist-packages', ('importlib-metadata', '4.6.4'): '/usr/lib/python3/dist-packages', ('sphinx', '4.5.0'): '/usr/lib/python3/dist-packages', ('chardet', '4.0.0'): '/usr/lib/python3/dist-packages', ('roman', '3.3'): '/usr/lib/python3/dist-packages', ('idna', '3.3'): '/usr/lib/python3/dist-packages', ('pyparsing', '3.0.7'): '/usr/lib/python3/dist-packages', ('jinja2', '3.0.3'): '/usr/lib/python3/dist-packages', ('requests', '2.27.1'): '/usr/lib/python3/dist-packages', ('pygments', '2.11.2'): '/usr/lib/python3/dist-packages', ('babel', '2.8.0'): '/usr/lib/python3/dist-packages', ('snowballstemmer', '2.2.0'): '/usr/lib/python3/dist-packages', ('markupsafe', '2.0.1'): '/usr/lib/python3/dist-packages', ('urllib3', '1.26.9'): '/usr/lib/python3/dist-packages', ('six', '1.16.0'): '/usr/lib/python3/dist-packages', ('imagesize', '1.3.0'): '/usr/lib/python3/dist-packages', ('zipp', '1.0.0'): '/usr/lib/python3/dist-packages', ('wheel', '0.37.1'): '/usr/lib/python3/dist-packages', ('docutils', '0.17.1'): '/usr/lib/python3/dist-packages', ('alabaster', '0.7.12'): '/usr/lib/python3/dist-packages'}), supported_tags=None, use_2to3=False, installer_impl=<class 'pex.installer.WheelInstaller'>)

  Bases: `pex.translator.TranslatorBase`

  translate(package, into=None)

    From a SourcePackage, translate to a binary distribution.

class pex.translator.TranslatorBase

  Bases: `abc.AbstractClass`

  Translate a link into a distribution.

class pex.translator.WheelTranslator(**kw)

  Bases: `pex.translator.BinaryTranslator`

## pex.util module

class pex.util.Memoizer

  Bases: `object`

  A thread safe class for memoizing the results of a computation.

pex.util.iter_pth_paths(filename)

  Given a .pth file, extract and yield all inner paths without honoring imports. This shadows python’s site.py behavior, which is invoked at interpreter startup.

pex.util.merge_split(*paths)

  Merge paths into a single path delimited by colons and split on colons to return a list of paths.

  Parameters

    paths – a variable length list of path strings

  Returns

    a list of paths from the merged path list split by colons

pex.util.named_temporary_file(*args, **kwargs)

  Due to a bug in python (https://bugs.python.org/issue14243), we need this to be able to use the temporary file without deleting it.

## pex.variables module

class pex.variables.Variables(environ=None, rc=None, use_defaults=True)

  Bases: `object`

  Environment variables supported by the PEX runtime.

  property 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.

  property PEX_COVERAGE

    Boolean

    Enable coverage reporting for this PEX file. This requires that the “coverage” module is available in the PEX environment. Default: false.

  property 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.

  property 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.

  property PEX_HTTP_RETRIES

    Integer

    The number of HTTP retries when performing dependency resolution when building a PEX file. Default: 5.

  property 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.

  property PEX_IGNORE_RCFILES

    Boolean

    Explicitly disable the reading/parsing of pexrc files (~/.pexrc). Default: false.

  property 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.

  property 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.

  property 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”.

  property 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.

  property PEX_PROFILE

    Boolean

    Enable application profiling. If specified and PEX_PROFILE_FILENAME is not specified, PEX will print profiling information to stdout.

  property PEX_PROFILE_FILENAME

    Filename

    Profile the application and dump a profile into the specified filename in the standard “profile” module format.

  property PEX_PROFILE_SORT

    String

    Toggle the profile sorting algorithm used to print out profile columns. Default: ‘cumulative’.

  property 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.

  property PEX_PYTHON_PATH

    String

    A colon-separated string containing paths of blessed Python interpreters for overriding the Python interpreter used to invoke this PEX. Must be absolute paths to the interpreter.

    Ex: “/path/to/python27:/path/to/python36”

  property 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

  property 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.

  property PEX_TEARDOWN_VERBOSE

    Boolean

    Enable verbosity for when the interpreter shuts down. This is mostly only useful for debugging PEX itself. Default: false.

  property 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

  classmethod from_rc(rc=None)

    Read pex runtime configuration variables from a pexrc file.

    Parameters

      rc – an absolute path to a pexrc file.

    Returns

      A dict of key value pairs found in processed pexrc files.

    Return type

      dict

  patch(**kw)

    Update the environment for the duration of a context.

  strip_defaults()

    Returns a copy of these variables but with defaults stripped.

    Any variables not explicitly set in the environment will have a value of None.