Previous Page
Next Page

13.5. 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.5.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:

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

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

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

  • 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 completely disable any default encoding between Unicode and plain strings. You may optionally edit to select either block.

  • 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, since any Python upgrade or reinstallation might overwrite such customizations. sitecustomize's main task can be to set the correct default encoding for the site. A Western European site, for example, may choose to call from sitecustomize sys.setdefaultencoding('iso-8859-1').

  • 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 all of the spots where a specific codec is necessary.

13.5.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 library 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 finds a file named 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 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, 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 could document that it looks for a file named in the user's home directory, as indicated by environment variable HOME, and loads it in the application's 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, '')
    if os.path.isfile(userscript):

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

Previous Page
Next Page