lsst.utils

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

Changes

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

Inheritance diagram of lsst.utils.wrappers.TemplateMeta

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

Inheritance diagram of lsst.utils.tests.MemoryTestCase, lsst.utils.tests.ExecutablesTestCase, lsst.utils.tests.TestCase

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

Inheritance diagram of lsst.utils.logging.LsstLogAdapter, lsst.utils.logging.PeriodicLogger

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

Inheritance diagram of lsst.utils.classes.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.

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

Inheritance diagram of lsst.utils.packages.Packages

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.