#!/usr/bin/env python
# coding=utf-8
import collections
import contextlib
import importlib
import logging
import pkgutil
import re
import shlex
import sys
import threading
import traceback as tb
from functools import partial
from packaging import version
from typing import Union
from pathlib import Path
import wrapt
__all__ = [
"NO_LOGGER",
"PYTHON_IDENTIFIER",
"CircularDependencyError",
"ObserverError",
"SacredInterrupt",
"TimeoutInterrupt",
"create_basic_stream_logger",
"recursive_update",
"iterate_flattened",
"iterate_flattened_separately",
"set_by_dotted_path",
"get_by_dotted_path",
"iter_prefixes",
"join_paths",
"is_prefix",
"convert_to_nested_dict",
"convert_camel_case_to_snake_case",
"print_filtered_stacktrace",
"optional_kwargs_decorator",
"get_inheritors",
"apply_backspaces_and_linefeeds",
"rel_path",
"IntervalTimer",
"PathType",
]
NO_LOGGER = logging.getLogger("ignore")
NO_LOGGER.disabled = 1
PATHCHANGE = object()
PYTHON_IDENTIFIER = re.compile("^[a-zA-Z_][_a-zA-Z0-9]*$")
PathType = Union[str, bytes, Path]
class ObserverError(Exception):
"""Error that an observer raises but that should not make the run fail."""
class SacredInterrupt(Exception):
"""Base-Class for all custom interrupts.
For more information see :ref:`custom_interrupts`.
"""
STATUS = "INTERRUPTED"
class TimeoutInterrupt(SacredInterrupt):
"""Signal that the experiment timed out.
This exception can be used in client code to indicate that the run
exceeded its time limit and has been interrupted because of that.
The status of the interrupted run will then be set to ``TIMEOUT``.
For more information see :ref:`custom_interrupts`.
"""
STATUS = "TIMEOUT"
class SacredError(Exception):
def __init__(
self,
message,
print_traceback=True,
filter_traceback="default",
print_usage=False,
):
super().__init__(message)
self.print_traceback = print_traceback
if filter_traceback not in ["always", "default", "never"]:
raise ValueError(
"filter_traceback must be one of 'always', "
"'default' or 'never', not " + filter_traceback
)
self.filter_traceback = filter_traceback
self.print_usage = print_usage
class CircularDependencyError(SacredError):
"""The ingredients of the current experiment form a circular dependency."""
@classmethod
@contextlib.contextmanager
def track(cls, ingredient):
try:
yield
except CircularDependencyError as e:
if not e.__circular_dependency_handled__:
if ingredient in e.__ingredients__:
e.__circular_dependency_handled__ = True
e.__ingredients__.append(ingredient)
raise e
def __init__(
self,
message="Circular dependency detected:",
ingredients=None,
print_traceback=True,
filter_traceback="default",
print_usage=False,
):
super().__init__(
message,
print_traceback=print_traceback,
filter_traceback=filter_traceback,
print_usage=print_usage,
)
if ingredients is None:
ingredients = []
self.__ingredients__ = ingredients
self.__circular_dependency_handled__ = False
def __str__(self):
return super().__str__() + "->".join(
[i.path for i in reversed(self.__ingredients__)]
)
class ConfigError(SacredError):
"""Pretty prints the conflicting configuration values."""
def __init__(
self,
message,
conflicting_configs=(),
print_conflicting_configs=True,
print_traceback=True,
filter_traceback="default",
print_usage=False,
config=None,
):
super().__init__(
message,
print_traceback=print_traceback,
filter_traceback=filter_traceback,
print_usage=print_usage,
)
self.print_conflicting_configs = print_conflicting_configs
if isinstance(conflicting_configs, str):
conflicting_configs = (conflicting_configs,)
self.__conflicting_configs__ = conflicting_configs
self.__prefix_handled__ = False
if config is None:
config = {}
self.__config__ = config
@classmethod
@contextlib.contextmanager
def track(cls, wrapped):
try:
yield
except ConfigError as e:
if not e.__prefix_handled__:
if wrapped.prefix:
e.__conflicting_configs__ = (
join_paths(wrapped.prefix, str(c))
for c in e.__conflicting_configs__
)
e.__config__ = wrapped.config
e.__prefix_handled__ = True
raise e
def __str__(self):
s = super().__str__()
if self.print_conflicting_configs:
# Add a list formatted as below to the string s:
#
# Conflicting configuration values:
# a=3
# b.c=4
s += "\nConflicting configuration values:"
for conflicting_config in self.__conflicting_configs__:
s += "\n {}={}".format(
conflicting_config,
get_by_dotted_path(self.__config__, conflicting_config),
)
return s
class InvalidConfigError(ConfigError):
"""Can be raised in the user code if an error in the configuration is detected.
Examples
--------
>>> # Experiment definitions ...
... @ex.automain
... def main(a, b):
... if a != b['a']:
... raise InvalidConfigError(
... 'Need to be equal',
... conflicting_configs=('a', 'b.a'))
"""
pass
class MissingConfigError(SacredError):
"""A config value that is needed by a captured function is not present in the provided config."""
def __init__(
self,
message="Configuration values are missing:",
missing_configs=(),
print_traceback=False,
filter_traceback="default",
print_usage=True,
):
message = "{} {}".format(message, missing_configs)
super().__init__(
message,
print_traceback=print_traceback,
filter_traceback=filter_traceback,
print_usage=print_usage,
)
class NamedConfigNotFoundError(SacredError):
"""A named config is not found."""
def __init__(
self,
named_config,
message="Named config not found:",
available_named_configs=(),
print_traceback=False,
filter_traceback="default",
print_usage=False,
):
message = '{} "{}". Available config values are: {}'.format(
message, named_config, available_named_configs
)
super().__init__(
message,
print_traceback=print_traceback,
filter_traceback=filter_traceback,
print_usage=print_usage,
)
class ConfigAddedError(ConfigError):
SPECIAL_ARGS = {"_log", "_config", "_seed", "__doc__", "config_filename", "_run"}
"""Special args that show up in the captured args but can never be set
by the user"""
def __init__(
self,
conflicting_configs,
message="Added new config entry that is not used anywhere",
captured_args=(),
print_conflicting_configs=True,
print_traceback=False,
filter_traceback="default",
print_usage=False,
print_suggestions=True,
config=None,
):
super().__init__(
message,
conflicting_configs=conflicting_configs,
print_conflicting_configs=print_conflicting_configs,
print_traceback=print_traceback,
filter_traceback=filter_traceback,
print_usage=print_usage,
config=config,
)
self.captured_args = captured_args
self.print_suggestions = print_suggestions
def __str__(self):
s = super().__str__()
if self.print_suggestions:
possible_keys = set(self.captured_args) - self.SPECIAL_ARGS
if possible_keys:
s += "\nPossible config keys are: {}".format(possible_keys)
return s
class SignatureError(SacredError, TypeError):
"""Error that is raised when the passed arguments do not match the functions signature."""
def __init__(
self,
message,
print_traceback=True,
filter_traceback="always",
print_usage=False,
):
super().__init__(message, print_traceback, filter_traceback, print_usage)
def create_basic_stream_logger():
"""Sets up a basic stream logger.
Configures the root logger to use a
`logging.StreamHandler` and sets the logging level to `logging.INFO`.
Notes
-----
This does not change the logger configuration if the root logger
already is configured (i.e. `len(getLogger().handlers) > 0`)
"""
logging.basicConfig(
level=logging.INFO, format="%(levelname)s - %(name)s - %(message)s"
)
return logging.getLogger("")
def recursive_update(d, u):
"""
Given two dictionaries d and u, update dict d recursively.
E.g.:
d = {'a': {'b' : 1}}
u = {'c': 2, 'a': {'d': 3}}
=> {'a': {'b': 1, 'd': 3}, 'c': 2}
"""
for k, v in u.items():
if isinstance(v, collections.Mapping):
r = recursive_update(d.get(k, {}), v)
d[k] = r
else:
d[k] = u[k]
return d
def iterate_flattened_separately(dictionary, manually_sorted_keys=None):
"""
Recursively iterate over the items of a dictionary in a special order.
First iterate over manually sorted keys and then over all items that are
non-dictionary values (sorted by keys), then over the rest
(sorted by keys), providing full dotted paths for every leaf.
"""
manually_sorted_keys = manually_sorted_keys or []
def get_order(key_and_value):
key, value = key_and_value
if key in manually_sorted_keys:
return 0, manually_sorted_keys.index(key)
elif not is_non_empty_dict(value):
return 1, key
else:
return 2, key
for key, value in sorted(dictionary.items(), key=get_order):
if is_non_empty_dict(value):
yield key, PATHCHANGE
for k, val in iterate_flattened_separately(value, manually_sorted_keys):
yield join_paths(key, k), val
else:
yield key, value
def is_non_empty_dict(python_object):
return isinstance(python_object, dict) and python_object
def iterate_flattened(d):
"""
Recursively iterate over the items of a dictionary.
Provides a full dotted paths for every leaf.
"""
for key in sorted(d.keys()):
value = d[key]
if isinstance(value, dict) and value:
for k, v in iterate_flattened(d[key]):
yield join_paths(key, k), v
else:
yield key, value
def set_by_dotted_path(d, path, value):
"""
Set an entry in a nested dict using a dotted path.
Will create dictionaries as needed.
Examples
--------
>>> d = {'foo': {'bar': 7}}
>>> set_by_dotted_path(d, 'foo.bar', 10)
>>> d
{'foo': {'bar': 10}}
>>> set_by_dotted_path(d, 'foo.d.baz', 3)
>>> d
{'foo': {'bar': 10, 'd': {'baz': 3}}}
"""
split_path = path.split(".")
current_option = d
for p in split_path[:-1]:
if p not in current_option:
current_option[p] = dict()
current_option = current_option[p]
current_option[split_path[-1]] = value
def get_by_dotted_path(d, path, default=None):
"""
Get an entry from nested dictionaries using a dotted path.
Example
-------
>>> get_by_dotted_path({'foo': {'a': 12}}, 'foo.a')
12
"""
if not path:
return d
split_path = path.split(".")
current_option = d
for p in split_path:
if p not in current_option:
return default
current_option = current_option[p]
return current_option
def iter_prefixes(path):
"""
Iterate through all (non-empty) prefixes of a dotted path.
Example
-------
>>> list(iter_prefixes('foo.bar.baz'))
['foo', 'foo.bar', 'foo.bar.baz']
"""
split_path = path.split(".")
for i in range(1, len(split_path) + 1):
yield join_paths(*split_path[:i])
def join_paths(*parts):
"""Join different parts together to a valid dotted path."""
return ".".join(str(p).strip(".") for p in parts if p)
def is_prefix(pre_path, path):
"""Return True if pre_path is a path-prefix of path."""
pre_path = pre_path.strip(".")
path = path.strip(".")
return not pre_path or path.startswith(pre_path + ".")
def rel_path(base, path):
"""Return path relative to base."""
if base == path:
return ""
assert is_prefix(base, path), "{} not a prefix of {}".format(base, path)
return path[len(base) :].strip(".")
def convert_to_nested_dict(dotted_dict):
"""Convert a dict with dotted path keys to corresponding nested dict."""
nested_dict = {}
for k, v in iterate_flattened(dotted_dict):
set_by_dotted_path(nested_dict, k, v)
return nested_dict
def _is_sacred_frame(frame):
return frame.f_globals["__name__"].split(".")[0] == "sacred"
def print_filtered_stacktrace(filter_traceback="default"):
print(format_filtered_stacktrace(filter_traceback), file=sys.stderr)
def format_filtered_stacktrace(filter_traceback="default"):
"""
Returns the traceback as `string`.
`filter_traceback` can be one of:
- 'always': always filter out sacred internals
- 'default': Default behaviour: filter out sacred internals
if the exception did not originate from within sacred, and
print just the internal stack trace otherwise
- 'never': don't filter, always print full traceback
- All other values will fall back to 'never'.
"""
exc_type, exc_value, exc_traceback = sys.exc_info()
# determine if last exception is from sacred
current_tb = exc_traceback
while current_tb.tb_next is not None:
current_tb = current_tb.tb_next
if filter_traceback == "default" and _is_sacred_frame(current_tb.tb_frame):
# just print sacred internal trace
header = [
"Exception originated from within Sacred.\n"
"Traceback (most recent calls):\n"
]
texts = tb.format_exception(exc_type, exc_value, current_tb)
return "".join(header + texts[1:]).strip()
elif filter_traceback in ("default", "always"):
# print filtered stacktrace
if sys.version_info >= (3, 5):
tb_exception = tb.TracebackException(
exc_type, exc_value, exc_traceback, limit=None
)
return "".join(filtered_traceback_format(tb_exception))
else:
s = "Traceback (most recent calls WITHOUT Sacred internals):"
current_tb = exc_traceback
while current_tb is not None:
if not _is_sacred_frame(current_tb.tb_frame):
tb.print_tb(current_tb, 1)
current_tb = current_tb.tb_next
s += "\n".join(tb.format_exception_only(exc_type, exc_value)).strip()
return s
elif filter_traceback == "never":
# print full stacktrace
return "\n".join(tb.format_exception(exc_type, exc_value, exc_traceback))
else:
raise ValueError("Unknown value for filter_traceback: " + filter_traceback)
def format_sacred_error(e, short_usage):
lines = []
if e.print_usage:
lines.append(short_usage)
if e.print_traceback:
lines.append(format_filtered_stacktrace(e.filter_traceback))
else:
lines.append("\n".join(tb.format_exception_only(type(e), e)))
return "\n".join(lines)
def filtered_traceback_format(tb_exception, chain=True):
if chain:
if tb_exception.__cause__ is not None:
yield from filtered_traceback_format(tb_exception.__cause__, chain=chain)
yield tb._cause_message
elif (
tb_exception.__context__ is not None
and not tb_exception.__suppress_context__
):
yield from filtered_traceback_format(tb_exception.__context__, chain=chain)
yield tb._context_message
yield "Traceback (most recent calls WITHOUT Sacred internals):\n"
current_tb = tb_exception.exc_traceback
while current_tb is not None:
if not _is_sacred_frame(current_tb.tb_frame):
stack = tb.StackSummary.extract(
tb.walk_tb(current_tb), limit=1, lookup_lines=True, capture_locals=False
)
yield from stack.format()
current_tb = current_tb.tb_next
yield from tb_exception.format_exception_only()
# noinspection PyUnusedLocal
@wrapt.decorator
def optional_kwargs_decorator(wrapped, instance=None, args=None, kwargs=None):
# here wrapped is itself a decorator
if args: # means it was used as a normal decorator (so just call it)
return wrapped(*args, **kwargs)
else: # used with kwargs, so we need to return a decorator
return partial(wrapped, **kwargs)
def get_inheritors(cls):
"""Get a set of all classes that inherit from the given class."""
subclasses = set()
work = [cls]
while work:
parent = work.pop()
for child in parent.__subclasses__():
if child not in subclasses:
subclasses.add(child)
work.append(child)
return subclasses
# Credit to Zarathustra and epost from stackoverflow
# Taken from http://stackoverflow.com/a/1176023/1388435
def convert_camel_case_to_snake_case(name):
"""Convert CamelCase to snake_case."""
s1 = re.sub("(.)([A-Z][a-z]+)", r"\1_\2", name)
return re.sub("([a-z0-9])([A-Z])", r"\1_\2", s1).lower()
def apply_backspaces_and_linefeeds(text):
"""
Interpret backspaces and linefeeds in text like a terminal would.
Interpret text like a terminal by removing backspace and linefeed
characters and applying them line by line.
If final line ends with a carriage it keeps it to be concatenable with next
output chunk.
"""
orig_lines = text.split("\n")
orig_lines_len = len(orig_lines)
new_lines = []
for orig_line_idx, orig_line in enumerate(orig_lines):
chars, cursor = [], 0
orig_line_len = len(orig_line)
for orig_char_idx, orig_char in enumerate(orig_line):
if orig_char == "\r" and (
orig_char_idx != orig_line_len - 1
or orig_line_idx != orig_lines_len - 1
):
cursor = 0
elif orig_char == "\b":
cursor = max(0, cursor - 1)
else:
if (
orig_char == "\r"
and orig_char_idx == orig_line_len - 1
and orig_line_idx == orig_lines_len - 1
):
cursor = len(chars)
if cursor == len(chars):
chars.append(orig_char)
else:
chars[cursor] = orig_char
cursor += 1
new_lines.append("".join(chars))
return "\n".join(new_lines)
def module_exists(modname):
"""Checks if a module exists without actually importing it."""
try:
return pkgutil.find_loader(modname) is not None
except ImportError:
# TODO: Temporary fix for tf 1.14.0.
# Should be removed once fixed in tf.
return True
def modules_exist(*modnames):
return all(module_exists(m) for m in modnames)
def module_is_in_cache(modname):
"""Checks if a module was imported before (is in the import cache)."""
return modname in sys.modules
def parse_version(version_string):
"""Returns a parsed version string."""
return version.parse(version_string)
def get_package_version(name):
"""Returns a parsed version string of a package."""
version_string = importlib.import_module(name).__version__
return parse_version(version_string)
def ensure_wellformed_argv(argv):
if argv is None:
argv = sys.argv
elif isinstance(argv, str):
argv = shlex.split(argv)
else:
if not isinstance(argv, (list, tuple)):
raise ValueError("argv must be str or list, but was {}".format(type(argv)))
if not all([isinstance(a, str) for a in argv]):
problems = [a for a in argv if not isinstance(a, str)]
raise ValueError(
"argv must be list of str but contained the "
"following elements: {}".format(problems)
)
return argv
class IntervalTimer(threading.Thread):
@classmethod
def create(cls, func, interval=10):
stop_event = threading.Event()
timer_thread = cls(stop_event, func, interval)
return stop_event, timer_thread
def __init__(self, event, func, interval=10.0):
super().__init__()
self.stopped = event
self.func = func
self.interval = interval
def run(self):
while not self.stopped.wait(self.interval):
self.func()
self.func()
