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.
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.
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

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, rhs)	Highly-configurable floating point comparisons for scalars and arrays.
assertFloatsNotEqual(testCase, lhs, rhs, **kwds)	Fail a test if the given floating point values are equal to within the given tolerances.
assertFloatsEqual(testCase, lhs, rhs, **kwargs)	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, 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.

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

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.
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, 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

getVersionFromPythonModule(module)	Determine the version of a python module.
getPythonPackages()	Get imported python packages and their versions.
getEnvironmentPackages([include_all])	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.