jacinle package

The Jacinle library.

This main library contains a set of useful utility functions and classes for general Python scripting.

There are a few automatically imported submodules that can be accessed by jacinle.<submodule>.

Command Line Tools

JacArgumentParser(*args, **kwargs) A customized argument parser.
yes_or_no(question, default) Ask a yes/no question via input() and return their answer.
maybe_mkdir(dirname) Make a directory if it does not exist.
git_guard(force) A utility function to guard the current git repo.

Logging

get_logger([name, formatter]) Get logger with given name.
set_logger_output_file(fout[, mode]) set the output file for all loggers.

Configuration

See jacinle.config.environ_v2 for more details.

configs The global configuration dictionary.
def_configs() A context manager to enable configuration definition mode.
def_configs_func(func) A decorator to enable configuration definition mode when calling a function.
set_configs() A context manager to enable configuration setting mode.
set_configs_func(func) A decorator to enable configuration setting mode when calling a function.
jac_getenv(name, default, type, type, …) Get the environment variable with the given name.
jac_is_verbose([default, prefix]) Return if the verbose mode is enabled.
jac_is_debug([default, prefix]) Return if the debug mode is enabled.

Utilities (Core)

EmptyContext An empty context manager that does nothing.
KeyboardInterruptContext A context manager that catches KeyboardInterrupt and does nothing.
JacEnum A customized enumeration class, adding helper functions for string-based argument parsing.
Clock(tick) A clock that can be used to measure the time.
deprecated(func) A helper decorator to mark a function as deprecated.
load_module(module_name) Import a module by its module name (e.g., jacinle.utils.imp).
load_module_filename(module_filename) Import a module by its filename (e.g., /Users/jiayuan/Projects/Jacinle/jacinle/utils/imp.py).
load_source(filename, name) Load a source file as a module.
gofor(v) A go-style for loop for dict, list, tuple, set, etc.
run_once(func) A decorator to run a function only once.
try_run(lambda_) A function that tries to run a function, and returns None if it fails (without raising exceptions).
map_exec(func, *iterables) Execute a function on each element of the iterables, and return the results.
filter_exec(func, iterable) Execute a filter function on each element of the iterable, and return the results.
first(iterable, default) Get the first element of an iterable.
first_n(iterable, n) Get the first n elements of an iterable.
stmap(func, iterable) A map function that recursively follows the structure of the iterable.
method2func(method_name) Convert a method name to a function that calls the method.
map_exec_method(method_name, iterable) Execute a method on each element of the iterable, and return the results.
decorator_with_optional_args([func, is_method]) Make a decorator that can be used with or without arguments.
cond_with(with_statement, cond) A context manager that runs a with statement only if the condition is true.
cond_with_group(cond, *with_statement) A context manager that runs a group of with statements only if the condition is true.
merge_iterable(v1, v2) Merge two iterables into a single iterable.
dict_deep_update(a, Any], b, Any]) Update a dictionary recursively.
dict_deep_kv(d, Any], sort[, sep]) Get a flattened dictionary with keys as the path to the value.
dict_deep_keys(d, Any], sort[, sep]) Get the keys of a flattened dictionary.
assert_instance(ins, clz, Tuple[type, …]], msg) Assert that an instance is of a certain type.
assert_none(ins, msg) Assert that the input is None.
assert_notnone(ins, msg, name) Assert that the input is not None.
notnone_property(fget) A property that raises an error if the value is None.
synchronized([mutex]) A decorator that synchronizes the execution of a function.
timeout(timeout, fps) A decorator that raises a TimeoutError if the execution time of the function exceeds the timeout.
make_dummy_func([message]) Make a dummy function that raises an error when called.
repr_from_str(self) A helper function to generate the repr string from the __str__ method.
class_name(instance_or_class) Get the class name of an instance or a class object.
func_name(func) Get a full name of a function, including the module name.
method_name(method) Get a full name of a method, including the module name and the class name.
class_name_of_method(method) Get the class name of a method.
indent_text(text[, level]) Indent the text by the given level.
stprint(data, key, indent, file, …) Structure print.
stformat(data[, key, indent, max_depth]) Structure format.
kvprint(data, indent, sep, end, max_key_len, …) Print the key-value pairs.
kvformat(data[, indent, sep, end, max_key_len]) Format the key-value pairs.
print_to_string([target]) Create a PrintToStringContext and return the context manager.
print_to(print_func[, target, rstrip]) Redirect the print to a function.
suppress_stdout() A context manager that suppress the stdout.

