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.

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.

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

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.

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

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.