| [2] | 1 |
|
|---|
| 2 | :mod:`user` --- User-specific configuration hook
|
|---|
| 3 | ================================================
|
|---|
| 4 |
|
|---|
| 5 | .. module:: user
|
|---|
| 6 | :synopsis: A standard way to reference user-specific modules.
|
|---|
| 7 | :deprecated:
|
|---|
| 8 |
|
|---|
| 9 | .. deprecated:: 2.6
|
|---|
| [391] | 10 | The :mod:`user` module has been removed in Python 3.
|
|---|
| [2] | 11 |
|
|---|
| 12 | .. index::
|
|---|
| 13 | pair: .pythonrc.py; file
|
|---|
| 14 | triple: user; configuration; file
|
|---|
| 15 |
|
|---|
| 16 | As a policy, Python doesn't run user-specified code on startup of Python
|
|---|
| 17 | programs. (Only interactive sessions execute the script specified in the
|
|---|
| 18 | :envvar:`PYTHONSTARTUP` environment variable if it exists).
|
|---|
| 19 |
|
|---|
| 20 | However, some programs or sites may find it convenient to allow users to have a
|
|---|
| 21 | standard customization file, which gets run when a program requests it. This
|
|---|
| 22 | module implements such a mechanism. A program that wishes to use the mechanism
|
|---|
| 23 | must execute the statement ::
|
|---|
| 24 |
|
|---|
| 25 | import user
|
|---|
| 26 |
|
|---|
| 27 | .. index:: builtin: execfile
|
|---|
| 28 |
|
|---|
| 29 | The :mod:`user` module looks for a file :file:`.pythonrc.py` in the user's home
|
|---|
| 30 | directory and if it can be opened, executes it (using :func:`execfile`) in its
|
|---|
| 31 | own (the module :mod:`user`'s) global namespace. Errors during this phase are
|
|---|
| 32 | not caught; that's up to the program that imports the :mod:`user` module, if it
|
|---|
| 33 | wishes. The home directory is assumed to be named by the :envvar:`HOME`
|
|---|
| 34 | environment variable; if this is not set, the current directory is used.
|
|---|
| 35 |
|
|---|
| 36 | The user's :file:`.pythonrc.py` could conceivably test for ``sys.version`` if it
|
|---|
| 37 | wishes to do different things depending on the Python version.
|
|---|
| 38 |
|
|---|
| 39 | A warning to users: be very conservative in what you place in your
|
|---|
| 40 | :file:`.pythonrc.py` file. Since you don't know which programs will use it,
|
|---|
| 41 | changing the behavior of standard modules or functions is generally not a good
|
|---|
| 42 | idea.
|
|---|
| 43 |
|
|---|
| 44 | A suggestion for programmers who wish to use this mechanism: a simple way to let
|
|---|
| 45 | users specify options for your package is to have them define variables in their
|
|---|
| 46 | :file:`.pythonrc.py` file that you test in your module. For example, a module
|
|---|
| 47 | :mod:`spam` that has a verbosity level can look for a variable
|
|---|
| 48 | ``user.spam_verbose``, as follows::
|
|---|
| 49 |
|
|---|
| 50 | import user
|
|---|
| 51 |
|
|---|
| 52 | verbose = bool(getattr(user, "spam_verbose", 0))
|
|---|
| 53 |
|
|---|
| 54 | (The three-argument form of :func:`getattr` is used in case the user has not
|
|---|
| 55 | defined ``spam_verbose`` in their :file:`.pythonrc.py` file.)
|
|---|
| 56 |
|
|---|
| 57 | Programs with extensive customization needs are better off reading a
|
|---|
| 58 | program-specific customization file.
|
|---|
| 59 |
|
|---|
| 60 | Programs with security or privacy concerns should *not* import this module; a
|
|---|
| 61 | user can easily break into a program by placing arbitrary code in the
|
|---|
| 62 | :file:`.pythonrc.py` file.
|
|---|
| 63 |
|
|---|
| 64 | Modules for general use should *not* import this module; it may interfere with
|
|---|
| 65 | the operation of the importing program.
|
|---|
| 66 |
|
|---|
| 67 |
|
|---|
| 68 | .. seealso::
|
|---|
| 69 |
|
|---|
| 70 | Module :mod:`site`
|
|---|
| 71 | Site-wide customization mechanism.
|
|---|
| 72 |
|
|---|
