Module docplex.cp.utils

Miscellaneous utility functions. Some of theme are here to prevent possible port problems between the different versions of Python.

This module is theoretically not public, but documented because some public classes are extending classes defined here.

class docplex.cp.utils.Barrier(parties)

Bases: object

Barrier blocking multiple threads.

This class implements a simple barrier with no timeout. Implemented here because not available in Python 2

Constructor

Parameters:parties – Number of parties required before unlocking the barrier

wait()

Wait for the barrier This method blocks the calling thread until required number of threads has called this method.

class docplex.cp.utils.Chrono

Bases: object

Chronometer

Constructor Create a new chronometer initialized with current time.

get_elapsed()

Get the chrono elapsed time.

Returns:Time spent from chronometer start time (float), in seconds

get_start()

Get the chrono start time.

Returns:Time when chronometer has been started

restart()

Restart chrono to current time

class docplex.cp.utils.Context(**kwargs)

Bases: dict

Class handling miscellaneous list of parameters.

Constructor

Parameters:**kwargs – List of key=value to initialize context with.

clone()

Clone this context and all sub-contexts recursively.

Returns:Cloned copy of this context.

del_attribute(name)

Remove a context attribute.

Parameters:name – Attribute name Returns:True if attribute has been removed, False if it was not present

export_flat(out=None)

Export this context in flat format

Each context attribute is written on a single line <path>=<value> with UTF-8 encoding.

Parameters:out (Optional) – Target output stream or file name. If not given, default value is sys.stdout.

export_flat_as_string()

Export this context in flat format as a string.

Each context attribute is written on a single line <path>=<value>

Parameters:out (Optional) – Target output stream or file name. If not given, default value is sys.stdout.

get_attribute(name, default=None)

Get a context attribute.

This method search first attribute in this context. If not found, it moves up to parent context, and continues as long as not found or root is reached.

Parameters:

• name – Attribute name
• default – Optional, default value if attribute is absent

Returns:

Attribute value, default value if not found

get_by_path(path, default=None)

Get a context attribute using its path.

Attribute path is a sequence of attribute names separated by dots.

Parameters:

• path – Attribute path
• default – Optional, default value if attribute is not found

Returns:

Attribute value, default value if not found

get_log_output()

Get this context log output

This method returns the log_output defined in attribute ‘log_output’ and convert it to sys.stdout if its value is True

Returns:Log output stream, None if none

get_parent()

Get the parent context.

Each time a context attribute is set to a context, its parent is assigned to the context where it is stored.

Returns:Parent context, None if this context is root

get_root()

Get the root context (last parent with no parent).

Returns:Root context

import_flat(inp=None)

Import a flat file in this context

Each context attribute is added in this context. Each value is converted in the most appropriate type: string, integer, float, boolean or None. Only atomic values are allowed, not lists or other Python complex objects.

Parameters:inp – Input stream or file

is_log_enabled(vrb)

Check if log is enabled for a given verbosity

This method get this context ‘log_output’ attribute to retrieve the log output, and the attribute ‘verbose’ to retrieve the current verbosity level.

Parameters:vrb – Required verbosity level, None for always

log(vrb, *msg)

Log a message if log is enabled with enough verbosity

This method get this context ‘log_output’ attribute to retrieve the log output, and the attribute ‘verbose’ to retrieve the current verbosity level.

Parameters:

• vrb – Required verbosity level, None for always
• msg – Message elements to log (concatenated on one line)

print_context(out=None, indent='')

Print this context.

At each level, atomic values are printed first, then sub-contexts, in alphabetical order.

DEPRECATED. Use write() instead.

Parameters:

• out (Optional) – Target output stream or file name. If not given, default value is sys.stdout.
• indent (Optional) – Start line indentation. Default is empty

search_and_replace_attribute(name, value, path='')

Replace an existing attribute.

The attribute is searched first as a value in this context node. If not found, it is searched recursively in children contexts, in alphabetical order.

Parameters:

• name – Attribute name
• value – Attribute value, None to remove attribute
• path – Path of the current node. default is ‘’

Returns:

Full path of the attribute that has been found and replaced, None if not found

