[Python-Dev] PEP: per user site-packages directory

[Christian Heimes]

MA Lemburg has suggested a per user site-packages directory in the
"pkgutil, pkg_resource and Python 3.0 name space packages" thread. I've
written a short PEP about it for Python 2.6 and 3.0.

PEP: XXX
Title: Per user site-packages directory
Version: $Revision$
Last-Modified: $Date$
Author: Christian Heimes <christian(at)cheimes(dot)de>
Status: Draft
Type: Standards Track
Content-Type: text/x-rst
Created: 11-Jan-2008
Python-Version: 2.6, 3.0
Post-History:


Abstract
========

This PEP proposes a new a per user site-packages directory to allow
users the local installation of Python packages in their home directory.


Rationale
=========

Current Python versions don't have an unified way to install packages
into the home directory of an user (except for Mac Framework
builds). Users are either forced to ask the system administrator to
install or update a package for them or to use one of the many
workaround like Virtual Python [1]_, Working Env [2]_ or
Virtual Env [3]_.

It's not the goal of the PEP to replace the tools or to implement
isolated installations of Python. It only implements the most common
use case of an additional site-packages directory for each user.

The feature can't be implemented using the environment variable
*PYTHONPATH*. The env var just inserts a new directory to the beginning
of *sys.path* but it doesn't parse the pth files in the directory. A
full blown site-packages path is required for several applications
and Python eggs.


Specification
=============

site directory (site-packages)

   A directory in sys.path. In contrast to ordinary directories the pth
   files in the directory are processed, too.


user site directory

   A site directory inside the users' home directory. An user site
   directory is specific to a Python version. The path contains
   the version number (major and minor only).

   Windows: %APPDATA%/Python/Python26/site-packages
   Mac: ~/Library/Python/2.6/site-packages
   Unix: ~/.local/lib/python2.6/site-packages


user configuration directory

   Usually the parent directory of the user site directory. It's meant
   for Python version specific data like config files.

   Windows: %APPDATA%/Python/Python26
   Mac: ~/Library/Python/2.6
   Unix: ~/.local/lib/python2.6

user base directory

   It's located inside the user's home directory. The user site and
   use config directory are inside the base directory. On some systems
   the directory may be shared with 3rd party apps.

   Windows: %APPDATA%/Python
   Mac: ~/Library/Python
   Unix: ~/.local


On Windows APPDATA was chosen because it is the most logical place for
application data. Microsoft recommands that software doesn't write to
USERPROFILE [5]_ and My Documents is not suited for application data,
too. [8]_

On Linux ~/.local/ was chosen in favor over ./~python/ because the
directory is already used by several other programs in analogy to
/usr/local. [7]_


Implementation
==============

The site module gets a new method adduserpackage() which adds the
appropriate directory to the search path. The directory is not added if
it doesn't exist when Python is started. However the location of the
user site directory and user base directory is stored in an internal
variable for distutils.

The user site directory is added before the system site directories
but after Python's search paths and PYTHONPATH. This setup allows the
user to install a different version of a package than the system
administrator but it prevents the user from accidently overwriting a
stdlib module. Stdlib modules can still be overwritten with PYTHONPATH.

distutils.command.install (setup.py install) gets a new argument
--user to install packages in the user site directory. The required
directories are created by install.

distutils.sysconfig will get methods to access the private variables
of site. (not yet implemented)

The Windows updater needs to be updated, too. It should create an menu
item which opens the user site directory in a new explorer windows.


Backwards Compatibility
=======================

TBD


Open Questions
==============

* Are the directories for Windows, Mac and Unix fine?

* Mac: Should framework and non-framework builds of Python use the
  same directories?

* The patch also adds a usecustomize hook to site. Is it useful and
  should it stay?


Reference Implementation
========================

A reference implementation is available in the bug tracker. [4]_


Acknowledgments
===============

The implementation of this PEP, if accepted, is sponsored by Google
through the Google Summer of Code program.


Copyright
=========

This document has been placed in the public domain.


References
==========

.. [1] Virtual Python

http://peak.telecommunity.com/DevCenter/EasyInstall#creating-a-virtual-python

.. [2]  Working Env
   http://pypi.python.org/pypi/workingenv.py
   http://blog.ianbicking.org/workingenv-revisited.html

.. [3] Virtual Env
   http://pypi.python.org/pypi/virtualenv

.. [4] reference implementation
   http://bugs.python.org/issue1799

.. [5] MSDN: CSIDL
   http://msdn2.microsoft.com/en-us/library/bb762494.aspx

.. [6] Initial suggestion for a per user site-packages directory
   http://permalink.gmane.org/gmane.comp.python.devel/90902

.. [7] Suggestion of ~/.local/
   http://permalink.gmane.org/gmane.comp.python.devel/90925

.. [8] APPDATA discussion
   http://permalink.gmane.org/gmane.comp.python.devel/90932


..
   Local Variables:
   mode: indented-text
   indent-tabs-mode: nil
   sentence-end-double-space: t
   fill-column: 70
   coding: utf-8
   End: