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)[source]

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()[source]

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

class docplex.cp.utils.Chrono[source]

Bases: object

Chronometer

Constructor Create a new chronometer initialized with current time.

get_elapsed()[source]

Get the chrono elapsed time.

Returns:Time spent from chronometer start time (float), in seconds
get_start()[source]

Get the chrono start time.

Returns:Time when chronometer has been started
restart()[source]

Restart chrono to current time

class docplex.cp.utils.Context(**kwargs)[source]

Bases: dict

Class handling miscellaneous list of parameters.

Constructor

Parameters:**kwargs – List of key=value to initialize context with.
clone()[source]

Clone this context and all sub-contexts recursively.

Returns:Cloned copy of this context.
del_attribute(name)[source]

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)[source]

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()[source]

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)[source]

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)[source]

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()[source]

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()[source]

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()[source]

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

Returns:Root context
import_flat(inp=None)[source]

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)[source]

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)[source]

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='')[source]

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='')[source]

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)[source]

Set a context attribute.

Parameters:
  • name – Attribute name
  • value – Attribute value
set_by_path(path, value)[source]

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)[source]

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='')[source]

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)[source]

Bases: Exception

Exception thrown in case of CPO errors.

Constructor

Parameters:msg – Error message
exception docplex.cp.utils.CpoNotSupportedException(msg)[source]

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)[source]

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()[source]

Clear all dictionary content

get(*param)[source]

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

Returns:Function result
class docplex.cp.utils.IdAllocator(prefix, bdgts='0123456789')[source]

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()[source]

Allocate a new id.

Returns:Next id for this allocator
get_count()[source]

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()[source]

Get the name prefix used by this allocator.

Returns:Name prefix
class docplex.cp.utils.IdentityAccessor[source]

Bases: object

Object implementing a __getitem__ that returns the key as value.

class docplex.cp.utils.InfoDict[source]

Bases: dict

Dictionary used to store information of various types.

clone()[source]

Clone this information dictionary

Returns:New information dictionary, cloned copy of this one.
incr(key, val)[source]

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='')[source]

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='')[source]

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[source]

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()[source]

Clear all dictionary content

get(key, default=None)[source]

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()[source]

Get the list of all keys

set(key, value)[source]

Set a value in the dictionary.

Parameters:
  • key – Key
  • value – Value
values()[source]

Get the list of all values

class docplex.cp.utils.ListDict[source]

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)[source]

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)[source]

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()[source]

Clear all dictionary content

get(key)[source]

Get a value from the cache

Parameters:key – Key
Returns:Value corresponding to the key, None if not found
keys()[source]

Get the list of all keys

set(key, value)[source]

Set a value in the cache

Parameters:
  • key – Key
  • value – Value
size()[source]

Get the current size of the cache

values()[source]

Get the list of all values

class docplex.cp.utils.ObjectCacheById(maxsize)[source]

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()[source]

Clear all dictionary content

get(key)[source]

Get a value from the cache.

Parameters:key – Key
Returns:Value corresponding to the key, None if not found
keys()[source]

Get the list of all keys

set(key, value)[source]

Set a value in the cache.

Parameters:
  • key – Key
  • value – Value
values()[source]

Get the list of all values

class docplex.cp.utils.PersistentContext(cfile)[source]

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()[source]

Save this context in the file.

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

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()[source]

Allocate a new id

Returns:Next id for this allocator
get_count()[source]

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()[source]

Get the name prefix used by this allocator.

Returns:Name prefix
reset()[source]

Reset the allocator

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

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()[source]

Close this reader.

readline()[source]

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)[source]

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)[source]

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)[source]

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)[source]
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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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()[source]

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)[source]

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)[source]

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()[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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()[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

Check if a value is a panda serie.

Parameters:val – Value to check
Returns:False
docplex.cp.utils.is_string(val)[source]

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)[source]

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)[source]

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)[source]

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=())[source]

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)[source]

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)[source]

Convert a string in unicode.

Parameters:s – String to convert
Returns:String in unicode
docplex.cp.utils.open_utf8(file, mode='r')[source]

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)[source]

Parse a JSON string.

Parameters:jstr – String containing JSON document
Returns:Python representation of JSON document
docplex.cp.utils.read_string_file(file)[source]

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

Returns:File content as a string
docplex.cp.utils.replace(obj, rfun)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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