monty package

Subpackages

• monty.os package
  • Submodules
  • monty.os.path module
  • Module contents

Submodules

monty.bisect module

find_ge(a, x)

Find leftmost item greater than or equal to x.

find_gt(a, x)

Find leftmost value greater than x.

find_le(a, x)

Find rightmost value less than or equal to x.

find_lt(a, x)

Find rightmost value less than x.

index(a, x, atol=None)

Locate the leftmost value exactly equal to x.

monty.collections module

class AttrDict(*args, **kwargs)

Bases: dict

Allows to access dict keys as obj.foo in addition to the traditional way obj[‘foo’]”

Example

>>> d = AttrDict(foo=1, bar=2)
>>> assert d["foo"] == d.foo
>>> d.bar = "hello"
>>> assert d.bar == "hello"

copy()

class FrozenAttrDict(*args, **kwargs)

Bases: monty.collections.frozendict

A dictionary that:

• does not permit changes.
• Allows to access dict keys as obj.foo in addition to the traditional way obj[‘foo’]

class MongoDict(*args, **kwargs)

Bases: object

This dict-like object allows one to access the entries in a nested dict as attributes. Entries (attributes) cannot be modified. It also provides Ipython tab completion hence this object is particularly useful if you need to analyze a nested dict interactively (e.g. documents extracted from a MongoDB database).

>>> m = MongoDict({'a': {'b': 1}, 'x': 2})
>>> assert m.a.b == 1 and m.x == 2
>>> assert "a" in m and "b" in m.a
>>> m["a"]
{'b': 1}

Note

Cannot inherit from ABC collections.Mapping because otherwise dict.keys and dict.items will pollute the namespace. e.g MongoDict({“keys”: 1}).keys would be the ABC dict method.

class Namespace(*args, **kwargs)

Bases: dict

A dictionary that does not permit to redefine its keys.

update(*args, **kwargs)

as_set(obj)

Convert obj into a set, returns None if obj is None.

>>> assert as_set(None) is None and as_set(1) == set([1]) and as_set(range(1,3)) == set([1, 2])

dict2namedtuple(*args, **kwargs)

Helper function to create a namedtuple from a dictionary.

Example

>>> t = dict2namedtuple(foo=1, bar="hello")
>>> assert t.foo == 1 and t.bar == "hello"

>>> t = dict2namedtuple([("foo", 1), ("bar", "hello")])
>>> assert t[0] == t.foo and t[1] == t.bar

Warning

• The order of the items in the namedtuple is not deterministic if kwargs are used. namedtuples, however, should always be accessed by attribute hence this behaviour should not represent a serious problem.
• Don’t use this function in code in which memory and performance are crucial since a dict is needed to instantiate the tuple!

class frozendict(*args, **kwargs)

Bases: dict

A dictionary that does not permit changes. The naming violates PEP8 to be consistent with standard Python’s “frozenset” naming.

update(*args, **kwargs)

tree()

A tree object, which is effectively a recursive defaultdict that adds tree as members.

Usage:

x = tree() x[‘a’][‘b’][‘c’] = 1

Returns:A tree.

monty.design_patterns module

class NullFile

Bases: object

A file object that is associated to /dev/null.

no-op

class NullStream

Bases: object

A fake stream with a no-op write..

write(*args)

no-op

cached_class(klass)

Decorator to cache class instances by constructor arguments. This results in a class that behaves like a singleton for each set of constructor arguments, ensuring efficiency.

Note that this should be used for immutable classes only. Having a cached mutable class makes very little sense. For efficiency, avoid using this decorator for situations where there are many constructor arguments permutations.

The keywords argument dictionary is converted to a tuple because dicts are mutable; keywords themselves are strings and so are always hashable, but if any arguments (keyword or positional) are non-hashable, that set of arguments is not cached.

singleton(cls)

This decorator can be used to create a singleton out of a class.

Usage:

@singleton
class MySingleton():

    def __init__():
        pass

monty.dev module

This module implements several useful functions and decorators that can be particularly useful for developers. E.g., deprecating methods / classes, etc.

deprecated(replacement=None, message=None)

Decorator to mark classes or functions as deprecated, with a possible replacement.

Parameters:

• replacement (callable) – A replacement class or method.
• message (str) – A warning message to be displayed.

Returns:

Original function, but with a warning to use the updated class.

get_ncpus()

Note

If you are using Python >= 2.7, multiprocessing.cpu_count() already provides the number of CPUs. In fact, this is the first method tried. The purpose of this function is to cater to old Python versions that still exist on many Linux style clusters.

Number of virtual or physical CPUs on this system, i.e. user/real as output by time(1) when called with an optimally scaling userspace-only program. Return -1 if ncpus cannot be detected. Taken from: http://stackoverflow.com/questions/1006289/how-to-find-out-the-number-of- cpus-in-python

install_excepthook(hook_type='color', **kwargs)

This function replaces the original python traceback with an improved version from Ipython. Use color for colourful traceback formatting, verbose for Ka-Ping Yee’s “cgitb.py” version kwargs are the keyword arguments passed to the constructor. See IPython.core.ultratb.py for more info.

Returns:0 if hook is installed successfully.

class requires(condition, message)

Bases: object

Decorator to mark classes or functions as requiring a specified condition to be true. This can be used to present useful error messages for optional dependencies. For example, decorating the following code will check if scipy is present and if not, a runtime error will be raised if someone attempts to call the use_scipy function:

try:
    import scipy
except ImportError:
    scipy = None

@requires(scipy is not None, "scipy is not present.")
def use_scipy():
    print(scipy.majver)

Parameters:

• condition – Condition necessary to use the class or function.
• message – A message to be displayed if the condition is not True.

monty.fnmatch module

This module provides support for Unix shell-style wildcards

class WildCard(wildcard, sep='|')

Bases: object

This object provides an easy-to-use interface for filename matching with shell patterns (fnmatch).

>>> w = WildCard("*.nc|*.pdf")
>>> w.filter(["foo.nc", "bar.pdf", "hello.txt"])
['foo.nc', 'bar.pdf']

>>> w.filter("foo.nc")
['foo.nc']

Initializes a WildCard.

Parameters:

• wildcard (str) – String of tokens separated by sep. Each token represents a pattern.
• sep (str) – Separator for shell patterns.

filter(names)

Returns a list with the names matching the pattern.

match(name)

Returns True if name matches one of the patterns.

monty.fractions module

Math functions.

gcd(*numbers)

Returns the greatest common divisor for a sequence of numbers.

Parameters:*numbers – Sequence of numbers. Returns:(int) Greatest common divisor of numbers.

gcd_float(numbers, tol=1e-08)

Returns the greatest common divisor for a sequence of numbers. Uses a numerical tolerance, so can be used on floats

Parameters:

• numbers – Sequence of numbers.
• tol – Numerical tolerance

Returns:

(int) Greatest common divisor of numbers.

lcm(*numbers)

Return lowest common multiple of a sequence of numbers.

Parameters:*numbers – Sequence of numbers. Returns:(int) Lowest common multiple of numbers.

monty.functools module

functools, especially backported from Python 3.

exception TimeoutError(message)

Bases: Exception

class lazy_property(func)

Bases: object

lazy_property descriptor

Used as a decorator to create lazy attributes. Lazy attributes are evaluated on first use.

classmethod invalidate(inst, name)

Invalidate a lazy attribute.

This obviously violates the lazy contract. A subclass of lazy may however have a contract where invalidation is appropriate.

lru_cache(maxsize=128, typed=False)

Least-recently-used cache decorator, which is a backport of the same function in Python >= 3.2.

If maxsize is set to None, the LRU features are disabled and the cache can grow without bound.

If typed is True, arguments of different types will be cached separately. For example, f(3.0) and f(3) will be treated as distinct calls with distinct results.

Arguments to the cached function must be hashable.

View the cache statistics named tuple (hits, misses, maxsize, currsize) with f.cache_info(). Clear the cache and statistics with f.cache_clear(). Access the underlying function with f.__wrapped__.

See: http://en.wikipedia.org/wiki/Cache_algorithms#Least_Recently_Used

prof_main(main)

Decorator for profiling main programs.

Profiling is activated by prepending the command line options supported by the original main program with the keyword prof. .. rubric:: Example

$ script.py arg –foo=1

becomes

