tree Reference

Tree

class tree.tree.Tree(config=None, key=None, uproot_with=None, update=None, exclude=None, product_root=None, git=None)[source]

Bases: object

Initialize the sdss tree object

This class provides Python programmatic access to the SDSS tree envionment structure

Parameters:
  • key (str | list) – A section or list of sections of the tree to add into the local environment

  • uproot_with (str) – A new TREE_DIR path used to override an existing TREE_DIR environment variable

  • config (str) – Name of manual config file to load. Default is sdsswork.

  • update (bool) – If True, overwrites existing tree environment variables in your local environment. Default is False.

  • exclude (list) – A list of environment variables to exclude from forced updates

  • root (str) – An absolute directory path to override as the software product root

  • git (bool) – If True, looks for SDSS_GIT_ROOT environment variable as product root instead of SDSS_SVN_ROOT

Variables:
  • treedir (str) – The directory of the tree

  • sasbasedir (str) – The root directory of SAS

  • productroot_dir (str) – The root directory of installed software products from svn or github

  • environ (dict) – All of the environment paths defnined in the currntly loaded SDSS configuration file

  • paths (dict) – All of the sdss_access paths defined in the currently loaded configuration

  • phase (int) – Which SDSS phase the currently loaded config belongs to

add_limbs(key=None)[source]

Add a new section from the tree into the existing os environment

Parameters:

key (str) – The section name to grab from the environment

add_paths_to_os(key=None, update=None)[source]

Add the paths in tree environ into the os environ

This code goes through the tree environ and checks for existence in the os environ, then adds them

Parameters:
  • key (str) – The section name to check against / add

  • update (bool) – If True, overwrites existing tree environment variables in your local environment. Default is False.

branch_out(limb=None)[source]

Set the individual section branches

This adds the various sections of the config file into the tree environment for access later. Optionally can specify a specific branch. This does not yet load them into the os environment.

Parameters:

limb (str | list) – A section or lists of sections of the config to add into the environ

check_missing_path_envvars()[source]

Checks paths envars against main envvar list

Extracts the used environment variables from all the sdss_access path definitions in tree.paths, and checks them against the list of defined environment variables in tree.environ. Returns a list of any path environment variables that are missing from the valid definitions in the environment.

Returns:

list – A list of missing environment variables

classmethod get_available_releases(public=None)[source]

Get the available releases

Parameters:

public (bool) – If True, only return public data releases

static get_orig_os_environ()[source]

Returns the original os.environ

get_paths(key)[source]

Retrieve a set of environment paths from the config

Parameters:

key (str) – The section name to grab from the environment

Returns:

dict – An ordered dict containing all of the paths from the specified section, as key:val = name:path

static get_product_root(root=None, git=None)[source]

Get the sdss product root used for svn/git products

Attempts to extract the root directory for SDSS-installed git/svn products. Uses the following environment variables in order of precendence: PRODUCT_ROOT, SDSS_SVN_ROOT, SDSS_INSTALL_PRODUCT_ROOT, SDSS_PRODUCT_ROOT, SDSS4_PRODUCT_ROOT. If no root is found uses one directory up from SAS_BASE_DIR.

Parameters:
  • root (str) – An absolute directory path to override as the product root

  • git (bool) – If True, looks for SDSS_GIT_ROOT environment variable as product root.

Returns:

dict – The directory path to sdss-installed svn/git products

get_release_from_config() str[source]

Get a release name from a config

Convert a config name into its valid release name. All “work” config, i.e. “sdsswork”, belong to the “WORK” release.

Returns:

str – the release name

identify_envvar(file)[source]

Identifies the environment variable used in a file path

identify_section(envvar, guess=False)[source]

Identifies the tree ini section from an environment variable

static list_available_configs()[source]

List the available config files able to be loaded

list_configs()[source]

List available configs to load

list_keys()[source]

List the available keys you can load

load_config(config=None)[source]

Load a config file

Parameters:

config (str) – Optional name of manual config file to load

replant_tree(config=None, exclude=None, preserve_envvars=None)[source]

Replant the tree with a different config setup

Resets the python tree with the new config. Automatically updates the session os.environ with the new tree config environment variables. If preserve_envvars is set to True, preserves the original os environ during tree update. If preserve_envvars is set to a list of environment variables, preserves only that subset.

Parameters:
  • config (str) – The config name to reload

  • exclude (list) – A list of environment variables to exclude from forced updates

  • preserve_envvars (bool | list) – Flag to indicate some or all original environment variables to preserve

static reset_os_environ()[source]

Resets os.environ with the orignal cache before tree mods

set_product_root(root=None, git=None)[source]

Sets the sdss product root used for svn/git products

Sets the root directory for SDSS-installed git/svn products as the $PRODUCT_ROOT environment variable. Attempts to find a viable $PRODUCT_ROOT using get_product_method. Viable product roots in order of precendence: SDSS_SVN_ROOT, SDSS_INSTALL_PRODUCT_ROOT, SDSS_PRODUCT_ROOT, SDSS4_PRODUCT_ROOT. If no root is found uses one directory up from SAS_BASE_DIR.

Parameters:
  • root (str) – An absolute directory path to override as the product root

  • git (bool) – If True, looks for SDSS_GIT_ROOT environment variable as product root.

