lsst.utils

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

Changes

• 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

digraph inheritance427d8f8179 { bgcolor=transparent; rankdir=LR; size="8.0, 12.0"; "TemplateMeta" [URL="../../../py-api/lsst.utils.TemplateMeta.html#lsst.utils.TemplateMeta",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="A metaclass for abstract base classes that tie together wrapped C++"]; }

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.
ImportTestCase([methodName])	Test that the named packages can be imported and all files within that package.
TestCase([methodName])	Subclass of unittest.TestCase that adds some custom assertions for convenience.

Class Inheritance Diagram

digraph inheritancea7d49b55f8 { bgcolor=transparent; rankdir=LR; size="8.0, 12.0"; "ExecutablesTestCase" [URL="../../../py-api/lsst.utils.tests.ExecutablesTestCase.html#lsst.utils.tests.ExecutablesTestCase",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="Test that executables can be run and return good status."]; "TestCase" -> "ExecutablesTestCase" [arrowsize=0.5,style="setlinewidth(0.5)"]; "ImportTestCase" [URL="../../../py-api/lsst.utils.tests.ImportTestCase.html#lsst.utils.tests.ImportTestCase",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="Test that the named packages can be imported and all files within"]; "TestCase" -> "ImportTestCase" [arrowsize=0.5,style="setlinewidth(0.5)"]; "MemoryTestCase" [URL="../../../py-api/lsst.utils.tests.MemoryTestCase.html#lsst.utils.tests.MemoryTestCase",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="Check for resource leaks."]; "TestCase" -> "MemoryTestCase" [arrowsize=0.5,style="setlinewidth(0.5)"]; "TestCase" [URL="../../../py-api/lsst.utils.tests.TestCase.html#lsst.utils.tests.TestCase",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="Subclass of unittest.TestCase that adds some custom assertions for"]; "TestCase" -> "TestCase" [arrowsize=0.5,style="setlinewidth(0.5)"]; "TestCase" [fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",tooltip="A class whose instances are single test cases."]; }

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

digraph inheritance072fe32b5f { bgcolor=transparent; rankdir=LR; size="8.0, 12.0"; "LoggerAdapter" [fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",tooltip="An adapter for loggers which makes it easier to specify contextual"]; "LsstLogAdapter" [URL="../../../py-api/lsst.utils.logging.LsstLogAdapter.html#lsst.utils.logging.LsstLogAdapter",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="A special logging adapter to provide log features for LSST code."]; "LoggerAdapter" -> "LsstLogAdapter" [arrowsize=0.5,style="setlinewidth(0.5)"]; "PeriodicLogger" [URL="../../../py-api/lsst.utils.logging.PeriodicLogger.html#lsst.utils.logging.PeriodicLogger",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="Issue log messages if a time threshold has elapsed."]; }

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

digraph inheritancee6726f6b2b { bgcolor=transparent; rankdir=LR; size="8.0, 12.0"; "Singleton" [URL="../../../py-api/lsst.utils.classes.Singleton.html#lsst.utils.classes.Singleton",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="Metaclass to convert a class to a Singleton."]; }

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.
find_outside_stacklevel(*module_names[, ...])	Find the stacklevel for outside of the given module.

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

digraph inheritanceed80ad38d5 { bgcolor=transparent; rankdir=LR; size="8.0, 12.0"; "Packages" [URL="../../../py-api/lsst.utils.packages.Packages.html#lsst.utils.packages.Packages",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="A table of packages and their versions."]; }

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 prior to version 3.10.

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.