cape.capeconfig: Interface to user-specific CAPE configuration

This file reads the settings file in either ~/.capeconfig.json or $CAPE_CONFIGFILE, as controlled by cape.sysutils. It provides the class CapeConfig. The purpose of this configuration file is to set user-specific preferences and SSH paths.

For example, on Linux, the user may specify a preferred PDF reader application. Users may also inform the user of their local workstation so that commands like cape open-pdf $PDFFILE will first send them from an HPC login node to a local workstation and open it there.

class cape.capeconfig.CapeConfig(*args, **kw)

Bases: OptionsDict

check_local() → bool

Check if the current host is “local”

Call:

>>> q = opts.check_local()

Inputs:

opts: CapeConfig

Cape configuration options instance

Outputs:

q: True | False

Whether current host is “local”

check_remote() → bool

Check if the current host is “remote”

Call:

>>> q = opts.check_remote()

Inputs:

opts: CapeConfig

Cape configuration options instance

Outputs:

q: True | False

Whether current host is “remote”

get_CacheDir(j=None, i=None, **kw)

Get Location for CAPE to cache files

Call:

>>> CacheDir = opts.get_CacheDir(j=None, i=None, **kw)

Inputs:

opts: CapeConfig

options interface

j: {None} | int

Phase index; use None to just return v

i: {None} | int | np.ndarray

opts.x index(es) to use with @expr, @map, etc.

vdef: {None} | object

Manual default

mode: {None} | 0 | 1 | 2 | 3

Warning mode code

0:

no checks

1:

validate silently

2:

validate and show warnings

3:

raise an exception if invalid

ring: {opts._optring[key]} | True | False

Override option to loop through phase inputs

listdepth: {0} | int > 0

Depth of list to treat as a scalar

x: {None} | dict

Ref conditions to use with @expr, @map, etc.; often a run matrix; used in combination with i

sample: {True} | False

Apply j, i, and other settings recursively if output is a list or dict

Outputs:

CacheDir: {'~/.cache/cape'} | str

Location for CAPE to cache files

get_JumpHost() → str | None

Get name of SSH JumpHost needed to transfer files

The result is based on the name of the current host

Call:

>>> jumphost = opts.get_JumpHost()

Inputs:

opts: CapeConfig

Cape configuration options instance

Outputs:

jumphost: None | str

Name of jump host, if any

get_LocalHost(j=None, i=None, **kw)

Get Name of ‘local’ machine; CAPE on remote systems will transfer files to this location for easier viewing. Override with $CAPE_LOCAL_HOST

Call:

>>> LocalHost = opts.get_LocalHost(j=None, i=None, **kw)

Inputs:

opts: CapeConfig

options interface

j: {None} | int

Phase index; use None to just return v

i: {None} | int | np.ndarray

opts.x index(es) to use with @expr, @map, etc.

vdef: {None} | object

Manual default

mode: {None} | 0 | 1 | 2 | 3

Warning mode code

0:

no checks

1:

validate silently

2:

validate and show warnings

3:

raise an exception if invalid

ring: {opts._optring[key]} | True | False

Override option to loop through phase inputs

listdepth: {0} | int > 0

Depth of list to treat as a scalar

x: {None} | dict

Ref conditions to use with @expr, @map, etc.; often a run matrix; used in combination with i

sample: {True} | False

Apply j, i, and other settings recursively if output is a list or dict

Outputs:

LocalHost: {None} | str

Name of ‘local’ machine; CAPE on remote systems will transfer files to this location for easier viewing. Override with $CAPE_LOCAL_HOST

get_LocalHostPatterns(j=None, i=None, **kw)

Get List of regexes to tell CAPE that current host is ‘local.’

Call:

>>> LocalHostPatterns = opts.get_LocalHostPatterns(j=None, i=None, **kw)

Inputs:

opts: CapeConfig

options interface

j: {None} | int

Phase index; use None to just return v

i: {None} | int | np.ndarray

opts.x index(es) to use with @expr, @map, etc.

vdef: {None} | object

Manual default

mode: {None} | 0 | 1 | 2 | 3

Warning mode code

0:

no checks

1:

validate silently

2:

validate and show warnings

3:

raise an exception if invalid

ring: {opts._optring[key]} | True | False

Override option to loop through phase inputs

listdepth: {0} | int > 0

Depth of list to treat as a scalar

x: {None} | dict

Ref conditions to use with @expr, @map, etc.; often a run matrix; used in combination with i

sample: {True} | False

Apply j, i, and other settings recursively if output is a list or dict

Outputs:

LocalHostPatterns: {None} | list[str]

List of regexes to tell CAPE that current host is ‘local.’

get_PDFReader() → str | None

get_PNGReader() → str | None

get_RemoteHost(j=None, i=None, **kw)

Get Remote host for cape receive-file to get files from. Override with $CAPE_REMOTE_HOST.

Call:

>>> RemoteHost = opts.get_RemoteHost(j=None, i=None, **kw)

Inputs:

opts: CapeConfig

options interface

j: {None} | int

