jacinle.utils package

Submodules

jacinle.utils.argument module

jacinle.utils.argument.get_2dshape(x: Union[int, Sequence[int], None], default: Tuple[int, int] = None, type: type = <class 'int'>) → Tuple[int, int]

Convert a value or a tuple to a tuple of length 2.

Parameters:

• x – a value of type type, or a tuple of length 2. If the input is a single value, it will be duplicated to a tuple of length 2.
• default – default value.
• type – expected type of the element.

Returns:

a tuple of length 2.

jacinle.utils.argument.get_3dshape(x: Union[int, Sequence[int], None], default: Tuple[int, int, int] = None, type: type = <class 'int'>) → Tuple[int, int, int]

Convert a value or a tuple to a tuple of length 3.

Parameters:

• x – a value of type type, or a tuple of length 3. If the input is a single value, it will be duplicated to a tuple of length 3.
• default – default value.
• type – expected type of the element.

Returns:

a tuple of length 3.

jacinle.utils.argument.get_4dshape(x: Union[int, Sequence[int], None], default: Tuple[int, int, int, int] = None, type: type = <class 'int'>) → Tuple[int, int, int, int]

Convert a value or a tuple to a tuple of length 4.

Parameters:

• x – a value of type type, or a tuple of length 4. If there is only one value, it will return (1, x, x, 1). If there are two values, it will return (1, x[0], x[1], 1).
• default – default value.
• type – expected type of the element.

Returns:

a tuple of length 4.

jacinle.utils.argument.astuple(arr_like: Any) → Tuple

Convert a sequence or a single value to a tuple. This method differ from the system method tuple in that a single value (incl. int, string, bytes) will be converted to a tuple of length 1.

Parameters:arr_like – a sequence or a single value. Returns:a tuple.

jacinle.utils.argument.asshape(arr_like: Union[int, Sequence[int], None]) → Optional[Tuple[int, ...]]

Convert a sequence or a single value to a tuple of integers. It will return None if the input is None.

Parameters:arr_like – a sequence or a single value. Returns:a tuple of integers.

jacinle.utils.argument.canonize_args_list(args: Tuple[Any], *, allow_empty: bool = False, cvt: Optional[Callable[[Any], Any]] = None) → Tuple[Any]

Convert the argument list to a tuple of values. This is useful to make unified interface for shape-related operations.

Example

def foo(*args):
    args = canonize_args_list(args, allow_empty=True)
    print(args)

foo(1, 2, 3)  # (1, 2, 3)
foo((1, 2, 3))  # (1, 2, 3)
foo(1)  # (1,)
foo()  # ()

Parameters:

• args – the argument list.
• allow_empty – whether to allow empty argument list.
• cvt – a function to be applied to each element.

class jacinle.utils.argument.UniqueValueGetter(msg: str = 'Unique value checking failed', default: Any = None)

Bases: object

A helper class to ensure that a value is unique.

Example

uvg = UniqueValueGetter()
uvg.set(1)
uvg.set(2)  # will raise ValueError
uvg.set(1)

print(uvg.get())  # 1

get()

set(v)

jacinle.utils.cache module

class jacinle.utils.cache.cached_property(fget)

Bases: object

A decorator that converts a function into a cached property. Similar to @property, but the function result is cached.

jacinle.utils.cache.cached_result(func)

A decorator that caches the result of a function. Note that this decorator does not support any arguments to the function.

jacinle.utils.cache.fs_cached_result(filename: str, force_update: bool = False, verbose: bool = False) → Callable[[Callable], Callable]

A decorator that caches the result of a function into a file. Note that this decorator does not take care of any arguments to the function.

Parameters:

• filename – the filename to store the result.
• force_update – if True, the result will be updated even if the file exists.
• verbose – if True, the filenames will be printed to the console.

Returns:

a decorator function.

jacinle.utils.container module

class jacinle.utils.container.G

Bases: dict

A simple container that wraps a dict and provides attribute access to the dict.

Example

>>> g = G()
>>> g.a = 1
>>> g['b'] = 2

format(sep=': ', end='\n')

Format the dict as a string using jacinle.utils.printing.kvformat().

print(sep=': ', end='\n', file=None)

Print the dict using jacinle.utils.printing.kvprint().

jacinle.utils.container.g = {}

A simple global dict-like object.

class jacinle.utils.container.GView(dict_=None)

Bases: object

A simple container that wraps a dict and provides attribute access to the dict. In contrast to G, this class wraps around an existing dict.

copy()

Return a shallow copy of the underlying dict.