set_attribute(name, value)

Set a context attribute.

Parameters:

• name – Attribute name
• value – Attribute value

set_by_path(path, value)

Set a context attribute using its path.

Attribute path is a sequence of attribute names separated by dots.

Parameters:

• path – Attribute path
• value – Attribute value

set_other(ctx)

Set another context into this one.

All attributes of given context are set in this one, replacing previous value if any. If one value is another context, it is cloned before being set.

Parameters:ctx – Other context to add to this one.

write(out=None, indent='')

Write this context.

At each level, atomic values are printed first, then sub-contexts, in alphabetical order.

If the given output is a string, it is considered as a file name that is opened by this method using ‘utf-8’ encoding.

Parameters:

• out (Optional) – Target output stream or file name. If not given, default value is sys.stdout.
• indent (Optional) – Start line indentation. Default is empty

exception docplex.cp.utils.CpoException(msg)

Bases: Exception

Exception thrown in case of CPO errors.

Constructor

Parameters:msg – Error message

exception docplex.cp.utils.CpoNotSupportedException(msg)

Bases: docplex.cp.utils.CpoException

Exception thrown when a CPO function is not supported.

Constructor

Parameters:msg – Error message

class docplex.cp.utils.FunctionCache(f)

Bases: object

Object caching the result of a function. Future calls with same parameters returns a result stored in a cache dictionary.

This object is not thread-safe.

Constructor

Parameters:f – Function whose results should be cached.

clear()

Clear all dictionary content

get(*param)

Get the function result for a given parameter :param param: Function parameters

Returns:Function result

class docplex.cp.utils.IdAllocator(prefix, bdgts='0123456789')

Bases: object

Allocator of identifiers.

This implementation is not thread-safe. Use SafeIdAllocator for a usage in a multi-thread environment.

Constructor

Parameters:

• prefix – Prefix of all ids
• bdgts – List of digit characters to be use for counter conversion

allocate()

Allocate a new id.

Returns:Next id for this allocator

get_count()

Get the number of id that has been allocated by this allocator.

Returns:Number of id that has been allocated by this allocator.

get_prefix()

Get the name prefix used by this allocator.

Returns:Name prefix

class docplex.cp.utils.IdentityAccessor

Bases: object

Object implementing a __getitem__ that returns the key as value.

class docplex.cp.utils.InfoDict

Bases: dict

Dictionary used to store information of various types.

clone()

Clone this information dictionary

Returns:New information dictionary, cloned copy of this one.

incr(key, val)

Increment the value of an attribute considered as a number.

If the attribute is not already in the dictionary, it is set to the given increment value.

Parameters:

• key – Attribute key
• val – Value to add

print_infos(out=None, indent='')

Print this information structure.

Attributes are sorted in alphabetical order

If the given output is a string, it is considered as a file name that is opened by this method using ‘utf-8’ encoding.

DEPRECATED. Use write() instead.

Parameters:

• out (Optional) – Target output stream or file name. If not given, default value is sys.stdout.
• indent (Optional) – Start line indentation. Default is empty

write(out=None, indent='')

Write this information structure.

Attributes are sorted in alphabetical order

If the given output is a string, it is considered as a file name that is opened by this method using ‘utf-8’ encoding.

Parameters:

• out (Optional) – Target output stream or file name. If not given, default value is sys.stdout.
• indent (Optional) – Start line indentation. Default is empty

class docplex.cp.utils.KeyIdDict

Bases: object

Dictionary using internally id of the key objects as dictionary key.

This object allows to use any Python object as key (with no __hash__() function), and to map a value on the physical instance of the key.

clear()

Clear all dictionary content

get(key, default=None)

Get a value from the dictionary.

Parameters:

• key – Key
• default – Default value if not found. Default is None.

Returns:

Value corresponding to the key, default value (None) if not found

keys()

Get the list of all keys

set(key, value)

Set a value in the dictionary.

Parameters:

• key – Key
• value – Value

values()

Get the list of all values

class docplex.cp.utils.ListDict

Bases: dict

Dictionary specialized to associate lists to the keys.

