SpacePy Configuration

SpacePy has a few tunable options that can be altered through the spacepy.rc configuration file. All options have defaults which will be used if not specified in the configuration file. These defaults are usually fine for most people and may change between SpacePy releases, so we do not recommend changing the configuration file without substantial reason.

spacepy.rc lives in the per-user SpacePy directory, called .spacepy. You can find this directory by:

>>> import spacepy
>>> spacepy.DOT_FLN
'/home/username/.spacepy'

On Unix-like operating systems, it is in a user’s home directory; on Windows, in the user’s Documents and Settings folder. If it doesn’t exist, this directory (and spacepy.rc) is automatically created when SpacePy is imported.

spacepy.rc has an INI-style format, parsed by configparser. It contains a single section, [spacepy].

The spacepy directory

If you prefer a different location for the SpacePy directory, set the environment variable $SPACEPY to a location of your choice. For example, with a csh, or tcsh you would:

setenv SPACEPY /a/different/dir

for the bash shell you would:

export SPACEPY=/a/different/dir

If $SPACEPY is not an absolute path, it is treated as relative to the working directory at the time of import. In particular, that means if it is defined as an empty string (rather than an undefined variable), .spacepy is made directly in the current directory. Home directory references (~) are expanded via expanduser().

If you change the default location, make sure you add the environment variable $SPACEPY to your .cshrc, .tcshrc, or .bashrc script. If this directory does not exist, it will be created.

The actual .spacepy directory is made inside the directory specified by $SPACEPY.

This directory contains the configuration file and also SpacePy-related data, which can be updated with update().

Available configuration options

enable_old_data_warning

SpacePy maintains certain databases from external sources, notably the leapsecond database used by time. By default UserWarning is issued if the leap second database is out of date. Set this option to False to suppress this warning (and warnings about out-of-date data which may be added in the future.)

keepalive

True to attempt to use HTTP keepalives when downloading data in update() (default). This is faster when downloading many small files but may be fragile (e.g. if a proxy server is required). Set to False for a more robust and flexible, but slower, codepath.

leapsec_url

URL of the leapsecond database used by time conversions. update() will download from the URL. The default should almost always be acceptable.

ncpus

Number of CPUs to use for computations that can be multithreaded/multiprocessed. By default, they will use the number of CPUs reported by multiprocessing.cpu_count(). You may wish to set this to a lower number if you need to reserve other processors on your machine.

notice

True to display the SpacePy license and other information on import (default); False to omit.

omni2_url

URL containing the OMNI2 data. update() will download from the URL. The default should almost always be acceptable.

qindenton_url

URL containing Qin-Denton packaging of OMNI data as as single file. update() will download from the URL. The default should almost always be acceptable.

qd_daily_url

URL containing Qin-Denton packaging of OMNI data in daily files, supplemental to qindenton_url. update() will download from the URL. The default should almost always be acceptable.

psddata_url

URL containing PSD data. update() will download from the URL if requested. The default should almost always be acceptable.

support_notice

True to display a notice on import if not a release version of SpacePy (default); False to omit. Those regularly installing from git instead of a release may want to set this to False.

user_agent

User Agent for network access. If this is set, update() will use this User Agent string on all HTTP requests. Normally leaving this unset should be fine.

Developer documentation

spacepy.rc is loaded into a dictionary (spacepy.config) by SpacePy’s main __init__.py. All options from the [spacepy] section are loaded, with no developer intervention needed. Each key is the option’s name; the associated value is the option’s value. To specify a default, add to the defaults dictionary at the top of _read_config; each default, if not overridden by the config file, will be included in the config dict. Values are assumed to be strings. The caster dictionary is keyed by option name; the value for each key is a function to be applied to the value with the same key to produce a different type from a string.

Release:

0.7.0

Doc generation date:

Nov 08, 2024

For additions or fixes to this page, contact the SpacePy Team at Los Alamos.