format(sep=': ', end='\n')

Format the dict as a string using jacinle.utils.printing.kvformat().

items()

Iterate over the items of the underlying dict.

keys()

Return the keys of the underlying dict.

print(sep=': ', end='\n', file=None)

Print the dict using jacinle.utils.printing.kvprint().

raw()

Return the underlying dict.

update(other)

Update the underlying dict with another dict.

values()

Return the values of the underlying dict.

class jacinle.utils.container.SlotAttrObject(**kwargs)

Bases: object

Create a object that allows only a fixed set of attributes to be set.

clone(deep: bool = False)

Return a shallow or a deep copy of the object.

update(**kwargs)

Update the attributes of the object.

class jacinle.utils.container.OrderedSet(initial_list: Optional[Iterable[Any]] = None)

Bases: object

A set that keeps the order of the elements.

append(value)

Append an element to the set.

as_list()

Return the elements as a list.

remove(value)

Remove an element from the set.

jacinle.utils.context module

class jacinle.utils.context.EmptyContext

Bases: object

An empty context manager that does nothing.

class jacinle.utils.context.KeyboardInterruptContext

Bases: object

A context manager that catches KeyboardInterrupt and does nothing.

class jacinle.utils.context.SaverContext

Bases: object

Save some information before entering the context. Restore the information after.

Inspired by: https://github.com/caelan/pybullet-planning/blob/master/pybullet_tools/utils.py

restore()

save()

jacinle.utils.debug module

jacinle.utils.debug.hook_exception_ipdb()

Add a hook to ipdb when an exception is raised.

jacinle.utils.debug.unhook_exception_ipdb()

Remove the hook to ipdb when an exception is raised.

jacinle.utils.debug.exception_hook(enable: bool = True)

A context manager to temporarily enable the ipdb exception hook.

jacinle.utils.debug.decorate_exception_hook(func: Callable) → Callable

A decorator to decorate the exception hook when calling a function.

jacinle.utils.debug.timeout_ipdb(locals_, timeout: float = 3)

A context manager that enters ipdb when timeout. This is useful when you want to debug a function that is stuck in a loop.

Example

with timeout_ipdb(locals(), timeout=3):
    while True:
        pass

Parameters:

• locals – the locals() of the function.
• timeout – the timeout in seconds.

jacinle.utils.debug.log_function(init_function: Optional[Callable] = None, *, verbose: bool = True)

A decorator to log the function call. This is useful to debug the function call stack. The call stack will be formated with indentations.

Parameters:

• init_function – the function to be wrapped. If not specified, this function will return a decorator.
• verbose – whether to print detailed log. By default, only the function name is printed.

Example

@log_function
def foo():
    bar()

@log_function
def bar():
    pass

foo()

Output:

Entering: foo
    Entering: bar
    Exiting: bar
    Return: None
Exiting: foo
Return: None

jacinle.utils.debug.profile(field='tottime', top_k=10)

A context manager to profile the code in the context. After profiling is done, the top k functions will be printed.

Parameters:

• field – the field to sort the profile result. See cProfile.Profile.print_stats for more details.
• top_k – the number of top functions to print.

Example

with profile():
    foo()

jacinle.utils.debug.time(name=None)

A context manager to time the code in the context. After timing is done, the time will be printed.

Parameters:name – the name of the context. If None, the default name 'DEFAULT' will be used.

Example

with time():
    foo()

jacinle.utils.defaults module

jacinle.utils.defaults.option_context(name, is_local=True, **kwargs)

class jacinle.utils.defaults.FileOptions(__file__, **init_kwargs)

Bases: object

A class that stores options in a single file.

Example

# file: my_module.py
options = FileOptions(__file__, number_to_add=1)

def my_func(x: int) -> int:
    return x + options.number_to_add

# file: my_script.py
import my_module
my_module.options.set(number_to_add=2)
my_module.my_func(1)  # returns 3

set(**kwargs)

jacinle.utils.defaults.ARGDEF = <object object>

A special value to indicate that the default value of an argument will be determined in a deferred manner. See default_args().

jacinle.utils.defaults.default_args(func)

A helper function handles the case of “fall-through” default arguments. Suppose we have two functions: f and g, and f calls g. g has a default argument x, e.g., x=1. In many cases, we do not want to specify the default value of x in f. One way to do this is to use None as the default value of x in f, and then check if x is None in g. However this does not handle cases where x can be None in other cases. It also requires additional checks in g. With this decorator, we can simply write x=ARGDEF in f, and then x will be set to 1 in g.