This class is a dictionary that enables to associate to each key a list of values. When adding a value, key and list are created if not present, otherwise element is added to the existing list.

append(key, val)

append a value to the list associated to a key.

Parameters:

• key – Attribute key
• val – Value to add to this key list

class docplex.cp.utils.ObjectCache(maxsize)

Bases: object

Limited size object cache.

This object allows to associate an object to a key. This cache is limited in size. This means that, if the max size is reached, adding a new object removes the oldest.

clear()

Clear all dictionary content

get(key)

Get a value from the cache

Parameters:key – Key Returns:Value corresponding to the key, None if not found

keys()

Get the list of all keys

set(key, value)

Set a value in the cache

Parameters:

• key – Key
• value – Value

size()

Get the current size of the cache

values()

Get the list of all values

class docplex.cp.utils.ObjectCacheById(maxsize)

Bases: object

Object cache that uses object id as key.

This object allows to associate an object to a key. It is implemented using a dict that uses the id of the key as dict key. This allows to:

• Use any Python object as key, even if it does not implement __hash__() function,
• Use different key objects that are logically equal

This cache is limited in size. This means that, if the max size is reached, adding a new object will remove the oldest.

clear()

Clear all dictionary content

get(key)

Get a value from the cache.

Parameters:key – Key Returns:Value corresponding to the key, None if not found

keys()

Get the list of all keys

set(key, value)

Set a value in the cache.

Parameters:

• key – Key
• value – Value

values()

Get the list of all values

class docplex.cp.utils.PersistentContext(cfile)

Bases: docplex.cp.utils.Context

Persistent context stored in a file.

Constructor

If the given file exists, it is read in this context.

Parameters:cfile – File where context is stored with its flat representation

save()

Save this context in the file.

class docplex.cp.utils.SafeIdAllocator(prefix, bdgts='0123456789')

Bases: object

Allocator of identifiers.

This implementation uses a lock to protect the increment of the counter, allowing to use it by multiple threads.

Constructor

Parameters:

• prefix – Prefix of all ids
• bdgts – (Optional) List of digit characters to be use for counter conversion

allocate()

Allocate a new id

Returns:Next id for this allocator

get_count()

Get the number of id that has been allocated by this allocator.

Returns:Number of id that has been allocated by this allocator.

get_prefix()

Get the name prefix used by this allocator.

Returns:Name prefix

reset()

Reset the allocator

class docplex.cp.utils.TextFileLineReader(file, encoding='utf-8-sig')

Bases: object

Reader for text files, possibly compressed using gzip

Create a text file line reader.

Parameters:

• file – File name
• encoding – (Optional) Character encoding, UTF-8 by default

close()

Close this reader.

readline()

Read next line of text.

Returns:Next line of text, including ending end of line character, empty line if end of file

docplex.cp.utils.assert_arg_int_interval(val, mn, mx, name=None)

Check that an argument is an integer in a given interval.

Parameters:

• val – Argument value
• mn – Minimal possible value (included)
• mx – Maximal possible value (excluded)
• name – Name of the parameter (optional), used in raised exception.

Raises:

TypeError exception if wrong argument type

docplex.cp.utils.check_default(val, default)

Check that an argument value is DEFAULT and returns the default value if so.

This method has to be used in conjunction with usage of the DEFAULT constant as default value of a parameter. It allows to assign a parameter to a default value that can be computed dynamically.

Parameters:

• val – Value to check
• default – Default value to return if val is DEFAULT

Returns:

val if val is different from DEFAULT, default otherwise

docplex.cp.utils.compare_natural(s1, s2)

Compare two strings in natural order (for numbers that are inside).

Parameters:

• s1 – First string
• s2 – Second string

Returns:

integer <0 if s1 < s2, 0 if s1 == s2, >0 if s1 > s2

docplex.cp.utils.create_stdout_logger(name)

Create a default logger on stdout with default formatter printing time at the beginning.

of the line.

Parameters:name – Name of the logger

docplex.cp.utils.decode_integer_big_endian_4(frame, start)

Encode an integer in a byte array using big endian on 4 bytes. :param frame: Source byte array :param start: Read start index

Returns:Decoded integer value

docplex.cp.utils.encode_csv_string(str)