Phase index; use None to just return v

i: {None} | int | np.ndarray

opts.x index(es) to use with @expr, @map, etc.

vdef: {None} | object

Manual default

mode: {None} | 0 | 1 | 2 | 3

Warning mode code

0:

no checks

1:

validate silently

2:

validate and show warnings

3:

raise an exception if invalid

ring: {opts._optring[key]} | True | False

Override option to loop through phase inputs

listdepth: {0} | int > 0

Depth of list to treat as a scalar

x: {None} | dict

Ref conditions to use with @expr, @map, etc.; often a run matrix; used in combination with i

sample: {True} | False

Apply j, i, and other settings recursively if output is a list or dict

Outputs:

RemoteHost: {None} | str

Remote host for cape receive-file to get files from. Override with $CAPE_REMOTE_HOST.

get_RemoteHostPatterns(j=None, i=None, **kw)

Get List of regexes for host names to tell CAPE that current host is ‘remote’; cape post-file and cape receive-file will not transfer files.

Call:

>>> RemoteHostPatterns = opts.get_RemoteHostPatterns(j=None, i=None, **kw)

Inputs:

opts: CapeConfig

options interface

j: {None} | int

Phase index; use None to just return v

i: {None} | int | np.ndarray

opts.x index(es) to use with @expr, @map, etc.

vdef: {None} | object

Manual default

mode: {None} | 0 | 1 | 2 | 3

Warning mode code

0:

no checks

1:

validate silently

2:

validate and show warnings

3:

raise an exception if invalid

ring: {opts._optring[key]} | True | False

Override option to loop through phase inputs

listdepth: {0} | int > 0

Depth of list to treat as a scalar

x: {None} | dict

Ref conditions to use with @expr, @map, etc.; often a run matrix; used in combination with i

sample: {True} | False

Apply j, i, and other settings recursively if output is a list or dict

Outputs:

RemoteHostPatterns: {None} | list[str]

List of regexes for host names to tell CAPE that current host is ‘remote’; cape post-file and cape receive-file will not transfer files.

get_opt(opt: str, vdef=None, **kw) → Any

Get value of an option with environment var override

Call:

>>> v = opts.get_opt(opt, vdef=None)

Inputs:

opts: CapeConfig

Cape configuration options instance

vdef: {None} | any

Default value

Outputs:

v: any

Option value, with following order of importance

1. Environment variable

2. Value set in ~/.capeconfig

3. Default value from class

4. vdef

set_CacheDir(v, j=None, mode=None)

Get Location for CAPE to cache files

Call:

>>> opts.set_CacheDir(CacheDir, j=None, i=None, **kw)

Inputs:

opts: CapeConfig

options interface

CacheDir: {'~/.cache/cape'} | str

Location for CAPE to cache files

j: {None} | int

Phase index; use None to just return v

mode: {None} | 0 | 1 | 2 | 3

Warning mode code

0:

no checks

1:

validate silently

2:

validate and show warnings

3:

raise an exception if invalid

listdepth: {0} | int > 0

Depth of list to treat as a scalar

set_LocalHost(v, j=None, mode=None)

Get Name of ‘local’ machine; CAPE on remote systems will transfer files to this location for easier viewing. Override with $CAPE_LOCAL_HOST

Call:

>>> opts.set_LocalHost(LocalHost, j=None, i=None, **kw)

Inputs:

opts: CapeConfig

options interface

LocalHost: {None} | str

Name of ‘local’ machine; CAPE on remote systems will transfer files to this location for easier viewing. Override with $CAPE_LOCAL_HOST

j: {None} | int

Phase index; use None to just return v

mode: {None} | 0 | 1 | 2 | 3

Warning mode code

0:

no checks

1:

validate silently

2:

validate and show warnings

3:

raise an exception if invalid

listdepth: {0} | int > 0

Depth of list to treat as a scalar

set_LocalHostPatterns(v, j=None, mode=None)

Get List of regexes to tell CAPE that current host is ‘local.’

Call:

>>> opts.set_LocalHostPatterns(LocalHostPatterns, j=None, i=None, **kw)

Inputs:

opts: CapeConfig

options interface

LocalHostPatterns: {None} | list[str]

List of regexes to tell CAPE that current host is ‘local.’

j: {None} | int

Phase index; use None to just return v

mode: {None} | 0 | 1 | 2 | 3

Warning mode code

0:

no checks

1:

validate silently

2:

validate and show warnings

3:

raise an exception if invalid

listdepth: {0} | int > 0

Depth of list to treat as a scalar

set_PDFReader(v, j=None, mode=None)

Get Preferred PDF reader. Override with $CAPE_PDF_READER.

Call:

>>> opts.set_PDFReader(PDFReader, j=None, i=None, **kw)

Inputs:

opts: CapeConfig

options interface

PDFReader: {None} | str

Preferred PDF reader. Override with $CAPE_PDF_READER.

j: {None} | int

Phase index; use None to just return v

mode: {None} | 0 | 1 | 2 | 3

Warning mode code

0:

no checks

1:

validate silently

2:

validate and show warnings

3:

raise an exception if invalid

listdepth: {0} | int > 0

Depth of list to treat as a scalar

set_PNGReader(v, j=None, mode=None)

Get Preferred PNG image viewer. Override with $CAPE_PNG_READER.

Call:

>>> opts.set_PNGReader(PNGReader, j=None, i=None, **kw)

Inputs:

opts: CapeConfig

options interface

PNGReader: {None} | str

Preferred PNG image viewer. Override with $CAPE_PNG_READER.

j: {None} | int

Phase index; use None to just return v

mode: {None} | 0 | 1 | 2 | 3

Warning mode code

0:

no checks

1:

validate silently

2:

validate and show warnings

3:

raise an exception if invalid

listdepth: {0} | int > 0

Depth of list to treat as a scalar

set_RemoteHost(v, j=None, mode=None)

Get Remote host for cape receive-file to get files from. Override with $CAPE_REMOTE_HOST.

Call:

>>> opts.set_RemoteHost(RemoteHost, j=None, i=None, **kw)

Inputs:

opts: CapeConfig

options interface

RemoteHost: {None} | str

Remote host for cape receive-file to get files from. Override with $CAPE_REMOTE_HOST.

j: {None} | int

Phase index; use None to just return v

mode: {None} | 0 | 1 | 2 | 3

Warning mode code

0:

no checks

1:

validate silently

2:

validate and show warnings

3:

raise an exception if invalid

listdepth: {0} | int > 0

Depth of list to treat as a scalar

set_RemoteHostPatterns(v, j=None, mode=None)

Get List of regexes for host names to tell CAPE that current host is ‘remote’; cape post-file and cape receive-file will not transfer files.

Call:

>>> opts.set_RemoteHostPatterns(RemoteHostPatterns, j=None, i=None, **kw)

Inputs:

opts: CapeConfig

options interface

RemoteHostPatterns: {None} | list[str]

List of regexes for host names to tell CAPE that current host is ‘remote’; cape post-file and cape receive-file will not transfer files.

j: {None} | int

Phase index; use None to just return v

mode: {None} | 0 | 1 | 2 | 3

Warning mode code

0:

no checks

1:

validate silently

2:

validate and show warnings

3:

raise an exception if invalid

listdepth: {0} | int > 0

Depth of list to treat as a scalar

class cape.capeconfig.JumpHostConfig(*args, **kw)

Bases: OptionsDict

cape.capeconfig.check_cape_local() → bool

Check if the current host is “local”

Call:

>>> q = check_cape_local()

Outputs:

q: True | False

Whether current host is “local”

cape.capeconfig.check_cape_remote() → bool

Check if the current host is “remote”

Call:

>>> q = check_cape_remote()

Outputs:

q: True | False

Whether current host is “remote”

cape.capeconfig.get_cape_cachedir() → str

Get (and create) cache folder

The order of precedence is

1. The environment variable $CAPE_CACHE_DIR

2. The CacheDir setting in ~/.capeconfig.json

3. The global default ~/.cache/cape/

Call:

>>> cachedir = get_cape_cachedir()

Outputs:

cachedir: str

Location of cache to use for temporary CAPE files

cape.capeconfig.get_cape_configfile() → str

cape.capeconfig.get_cape_jumphost() → str | None

Get JumpHost for SSH to reach intended target, based on $HOST

Call:

>>> jumphost = get_cape_jumphost()

Outputs:

jumphost: None | str

Name of SSH JumpHost needed, if needed

cape.capeconfig.get_cape_opt(opt: str)

Get a CAPE user configuration option

Call:

>>> v = get_cape_opt(opt)

Inputs:

opt: str

Name of option

Outputs:

v: str | list | dict

Value of option

cape.capeconfig.get_pdf_viewer() → str

Get the preferred PDF viewer application based on system

Call:

>>> viewer = get_pdf_viewer()

Outputs:

viewer: str

Name of application to open PDF

Versions:

• 2026-08-07 @ddalle: v1.0

cape.capeconfig.get_png_viewer() → str

Get the preferred PNG viewer application based on system

Call:

>>> viewer = get_png_viewer()

Outputs:

viewer: str

Name of application to open PNG

Versions:

• 2026-08-31 @ddalle: v1.0

cape.capeconfig.read_cape_config() → CapeConfig

Read config from ~/.capeconfig.json or $CAPE_CONFIG_FILE

Call:

>>> opts = read_cape_config()

Outputs:

opts: CapeConfig

CAPE user settings

cape.capeconfig.set_cape_opt(opt: str, v: Any, blend: bool = False)

Set (or blend) a CAPE user configuration option

Call:

>>> set_cape_opt(opt, v, blend=False)

Inputs:

opt: str

Name of option

v: str

Value to set

blend: True | {False}

Combine user’s option with existing for list | dict

cape.capeconfig.show_cape_config(opt: str) → str

Get a CAPE user configuration option as a string

Call:

>>> txt = show_cape_config(opt)

Inputs:

opt: str

Name of option

Outputs:

txt: str

Value of option