Example

def f(x=ARGDEF):
    g(x)

@default_args
def g(x=1):
    print(x)

f()  # prints 1
f(2)  # prints 2

jacinle.utils.deprecated module

jacinle.utils.deprecated.deprecated(func)

A helper decorator to mark a function as deprecated. It will result in a warning being emitted when the function is used (each function is only warned once).

jacinle.utils.enum module

class jacinle.utils.enum.JacEnum

Bases: enum.Enum

A customized enumeration class, adding helper functions for string-based argument parsing.

assert_valid = <bound method JacEnum.assert_valid of <enum 'JacEnum'>>

choice_names = <bound method JacEnum.choice_names of <enum 'JacEnum'>>

choice_objs = <bound method JacEnum.choice_objs of <enum 'JacEnum'>>

choice_values = <bound method JacEnum.choice_values of <enum 'JacEnum'>>

from_string = <bound method JacEnum.from_string of <enum 'JacEnum'>>

is_valid = <bound method JacEnum.is_valid of <enum 'JacEnum'>>

type_name = <bound method JacEnum.type_name of <enum 'JacEnum'>>

jacinle.utils.env module

jacinle.utils.env.jac_getenv(name: str, default: Any = None, type: Union[str, type, None] = None, prefix: str = None) → Any

Get the environment variable with the given name.

Parameters:

• name – the name of the environment variable.
• default – the default value if the environment variable is not set.
• type – the type of the environment variable. If not given, the type of the default value will be used. It supports a special type, denoted by a string 'bool', indicating that the value will be converted to a boolean value (‘true’/’false’, ‘yes’/’no’, ‘1’/’0’).
• prefix – the prefix of the environment variable. If not given, the prefix will be JAC_.

Returns:

the value of the environment variable.

jacinle.utils.env.jac_is_verbose(default='n', prefix=None)

Return if the verbose mode is enabled. This is controlled by the environment variable JAC_VERBOSE.

jacinle.utils.env.jac_is_debug(default='n', prefix=None)

Return if the debug mode is enabled. This is controlled by the environment variable JAC_DEBUG or the --debug argument in the command line.

jacinle.utils.exception module

jacinle.utils.exception.format_exc(ei)

Format an exception info tuple into a string. Useful in context managers.

jacinle.utils.filelock module

A platform independent file lock that supports the with-statement.

Original License:

This is free and unencumbered software released into the public domain.

Anyone is free to copy, modify, publish, use, compile, sell, or distribute this software, either in source code form or as a compiled binary, for any purpose, commercial or non-commercial, and by any means.

In jurisdictions that recognize copyright laws, the author or authors of this software dedicate any and all copyright interest in the software to the public domain. We make this dedication for the benefit of the public at large and to the detriment of our heirs and successors. We intend this dedication to be an overt act of relinquishment in perpetuity of all present and future rights to this software under copyright law.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

For more information, please refer to <http://unlicense.org>

exception jacinle.utils.filelock.FileLockTimeout(lock_file)

Bases: TimeoutError

Raised when the lock could not be acquired in timeout seconds.

lock_file = None

The path of the file lock.

class jacinle.utils.filelock.BaseFileLock(lock_file, timeout=-1)

Bases: object

Implements the base class of a file lock.

acquire(timeout=None, poll_intervall=0.05)

Acquires the file lock or fails with a Timeout error.

Parameters:

• timeout (float) – the maximum time waited for the file lock. If timeout <= 0, there is no timeout and this method will block until the lock could be acquired. If timeout is None, the default timeout is used.
• poll_intervall (float) – we check once in poll_intervall seconds if we can acquire the file lock.

# You can use this method in the context manager (recommended)
with lock.acquire():
    pass

# Or you use an equal try-finally construct:
lock.acquire()
try:
    pass
finally:
    lock.release()

is_locked

True, if the object holds the file lock.

lock_file

The path to the lock file.

release(force=False)

Releases the file lock.

Please note, that the lock is only completly released, if the lock counter is 0.

Also note, that the lock file itself is not automatically deleted.

Parameters:force (bool) – If true, the lock counter is ignored and the lock is released in every case.

timeout

You can set a default timeout for the filelock. It will be used as fallback value in the acquire method, if no timeout value (None) is given.

If you want to disable the timeout, set it to a negative value.

A timeout of 0 means, that there is exactly one attempt to acquire the file lock.

class jacinle.utils.filelock.WindowsFileLock(lock_file, timeout=-1)

Bases: jacinle.utils.filelock.BaseFileLock

