pyomo.common.config

Core classes

ConfigDict([description, doc, implicit, …]) Store and manipulate a dictionary of configuration values.
ConfigList(*args, **kwds) Store and manipulate a list of configuration values.
ConfigValue(*args, **kwds) Store and manipulate a single configuration value.

Domain validators

PositiveInt(val) Domain validation function admitting strictly positive integers
NegativeInt(val) Domain validation function admitting strictly negative integers
NonNegativeInt(val) Domain validation function admitting integers >= 0
NonPositiveInt(val) Domain validation function admitting integers <= 0
PositiveFloat(val) Domain validation function admitting strictly positive numbers
NegativeFloat(val) Domain validation function admitting strictly negative numbers
NonPositiveFloat(val) Domain validation function admitting numbers less than or equal to 0
NonNegativeFloat(val) Domain validation function admitting numbers greater than or equal to 0
In(domain[, cast]) Domain validation class admitting a Container of possible values
InEnum(domain) Domain validation class admitting an enum value/name.
Path([basePath, expandPath]) Domain validator for path-like options.
PathList([basePath, expandPath]) Domain validator for a list of path-like objects.
DynamicImplicitDomain(callback) Implicit domain that can return a custom domain based on the key.
class pyomo.common.config.ConfigBase(default=None, domain=None, description=None, doc=None, visibility=0)[source]
class NoArgument[source]
declare_as_argument(*args, **kwds)[source]

Map this Config item to an argparse argument.

Valid arguments include all valid arguments to argparse’s ArgumentParser.add_argument() with the exception of ‘default’. In addition, you may provide a group keyword argument to either pass in a pre-defined option group or subparser, or else pass in the string name of a group, subparser, or (subparser, group).

display(content_filter=None, indent_spacing=2, ostream=None, visibility=None)[source]
generate_documentation(block_start=None, block_end=None, item_start=None, item_body=None, item_end=None, indent_spacing=2, width=78, visibility=0, format='latex')[source]
generate_yaml_template(indent_spacing=2, width=78, visibility=0)[source]
import_argparse(parsed_args)[source]
initialize_argparse(parser)[source]
name(fully_qualified=False)[source]
reset()[source]
set_default_value(default)[source]
set_domain(domain)[source]
unused_user_values()[source]
user_values()[source]
class pyomo.common.config.ConfigDict(description=None, doc=None, implicit=False, implicit_domain=None, visibility=0)[source]

Bases: pyomo.common.config.

Store and manipulate a dictionary of configuration values.

Parameters:
  • description (str, optional) – The short description of this list
  • doc (str, optional) – The long documentation string for this list
  • implicit (bool, optional) – If True, the ConfigDict will allow “implicitly” declared keys, that is, keys can be stored into the ConfigDict that were not prevously declared using declare() or declare_from().
  • implicit_domain (callable, optional) – The domain that will be used for any implicitly-declared keys. Follows the same rules as ConfigValue()’s domain.
  • visibility (int, optional) – The visibility of this ConfigDict when generating templates and documentation. Visibility supports specification of “advanced” or “developer” options. ConfigDicts with visibility=0 (the default) will always be printed / included. ConfigDicts with higher visibility values will only be included when the generation method specifies a visibility greater than or equal to the visibility of this object.
add(name, config)[source]
content_filters = {'all', 'userdata', None}
declare(name, config)[source]
declare_from(other, skip=None)[source]
get(key, default=NOTSET)[source]
items()[source]
iteritems()[source]

DEPRECATED.

Deprecated since version 6.0: The iteritems method is deprecated. Use dict.keys().

iterkeys()[source]

DEPRECATED.

Deprecated since version 6.0: The iterkeys method is deprecated. Use dict.keys().

itervalues()[source]

DEPRECATED.

Deprecated since version 6.0: The itervalues method is deprecated. Use dict.keys().

keys()[source]
reset()[source]
set_value(value, skip_implicit=False)[source]
setdefault(key, default=NOTSET)[source]
value(accessValue=True)[source]
values()[source]
class pyomo.common.config.ConfigList(*args, **kwds)[source]