Encode a string to be used in CSV file.

Parameters:str – String to encode Returns:Encoded string, including starting and ending double quote

docplex.cp.utils.encode_integer_big_endian_4(value, frame, start)

Encode an integer in a byte array using big endian on 4 bytes. :param value: Integer value to encode :param frame: Target byte array :param start: Write start index

docplex.cp.utils.equals(v1, v2)

Check that two values are logically equal, i.e. with the same attributes with the same values, recursively.

This method does not call __eq__ except on basic types, and is then proof to possible overloads of ‘==’

Parameters:

• v1 – First value
• v2 – Second value

Returns:

True if both values are identical, false otherwise

docplex.cp.utils.format_text(txt, size)

Format a given text in multiple lines. :param txt: Text to format :param size: Line size

Returns:List of lines.

docplex.cp.utils.get_file_name_only(file)

Get the name of a file, without directory or extension. :param file: File name

Returns:Name of the file, without directory or extension

docplex.cp.utils.get_main_file()

Get the name of the main Python module

Returns:Absolute path of the Python module that has been used as main. None if unknown.

docplex.cp.utils.get_module_element_from_path(opath)

Retrieve an element from a python module using its path <package>.<module>.<object>.

This can be for example a global function or a class.

Parameters:opath – Object path Returns:Module object

docplex.cp.utils.get_module_version(mname)

Get the version of a Python module

Parameters:mname – Module name Returns:Version of the module, None if not installed, “Unknown” if not set in the module

docplex.cp.utils.get_system_path()

Get the system path as a list of directory names

Returns:List of names in the system path

docplex.cp.utils.int_to_base(val, bdgts)

Convert an integer into a string with a given base.

Parameters:

• val – Integer value to convert
• bdgts – List of base digits

Returns:

String corresponding to the integer

docplex.cp.utils.is_array(val)

Check if a value is an array (list or tuple).

Parameters:val – Value to check Returns:True if value is an array (list or tuple)

docplex.cp.utils.is_array_of_type(val, typ)

Check that a value is an array with all elements instances of a given type.

Parameters:

• val – Value to check
• typ – Expected element type

Returns:

True if value is an array with all elements with expected type

docplex.cp.utils.is_bool(val)

Check if a value is a boolean, including numpy variants if any.

Parameters:val – Value to check Returns:True if value is a boolean.

docplex.cp.utils.is_exe_file(f)

Check that a file exists and is executable.

Parameters:f – File name Returns:True if file exists and is executable

docplex.cp.utils.is_float(val)

Check if a value is a float, including numpy variants if any.

Parameters:val – Value to check Returns:True if value is a float

docplex.cp.utils.is_in(val, lvals)

Replace the standard ‘in’ operator but uses ‘is’ to check membership.

This method is mandatory if element to check overloads operator ‘==’.

Parameters:

• val – Value to check
• lvals – List of candidate values

Returns:

True if value is in the list of values (presence checked with ‘is’)

docplex.cp.utils.is_in_notebook()

Check whether program is currently running inside a IPython or Jupyter notebook.

Returns:True if the program is running in a notebook, false otherwise.

docplex.cp.utils.is_int(val)

Check if a value is an integer, including numpy variants if any.

Parameters:val – Value to check Returns:True if value is an integer.

docplex.cp.utils.is_int_array(val)

Check that a value is an array of integers.

Parameters:val – Value to check Returns:True if value is an array where all elements are integers

docplex.cp.utils.is_int_value(val, xv)

Check if a value is an integer equal to an expected value. Allows to check integer value equality even if == operator is overloaded

Parameters:

• val – Value to check
• xv – Expected integer value

Returns:

True if value is an integer.

docplex.cp.utils.is_iterable(val)

Check if a value is iterable, but not a string.

Parameters:val – Value to check Returns:True if value is iterable

docplex.cp.utils.is_number(val)

Check if a value is a number, including numpy variants if any.

Parameters:val – Value to check Returns:True if value is a number

docplex.cp.utils.is_panda_series(val)

Check if a value is a panda serie.

Parameters:val – Value to check Returns:False

docplex.cp.utils.is_string(val)