Utilities (IO)

load(filename, **kwargs) Load a file with automatic file type detection.
dump(filename, obj, **kwargs) Dump a file with automatic file type detection.
lsdir(dirname, pattern, return_type, …) List all files in a directory.
mkdir(path) Create a directory if it does not exist without raising errors when the directory already exists.

Utilities (Cache)

cached_property(fget) A decorator that converts a function into a cached property.
cached_result(func) A decorator that caches the result of a function.
fs_cached_result(filename, force_update, verbose) A decorator that caches the result of a function into a file.

Utilities (TQDM)

get_current_tqdm() Get the current tqdm instance.
tqdm(iterable, **kwargs) Wrapped tqdm, where default kwargs will be load, and support for i in tqdm(10) usage.
tqdm_pbar(**kwargs) Create a tqdm progress bar with the given kwargs.
tqdm_gofor(iterable, **kwargs) Create a tqdm progress bar for the given iterable, and use it as the progress bar for jacinle.utils.meta.gofor().
tqdm_zip(*iterable, **kwargs) Create a tqdm progress bar for a zip of the given iterables, and use it as the progress bar.
TQDMPool([nr_workers])

Utilities (Math)

GroupMeters()
safe_sum(*values) A safe sum function that uses the first value as the initial value.
mean(values[, default]) A mean function that returns the default value when the input is empty.
std(values[, default]) A standard deviation function that returns the default value when the input is empty.
rms(values[, default]) A root mean square function that returns the default value when the input is empty.
prod(values[, default]) A product function that returns the default value when the input is empty.
divup(n, d) Divide n by d and round up.
reset_global_seed(seed, verbose) Reset the global seed for all random number generators.
seed(seed)
with_seed(seed, verbose) A context manager that sets the global seed to the given value, and restores it after the context.

Utilities (Container)

g A simple global dict-like object.
G A simple container that wraps a dict and provides attribute access to the dict.
GView([dict_]) A simple container that wraps a dict and provides attribute access to the dict.
SlotAttrObject(**kwargs) Create a object that allows only a fixed set of attributes to be set.
OrderedSet(initial_list) A set that keeps the order of the elements.

Utilities (Defaults)

See jacinle.utils.defaults for more details.

defaults_manager Defaults manager can be used to create program or thread-level registries.
wrap_custom_as_default
gen_get_default
gen_set_default
option_context(name[, is_local])
FileOptions(__file__, **init_kwargs) A class that stores options in a single file.
default_args(func) A helper function handles the case of “fall-through” default arguments.
ARGDEF A special value to indicate that the default value of an argument will be determined in a deferred manner.

Utilities (Exception and Debugging)

hook_exception_ipdb() Add a hook to ipdb when an exception is raised.
exception_hook(enable) A context manager to temporarily enable the ipdb exception hook.
timeout_ipdb(locals_, timeout) A context manager that enters ipdb when timeout.
log_function(init_function, *, verbose) A decorator to log the function call.
profile([field, top_k]) A context manager to profile the code in the context.
time([name]) A context manager to time the code in the context.
format_exc(ei) Format an exception info tuple into a string.

Utilities (Network and Misc)

get_local_addr() Get the local IP address of the machine.
gen_time_string() Generate a time string with format: %Y%m%d-%H%M%S-%f.
gen_uuid4() Generate a UUID4 string.
jacinle.seed(self, seed=None)

Reseed a legacy MT19937 BitGenerator

Notes

This is a convenience, legacy function.

The best practice is to not reseed a BitGenerator, rather to recreate a new one. This method is here for legacy reasons. This example demonstrates best practice.

>>> from numpy.random import MT19937
>>> from numpy.random import RandomState, SeedSequence
>>> rs = RandomState(MT19937(SeedSequence(123456789)))
# Later, you want to restart the stream
>>> rs = RandomState(MT19937(SeedSequence(987654321)))

Subpackages