labscript_utils.versions

exception labscript_utils.versions.BrokenInstall

class labscript_utils.versions.NoVersionInfo

class labscript_utils.versions.NotFound

exception labscript_utils.versions.VersionException

labscript_utils.versions._get_literal_version(filename)

Tokenize a source file and return any __version__ = <version> literal defined in it.

Parameters

filename (str) – The path to the file to tokenize.

Returns

Any version literal found matching the above criteria, or None.

labscript_utils.versions._get_metadata_version(project_name, import_path)

Gets the package metadata version.

Parameters

• project_name (str) – The package name (e.g. the name used when pip installing the package).

• import_path (str) – The path to the folder containing the installed package.

Raises

BrokenInstall – Raised if the package installation is corrupted (multiple packages matching the given arguments were found). May occur if (un)installation for a particular package version only partially completed.

Returns

The metadata version for a package with the given project name located at the given import path, or None if there is no such package.

labscript_utils.versions.check_version(module_name, at_least, less_than, version=None, project_name=None)

Checks if a module version is within specified bounds.

Checks that the version of the given module is at least and less than the given version strings. This function uses get_version() to determine version numbers without importing modules. In order to do this, project_name must be provided if it differs from module_name. For example, pyserial is imported as ‘serial’, but the project name, as passed to a ‘pip install’ command, is ‘pyserial’. Therefore to check the version of pyserial, pass in module_name='serial' and project_name='pyserial'. You can also pass in a version string yourself, in which case no inspection of packages will take place.

Parameters

• module_name (str) – The name of the module to check.

• at_least (str) – The minimum acceptable module version.

• less_than (str) – The minimum unacceptable module version. Usually this would be the next major version if the package follows semver.

• version (str, optional) – The current version of the installed package. Useful when the package version is stored in a non-standard location.

• project_name (str, optional) – The package name (e.g. the name used when pip installing the package). This must be specified if it does not match the module name.

Raises

VersionException – if the module was not found or its version could not be determined.

labscript_utils.versions.get_import_path(import_name)

Get which entry in sys.path a module would be imported from, without importing it.

Parameters

import_name (str) – The module name.

Raises

• ModuleNotFoundError – Raised if the module is not installed.

• NotImplementedError – Raised if the module is a “namespace package”. Support for namepsace packages is not currently availabled.

Returns

The path to the folder containing the module.

Return type

str

labscript_utils.versions.get_version(import_name, project_name=None, import_path=None)

Try very hard to get the version of a package without importing it.

If import_path is not given, first find where it would be imported from, without importing it. Then look for metadata in the same import path with the given project name (note: this is not always the same as the import name, it is the name for example you would ask pip to install). If that is found, return the version info from it. Otherwise look for a __version__.py file in the package directory, or a __version__ = <version> literal defined in the package source (without executing it).

Parameters

• import_name (str) – The module name.

• project_name (str, optional) – The package name (e.g. the name used when pip installing the package). This must be specified if it does not match the module name.

• import_path (str, optional) – The path to the folder containing the installed package.

Raises

NotImplementedError – Raised if the module name contains a period. Only top-level packages are supported at this time.

Returns

The version literal of the package. If the package cannot be found, NotFound is returned. If the version cannot be obtained in the above way, or if the version was found but was None, NoVersionInfo is returned.