Uses the msvcrt.locking() function to hard lock the lock file on windows systems.

class jacinle.utils.filelock.UnixFileLock(lock_file, timeout=-1)

Bases: jacinle.utils.filelock.BaseFileLock

Uses the fcntl.flock() to hard lock the lock file on unix systems.

class jacinle.utils.filelock.SoftFileLock(lock_file, timeout=-1)

Bases: jacinle.utils.filelock.BaseFileLock

Simply watches the existence of the lock file.

jacinle.utils.filelock.FileLock

Alias for the lock, which should be used for the current platform. On Windows, this is an alias for WindowsFileLock, on Unix for UnixFileLock and otherwise for SoftFileLock.

alias of jacinle.utils.filelock.UnixFileLock

jacinle.utils.imp module

jacinle.utils.imp.load_module(module_name: str) → Any

Import a module by its module name (e.g., jacinle.utils.imp).

Parameters:module_name – the name of the module. Returns:the imported module.

jacinle.utils.imp.load_module_filename(module_filename: str) → Any

Import a module by its filename (e.g., /Users/jiayuan/Projects/Jacinle/jacinle/utils/imp.py).

Parameters:module_filename – the filename of the module. Returns:the imported module.

jacinle.utils.imp.load_source(filename: str, name: Optional[str] = None) → Any

Load a source file as a module.

Parameters:

• filename – the filename of the source file.
• name – the name of the module.

Returns:

the loaded module.

jacinle.utils.imp.tuple_to_classname(t: Tuple[str, str]) → str

Convert a module-class tuple to a string.

Parameters:t – the module-class tuple. E.g., (‘jacinle.utils.imp’, ‘load_module’). Returns:the string representation of the module-class tuple. E.g., ‘jacinle.utils.imp.load_module’.

jacinle.utils.imp.classname_to_tuple(classname: str) → Tuple[str, str]

Convert a string to a module-class tuple.

Parameters:classname – the string representation of the module-class tuple. E.g., ‘jacinle.utils.imp.load_module’. Returns:the module-class tuple. E.g., (‘jacinle.utils.imp’, ‘load_module’).

jacinle.utils.imp.load_class(classname: Union[str, Tuple[str, str]], exit_on_error: bool = True)

Load a class by its classname (including module).

Parameters:

• classname – the classname of the class.
• exit_on_error – whether to exit the program when the class cannot be loaded.

Returns:

the loaded class.

jacinle.utils.imp.module_vars_as_dict(module: Any) → Dict[str, Any]

Get all variables in a module as a dictionary.

Parameters:module – the module. Returns:a dictionary of all variables in the module.

jacinle.utils.init module

jacinle.utils.init.enable_ipdb()

jacinle.utils.init.init_main()

jacinle.utils.init.release_syslim()

jacinle.utils.init.tune_opencv()

jacinle.utils.inspect module

jacinle.utils.inspect.class_name(instance_or_class: Any) → str

Get the class name of an instance or a class object.

Parameters:instance_or_class – an instance or a class object. Returns:the class name of the instance or the class object.

jacinle.utils.inspect.func_name(func: Callable) → str

Get a full name of a function, including the module name.

Parameters:func – a function. Returns:the full name of the function.

jacinle.utils.inspect.method_name(method: Callable) → str

Get a full name of a method, including the module name and the class name.

jacinle.utils.inspect.class_name_of_method(method: Callable) → str

Get the class name of a method.

jacinle.utils.inspect.bind_args(sig, *args, **kwargs)

Bind arguments to a signature.

jacinle.utils.inspect.get_subclasses(cls: type) → Iterable[type]

Get all subclasses of a class.

jacinle.utils.matching module

Functions to match names using glob patterns.

class jacinle.utils.matching.NameMatcher(rules: Union[Iterable[Tuple[str, Any]], Dict[str, Any], None] = None)

Bases: object

A name matcher based on a set of glob patterns.

The rule set is a list of (pattern, value) pairs. The pattern is a glob pattern, and the value is the value to be returned when the pattern matches.

Example

matcher = NameMatcher({'*.jpg': 'image', '*.png': 'image', '*.txt': 'text'})
with matcher:
    matcher.match('a.jpg')  # 'image'
    matcher.match('a.png')  # 'image'

matched, unused = matcher.get_last_stat()  # Return a tuple of (matched values, unmatched patterns).
print(matched)  # [('a.jpg', '*.jpg', 'image'), ('a.png', '*.png', 'image')]
print(unused)  # {'*.txt'}