$ script.py prof arg –foo=1

The decorated main accepts two new arguments:

prof_file: Name of the output file with profiling data

If not given, a temporary file is created.

sortby: Profiling data are sorted according to this value.

default is “time”. See sort_stats.

return_if_raise(exception_tuple, retval_if_exc, disabled=False)

Decorator for functions, methods or properties. Execute the callable in a try block, and return retval_if_exc if one of the exceptions listed in exception_tuple is raised (se also return_node_if_raise).

Setting disabled to True disables the try except block (useful for debugging purposes). One can use this decorator to define properties.

Example:

@return_if_raise(ValueError, None)
def return_none_if_value_error(self):
    pass

@return_if_raise((ValueError, KeyError), "hello")
def another_method(self):
    pass

@property
@return_if_raise(AttributeError, None)
def name(self):
    "Name of the object, None if not set."
    return self._name

return_none_if_raise = functools.partial(<function return_if_raise>, retval_if_exc=None)

This decorator returns None if one of the exceptions is raised.

@return_none_if_raise(ValueError) def method(self):

class timeout(seconds=1, error_message='Timeout')

Bases: object

Timeout function. Use to limit matching to a certain time limit. Note that this works only on Unix-based systems as it uses signal. Usage:

try:

with timeout(3):

do_stuff()

except TimeoutError:

do_something_else()

Parameters:

• seconds (int) – Allowed time for function in seconds.
• error_message (str) – An error message.

handle_timeout(signum, frame)

monty.inspect module

Useful additional functions to help get information about live objects

all_subclasses(cls)

Given a class cls, this recursive function returns a list with all subclasses, subclasses of subclasses, and so on.

caller_name(skip=2)

Get a name of a caller in the format module.class.method

skip specifies how many levels of stack to skip while getting caller name. skip=1 means “who calls me”, skip=2 “who calls my caller” etc.

An empty string is returned if skipped levels exceed stack height

Taken from:

https://gist.github.com/techtonik/2151727

Public Domain, i.e. feel free to copy/paste

find_top_pyfile()

This function inspects the Cpython frame to find the path of the script.

initializer(func)

Automatically assigns the parameters. http://stackoverflow.com/questions/1389180/python-automatically-initialize-instance-variables

>>> class process:
...     @initializer
...     def __init__(self, cmd, reachable=False, user='root'):
...         pass
>>> p = process('halt', True)
>>> p.cmd, p.reachable, p.user
('halt', True, 'root')

monty.io module

Augments Python’s suite of IO functions with useful transparent support for compressed files.

class FileLock(file_name, timeout=10, delay=0.05)

Bases: object

A file locking mechanism that has context-manager support so you can use it in a with statement. This should be relatively cross-compatible as it doesn’t rely on msvcrt or fcntl for the locking. Taken from http://www.evanfosmark.com/2009/01/cross-platform-file-locking -support-in-python/

Prepare the file locker. Specify the file to lock and optionally the maximum timeout and the delay between each attempt to lock.

Parameters:

• file_name – Name of file to lock.
• timeout – Maximum timeout for locking. Defaults to 10.
• delay – Delay between each attempt to lock. Defaults to 0.05.

Error

alias of FileLockException

acquire()

Acquire the lock, if possible. If the lock is in use, it check again every delay seconds. It does this until it either gets the lock or exceeds timeout number of seconds, in which case it throws an exception.

release()

Get rid of the lock by deleting the lockfile. When working in a with statement, this gets automatically called at the end.

exception FileLockException

Bases: Exception

Exception raised by FileLock.

get_open_fds()

Return the number of open file descriptors for current process

reverse_readfile(filename)

A much faster reverse read of file by using Python’s mmap to generate a memory-mapped file. It is slower for very small files than reverse_readline, but at least 2x faster for large files (the primary use of such a method).

Parameters:filename (str) – Name of file to read. Yields:Lines from the file in reverse order.

reverse_readline(m_file, blk_size=4096, max_mem=4000000)

Generator method to read a file line-by-line, but backwards. This allows one to efficiently get data at the end of a file.

Based on code by Peter Astrand <astrand@cendio.se>, using modifications by Raymond Hettinger and Kevin German. http://code.activestate.com/recipes/439045-read-a-text-file-backwards -yet-another-implementat/

