Previous Section Next Section

13.6 Site and User Customization

Python provides a specific hook to let each site customize some aspects of Python's behavior at the start of each run. Customization by each single user is not enabled by default, but Python specifies how programs that want to run user-provided code at startup can explicitly request such customization.

13.6.1 The site and sitecustomize Modules

Python loads standard module site just before the main script. If Python is run with option -S, Python does not load site. -S allows faster startup, but saddles the main script with initialization chores. site's tasks are:

  1. Putting sys.path in standard form (absolute paths, no duplicates).

  2. Interpreting each .pth file found in the Python home directory, adding entries to sys.path, and/or importing modules, as each .pth file indicates.

  3. Adding built-ins used to display information in interactive sessions (quit, exit, copyright, credits, and license).

  4. Setting the default Unicode encoding to 'ascii'. site's source code includes two blocks, each guarded by if 0:, one to set the default encoding to be locale dependent, and the other to disable default encoding and decoding between Unicode and plain strings. You may optionally edit site.py to select either block.

  5. Trying to import sitecustomize (should import sitecustomize raise an ImportError exception, site catches and ignores it). sitecustomize is the module that each site's installation can optionally use for further site-specific customization beyond site's tasks. It is generally best not to edit site.py, as any Python upgrade or reinstallation might overwrite your customizations. sitecustomize's main task is often to set the correct default encoding for the site. Western European sites, for example, may choose to call sys.setdefaultencoding('iso-8859-1').

  6. After sitecustomize is done, removing from module sys the attribute sys.setdefaultencoding.

Thus, Python's default Unicode encoding can be set only at the start of a run, not changed in midstream during the run. In an emergency, if a specific main script desperately needs to break this guideline and set a different default encoding from that used by all other scripts, you may place the following snippet at the start of the main script:

import sys                               # get the sys module object
reload(sys)                              # restore module sys from disk
sys.setdefaultencoding('iso-8859-15')    # or whatever codec you need
del sys.setdefaultencoding               # ensure against later accidents

However, this is not good style. You should refactor your script so that it can accept whatever default encoding the site has chosen, and pass the encoding name explicitly in those spots where a specific codec is necessary.

13.6.2 User Customization

Each interactive Python interpreter session runs the script indicated by environment variable PYTHONSTARTUP. Outside of interactive interpreter sessions, there is no automatic per-user customization. To request per-user customization, a Python main script can explicitly import user. Standard module user, when loaded, first determines the user's home directory, as indicated by environment variable HOME (or, failing that, HOMEPATH, possibly preceded by HOMEDRIVE on Windows systems only). If the environment does not indicate a home directory, user uses the current directory. If module user locates a file named .pythonrc.py in the indicated directory, user executes that file, with built-in function execfile, in module user's own global namespace.

Scripts that don't import user do not load .pythonrc.py. Of course, any given script is free to arrange other specific ways to load whatever startup or plug-in user-supplied files it requires. Such application-specific arrangements are more common than importing user. A generic .pythonrc.py, as loaded via import user, needs to be usable with any application that loads it. Specialized, application-specific startup and plug-in user-supplied files only need to follow whatever convention a specific application documents.

For example, your application MyApp.py could document that it looks for a file named .myapprc.py in the user's home directory, as indicated by environment variable HOME, and loads it in the application main script's global namespace. You could then have the following code in your main script:

import os
homedir = os.environ.get('HOME')
if homedir is not None:
    userscript = os.path.join(homedir, '.myapprc.py')
    if os.path.isfile(userscript):
        execfile(userscript)

In this case, the .myapprc.py user customization script, if present, has to deal only with MyApp-specific user customization tasks.
    Previous Section Next Section