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.

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.