lsst.utils

The lsst.utils module provides common code for tests, interfacing between C++ and Python, and debugging.

Changes

• lsst-utils v29.1.1 (2025-06-19)
• lsst-utils v29.1.0 (2025-05-22)
• lsst-utils v29.0.0 (2025-03-24)
• lsst-utils v28.0.0 (2024-11-19)
• lsst-utils 27.0.0 (2024-05-28)
• lsst-utils v26.0.0 (2023-09-22)
• lsst-utils v25.0.0 (2023-02-17)
• lsst-utils v24.0.0 (2022-08-26)
• lsst-utils v23.0.0 (2021-09-27)
• lsst-utils v22.0 (2021-07-09)
• lsst-utils v21.0 (2020-12-08)

Contributing

lsst.utils is developed at https://github.com/lsst/utils. You can find Jira issues for this module under the utils component.

Python API reference

lsst.utils Package

Functions

continueClass(cls)	Re-open the decorated class, adding any new definitions into the original.
deprecate_pybind11(obj, reason, version[, ...])	Deprecate a pybind11-wrapped C++ interface function, method or class.
doImport(importable)	Import a python object given an importable string and return it.
doImportType(importable)	Import a python type given an importable string and return it.
getPackageDir(package_name)	Find the file system location of the EUPS package.
inClass(cls[, name])	Add the decorated function to the given class as a method.
inheritDoc(klass)	Extend existing documentation for a method that exists in another class and extend it with any additional documentation defined.
suppress_deprecations([category])	Suppress warnings generated by deprecated.sphinx.deprecated.

Classes

TemplateMeta(name, bases, attrs)

A metaclass for abstract base classes that tie together wrapped C++ template types.

Class Inheritance Diagram

lsst.utils.tests Module

Functions

assertFloatsAlmostEqual(testCase, lhs, rhs)	Highly-configurable floating point comparisons for scalars and arrays.
assertFloatsEqual(testCase, lhs, rhs, **kwargs)	Assert that lhs == rhs (both numeric types, whether scalar or array).
assertFloatsNotEqual(testCase, lhs, rhs, **kwds)	Fail a test if the given floating point values are equal to within the given tolerances.
classParameters(**settings)	Class decorator for generating unit tests.
debugger(*exceptions)	Enter the debugger when there's an uncaught exception.
getTempFilePath(ext[, expectOutput])	Return a path suitable for a temporary file and try to delete the file on success.
init()	Initialize the memory tester and file descriptor leak tester.
methodParameters(**settings)	Iterate over supplied settings to create subtests automatically.
temporaryDirectory()	Context manager that creates and destroys a temporary directory.

Classes

ExecutablesTestCase([methodName])	Test that executables can be run and return good status.
ImportTestCase([methodName])	Test that the named packages can be imported and all files within that package.
MemoryTestCase([methodName])	Check for resource leaks.
TestCase([methodName])	Subclass of unittest.TestCase that adds some custom assertions for convenience.

Class Inheritance Diagram

lsst.utils.logging Module

Functions

getLogger([name, logger])	Get a logger compatible with LSST usage.
getTraceLogger(logger, trace_level)	Get a logger with the appropriate TRACE name.
trace_set_at(name, number)	Adjust logging level to display messages with the trace number being less than or equal to the provided value.

Classes

LsstLogAdapter(logger[, extra])	A special logging adapter to provide log features for LSST code.
PeriodicLogger(logger[, interval, level])	Issue log messages if a time threshold has elapsed.

Class Inheritance Diagram

lsst.utils.iteration Module

Functions

chunk_iterable(data[, chunk_size])	Return smaller chunks of an iterable.
ensure_iterable(a)	Ensure that the input is iterable.
isplit(string, sep)	Split a string or bytes by separator returning a generator.
sequence_to_string(values)	Convert a list of integers or strings into a compact string representation by merging consecutive values or sequences.

lsst.utils.classes Module

Functions

cached_getter(func)	Decorate a method to cache the result.
immutable(cls)	Decorate a class to simulate a simple form of immutability.

Classes

Singleton

Metaclass to convert a class to a Singleton.

Class Inheritance Diagram

lsst.utils.introspection Module

Functions

find_outside_stacklevel(*module_names[, ...])	Find the stacklevel for outside of the given module.
get_caller_name([stacklevel])	Get the name of the caller method.
get_class_of(typeOrName)	Given the type name or a type, return the python type.
get_full_type_name(cls_)	Return full type name of the supplied entity.
get_instance_of(typeOrName, *args, **kwargs)	Given the type name or a type, instantiate an object of that type.
take_object_census()	Count the number of existing objects, by type.
trace_object_references(target_class[, ...])	Find the chain(s) of references that make(s) objects of a class reachable.

lsst.utils.timer Module

Functions

duration_from_timeMethod(metadata, method_name)	Parse the metadata entries from timeMethod and return a duration.
logInfo(obj, prefix[, logLevel, metadata, ...])	Log timer information to obj.metadata and obj.log.
profile(filename[, log])	Profile the enclosed code block and save the result to a file.
timeMethod([_func, metadata, logger, logLevel])	Measure duration of a method.
time_this([log, msg, level, prefix, args, ...])	Time the enclosed block and issue a log message.

lsst.utils.packages Module

Functions

getAllPythonDistributions()	Get the versions for all Python distributions that are installed.
getCondaPackages()	Get products and their versions from the conda environment.
getEnvironmentPackages([include_all])	Get products and their versions from the environment.
getPythonPackages()	Get imported python packages and their versions.
getVersionFromPythonModule(module)	Determine the version of a python module.

Classes

Packages

A table of packages and their versions.

Class Inheritance Diagram

lsst.utils.usage Module

Functions

get_current_mem_usage()	Report current memory usage.
get_peak_mem_usage()	Report peak memory usage.

lsst.utils.threads Module

Functions

disable_implicit_threading()	Do whatever is necessary to try to prevent implicit threading.
set_thread_envvars([num_threads, override])	Set common threading environment variables to the given value.