Reads file forwards and reverses in memory for files smaller than the max_mem parameter, or for gzip files where reverse seeks are not supported.

Files larger than max_mem are dynamically read backwards.

Parameters:

• m_file (File) – File stream to read (backwards)
• blk_size (int) – The buffer size. Defaults to 4096.
• max_mem (int) – The maximum amount of memory to involve in this operation. This is used to determine when to reverse a file in-memory versus seeking portions of a file. For bz2 files, this sets the maximum block size.

Returns:

Generator that returns lines from the file. Similar behavior to the file.readline() method, except the lines are returned from the back of the file.

zopen(filename, *args, **kwargs)

This function wraps around the bz2, gzip and standard python’s open function to deal intelligently with bzipped, gzipped or standard text files.

Parameters:

• filename (str/Path) – filename or pathlib.Path.
• *args – Standard args for python open(..). E.g., ‘r’ for read, ‘w’ for write.
• **kwargs – Standard kwargs for python open(..).

Returns:

File-like object. Supports with context.

monty.itertools module

chunks(items, n)

Yield successive n-sized chunks from a list-like object.

>>> import pprint
>>> pprint.pprint(list(chunks(range(1, 25), 10)))
[(1, 2, 3, 4, 5, 6, 7, 8, 9, 10),
 (11, 12, 13, 14, 15, 16, 17, 18, 19, 20),
 (21, 22, 23, 24)]

ilotri(items, diago=True, with_inds=False)

A generator that yields the lower triangle of the matrix (items x items)

Parameters:

• items – Iterable object with elements [e0, e1, ...]
• diago – False if diagonal matrix elements should be excluded
• with_inds – If True, (i,j) (e_i, e_j) is returned else (e_i, e_j)

>>> for (ij, mate) in ilotri([0,1], with_inds=True):
...     print("ij:", ij, "mate:", mate)
ij: (0, 0) mate: (0, 0)
ij: (1, 0) mate: (1, 0)
ij: (1, 1) mate: (1, 1)

iterator_from_slice(s)

Constructs an iterator given a slice object s.

Note

The function returns an infinite iterator if s.stop is None

iuptri(items, diago=True, with_inds=False)

A generator that yields the upper triangle of the matrix (items x items)

Parameters:

• items – Iterable object with elements [e0, e1, ...]
• diago – False if diagonal matrix elements should be excluded
• with_inds – If True, (i,j) (e_i, e_j) is returned else (e_i, e_j)

>>> for (ij, mate) in iuptri([0,1], with_inds=True):
...     print("ij:", ij, "mate:", mate)
ij: (0, 0) mate: (0, 0)
ij: (0, 1) mate: (0, 1)
ij: (1, 1) mate: (1, 1)

monty.json module

JSON serialization and deserialization utilities.

exception MSONError

Bases: Exception

Exception class for serialization errors.

class MSONable

Bases: object

This is a mix-in base class specifying an API for msonable objects. MSON is Monty JSON. Essentially, MSONable objects must implement an as_dict method, which must return a json serializable dict and must also support no arguments (though optional arguments to finetune the output is ok), and a from_dict class method that regenerates the object from the dict generated by the as_dict method. The as_dict method should contain the “@module” and “@class” keys which will allow the MontyEncoder to dynamically deserialize the class. E.g.:

d["@module"] = self.__class__.__module__
d["@module"] = self.__class__.__name__

A default implementation is provided in MSONable, which automatically determines if the class already contains self.argname or self._argname attributes for every arg. If so, these will be used for serialization in the dict format. Similarly, the default from_dict will deserialization classes of such form. An example is given below:

class MSONClass(MSONable):

def __init__(self, a, b, c, d=1, **kwargs):
    self.a = a
    self.b = b
    self._c = c
    self._d = d
    self.kwargs = kwargs

For such classes, you merely need to inherit from MSONable and you do not need to implement your own as_dict or from_dict protocol.

as_dict()

A JSON serializable dict representation of an object.

classmethod from_dict(d)

to_json()

Returns a json string representation of the MSONable object.

class MontyDecoder(*, object_hook=None, parse_float=None, parse_int=None, parse_constant=None, strict=True, object_pairs_hook=None)