append_rule(rule: Tuple[str, Any])

Append a rule to the rule set. The rule is a (pattern, value) pair.

Parameters:rule – the rule to be appended.

begin(*, force_compile=False)

Begin a matching session.

compile()

Compile the rule set.

end()

End a matching session, which returns a tuple of (matched values, unmatched patterns). See the docstring of NameMatcher for more details.

get_last_stat()

Get the last matching session’s result.

insert_rule(index: int, rule: Tuple[str, Any])

Insert a rule to the rule set at a given position (priority). The rule is a (pattern, value) pair.

map() → Dict[str, Any]

Get the map of {pattern: value}.

match(k: str) → Optional[Any]

Match a name against the rule set. Return the value if matched, otherwise return None.

Parameters:k – the name to be matched. Returns:The value if matched, otherwise None.

pop_rule(index=None)

Pop a rule from the rule set.

Parameters:index – the index of the rule to be popped. If None, the last rule will be popped.

rules

Get the rules.

class jacinle.utils.matching.IENameMatcher(include: Optional[Iterable[str]], exclude: Optional[Iterable[str]])

Bases: object

A name matcher based on two sets of glob patterns: one for inclusion and one for exclusion.

• When include is None, exclude is not None, the matcher will match all names that are not excluded.
• When include is not None, exclude is None, the matcher will match all names that are included.

• When include is not None, exclude is not None, the matcher will match all names that are included and not excluded.

  The exclude rule set has higher priority than the include rule set.

Example

matcher = IENameMatcher(include=['*.jpg', '*.png'], exclude=['*.bak.png'])
with matcher:
    matcher.match('a.jpg')  # True
    matcher.match('a.png')  # True
    matcher.match('a.bak.png')  # False
    matcher.match('a.txt')  # False
    matcher.match('a.bak.txt')  # False

stat_type, things = matcher.get_last_stat()
print(stat_type)  # 'exclude'
# Everything that has been rejected.
print(things)  # ['a.bak.png', 'a.txt', 'a.bak.txt']

begin()

Begin a matching session.

end()

End a matching session, which returns a tuple of (stat_type, things) See the docstring of IENameMatcher.

get_last_stat()

Get the last matching session’s result.

match(k: str) → bool

Match a name against the rule set. Return True if matched, otherwise return False.

jacinle.utils.meta module

jacinle.utils.meta.gofor(v: Iterable[Any]) → Iterable[Tuple[Any, Any]]

A go-style for loop for dict, list, tuple, set, etc.

• dict: for key, value in gofor(dict):
• list, tuple, set: for index, value in gofor(list):

Parameters:v – the iterable object.

jacinle.utils.meta.run_once(func)

A decorator to run a function only once.

jacinle.utils.meta.try_run(lambda_)

A function that tries to run a function, and returns None if it fails (without raising exceptions).

jacinle.utils.meta.map_exec(func, *iterables) → List[Any]

Execute a function on each element of the iterables, and return the results.

jacinle.utils.meta.filter_exec(func, iterable: Iterable[Any]) → List[Any]

Execute a filter function on each element of the iterable, and return the results.

jacinle.utils.meta.first(iterable: Iterable[Any], default: Any = None) → Any

Get the first element of an iterable. If the iterable is empty, return the default value.

Parameters:

• iterable – the iterable object.
• default – the default value.

Returns:

the first element of the iterable, or the default value.

jacinle.utils.meta.first_n(iterable: Iterable[T_co], n: int = 10) → Optional[List[Any]]

Get the first n elements of an iterable. If the iterable has less than n elements, return None.

Parameters:

• iterable – the iterable object.
• n – the number of elements to get.

Returns:

the first n elements of the iterable, or None.

jacinle.utils.meta.stmap(func, iterable: Iterable[Any]) → Iterable[Any]

A map function that recursively follows the structure of the iterable.

• list, tuple: return [func(v) for v in iterable]
• set: return {func(v) for v in iterable}
• dict: return {k: func(v) for k, v in iterable.items()}

Parameters:

• func – the function to be applied.
• iterable – the iterable object.

Returns:

the mapped iterable.

jacinle.utils.meta.method2func(method_name: str) → Callable

Convert a method name to a function that calls the method. Equivalent to lambda x: x.method_name().

Parameters:method_name – the method name.

jacinle.utils.meta.map_exec_method(method_name, iterable: Iterable[Any]) → List[Any]

Execute a method on each element of the iterable, and return the results.

Parameters:

• method_name – the method name.
• iterable – the iterable object.

