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] -
-
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).
-
-
class
pyomo.common.config.
ConfigDict
(description=None, doc=None, implicit=False, implicit_domain=None, visibility=0)[source] Bases:
ConfigBase
,Mapping
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()
ordeclare_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.
-
content_filters
= {'all', None, 'userdata'}
-
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().
-
class
pyomo.common.config.
ConfigList
(*args, **kwds)[source] Bases:
ConfigBase
,Sequence
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 completeConfigDict
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.
-
class
pyomo.common.config.
ConfigValue
(*args, **kwds)[source] Bases:
ConfigBase
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 completeConfigDict
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.
-
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 ifTrue
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.
- domain (Container) – The container that specifies the allowable values. Incoming
values are passed to
-
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
- basePath (None, str, ConfigValue) – The base path that will be prepended to any non-absolute path
values provided. If None, defaults to
-
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 toPath
, 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
- basePath (Union[None, str, ConfigValue]) – The base path that will be prepended to any non-absolute path
values provided. If None, defaults to