Bases: json.decoder.JSONDecoder

A Json Decoder which supports the MSONable API. By default, the decoder attempts to find a module and name associated with a dict. If found, the decoder will generate a Pymatgen as a priority. If that fails, the original decoded dictionary from the string is returned. Note that nested lists and dicts containing pymatgen object will be decoded correctly as well.

Usage:

# Add it as a cls keyword when using json.load json.loads(json_string, cls=MontyDecoder)

object_hook, if specified, will be called with the result of every JSON object decoded and its return value will be used in place of the given dict. This can be used to provide custom deserializations (e.g. to support JSON-RPC class hinting).

object_pairs_hook, if specified will be called with the result of every JSON object decoded with an ordered list of pairs. The return value of object_pairs_hook will be used instead of the dict. This feature can be used to implement custom decoders that rely on the order that the key and value pairs are decoded (for example, collections.OrderedDict will remember the order of insertion). If object_hook is also defined, the object_pairs_hook takes priority.

parse_float, if specified, will be called with the string of every JSON float to be decoded. By default this is equivalent to float(num_str). This can be used to use another datatype or parser for JSON floats (e.g. decimal.Decimal).

parse_int, if specified, will be called with the string of every JSON int to be decoded. By default this is equivalent to int(num_str). This can be used to use another datatype or parser for JSON integers (e.g. float).

parse_constant, if specified, will be called with one of the following strings: -Infinity, Infinity, NaN. This can be used to raise an exception if invalid JSON numbers are encountered.

If strict is false (true is the default), then control characters will be allowed inside strings. Control characters in this context are those with character codes in the 0-31 range, including '\t' (tab), '\n', '\r' and '\0'.

decode(*args, **kwargs)

process_decoded(d)

Recursive method to support decoding dicts and lists containing pymatgen objects.

class MontyEncoder(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)

Bases: json.encoder.JSONEncoder

A Json Encoder which supports the MSONable API, plus adds support for numpy arrays, datetime objects, bson ObjectIds (requires bson).

Usage:

# Add it as a *cls* keyword when using json.dump
json.dumps(object, cls=MontyEncoder)

Constructor for JSONEncoder, with sensible defaults.

If skipkeys is false, then it is a TypeError to attempt encoding of keys that are not str, int, float or None. If skipkeys is True, such items are simply skipped.

If ensure_ascii is true, the output is guaranteed to be str objects with all incoming non-ASCII characters escaped. If ensure_ascii is false, the output can contain non-ASCII characters.

If check_circular is true, then lists, dicts, and custom encoded objects will be checked for circular references during encoding to prevent an infinite recursion (which would cause an OverflowError). Otherwise, no such check takes place.

If allow_nan is true, then NaN, Infinity, and -Infinity will be encoded as such. This behavior is not JSON specification compliant, but is consistent with most JavaScript based encoders and decoders. Otherwise, it will be a ValueError to encode such floats.

If sort_keys is true, then the output of dictionaries will be sorted by key; this is useful for regression tests to ensure that JSON serializations can be compared on a day-to-day basis.

If indent is a non-negative integer, then JSON array elements and object members will be pretty-printed with that indent level. An indent level of 0 will only insert newlines. None is the most compact representation.

If specified, separators should be an (item_separator, key_separator) tuple. The default is (‘, ‘, ‘: ‘) if indent is None and (‘,’, ‘: ‘) otherwise. To get the most compact JSON representation, you should specify (‘,’, ‘:’) to eliminate whitespace.

If specified, default is a function that gets called for objects that can’t otherwise be serialized. It should return a JSON encodable version of the object or raise a TypeError.

default(o)

Overriding default method for JSON encoding. This method does two things: (a) If an object has a to_dict property, return the to_dict output. (b) If the @module and @class keys are not in the to_dict, add them to the output automatically. If the object has no to_dict property, the default Python json encoder default method is called.

Parameters:o – Python object. Returns:Python dict representation.

jsanitize(obj, strict=False, allow_bson=False)

This method cleans an input json-like object, either a list or a dict or some sequence, nested or otherwise, by converting all non-string dictionary keys (such as int and float) to strings, and also recursively encodes all objects using Monty’s as_dict() protocol.