Check if a value is a string or a variant.

Parameters:val – Value to check Returns:True if value is a string

docplex.cp.utils.is_symbol(s)

Check whether a string can be used in a symbol.

Parameters:s – String to check Returns:True if character string can be used as s symbol

docplex.cp.utils.is_symbol_char(c)

Check whether a character can be used in a symbol.

Parameters:c – Character Returns:True if character in 0..9, a..z, A..Z, _ or .

docplex.cp.utils.is_tuple(val)

Check if a value is a tuple.

Parameters:val – Value to check Returns:True if value is a tuple

docplex.cp.utils.list_module_public_functions(mod, excepted=())

Build the list of all public functions of a module.

Parameters:

• mod – Module to parse
• excepted – List of function names to not include. Default is none.

Returns:

List of public functions declared in this module

docplex.cp.utils.make_directories(path)

Ensure a directory path exists.

Parameters:path – Directory path to check or create Raises:Any IO exception if directory creation is not possible

docplex.cp.utils.make_unicode(s)

Convert a string in unicode.

Parameters:s – String to convert Returns:String in unicode

docplex.cp.utils.open_utf8(file, mode='r')

Open a stream for read or write with UTF-8 encoding.

Parameters:

• file – File to open
• mode – Open mode

docplex.cp.utils.parse_json_string(jstr)

Parse a JSON string.

Parameters:jstr – String containing JSON document Returns:Python representation of JSON document

docplex.cp.utils.read_string_file(file)

Read a file as a string. :param file: File name

Returns:File content as a string

docplex.cp.utils.replace(obj, rfun)

Build a copy of a source object and apply a replacement function on all its attributes.

If an object is not changed, its original version is returned.

Parameters:

• obj – Source object
• rfun – Value replacement function

Returns:

Copy of source object with all values replaced, or same object if no value has been replaced.

docplex.cp.utils.replace_in_tuple(tpl, ndx, val)

Replace a value in a tuple.

A new tuple is created with one value changed by another.

Parameters:

• tpl – Source tuple
• ndx – Index of the tuple value to change
• val – new value

Returns:

New tuple with value at position ‘ndx’ replaced by ‘val’

docplex.cp.utils.search_exec_file(f, path)

Search the first occurrence of an executable file in a given path.

Parameters:

• f – Executable file name
• path – Path where search the file

Returns:

Full path of the first executable file found, None if not found

docplex.cp.utils.string_to_value(s)

Convert a string in its most representative python value

If the string is encapsulated in double_quotes, the internal string is returned. If string in lower case is “none”, None is returned. If string in lower case is “true” or “false”, True or False is returned. If string matches an integer, the integer is returned. If the string matches a float, the float is returned Otherwise, string is returned as it is

Parameters:s – String to convert Returns:Value corresponding to the string

docplex.cp.utils.to_compact_SI(val)

Convert a long value in a string using suffix k, M or G to display only 3 digits.

Parameters:val – Integer value to convert Returns:String representing this value with 3 significant digits

docplex.cp.utils.to_internal_string(strg)

Convert a string (without enclosing quotes) into internal string (interpret escape sequences).

Parameters:strg – String to convert Returns:Raw string corresponding to source

docplex.cp.utils.to_printable_id(s)

Build a CPO printable identifier from its raw string (add escape sequences and quotes if necessary).

Parameters:s – Identifier string Returns:Unicode CPO identifier string, including double quotes and escape sequences if needed if not only chars and integers

docplex.cp.utils.to_printable_string(s)

Build a printable string from raw string (add escape sequences and quotes if necessary).

Parameters:str – String to convert Returns:Unicode string, including always double quotes and escape sequences if needed

docplex.cp.utils.to_string(val)

Convert a value into a string, recursively for lists and tuples.

Parameters:val – Value to convert value Returns:String representation of the value

docplex.cp.utils.write_checking_unicode_errors(out, data)

Write data on a stream, and by-pass UnicodeEncodeError if any.

Parameters:

• out – Output stream
• data – Data to write

docplex.cp.utils.write_string_file(file, str)

Write a string into a file. :param file: File name :param str: String to write