jacinle.utils.meta.decorator_with_optional_args(func=None, *, is_method=False)

Make a decorator that can be used with or without arguments.

Parameters:

• func – the function to be decorated.
• is_method – whether the function is a method.

Example

 @decorator_with_optional_args
 def my_decorator(func=None, *, a=1, b=2):
     def wrapper(func):
         @functools.wraps(func)
         def new_func(*args, **kwargs):
             print(f'Calling {func.__name__} with a={a}, b={b}')
             return func(*args, **kwargs)
         return new_func
     return wrapper

 @my_decorator
 def func1():
     pass  # Calling func1 with a=1, b=2

 @my_decorator(a=2)
 def func2():
pass  # Calling func2 with a=2, b=2

jacinle.utils.meta.cond_with(with_statement, cond: bool)

A context manager that runs a with statement only if the condition is true.

jacinle.utils.meta.cond_with_group(cond: bool, *with_statement)

A context manager that runs a group of with statements only if the condition is true.

jacinle.utils.meta.merge_iterable(v1, v2)

Merge two iterables into a single iterable.

• list, tuple: return v1 + v2
• set: return v1 | v2
• dict: return {**v1, **v2}

Parameters:

• v1 – the first iterable.
• v2 – the second iterable.

Returns:

the merged iterable.

jacinle.utils.meta.dict_deep_update(a: Dict[Any, Any], b: Dict[Any, Any])

Update a dictionary recursively.

Parameters:

• a – the dictionary to be updated.
• b – the dictionary to update from.

jacinle.utils.meta.dict_deep_kv(d: Dict[Any, Any], sort: bool = True, sep='.', allow_dict: bool = False) → Dict[str, Any]

Get a flattened dictionary with keys as the path to the value.

Example

>>> d = {'a': 1, 'b': {'c': 2, 'd': 3}}
>>> dict_deep_kv(d)
{'a': 1, 'b.c': 2, 'b.d': 3}

Parameters:

• d – the dictionary.
• sort – whether to sort the keys.
• sep – the separator between keys.
• allow_dict – whether to allow dictionary values.

jacinle.utils.meta.dict_deep_keys(d: Dict[Any, Any], sort: bool = True, sep='.', allow_dict: bool = False) → List[str]

Get the keys of a flattened dictionary.

Parameters:

• d – the dictionary.
• sort – whether to sort the keys.
• sep – the separator between keys.
• allow_dict – whether to allow dictionary values.

Returns:

a list of keys.

See also

dict_deep_kv()

jacinle.utils.meta.assert_instance(ins: Any, clz: Union[type, Tuple[type, ...]], msg: str = None)

Assert that an instance is of a certain type.

jacinle.utils.meta.assert_none(ins: Any, msg: str = None)

Assert that the input is None.

jacinle.utils.meta.assert_notnone(ins: Any, msg: str = None, name: str = None)

Assert that the input is not None.

Parameters:

• ins – the input.
• msg – the error message. If not specified, a default message {name} is None will be used.
• name – the name of the input.

class jacinle.utils.meta.notnone_property(fget)

Bases: object

A property that raises an error if the value is None.

jacinle.utils.meta.synchronized(mutex=None)

A decorator that synchronizes the execution of a function.

Parameters:mutex – the mutex to use. If not specified, a new threading mutex will be created.

jacinle.utils.meta.timeout(timeout: float, fps: Optional[float] = None)

A decorator that raises a TimeoutError if the execution time of the function exceeds the timeout.

Parameters:

• timeout (float) – timeout in seconds.
• fps (float) – an optional fps to control the maximum number of iterations.

Example

import time
from jacinle.utils.meta import timeout
for _ in timeout(5.1):
    print('hello')
    time.sleep(1)

class jacinle.utils.meta.Clock(tick: Optional[float] = None)

Bases: object

A clock that can be used to measure the time.

tick(timeout=None)

Tick the clock.

Parameters:timeout – the timeout in seconds. If not specified, the timeout in the constructor will be used.

jacinle.utils.meta.make_dummy_func(message=None)

Make a dummy function that raises an error when called.

jacinle.utils.meta.repr_from_str(self)

A helper function to generate the repr string from the __str__ method.

Example

class Foo(object):
    def __str__(self):
        return 'Foo'

    __repr__ = repr_from_str

print(Foo())  # Foo
print(repr(Foo()))  # Foo[Foo]

jacinle.utils.meter module

class jacinle.utils.meter.AverageMeter

Bases: object

Computes and stores the average and current value

avg = 0

count = 0

reset()

