Finding dependencies

The dependency_finder sub-package attempts to determine all the dependencies of a given script, including the version of each dependency.

For each executable that is supported there is a sub-module containing a find_dependencies() function, and a series of heuristics for finding version information. There is also a sub-module core, which contains heuristics that are independent of the language, e.g. where the dependencies are under version control.

copyright:

Copyright 2006-2020, 2024 by the Sumatra team, see doc/authors.txt

license:

BSD 2-clause, see LICENSE for details.

For users of the API, the principal function of interest is the following.

sumatra.dependency_finder.find_dependencies(filename, executable)

Return a list of dependencies for a given script and programming language.

filename:

the path to the script whose dependencies should be found.

executable:

an instance of Executable or one of its subclasses.

This function returns a list of Dependency objects. There is a different Dependency subclass for each programming language, but all have the following attributes:

class sumatra.dependency_finder.core.BaseDependency(name, path=None, version='unknown', diff='', source=None)

Contains information about a program component, and tries to determine version information.

name:

an identifying name, e.g. the module name in Python

path:

the location of the dependency file in the local filesystem

version:

the version of the dependency, if that can be determined, otherwise ‘unknown’. Always a string, even if the version can also be represented as a number.

diff:

if the dependency is under version control and has been modified, the diff between the actual version and the last-committed version.

source:

an identifier for where the dependency came from, if known, e.g. the url of a version control repository or the name of a Linux package.

If you are interested in improving the dependency finder for an existing program/language, or in adding a dependency finder for a new program or language, you may be interested in the following.

Language-independent heuristics and utilities

sumatra.dependency_finder.core.find_versions(dependencies, heuristics)

Try to find version information by calling a series of functions in turn.

dependencies:

a list of Dependency objects.

heuristics:

a list of functions that accept a component as the single argument and return a version number or ‘unknown’.

Returns a possibly modified list of dependencies

sumatra.dependency_finder.core.find_versions_from_versioncontrol(dependencies)

Determine whether a file is under version control, and if so, obtain version information from this.

sumatra.dependency_finder.core.find_file(path, current_directory, search_dirs)

Look for path as an absolute path then relative to the current directory, then relative to search_dirs. Return the absolute path.

Python

sumatra.dependency_finder.python.find_versions_by_attribute(dependencies, executable)

Try to find version information from the attributes of a Python module.

sumatra.dependency_finder.python.find_versions_from_egg(dependencies)

Determine whether a Python module is provided as an egg, and if so, obtain version information from this.

sumatra.dependency_finder.python.find_imported_packages(filename, executable_path, debug=0, exclude_stdlib=True)

Find all imported top-level packages for a given Python file.

We cannot assume that the version of Python being used to run Sumatra is the same as that used to run the simulation/analysis. Therefore we need to run all the dependency finding and version checking in a subprocess with the correct version of Python.

sumatra.dependency_finder.python.find_dependencies(filename, executable)

Return a list of Dependency objects representing all the top-level modules or packages imported (directly or indirectly) by a given Python file.

Matlab

sumatra.dependency_finder.matlab.find_dependencies(filename, executable)

sumatra.dependency_finder.matlab.save_dependencies(cmd, filename)

save all dependencies to the file in the current folder

NEURON

sumatra.dependency_finder.neuron.find_xopened_files(file_path)

Find all files that are xopened, whether directly or indirectly, by a given Hoc file. Note that this only handles cases whether the path is given directly, not where it has been previously assigned to a strdef.

sumatra.dependency_finder.neuron.find_loaded_files(file_path, executable_path)

Find all files that are loaded with load_file(), whether directly or indirectly, by a given Hoc file. Note that this only handles cases whether the path is given directly, not where it has been previously assigned to a strdef. Also note that this is more complicated than xopen(), since NEURON also looks in any directories in $HOC_LIBRARY_PATH and $NEURONHOME/lib/hoc.

sumatra.dependency_finder.neuron.find_dependencies(filename, executable)

Return a list of Dependency objects representing all Hoc files imported (directly or indirectly) by a given Hoc file.

GENESIS

sumatra.dependency_finder.genesis.find_included_files(file_path)

Find all files that are included, whether directly or indirectly, by a given .g file.

sumatra.dependency_finder.genesis.find_dependencies(filename, executable)

Return a list of Dependency objects representing all files included, whether directly or indirectly, by a given .g file.

R

sumatra.dependency_finder.r.find_dependencies(filename, executable)

Return list of dependencies.

First determines dependency info for filename. This is done through an external call (using the Rscript from exectuable.path) to a custom R script that uses parse and simple pattern-matching to find all calls in filename that load external packages (i.e., the R calls “library” and “require”). The result is returned in a string with package info delimited by pre-set tokens. Info includes: name, version, local path, and repo source (repo name but no URLs).

Second, parses the dependency info into Dependency objects, returned in a list.