Bases: pyomo.common.config.

Store and manipulate a list of configuration values.

Parameters:
  • default (optional) – The default value that this ConfigList will take if no value is provided. If default is a list or ConfigList, then each member is cast to the ConfigList’s domain to build the default value, otherwise the default is cast to the domain and forms a default list with a single element.
  • domain (callable, optional) – The domain can be any callable that accepts a candidate value and returns the value converted to the desired type, optionally performing any data validation. The result will be stored / added to the ConfigList. Examples include type constructors like int or float. More complex domain examples include callable objects; for example, the In class that ensures that the value falls into an acceptable set or even a complete ConfigDict instance.
  • description (str, optional) – The short description of this list
  • doc (str, optional) – The long documentation string for this list
  • visibility (int, optional) – The visibility of this ConfigList when generating templates and documentation. Visibility supports specification of “advanced” or “developer” options. ConfigLists with visibility=0 (the default) will always be printed / included. ConfigLists with higher visibility values will only be included when the generation method specifies a visibility greater than or equal to the visibility of this object.
add(value=NOTSET)[source]

DEPRECATED.

Append the specified value to the list, casting as necessary.

Deprecated since version 5.7.2: ConfigList.add() has been deprecated. Use append()

append(value=NOTSET)[source]
get(key, default=NOTSET)[source]
reset()[source]
set_value(value)[source]
value(accessValue=True)[source]
class pyomo.common.config.ConfigValue(*args, **kwds)[source]

Bases: pyomo.common.config.

Store and manipulate a single configuration value.

Parameters:
  • default (optional) – The default value that this ConfigValue will take if no value is provided.
  • domain (callable, optional) – The domain can be any callable that accepts a candidate value and returns the value converted to the desired type, optionally performing any data validation. The result will be stored into the ConfigValue. Examples include type constructors like int or float. More complex domain examples include callable objects; for example, the In class that ensures that the value falls into an acceptable set or even a complete ConfigDict instance.
  • description (str, optional) – The short description of this value
  • doc (str, optional) – The long documentation string for this value
  • visibility (int, optional) – The visibility of this ConfigValue when generating templates and documentation. Visibility supports specification of “advanced” or “developer” options. ConfigValues with visibility=0 (the default) will always be printed / included. ConfigValues with higher visibility values will only be included when the generation method specifies a visibility greater than or equal to the visibility of this object.
set_value(value)[source]
value(accessValue=True)[source]
class pyomo.common.config.DynamicImplicitDomain(callback)[source]

Implicit domain that can return a custom domain based on the key.

This provides a mechanism for managing plugin-like systems, where the key specifies a source for additional configuration information. For example, given the plugin module, pyomo/common/tests/config_plugin.py:

from pyomo.common.config import ConfigDict, ConfigValue

def get_configuration(config):
    ans = ConfigDict()
    ans.declare('key1', ConfigValue(default=0, domain=int))
    ans.declare('key2', ConfigValue(default=5, domain=str))
    return ans(config)
>>> def _pluginImporter(name, config):
...     mod = importlib.import_module(name)
...     return mod.get_configuration(config)
>>> config = ConfigDict()
>>> config.declare('plugins', ConfigDict(
...     implicit=True,
...     implicit_domain=DynamicImplicitDomain(_pluginImporter)))
<pyomo.common.config.ConfigDict object at ...>
>>> config.plugins['pyomo.common.tests.config_plugin'] = {'key1': 5}
>>> config.display()
plugins:
  pyomo.common.tests.config_plugin:
    key1: 5
    key2: '5'

Note

This initializer is only useful for the ConfigDict implicit_domain argument (and not for “regular” domain arguments)

Parameters:callback (Callable[[str, object], ConfigBase]) – A callable (function) that is passed the ConfigDict key and value, and is expected to return the appropriate Config object (ConfigValue, ConfigList, or ConfigDict)
pyomo.common.config.PositiveInt(val)[source]