sum = 0

tot_count = 0

update(val, n=1)

val = 0

class jacinle.utils.meter.GroupMeters

Bases: object

avg

dump(filename, values='avg')

format(caption, values, kv_format, glue)

format_simple(caption=None, values='avg', compressed=True)

items()

reset()

sum

update(updates=None, value=None, n=1, prefix=None, **kwargs)

Update the meters.

Examples

>>> meters.update(key, value)
>>> meters.update({key1: value1, key2: value2})
>>> meters.update(key1=value1, key2=value2)

val

jacinle.utils.naming module

jacinle.utils.network module

jacinle.utils.network.get_local_addr() → str

Get the local IP address of the machine.

Returns:the local IP address.

jacinle.utils.network.get_local_addr_v1() → str

Get the local IP address of the machine. This is the old version of get_local_addr.

Returns:the local IP address.

jacinle.utils.network.get_local_addr_v2() → str

Get the local IP address of the machine. This is the new version of get_local_addr.

Returns:the local IP address.

jacinle.utils.numeric module

jacinle.utils.numeric.safe_sum(*values)

A safe sum function that uses the first value as the initial value. It can be used as a replacement of sum().

jacinle.utils.numeric.mean(values, default=0)

A mean function that returns the default value when the input is empty.

jacinle.utils.numeric.std(values, default=0)

A standard deviation function that returns the default value when the input is empty.

jacinle.utils.numeric.rms(values, default=0)

A root mean square function that returns the default value when the input is empty.

jacinle.utils.numeric.prod(values, default=1)

A product function that returns the default value when the input is empty.

jacinle.utils.numeric.divup(n, d)

Divide n by d and round up.

jacinle.utils.printing module

jacinle.utils.printing.indent_text(text: str, level=1, indent_format: Optional[str] = None, tabsize: Optional[int] = None) → str

Indent the text by the given level.

Parameters:

• text – the text to be indented.
• level – the indent level.
• indent_format – the indent format. If None, use the tabsize.
• tabsize – the tab size. If None, use the default tab size (2).

Returns:

The indented text.

jacinle.utils.printing.stprint(data, key: Optional[str] = None, indent: int = 0, file: Optional[io.TextIOBase] = None, indent_format: str = ' ', end_format: str = '\n', float_format: str = '{:.6f}', need_lock: bool = True, sort_key: bool = True, max_depth: int = 100)

Structure print.

Example

>>> data = dict(a=np.zeros(shape=(10, 10)), b=3)
>>> stprint(data)
dict{
    a: ndarray(10, 10), dtype=float64
    b: 3
}

Parameters:

• data – data to be print. Currently support Sequnce, Mappings and primitive types.
• key – for recursion calls. Do not use it if you don’t know how it works.
• indent – indent level.
• file – the file to print to.
• indent_format – the indent format.
• end_format – the end format.
• float_format – the float format.
• need_lock – whether to use the lock.
• sort_key – whether to sort the keys.
• max_depth – the maximum depth of the recursion.

jacinle.utils.printing.stformat(data, key=None, indent=0, max_depth=100, **kwargs)

Structure format. See stprint() for more details.

jacinle.utils.printing.kvprint(data, indent: int = 0, sep: str = ' : ', end: str = '\n', max_key_len: Optional[int] = None, file: Optional[io.TextIOBase] = None, float_format: str = '{:.6f}', need_lock: bool = True)

Print the key-value pairs.

Parameters:

• data – the data to be printed.
• indent – the indent level.
• sep – the separator between key and value.
• end – the end format.
• max_key_len – the maximum length of the key. If None, use the maximum length of the keys.
• file – the file to print to.
• float_format – the float format.
• need_lock – whether to use the lock.

jacinle.utils.printing.kvformat(data, indent=0, sep=' : ', end='\n', max_key_len=None)

Format the key-value pairs. See kvprint() for more details.

class jacinle.utils.printing.PrintToStringContext(target='STDOUT', stream=None, need_lock=True)

Bases: object

A context manager that redirect the print to a string.

Example

>>> with PrintToStringContext() as s:
...     print('hello')
>>> print(s.get())

get() → str

Get the string.

jacinle.utils.printing.print_to_string(target='STDOUT')

Create a PrintToStringContext and return the context manager.

jacinle.utils.printing.print_to(print_func, target='STDOUT', rstrip=True)

Redirect the print to a function.

Example

def print_func(s):
    print('print_func: {}'.format(s))

with print_to(print_func):
   print('hello')

Parameters:

• print_func – the function to redirect to.
• target – the target to redirect to. Can be ‘STDOUT’, ‘STDERR’.
• rstrip – whether to remove the trailing newlines.

jacinle.utils.printing.print2format(print_func: Callable) → Callable

A helper class to convert a “print” function to a “format” function.

jacinle.utils.printing.suppress_stdout()

A context manager that suppress the stdout.

jacinle.utils.registry module

class jacinle.utils.registry.Registry

Bases: object

fallback

has(entry)

items()

keys()

lookup(entry, fallback=True, default=None)

register(entry, value)

set_fallback(value)

unregister(entry)

class jacinle.utils.registry.DefaultRegistry

Bases: jacinle.utils.registry.Registry

lookup(entry, fallback=False, default=None)

class jacinle.utils.registry.RegistryGroup

Bases: object

lookup(registry_name, entry, fallback=True, default=None)

register(registry_name, entry, value, **kwargs)

class jacinle.utils.registry.CallbackRegistry

Bases: jacinle.utils.registry.Registry

A callable manager utils.

If there exists a super callback, it will block all callbacks. A super callback will receive the called name as its first argument.

Then the dispatcher will try to call the callback by name. If such name does not exists, a fallback callback will be called.

The fallback callback will also receive the called name as its first argument.

Example

>>> registry = CallbackRegistry()
>>> callback_func = print
>>> registry.register('name', callback_func)  # register a callback.
>>> registry.dispatch('name', 'arg1', 'arg2', kwarg1='kwarg1')  # dispatch.

dispatch(name, *args, **kwargs)

dispatch_direct(name, *args, **kwargs)

Dispatch by name, ignoring the super callback.

fallback_callback

set_fallback_callback(callback)

set_super_callback(callback)

super_callback

class jacinle.utils.registry.LockRegistry

Bases: jacinle.utils.registry.DefaultRegistry

synchronized(entry, activate=True)

jacinle.utils.registry.subclass_registry_point(wrapped)

class jacinle.utils.registry.SimpleEventRegistry(allowed_events=None)

Bases: object

allowed_events

register(event, callback)

trigger(event, *args, **kwargs)

class jacinle.utils.registry.EventRegistry

Bases: jacinle.utils.registry.Registry

DEF_PRIORITY = 10

lookup(entry, key=None, priority=10, default=None)

register(entry, callback, priority=10, subkey=None)

trigger(entry, *args, **kwargs)

trigger_args(entry, args, kwargs)

unregister(entry, key=None, priority=10)

class jacinle.utils.registry.EventRegistryGroup

Bases: jacinle.utils.registry.RegistryGroup

lookup(registry_name, entry, key=None, **kwargs)

trigger(registry_name, entry, *args, **kwargs)

jacinle.utils.tqdm module

jacinle.utils.tqdm.get_tqdm_defaults()

Get the default kwargs for tqdm.

jacinle.utils.tqdm.get_current_tqdm()

Get the current tqdm instance. Only tqdms created by tqdm() will be returned.

jacinle.utils.tqdm.tqdm(iterable, **kwargs)

Wrapped tqdm, where default kwargs will be load, and support for i in tqdm(10) usage.

jacinle.utils.tqdm.tqdm_pbar(**kwargs)

Create a tqdm progress bar with the given kwargs.

jacinle.utils.tqdm.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().

jacinle.utils.tqdm.tqdm_zip(*iterable, **kwargs)

Create a tqdm progress bar for a zip of the given iterables, and use it as the progress bar.

jacinle.utils.uid module

jacinle.utils.uid.gen_time_string() → str

Generate a time string with format: %Y%m%d-%H%M%S-%f.

jacinle.utils.uid.gen_uuid4() → str

Generate a UUID4 string.

jacinle.utils.value_scheduler module

class jacinle.utils.value_scheduler.ValueScheduler

Bases: object

Essentially, define y = f(x), where x is a discrete, bounded variable.

get(x)

class jacinle.utils.value_scheduler.MonotonicSchedulerBase(begin, begin_value, end, end_value)

Bases: jacinle.utils.value_scheduler.ValueScheduler

get(x)

class jacinle.utils.value_scheduler.LinearScheduler(begin, begin_value, end, end_value)

Bases: jacinle.utils.value_scheduler.MonotonicSchedulerBase

get(x)

jacinle.utils.vendor module

jacinle.utils.vendor.has_vendor(vendor)

Check if the module is available.

jacinle.utils.vendor.requires_vendors(*vendors)

Decorator to check if the module is available. If not, raises an error when the function is called.