set_roots(uproot_with=None)[source]

Set the roots of the tree in the os environment

Parameters:

uproot_with (str) – A new TREE_DIR path used to override an existing TREE_DIR environment variable

show_forest(config=None)[source]

Show the environment for a specified config

Creates a dictionary environment for each config in the list of available configurations.

Parameters:

config (str) – The config to show

Returns:

dict – A dictionary of config environment(s)

to_dict(collapse=True)[source]

Convert tree environment to standard dicts

Converts the nested tree.environ into a series of ordinary dicts.

Parameters:

collapse (bool) – If True, collapses nested dicts into a single dict. Default is True.

write_old_paths_inifile(no_pipe=None)[source]

Write out an old sdss_paths ini file

New syntax for special functions is “@[name]|” compared to old syntax of “%[name]”. With no_pipe set to True, converts the new syntax to exactly the old syntax. If set to False, will write special functions as “%[name]|”.

Parameters:

no_pipe (bool) – If True, removes the special function | character

property phase

Return the phase of the survey from the loaded “work” environment

property release_date

Return the release date of the tree configuration

tree.tree.get_envvar_history(name: str) dict[source]

Get the history of a given environment variable

Returns a dictionary of the given environment variable definition in all available tree config files.

Parameters:

name (str) – The name of the environment variable

Returns:

dict – The environment variable definitions in each tree config file

tree.tree.get_path_history(name: str) dict[source]

Get the history of a given access path name

Returns a dictionary of the given acess path definition in all available tree config files.

Parameters:

name (str) – The name of the access path

Returns:

dict – The path definitions in each tree config file

tree.tree.get_tree_dir(uproot_with=None)[source]

Return the path to the tree product directory

Parameters:

uproot_with (str) – A new TREE_DIR path used to override an existing TREE_DIR environment variable

Returns:

str – The path to the tree python product directory

Changelog Utilities

tree.changelog.compute_changelog(new, old, pprint=None, to_list=None, remove_sas=True, include_paths=True, paths_only=None)[source]

Compute the difference between two Tree environments

Finds and prints the difference between two tree environment configurations. Accepts either string names of config files, e.g. “dr16” and “dr15”, or the preloaded Tree configs, e.g. Tree(config='dr16'). By default returns a dictionary of changes or use the pprint keyword to return a formatted print-friendly string for display. The to_list keyword returns a print-formatted list of strings parse parseable by docutree for Sphinx docs. Set include_paths to True to include a changelog of the sdss_access path definitions.

Parameters:
  • new (str|Tree) – The new tree enviroment to compare

  • old (str|Tree) – The old tree environment to compare

  • pprint (bool) – If True, returns a single joined string for printing. Default is False.

  • to_list (bool) – If True, returns a list of strings formatted for printing. Default is False.

  • remove_sas (bool) – If True, removes the SAS_BASE_DIR from environment values. Default is True.

  • include_paths (bool) – If True, includes changes to the sdss_access PATHS section. Default is True.

  • paths_only (bool) – If True, returns only changes in sdss_access PATHS section. Default is False.

Returns:

A dictionary of relevant changes between the two releases

Example

>>> # print the differences DR16 and DR15
>>> diffs = compute_changelog('dr16', 'dr15', pprint=True)
>>> print(diffs)
tree.changelog.compute_environment_changes(new, old, remove_sas=True)[source]

Compute the difference between two Tree environments

Compares two tree environment configurations and returns a dictionary with keys new, removed, and changes indicating newly added environments, newly removed environments, and environments where environment variable definitions have changed. Accepts either string names of config files, e.g. “dr16” and “dr15”, or the preloaded Tree configs, e.g. Tree(config='dr16').

Parameters:
  • new (str|Tree) – The new tree enviroment to compare

  • old (str|Tree) – The old tree environment to compare

  • remove_sas (bool) – If True, removes the SAS_BASE_DIR from environment values. Default is True.

Returns:

A dictionary of relevant changes between the two releases

tree.changelog.compute_path_changes(new, old, prepend_header=None)[source]

Compute the difference between two Tree PATH sections

Compares two tree PATH ini sections from the given environment configurations and returns adictionary with keys new, and updated, indicating newly added paths, and any paths that have been modified from the last release. Accepts either string names of config files, e.g. “dr16” and “dr15”, or the preloaded Tree configs, e.g. Tree(config='dr16').

Parameters:
  • new (str|Tree) – The new tree enviroment to compare

  • old (str|Tree) – The old tree environment to compare

  • prepend_header (bool) – If True, adds a header to the diff with release versions

Returns:

A dictionary of relevant changes between the two releases

tree.changelog.print_environment(changes, to_string=None)[source]

Print the environment changelog

Formats the changelog into a print-friendly list of strings.

Parameters:
  • changes (dict) – A dictionary of changes between two releases

  • to_string (bool) – If True, returns a single string

Returns:

A string list of print-formatted changes

tree.changelog.print_paths(changes, to_string=None, prepend_header=None)[source]

Print the path changelog

Formats the changelog into a print-friendly list of strings.

Parameters:
  • changes (dict) – A dictionary of changes between two releases

  • to_string (bool) – If True, returns a single string

Returns:

A string list of print-formatted changes