Pseudo Site-Packages

This module is mostly a re-implementation of site.addsitedir(), with slight modifications:

  1. We add the given directory to the sys.path.

  2. We search for *.pth files within that directory and process them (nearly) the same as site.addsitedir() does; the differences are:

    • we replace {extended_platform_spec} with a platform specifier;
    • we ignore the commands embedded in easy-install.pth files.
  3. We look for __site__.pth files within each top-level directory and process them as well. This allows for a tool to self-describe its paths and contain that metadata within its own repository, and therefore be usable without being “installed”.

We reimplemented this because:

  1. Our NFS was throwing some wierd errors with site.addsitedir() (due to ._* files).
  2. We wanted self-describing repositories.
  3. We needed a way to link in different build for different platforms.

Environment Variables


A colon-delimited list of sites to add as pseudo site-packages (see python_setup).

If the “site” is a directory, it will be processed as if it were a site-packages directory. If the “site” is a file named python, it will search for the corresponding site-packages directory.

If the current environment (equivalent to sys.executable) is found in this list then it will be used as a centering point for the other sites listed. Anything before the current environment will be prepended to sys.path, and anything after the current environment will be appended.


A colon-delimited list of sites to look for when using the dev command. Any ~ found may refer to any requested user’s home.

If unset, defaults to ~/dev:~/dev/venv/bin/python.

API Reference

class sitetools.sites.SysPathInserter(index=None)

Class to insert a series of paths into sys.path incrementally.


Add the given path to the decided place in sys.path

sitetools.sites.add_site_dir(dir_name, before=None, _path=None)

Add a pseudo site-packages directory to sys.path.

  • dir_name (str) – The directory to add.
  • before (str) – A directory on sys.path that new paths should be

inserted before.

Looks for .pth files at the top-level and __site__.pth files within top-level directories.


Add a list of pseudo site-packages to sys.path.

This centers the list on sys.path around the current environment. I.e. if this environment is in the list, then directories before it in the list will be prepended to sys.path, and directories after it will be appended to sys.path.