Parameters:

• obj – input json-like object.
• strict (bool) – This parameters sets the behavior when jsanitize encounters an object it does not understand. If strict is True, jsanitize will try to get the as_dict() attribute of the object. If no such attribute is found, an attribute error will be thrown. If strict is False, jsanitize will simply call str(object) to convert the object to a string representation.
• allow_bson (bool) – This parameters sets the behavior when jsanitize encounters an bson supported type such as objectid and datetime. If True, such bson types will be ignored, allowing for proper insertion into MongoDb databases.

Returns:

Sanitized dict that can be json serialized.

monty.logging module

TODO: Modify module doc.

enable_logging(main)

This decorator is used to decorate main functions. It adds the initialization of the logger and an argument parser that allows one to select the loglevel. Useful if we are writing simple main functions that call libraries where the logging module is used

Parameters:main – main function.

logged(level=10)

Useful logging decorator. If a method is logged, the beginning and end of the method call will be logged at a pre-specified level.

Parameters:level – Level to log method at. Defaults to DEBUG.

monty.math module

nCr(n, r)

Calculates nCr.

Parameters:

• n (int) – total number of items.
• r (int) – items to choose

Returns:

nCr.

nPr(n, r)

Calculates nPr.

Parameters:

• n (int) – total number of items.
• r (int) – items to permute

Returns:

nPr.

monty.msgpack module

msgpack serialization and deserialization utilities. Right now, this is a stub using monty.json encoder and decoders. The naming is just for clearer usage with msgpack’s default and object_hook naming.

default(obj)

For use with msgpack.packb(obj, default=default). Supports Monty’s as_dict protocol, numpy arrays and datetime.

object_hook(d)

For use with msgpack.unpackb(dict, object_hook=object_hook.). Supports Monty’s as_dict protocol, numpy arrays and datetime.

monty.operator module

Useful additional functions for operators

operator_from_str(op)

Return the operator associated to the given string op.

Raises:KeyError if invalid string.

>>> assert operator_from_str("==")(1, 1) and operator_from_str("+")(1,1) == 2

monty.pprint module

draw_tree(node, child_iter=<function <lambda>>, text_str=<function <lambda>>)

Parameters:

• node – the root of the tree to be drawn,
• child_iter – function that when called with a node, returns an iterable over all its children
• text_str – turns a node into the text to be displayed in the tree.

The default implementations of these two arguments retrieve the children by accessing node.children and simply use str(node) to convert a node to a string. The resulting tree is drawn into a buffer and returned as a string.

Based on https://pypi.python.org/pypi/asciitree/

pprint_table(table, out=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='UTF-8'>, rstrip=False)

Prints out a table of data, padded for alignment Each row must have the same number of columns.

Parameters:

• table – The table to print. A list of lists.
• out – Output stream (file-like object)
• rstrip – if True, trailing withespaces are removed from the entries.

monty.re module

#TODO: Write module doc.

regrep(filename, patterns, reverse=False, terminate_on_match=False, postprocess=<class 'str'>)

A powerful regular expression version of grep.

Parameters:

• filename (str) – Filename to grep.
• patterns (dict) – A dict of patterns, e.g., {“energy”: “energy(sigma->0)s+=s+([d-.]+)”}.
• reverse (bool) – Read files in reverse. Defaults to false. Useful for large files, especially when used with terminate_on_match.
• terminate_on_match (bool) – Whether to terminate when there is at least one match in each key in pattern.
• postprocess (callable) – A post processing function to convert all matches. Defaults to str, i.e., no change.

Returns:

{key1: [[[matches...], lineno], [[matches...], lineno],

[[matches...], lineno], ...],

key2: ...}

For reverse reads, the lineno is given as a -ve number. Please note that 0-based indexing is used.

Return type:

A dict of the following form

monty.serialization module

This module implements serialization support for common formats such as json and yaml.

dumpfn(obj, fn, *args, **kwargs)

Dump to a json/yaml directly by filename instead of a File-like object. For YAML, ruamel.yaml must be installed. The file type is automatically detected. YAML is assumed if the filename contains “yaml” (lower or upper case). Otherwise, json is always assumed.

Parameters:

