Customizing sunpy#

The sunpyrc file#

The sunpy core package uses a sunpyrc configuration file to customize certain properties. You can control a number of key features of sunpy such as where your data will download to. sunpy looks for the sunpyrc file in a platform specific directory, which you can see the path for by running:

>>> import sunpy
>>> sunpy.print_config()  
FILES USED:
  ...

CONFIGURATION:
  [general]
  time_format = %Y-%m-%d %H:%M:%S
  working_dir = ...

  [downloads]
  download_dir = ...
  remote_data_manager_dir = ...
  cache_expiry = 10
  sample_dir = ...

  [database]
  url = sqlite:////...

  [logger]
  log_level = INFO
  use_color = True
  log_warnings = True
  log_exceptions = False
  log_to_file = False
  log_file_level = INFO
  log_file_format = %(asctime)s, %(origin)s, %(levelname)s, %(message)s

Do not edit the default file (the first in the “FILES USED:” list above) directly as every time you install or update sunpy, this file will be overwritten.

To maintain your personal customizations place a copy of the default “sunpyrc” file into the user configuration path. To find this path, use:

>>> from sunpy.extern.appdirs import AppDirs
>>> AppDirs('sunpy', 'sunpy').user_config_dir  

You can use sunpy.util.config.copy_default_config to write the default config into the correct place.

The user configuration path can also be set using an environment variable SUNPY_CONFIGDIR.

Depending on your system, it may be useful to have a site-wide configuration file. If it is used, it will be on the “FILES USED:” list below the default file. To find your system’s site configuration path for sunpy, use:

>>> from sunpy.extern.appdirs import AppDirs
>>> AppDirs('sunpy', 'sunpy').site_config_dir  

In Unix, the site and user configuration paths follow the XDG specifications.

The site configuration is applied before your personal user configuration, thus your configuration file will override the site configuration settings. For this reason, when you create or edit your personal configuration file, you may want to replicate the site configuration items into your own configuration file, or comment out the items in your configuration file that are set in the site configuration file.

See below for the example config file.

Dynamic settings#

You can also dynamically change the default settings in a python script or interactively from the python shell. All of the settings are stored in a Python ConfigParser instance called sunpy.config, which is global to the sunpy package. Settings can be modified directly, for example:

import sunpy
sunpy.config.set('downloads', 'download_dir', '/home/user/Downloads')

A sample sunpyrc file#

(download)

;
; SunPy Configuration
;
; This is a sample sunpy configuration file - you can find a copy
; of it on your system in site-packages/sunpy/data/sunpyrc. If you edit it
; there, please note that it will be overridden in your next install.
; If you want to keep a permanent local copy that will not be
; over-written, we use AppDirs https://pypi.org/project/appdirs/
; to find the right place for each OS to place it.
; So if you open the link, you can find the user_config_dir
; or print(sunpy.util.config.CONFIG_DIR) to find it on your own system.
; Note that any relative filepaths specified in the SunPy configuration file
; will be relative to SunPy's working directory.

;;;;;;;;;;;;;;;;;;;
; General Options ;
;;;;;;;;;;;;;;;;;;;
[general]

; The SunPy working directory is the parent directory where all generated
; and download files will be stored.
; Default Value: <user's home directory>/sunpy
; working_dir = /home/$USER/sunpy

; Time Format to be used for displaying time in output (e.g. graphs)
; The default time format is based on ISO8601 (replacing the T with space)
; note that the extra '%'s are escape characters
time_format = %Y-%m-%d %H:%M:%S

;;;;;;;;;;;;;
; Downloads ;
;;;;;;;;;;;;;
[downloads]

; Location to save download data to. Path should be specified relative to the
; SunPy working directory.
; Default value: data/
download_dir = data

; Location to save remote data manager (sunpy.data.manager) data to.
; Path should be specified relative to the SunPy working directory.
; Default value: data_manager/
remote_data_manager_dir = data_manager

; Time interval for cache expiry in days.
; Default value: 10
cache_expiry = 10

; Location where the sample data will be downloaded. If not specified, will be
; downloaded to platform specific user data directory.
; The default directory is specified by appdirs (https://github.com/ActiveState/appdirs)
; sample_dir = /data/sample_data

;;;;;;;;;;;;
; Logger   ;
;;;;;;;;;;;;
[logger]

# Threshold for the logging messages. Logging messages that are less severe
# than this level will be ignored. The levels are 'DEBUG', 'INFO', 'WARNING',
# 'ERROR'
log_level = INFO

# Whether to use color for the level names
use_color = True

# Whether to log warnings.warn calls
log_warnings = True

# Whether to log exceptions before raising them
log_exceptions = False

# Whether to always log messages to a log file
log_to_file = False

# The file to log messages to
# log_file_path = sunpy.log

# Threshold for logging messages to log_file_path
log_file_level = INFO

# Format for log file entries
log_file_format = %(asctime)s, %(origin)s, %(levelname)s, %(message)s