Domain validation function admitting strictly positive integers

This domain will admit positive integers (n > 0), as well as any types that are convertible to positive integers.

pyomo.common.config.NegativeInt(val)[source]

Domain validation function admitting strictly negative integers

This domain will admit negative integers (n < 0), as well as any types that are convertible to negative integers.

pyomo.common.config.NonNegativeInt(val)[source]

Domain validation function admitting integers >= 0

This domain will admit non-negative integers (n >= 0), as well as any types that are convertible to non-negative integers.

pyomo.common.config.NonPositiveInt(val)[source]

Domain validation function admitting integers <= 0

This domain will admit non-positive integers (n <= 0), as well as any types that are convertible to non-positive integers.

pyomo.common.config.PositiveFloat(val)[source]

Domain validation function admitting strictly positive numbers

This domain will admit positive floating point numbers (n > 0), as well as any types that are convertible to positive floating point numbers.

pyomo.common.config.NegativeFloat(val)[source]

Domain validation function admitting strictly negative numbers

This domain will admit negative floating point numbers (n < 0), as well as any types that are convertible to negative floating point numbers.

pyomo.common.config.NonPositiveFloat(val)[source]

Domain validation function admitting numbers less than or equal to 0

This domain will admit non-positive floating point numbers (n <= 0), as well as any types that are convertible to non-positive floating point numbers.

pyomo.common.config.NonNegativeFloat(val)[source]

Domain validation function admitting numbers greater than or equal to 0

This domain will admit non-negative floating point numbers (n >= 0), as well as any types that are convertible to non-negative floating point numbers.

class pyomo.common.config.In(domain, cast=None)[source]

Domain validation class admitting a Container of possible values

This will admit any value that is in the domain Container (i.e., Container.__contains__() returns True). Most common domains are list, set, and dict objects. If specified, incoming values are first passed to cast() to convert them to the appropriate type before looking them up in domain.

Parameters:
  • domain (Container) – The container that specifies the allowable values. Incoming values are passed to domain.__contains__(), and if True is returned, the value is accepted and returned.
  • cast (callable, optional) – A callable object. If specified, incoming values are first passed to cast, and the resulting object is checked for membership in domain

Note

For backwards compatibility, In accepts enum.Enum classes as domain Containers. If the domain is an Enum, then the constructor returns an instance of InEnum.

class pyomo.common.config.InEnum(domain)[source]

Domain validation class admitting an enum value/name.

This will admit any value that is in the specified Enum, including Enum members, values, and string names. The incoming value will be automatically cast to an Enum member.

Parameters:domain (enum.Enum) – The enum that incoming values should be mapped to
class pyomo.common.config.Path(basePath=None, expandPath=None)[source]

Domain validator for path-like options.

This will admit any object and convert it to a string. It will then expand any environment variables and leading usernames (e.g., “~myuser” or “~/”) appearing in either the value or the base path before concatenating the base path and value, expanding the path to an absolute path, and normalizing the path.

Parameters:
  • basePath (None, str, ConfigValue) – The base path that will be prepended to any non-absolute path values provided. If None, defaults to Path.BasePath.
  • expandPath (bool) – If True, then the value will be expanded and normalized. If False, the string representation of the value will be returned unchanged. If None, expandPath will defer to the (negated) value of Path.SuppressPathExpansion
class pyomo.common.config.PathList(basePath=None, expandPath=None)[source]

Domain validator for a list of path-like objects.

This will admit any iterable or object convertable to a string. Iterable objects (other than strings) will have each member normalized using Path. Other types will be passed to Path, returning a list with the single resulting path.

Parameters:
  • basePath (Union[None, str, ConfigValue]) – The base path that will be prepended to any non-absolute path values provided. If None, defaults to Path.BasePath.
  • expandPath (bool) – If True, then the value will be expanded and normalized. If False, the string representation of the value will be returned unchanged. If None, expandPath will defer to the (negated) value of Path.SuppressPathExpansion