• obj (object) – Object to dump.
• fn (str/Path) – filename or pathlib.Path.
• *args – Any of the args supported by json/yaml.dump.
• **kwargs – Any of the kwargs supported by json/yaml.dump.

Returns:

(object) Result of json.load.

loadfn(fn, *args, **kwargs)

Loads json/yaml/msgpack directly from a filename instead of a File-like object. For YAML, ruamel.yaml must be installed. The file type is automatically detected. YAML is assumed if the filename contains “yaml” (lower or upper case). Otherwise, json is always assumed.

Parameters:

• fn (str/Path) – filename or pathlib.Path.
• *args – Any of the args supported by json/yaml.load.
• **kwargs – Any of the kwargs supported by json/yaml.load.

Returns:

(object) Result of json/yaml/msgpack.load.

monty.shutil module

compress_dir(path, compression='gz')

Recursively compresses all files in a directory. Note that this compresses all files singly, i.e., it does not create a tar archive. For that, just use Python tarfile class.

Parameters:

• path (str) – Path to parent directory.
• compression (str) – A compression mode. Valid options are “gz” or “bz2”. Defaults to gz.

compress_file(filepath, compression='gz')

Compresses a file with the correct extension. Functions like standard Unix command line gzip and bzip2 in the sense that the original uncompressed files are not retained.

Parameters:

• filepath (str) – Path to file.
• compression (str) – A compression mode. Valid options are “gz” or “bz2”. Defaults to “gz”.

copy_r(src, dst)

Implements a recursive copy function similar to Unix’s “cp -r” command. Surprisingly, python does not have a real equivalent. shutil.copytree only works if the destination directory is not present.

Parameters:

• src (str) – Source folder to copy.
• dst (str) – Destination folder.

decompress_dir(path)

Recursively decompresses all files in a directory.

Parameters:path (str) – Path to parent directory.

decompress_file(filepath)

Decompresses a file with the correct extension. Automatically detects gz, bz2 or z extension.

Parameters:

• filepath (str) – Path to file.
• compression (str) – A compression mode. Valid options are “gz” or “bz2”. Defaults to “gz”.

gzip_dir(path, compresslevel=6)

Gzips all files in a directory. Note that this is different from shutil.make_archive, which creates a tar archive. The aim of this method is to create gzipped files that can still be read using common Unix-style commands like zless or zcat.

Parameters:

• path (str) – Path to directory.
• compresslevel (int) – Level of compression, 1-9. 9 is default for GzipFile, 6 is default for gzip.

monty.string module

Useful additional string functions.

boxed(msg, ch='=', pad=5)

Returns a string in a box

Parameters:

• msg – Input string.
• ch – Character used to form the box.
• pad – Number of characters ch added before and after msg.

>>> print(boxed("hello", ch="*", pad=2))
***********
** hello **
***********

indent(lines, amount, ch=' ')

Indent the lines in a string by padding each one with proper number of pad characters

is_string(s)

True if s behaves like a string (duck typing test).

list_strings(arg)

Always return a list of strings, given a string or list of strings as input.

Examples:

>>> list_strings('A single string')
['A single string']

>>> list_strings(['A single string in a list'])
['A single string in a list']

>>> list_strings(['A','list','of','strings'])
['A', 'list', 'of', 'strings']

make_banner(s, width=78, mark='*')

marquee(text='', width=78, mark='*')

Return the input string centered in a ‘marquee’.

Parameters:

• text (str) – Input string
• width (int) – Width of final output string.
• mark (str) – Character used to fill string.

Examples:

>>> marquee('A test', width=40)
'**************** A test ****************'

>>> marquee('A test', width=40, mark='-')
'---------------- A test ----------------'

marquee(‘A test’,40, ‘ ‘) ‘ A test ‘

remove_non_ascii(s)

Remove non-ascii characters in a file. Needed when support for non-ASCII is not available.

Parameters:s (str) – Input string Returns:String with all non-ascii characters removed.

str2unicode(s)

Converts strings to unicode in python 2. Ignores Python 3 strings.

Parameters:s (str/unicode) – Input string / unicode. Returns:Unicode.

unicode2str(s)

Forces a unicode to a string in Python 2, but transparently handles Python 3.

