lsst.utils

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

Changes

• 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.
demangleType(type_name)	Demangle a C++ type string.
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.
get_caller_name(skip)	Get the name of the caller method.
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.
isEnabled()	Check that backtrace is enabled.
suppress_deprecations(category)	Suppress warnings generated by deprecated.sphinx.deprecated.

Classes

TemplateMeta

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

Class Inheritance Diagram

lsst.utils.tests Module

Functions

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

Classes

MemoryTestCase([methodName])	Check for resource leaks.
ExecutablesTestCase([methodName])	Test that executables can be run and return good status.
TestCase([methodName])	Subclass of unittest.TestCase that adds some custom assertions for convenience.

Class Inheritance Diagram

lsst.utils.logging Module

Functions

getLogger(name, None] = None, logger, …)	Get a logger compatible with LSST usage.
getTraceLogger(logger, logging.Logger, …)	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, …)	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.

lsst.utils.classes Module

Functions

cached_getter(func, _R])	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

get_class_of(typeOrName, str])	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, str], *args, …)	Given the type name or a type, instantiate an object of that type.
get_caller_name(stacklevel)	Get the name of the caller method.

lsst.utils.timer Module

Functions

profile(filename, log)	Profile the enclosed code block and save the result to a file.
logInfo(obj, prefix, logLevel, metadata, …)	Log timer information to obj.metadata and obj.log.
timeMethod(_func, None] = None, *, metadata, …)	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

getVersionFromPythonModule(module)	Determine the version of a python module.
getPythonPackages()	Get imported python packages and their versions.
getEnvironmentPackages	Get products and their versions from the environment.
getCondaPackages	Get products and their versions from the conda environment.

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

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

lsst.utils.ellipsis Module

A type-annotation workaround for ... not having an exposed type in Python.

This module provides Ellipsis and EllipsisType symbols that are conditionally defined to point to the built-in “...” singleton and its type (respectively) at runtime, and an enum class and instance if typing.TYPE_CHECKING is True (an approach first suggested here). Type checkers should recognize enum literals as singletons, making this pair behave as expected under is comparisons and type-narrowing expressions, such as:

v: EllipsisType | int
if v is not Ellipsis:
    v += 2  # type checker should now see v as a pure int

This works best when there is a clear boundary between code that needs to be type-checked and can use Ellipsis instead of a literal “...”, and calling code that is either not type-checked or uses typing.Any to accept literal “...” values.