Parameters:s (str/unicode) – Input string / unicode. Returns:str in Python 2. Unchanged otherwise.

monty.subprocess module

class Command(command)

Bases: object

Enables to run subprocess commands in a different thread with TIMEOUT option.

Based on jcollado’s solution:

http://stackoverflow.com/questions/1191374/subprocess-with-timeout/4825933#4825933

and

https://gist.github.com/kirpit/1306188

retcode

Return code of the subprocess

killed

True if subprocess has been killed due to the timeout

output

stdout of the subprocess

error

stderr of the subprocess

Example

com = Command(“sleep 1”).run(timeout=2) print(com.retcode, com.killed, com.output, com.output)

run(timeout=None, **kwargs)

Run a command in a separated thread and wait timeout seconds. kwargs are keyword arguments passed to Popen.

Return: self

monty.tempfile module

Temporary directory and file creation utilities.

class ScratchDir(rootpath, create_symbolic_link=False, copy_from_current_on_enter=False, copy_to_current_on_exit=False)

Bases: object

Note

With effect from Python 3.2, tempfile.TemporaryDirectory already implements much of the functionality of ScratchDir. However, it does not provide options for copying of files to and from (though it is possible to do this with other methods provided by shutil).

Creates a “with” context manager that automatically handles creation of temporary directories (utilizing Python’s build in temp directory functions) and cleanup when done. This improves on Python’s built in functions by allowing for truly temporary workspace that are deleted when it is done. The way it works is as follows:

1. Create a temp dir in specified root path.
2. Optionally copy input files from current directory to temp dir.
3. Change to temp dir.
4. User performs specified operations.
5. Optionally copy generated output files back to original directory.
6. Change back to original directory.
7. Delete temp dir.

Initializes scratch directory given a root path. There is no need to try to create unique directory names. The code will generate a temporary sub directory in the rootpath. The way to use this is using a with context manager. Example:

with ScratchDir("/scratch"):
    do_something()

If the root path does not exist or is None, this will function as a simple pass through, i.e., nothing happens.

Parameters:

• rootpath (str/Path) – The path in which to create temp subdirectories. If this is None, no temp directories will be created and this will just be a simple pass through.
• create_symbolic_link (bool) – Whether to create a symbolic link in the current working directory to the scratch directory created.
• copy_from_current_on_enter (bool) – Whether to copy all files from the current directory (recursively) to the temp dir at the start, e.g., if input files are needed for performing some actions. Defaults to False.
• copy_to_current_on_exit (bool) – Whether to copy files from the scratch to the current directory (recursively) at the end. E .g., if output files are generated during the operation. Defaults to False.

SCR_LINK = 'scratch_link'

monty.termcolor module

Copyright (c) 2008-2011 Volvox Development Team

# Permission is hereby granted, free of charge, to any person obtaining a copy # of this software and associated documentation files (the “Software”), to deal # in the Software without restriction, including without limitation the rights # to use, copy, modify, merge, publish, distribute, sublicense, and/or sell # copies of the Software, and to permit persons to whom the Software is # furnished to do so, subject to the following conditions: # # The above copyright notice and this permission notice shall be included in # all copies or substantial portions of the Software. # # 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 OR COPYRIGHT HOLDERS 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. # # Author: Konstantin Lepa <konstantin.lepa@gmail.com>

ANSII Color formatting for output in terminal.

colored(text, color=None, on_color=None, attrs=None)

Colorize text.

Available text colors:

red, green, yellow, blue, magenta, cyan, white.

Available text highlights:

on_red, on_green, on_yellow, on_blue, on_magenta, on_cyan, on_white.

Available attributes:

bold, dark, underline, blink, reverse, concealed.

Example

colored(‘Hello, World!’, ‘red’, ‘on_grey’, [‘blue’, ‘blink’]) colored(‘Hello, World!’, ‘green’)

cprint(text, color=None, on_color=None, attrs=None, **kwargs)

Print colorize text.

It accepts arguments of print function.

Module contents

Monty is the missing complement to Python. Monty implements supplementary useful functions for Python that are not part of the standard library. Examples include useful utilities like transparent support for zipped files, useful design patterns such as singleton and cached_class, and many more.