pydrobert.param.serialization
Utilities for (de)serializing Parameterized objects
- class pydrobert.param.serialization.DefaultArrayDeserializer(**kwargs)[source]
Bases:
ParamConfigDeserializer
Default deserializer for numpy arrays
Keyword arguments can be passed to referenced methods by initializing this deserializer with those keyword arguments.
The process:
None
checkIf already a
numpy.ndarray
, set itIf a string ending with
'.npy'
, load it as a file path (numpy.load()
with kwargs)If bytes, load it with
numpy.frombuffer()
and kwargsIf a string, load it with
numpy.fromstring()
and kwargsTry initializing to array with
numpy.array()
and kwargs
- class pydrobert.param.serialization.DefaultArraySerializer[source]
Bases:
ParamConfigSerializer
Default numpy array serializer
The process: 1. If
None
, return 2. Call value’stolist()
method
- class pydrobert.param.serialization.DefaultBooleanDeserializer[source]
Bases:
ParamConfigDeserializer
Default deserializer for booleans
The process:
None
checkIf block is in
TRUE_VALUES
, set asTrue
If block is in
FALSE_VALUES
, set asFalse
If block is already a
bool
, use verbatim
- FALSE_VALUES = {'F', 0, 'False', '0', 'OFF', 'f', 'no', 'FALSE', 'off', 'NO', 'false'}
- TRUE_VALUES = {'True', 'yes', 1, 't', 'ON', 'TRUE', 'T', 'true', 'YES', '1', 'on'}
- class pydrobert.param.serialization.DefaultClassSelectorDeserializer(*args, **kwargs)[source]
Bases:
ParamConfigDeserializer
Default ClassSelector deserializer
The process:
None
checkIf the parameter’s
is_instance
attribute isTrue
:If block is an instance of the parameter’s
class_
attribute, set itTry instantiating the class with block as the first argument, with additional arguments and keyword arguments passed to the deserializer passed allong to the constructor.
Look for the block or the block name in the selector’s
param.ClassSelector.get_range
dictionary
- class pydrobert.param.serialization.DefaultClassSelectorSerializer[source]
Bases:
ParamConfigSerializer
Default ClassSelector serializer
The process:
- class pydrobert.param.serialization.DefaultDataFrameDeserializer(*args, **kwargs)[source]
Bases:
ParamConfigDeserializer
Default pandas.DataFrame deserializer
Keyword arguments and positional arguments can be passed to referenced methods by initializing this deserializer with those keyword arguments.
The process:
None
checkIf block is a data frame, set it
If block is a string that ends with one of a number of file suffixes, e.g.
".csv"
,".json"
,".html"
,".xls"
, use the associatedpandas.read_*
method with block as the first argument plus the deserializer’s extra args and kwargsIf block is a string, try
pandas.read_table()
Try initializing a
pandas.DataFrame
with block as the first argument plus the deserializer’s extra args and kwargs
- class pydrobert.param.serialization.DefaultDataFrameSerializer[source]
Bases:
ParamConfigSerializer
Default pandas.DataFrame serializer
The process:
If
None
, returnCall
tolist()
on thevalues
property of the parameter’s value and return
- class pydrobert.param.serialization.DefaultDateDeserializer(format=('%Y-%m-%dT%H:%M:%S.%f', '%Y-%m-%dT%H:%M:%S', '%Y-%m-%d'))[source]
Bases:
ParamConfigDeserializer
Default datetime.datetime deserializer
The process:
None
checkIf block is a
datetime.datetime
, set itIf the deserializer’s format argument is not None and block is a string:
If format is a string, try to convert block to a datetime using
datetime.datetime.strptime()
If format is list-like, parse a
datetime.datetime
object withdatetime.datetime.strptime(element, format)
. If the parse is successful, use that parsed datetime.
Try casting block to a float
If the float has a remainder or the value exceeds the maximum ordinal value, treat as a UTC timestamp
Otherwise, treat as a Gregorian ordinal time
Try instantiating a datetime with block as an argument to the constructor.
If
numpy
can be imported, try instantiating anumpy.datetime64
with block as an argument to the constructor.
- class pydrobert.param.serialization.DefaultDateRangeDeserializer(format=('%Y-%m-%dT%H:%M:%S.%f', '%Y-%m-%dT%H:%M:%S', '%Y-%m-%d'))[source]
Bases:
ParamConfigDeserializer
Default date range deserializer
Similar to deserializing a single
datetime.datetime
, but applied to each element separately. Cast to atuple
.
- class pydrobert.param.serialization.DefaultDateRangeSerializer(format=('%Y-%m-%d', '%Y-%m-%dT%H:%M:%S', '%Y-%m-%dT%H:%M:%S.%f'))[source]
Bases:
ParamConfigSerializer
Default date range serializer
Similar to serializing a single
datetime.datetime
, but applied to each element separately. Also cast to a list
- class pydrobert.param.serialization.DefaultDateSerializer(format=('%Y-%m-%d', '%Y-%m-%dT%H:%M:%S', '%Y-%m-%dT%H:%M:%S.%f'))[source]
Bases:
ParamConfigSerializer
Default datetime.datetime serializer
The process:
If
None
, returnIf a
datetime.datetime
instanceIf the format keyword argument of the serializer is not
None
:If format is a string, return the result of the value’s
strftime(format)
callIf format is list-like, iterate through it, formatting with
strftime(element)
. Whichever string which, when deserialized withstrptime(element)
, produces an equivalent :class`datetime.datetime` object as the value is returned. If no such string exists, the last string is returned.
Return the result of the value’s
timestamp()
call
If a
numpy.datetime64
instance, return the value cast to a string
- class pydrobert.param.serialization.DefaultDeserializer[source]
Bases:
ParamConfigDeserializer
Catch-all deserializer
This serializer performs a none check, then tries to set the parameter with the value of block verbatim.
- class pydrobert.param.serialization.DefaultIntegerDeserializer(*args, **kwargs)[source]
Bases:
_CastDeserializer
Default int deserializer
The process:
- class pydrobert.param.serialization.DefaultListDeserializer(*args, **kwargs)[source]
Bases:
ParamConfigDeserializer
Default list deserializer
The process:
None
checkIf the parameter’s
class_
attribute has been set, for each element in block (we always assume block is iterable):If the element is an instance of the class, leave it alone
Try instantiating a
class_
object using the element as the first argument plus any arguments or keyword arguments passed to the deserializer on initialization.
Cast to a list and set
- class pydrobert.param.serialization.DefaultListSelectorDeserializer[source]
Bases:
ParamConfigDeserializer
Default ListSelector deserializer
For each element in block (we assume block is iterable), match a value or name in the selector’s
param.ListSelector.get_range()
method
- class pydrobert.param.serialization.DefaultListSelectorSerializer[source]
Bases:
ParamConfigSerializer
Default ListSelector serializer
For each element in the value:
Search for its name in the selector’s
param.ListSelector.get_range()
dict and swap if for the name, if possibleOtherwise, use that element verbatim
- class pydrobert.param.serialization.DefaultNumberDeserializer(*args, **kwargs)[source]
Bases:
_CastDeserializer
Default float deserializer
The process:
- class pydrobert.param.serialization.DefaultNumericTupleDeserializer[source]
Bases:
ParamConfigDeserializer
Default numeric tuple deserializer
The process: 1.
None
check 2. Cast each element of block to afloat
3. Cast block to atuple
- class pydrobert.param.serialization.DefaultObjectSelectorDeserializer[source]
Bases:
ParamConfigDeserializer
Default
param.ObjectSelector
deserializerThe process:
None
checkMatch block to a value or name in the selector’s
param.ObjectSelector.get_range()
method
- class pydrobert.param.serialization.DefaultObjectSelectorSerializer[source]
Bases:
ParamConfigSerializer
Default ObjectSelector serializer
The process:
If
None
, returnSearch for the name of the value in the selector’s
param.ObjectSelector.get_range()
dictionary and return, if possibleReturn value verbatim
- class pydrobert.param.serialization.DefaultSerializer[source]
Bases:
ParamConfigSerializer
Default catch-all serializer. Returns value verbatim
- class pydrobert.param.serialization.DefaultSeriesSerializer[source]
Bases:
ParamConfigSerializer
Default pandas.Series serializer
The process:
If
None
, returnCall
tolist()
on thevalues
property of the parameter’s value and return
- class pydrobert.param.serialization.DefaultStringDeserializer(*args, **kwargs)[source]
Bases:
_CastDeserializer
Default str deserializer
The process:
- class pydrobert.param.serialization.DefaultTupleSerializer[source]
Bases:
ParamConfigSerializer
Default tuple serializer
The process: 1. If
None
, return 2. Casts the value to alist
- class pydrobert.param.serialization.JsonSerializable(*args, **kwds)[source]
Bases:
Serializable
Write/read to/from strings using JSON protocol
- class pydrobert.param.serialization.JsonStringArrayDeserializer(**kwargs)[source]
Bases:
DefaultArrayDeserializer
Parses a block as JSON before converting it into a numpy array
The default deserializer used in INI files. Input is always assumed to be a string or
None
. IfNone
, a none check is performed. Otherwise, it parses the value as JSON, then does the same asDefaultArrayDeserializer
. However, if the input ends in the file suffix".npy"
, the input will be immediately passed toDefaultArrayDeserializer
See also
deserialize_from_json
To deserialize JSON into
param.parameterized.Parameterized
instances
- class pydrobert.param.serialization.JsonStringDataFrameDeserializer(*args, **kwargs)[source]
Bases:
DefaultDataFrameDeserializer
Parses block as JSON before converting to pandas.DataFrame
The default deserializer used in INI files. Input is always assumed to be a string or
None
. IfNone
, a none check is performed. Otherwise, it parses the value as JSON, then does the same asDefaultDataFrameSerializer
. However, if the input ends in a file suffix like".csv"
,".xls"
, etc., the input will be immediately passed toDefaultDataFrameSerializer
See also
deserialize_from_json
To deserialize JSON into
param.parameterized.Parameterized
instances
- file_suffixes = {'csv', 'dta', 'feather', 'h5', 'html', 'json', 'parquet', 'pkl', 'sas7bdat', 'xls'}
- class pydrobert.param.serialization.ParamConfigDeserializer[source]
Bases:
object
Deserialize part of a configuration into a parameterized object
Subclasses of
ParamConfigDeserializer
are expected to implementdeserialize()
. Instances of the subclass can be passed intodeserialize_from_dict()
. The goal of a deserializer is to convert data into the value of a parameter in aparam.parameterized.Parameterized
object. The format of the incoming data is specific to where the dict-like input came from. For example, a JSON parser converts numeric strings to floats, and the contents of square braces ([]
) as lists. Inpydrobert.param.serialization
, there are a number of default deserializers (matching the patternDefault*Deserializer
) that are best guesses on how to deserialize data from a variety of sources- static check_if_allow_none_and_set(name, block, parameterized)[source]
Check if block can be made none and set it if allowed
Many
param.Param
parameters allowNone
as a value. This is a convenience method that deserializers can use to quickly check for aNone
value and set it in that case. This method sets the parameter and returnsTrue
in the following conditionsIf one of these conditions wasn’t met, the parameter remains unset and the method returns
False
.In
Default*Deserializer
documentation, a call to this method is referred to as a “none check”.
- abstract deserialize(name, block, parameterized)[source]
Deserialize data and store it in a parameterized object
- Parameters
name (
str
) – The name of the parameter in parameterized to store the value underblock (
Any
) – The data to deserialize into the parameter valueparameterized (
Parameterized
) – The parameterized instance containing a parameter with the name name. On completion of this method, that parameter will be set with the deserialized contents of block
- Raises
ParamConfigTypeError – If deserialization could not be performed
- class pydrobert.param.serialization.ParamConfigSerializer[source]
Bases:
object
Serialize a parameter value from a Parameterized object
Subclasses of
ParamConfigSerializer
are expected to implementserialize()
. Instances of the subclass can be passed intoserialize_to_dict()
. The goal of a serializer is to convert a parameter value from aparam.parameterized.Parameterized
object into something that can be handled by a dict-like data store. The format of the outgoing data should reflect where the dict-like data are going. For example, a JSON serializer can handle lists, but not an INI serializer. Inpydrobert.param.serialization
, there are a number of default serializers (matching the patternDefault*Serializer
) that are best guesses on how to serialize data from a variety of sources- help_string(name, parameterized)[source]
A string that helps explain this serialization
The return string will be included in the second element of the pair returned by
serialize_to_dict()
. Helps explain the serialized value to the user.
- abstract serialize(name, parameterized)[source]
Serialize data from a parameterized object and return it
- Parameters
name (
str
) – The name of the parameter in parameterized to retrieve the value fromparameterized (
Parameterized
) – The parameterized instance containing a parameter with the name name
- Returns
val (obj) – The serialized value of the parameter
- Raises
ParamConfigTypeError – If serialization could not be performed
- exception pydrobert.param.serialization.ParamConfigTypeError(parameterized, name, message='')[source]
Bases:
TypeError
Raised when failed to (de)serialize Parameterized object
- class pydrobert.param.serialization.RecklessJsonSerialization(*args, **kwds)[source]
Bases:
RecklessSerializableSerialization
,JsonSerializable
Reckless JSON (de)serialization
See also
register_serializer
For how this is used
- class pydrobert.param.serialization.RecklessSerializableSerialization(*args, **kwds)[source]
Bases:
SerializableSerialization
ABC for reckless serialization
- class pydrobert.param.serialization.RecklessYamlSerialization(*args, **kwds)[source]
Bases:
RecklessSerializableSerialization
,YamlSerializable
Reckless YAML (de)serialization
See also
register_serializer
For how this is used
- class pydrobert.param.serialization.Serializable(*args, **kwds)[source]
Bases:
Protocol
Protocol for classes capable of reading and writing objects from/to strings
- class pydrobert.param.serialization.SerializableSerialization(*args, **kwds)[source]
Bases:
Serialization
,Serializable
ABC for sensible serialization
- class pydrobert.param.serialization.YamlSerializable(*args, **kwds)[source]
Bases:
Serializable
Write/read to/from strings using YAML protocol
- class pydrobert.param.serialization.YamlSerialization(*args, **kwds)[source]
Bases:
SerializableSerialization
,YamlSerializable
YAML (de)serialization
See also
register_serializer
For how this is used
- pydrobert.param.serialization.deserialize_from_dict(dict_, parameterized, deserializer_name_dict=None, deserializer_type_dict=None, on_missing='warn')[source]
Deserialize a dictionary into a parameterized object
This function is suitable for deserializing the results of parsing a data storage file such as a YAML, JSON, or a section of an INI file (using the
yaml
,json
, andconfigparser
python modules, resp.) into aparam.parameterized.Parameterized
object. Each key in dict_ should match the name of a parameter in parameterized. The parameter will be deserialized into parameterized using aParamConfigDeserializer
object matched with the following precedent:If deserializer_name_dict is specified and contains the same key, the value of the item in deserializer_name_dict will be used.
If deserializer_type_dict and the type of the parameter in question exactly matches a key in deserializer_type_dict, the value of the item in deserializer_type_dict will be used.
If the type of the parameter in question has a default deserializer (i.e.
Default<type>Deserializer
), it will be used.DefaultBackupDeserializer
will be used.
It is possible to pass a dictionary as parameterized instead of a
param.parameterized.Parameterized
instance to this function. This is “hierarchical mode”. The values of parameterized can beparam.parameterized.Parameterized
objects or nested dictionaries. In this case, dict_ and deserializer_name_dict are expected to be dictionaries with the same hierarchical structure (though the latter can still beNone
). deserializer_type_dict can be a flat dictionary of types to be applied to all nodes, or a hierarchical dictionary of strings like dict_, or some combination. The leaves of dict_ deserialize into the leaves of parameterized. If no leaf of dict_ exists for a given parameterized leaf, that parameterized object will not be updated.Default deserializers are likely appropriate for basic types like strings, ints, bools, floats, and numeric tuples. For more complex data types, including recursive
param.parameterized.Parameterized
instances, custom deserializers are recommended.- Parameters
dict –
parameterized (
Union
[Parameterized
,dict
]) –on_missing (
Literal
[‘ignore’, ‘warn’, ‘raise’]) – What to do if the parameterized instance does not have a parameter listed in dict_, or, in the case of “hierarchical mode”, if dict_ contains a key with no matching parameterized object to populate
- Raises
ParamConfigTypeError – If deserialization of a value fails
- pydrobert.param.serialization.deserialize_from_ini(file, parameterized, deserializer_name_dict=None, deserializer_type_dict=None, on_missing='warn', defaults=None, comment_prefixes=('#', ';'), inline_comment_prefixes=(';',), one_param_section=None)[source]
Deserialize an INI (config) file into a parameterized instance
.INI syntax, extended with
configparser
.configparser
extends the INI syntax with value interpolation. Further, keys missing a value will be interpreted as having the valueNone
. This function converts an INI file to a dictionary, then populates parameterized with the contents of this dictionary.INI files are broken up into sections; all key-value pairs must belong to a section. If parameterized is a
param.parameterized.Parameterized
instance (rather than a hierarchical dictionary of them), the action will try to deserialize the section specified by one_param_section keyword argument.Because the INI syntax does not support standard containers like dicts or lists out-of-the-box, this function uses the
JsonString*Deserializer
to read container values to JSON strings before trying the standard method of deserialization. This solution was proposed here. DefaultsDefault<type>Deserializer
are clobbered by those of formJson<type>Deserializer
. You can get the original defaults back by including them in deserializer_type_dict- Parameters
file (
Union
[TextIO
,str
]) – The INI file to deserialize from. Can be a pointer or a pathparameterized (
Union
[Parameterized
,dict
]) –on_missing (
Literal
[‘ignore’, ‘warn’, ‘raise’]) –defaults (
Optional
[dict
]) – Default key-values used in interpolation (substitution). Terms such as(key)%s
(like a python 2.7 format string) are substituted with these valuescomment_prefixes (
Sequence
[str
]) – A sequence of characters that indicate a full-line comment in the INI fileinline_comment_prefixes (
Sequence
[str
]) – A sequence of characters that indicate an inline (including full-line) comment in the INI fileone_param_section (
Optional
[str
]) – If parameterized refers to a singleparam.parameterized.Parameterized
instance, this keyword is used to indicate which section of the INI file will be deserialized. If unspecified, will default to thename
attribute of parameterized
See also
deserialize_from_dict
A description of the deserialization process and the parameters to this function
- pydrobert.param.serialization.deserialize_from_json(file_, parameterized, deserializer_name_dict=None, deserializer_type_dict=None, on_missing='warn')[source]
Deserialize a YAML file into a parameterized instance
Composes
deserialize_from_json_to_obj()
withdeserialize_from_dict()
.
- pydrobert.param.serialization.deserialize_from_json_to_obj(file_)[source]
Deserialize a JSON file into an object
- Parameters
file – A path or pointer to the JSON file.
- pydrobert.param.serialization.deserialize_from_yaml(file, parameterized, deserializer_name_dict=None, deserializer_type_dict=None, on_missing='warn')[source]
Deserialize a YAML file into a parameterized instance
Composes
deserialize_from_yaml_to_obj()
withdeserialize_from_dict()
.
- pydrobert.param.serialization.deserialize_from_yaml_to_obj(file_, ordered=False)[source]
Deserialize a YAML file into an object
- Parameters
file – A path or pointer to the YAML file.
ordered (
bool
) – Whether to respect ordering in the deserialized dictionaries.
Notes
This function tries to use the YAML (de)serialization module to load the YAML file in the order listed in
pydrobert.param.config.YAML_MODULE_PRIORITIES
, falling back on the next if there’s anImportError
.
- pydrobert.param.serialization.register_serializer(mode)[source]
Add a custom (de)serialization protocol to parameterized instances
The serialization protocol to be registered is passed as mode, which can be one of
'reckless_json'
, which is identical to the standard'json'
serializer but for some simplifying assumptions to handle nesting. See the below note for more information.'yaml'
, which follows a similar parsing strategy to vanilla'json'
but (de)serializes in YAML format instead. Requires eitheryaml
orruamel.yaml
to be installed or will raise an import error at the first request.'reckless_yaml'
, which makes the same reckless assumptions asreckless_json'
but (de)serialized in the YAML format.
After calling this function, parameters can be serialized with the same mode registered via
param.Parameterized.param.serialize_parameters()
:>>> str_ = p.param.serialize_parameters(subset, mode) >>> p = P.param.deserialize_parameters(str_, subset, mode)
Warning
Functionality is in beta and subject to additions and modifications.
Notes
We make strong simplifying assumptions to handle nesting. The usual means of nesting
param.parameterized.Parameterized
instances is>>> class Parent(param.Parameterized): ... child = param.ClassSelector(SomeParameterizedClass) >>> parent = Parent(child=SomeParameterizedClass(leaf_value=1))
While the obvious solution is to recursively call (de)serialization on child instances, this solution is not suited to all situations. In deserialization, the child may be of type SomeParameterizedClass, but may also be one of its subclasses. If children are sharing references to the same instance, that information will be lost in serialization.
For now (keep track of this bug for changes),
mode="json"
will throw if it sees a nested parameterized instance in serialization or deserialization. Reckless serialization is performed recursively with no consideration for references. Deserialization is performed by recursing on the class provided to the class selector (i.e. SomeParameterizedClass), not any of its subclasses.To (de)serialize only a subset of parameters in a child instance, delimit child parameters with
<name_in_parent>.<name_in_child>
in the subset argument. In the example above, we can serialize only leaf_value using>>> parent.param.serialize_parameters({'child.leaf_value'}, mode="reckless_json")
See also
- pydrobert.param.serialization.serialize_from_obj_to_json(file_, obj, indent=2)[source]
Serialize an object into a json file
JSON syntax. Given a dictionary of parameter values, fills an JSON file with the contents of this dictionary.
- pydrobert.param.serialization.serialize_from_obj_to_yaml(file_, obj, help=None)[source]
Serialize an object into a YAML file
- Parameters
file – The YAML file to serialize to. Can be a pointer or a path.
obj (
Any
) – The thing to serialize.help (
Optional
[Any
]) – An optional thing containing strings representing help information. Will try to save as comments. If obj and help share a structure (e.g. bothlist
ordict
), the backend will try to organize help in similar fashion.
Notes
This function tries to use the YAML (de)serialization module to load the YAML file in the order listed in
pydrobert.param.config.YAML_MODULE_PRIORITIES
, falling back on the next if there’s anImportError
- pydrobert.param.serialization.serialize_to_dict(parameterized, only=None, serializer_name_dict=None, serializer_type_dict=None, on_missing='raise', include_help=False)[source]
Serialize a parameterized object into a dictionary
This function serializes data into a dictionary format, suitable for storage in a dict-like file format such as YAML or JSON. Each parameter will be serialized into the dictionary using a ParamConfigSerializer object, matched with the following precedent:
If serializer_name_dict is specified and contains the parameter name as a key, the value will be used.
If serializer_type_dict and the type of the parameter in question exactly matches a key in serializer_type_dict, the value of the item in serializer_type_dict will be used.
If the type of the parameter in question has a
Default<type>Serializer
, it will be used.DefaultBackupSerializer
will be used.
Default serializers are likely appropriate for basic types like strings, ints, bools, floats, and numeric tuples. For more complex data types, including recursive
param.parameterized.Parameterized
instances, custom serializers are recommended.It is possible to pass a dictionary as parameterized instead of a
param.parameterized.Parameterized
instance to this function. This is “hierarchical mode”. The values of parameterized can beparam.parameterized.Parameterized
objects or nested dictionaries. The returned dictionary will have the same hierarchical dictionary structure as parameterized, but with theparam.parameterized.Parameterized
values replaced with serialized dictionaries. In this case, only and serializer_name_dict are expected to be dictionaries with the same hierarchical structure (though they can still beNone
, which propagates to children), whose leaves correspond to the arguments used to serialize the leaves of parameterized. serializer_type_dict can also be hierarchical, can be flat, or be some combination.- Parameters
parameterized (
Union
[Parameterized
,dict
]) –only (
Optional
[Collection
[str
]]) – If specified, only the parameters with their names in this set will be serialized into the return dictionary. If unset, all parameters exceptname
will be serialized.on_missing (
Literal
[‘ignore’, ‘warn’, ‘raise’]) – What to do if the parameterized instance does not have a parameter listed in onlyinclude_help (
bool
) – IfTrue
, the return value will be a pair of dictionaries instead of a single dictionary. This dictionary will contain any help strings any serializers make available through a call tohelp_string
(orNone
if none is available).
- Returns
collections.OrderedDict or tuple – A dictionary of serialized parameters or a pair of dictionaries if include_help was
True
(the latter is the help dictionary). If parameterized was an ordered dictionary, the returned serialized dictionary will have the same order. Parameters from aparam.parameterized.Parameterized
instance are sorted alphabeticallly- Raises
ParamConfigTypeError – If serialization of a value fails
- pydrobert.param.serialization.serialize_to_ini(file, parameterized, only=None, serializer_name_dict=None, serializer_type_dict=None, on_missing='raise', include_help=True, help_prefix='#', one_param_section=None)[source]
Serialize a parameterized instance into an INI (config) file
.INI syntax, extended with
configparser
.configparser
extends the INI syntax with value interpolation. Further, keys missing a value will be interpreted as having the valueNone
. This function converts parameterized to a dictionary, then fills an INI file with the contents of this dictionary.INI files are broken up into sections; all key-value pairs must belong to a section. If parameterized is a
param.parameterized.Parameterized
instance (rather than a hierarchical dictionary of them), the action will try to serialize parameterized into the section specified by the one_param_section keyword argument. If parameterized is a hierarchical dictionary, it can only have depth 1, with each leaf being aparam.parameterized.Parameterized
instance. In this case, each key corresponds to a section. If an ordered dictionary, sections will be written in the same order as they exist in parameterized.Because the INI syntax does not support standard containers like dicts or lists out-of-the-box, this function uses the
JsonString*Serializer
to convert container values to JSON strings before writing them to the INI file. This solution was proposed here. DefaultsDefault<type>Serializer
are clobbered withJson<type>Serializer
.You can get the original defaults back by including them in serializer_type_dict.- Parameters
file (
Union
[str
,TextIO
]) – The INI file to serialize to. Can be a pointer or a path.parameterized (
Union
[Parameterized
,dict
]) –only (
Optional
[Collection
[str
]]) –on_missing (
Literal
[‘ignore’, ‘warn’, ‘raise’]) –include_help (
bool
) – IfTrue
, help documentation will be included at the top of the INI file for any parameters and/or serializers that support ithelp_prefix (
str
) – The character prefix used at the start of each help line, usually indicating a commentone_param_section (
Optional
[str
]) – If parameterized refers to a singleparam.parameterized.Parameterized
instance, this keyword is used to indicate which section of the INI file parameterized will be serialized to. IfNone
, thename
attribute of the parameterized instance will be the used
See also
- pydrobert.param.serialization.serialize_to_json(file_, parameterized, only=None, serializer_name_dict=None, serializer_type_dict=None, on_missing='raise', indent=2)[source]
Serialize a parameterized instance into a JSON file
Composes
serialize_to_dict()
withserialize_from_obj_to_json()
.
- pydrobert.param.serialization.serialize_to_yaml(file_, parameterized, only=None, serializer_name_dict=None, serializer_type_dict=None, on_missing='raise', include_help=True)[source]
Serialize a parameterized instance into a YAML file
Composes
serialize_to_dict()
withserialize_from_obj_to_yaml()
.
- pydrobert.param.serialization.unregister_serializer(mode)[source]
Unregister a previously registered custom serializer
See also
- pydrobert.param.serialization.yaml_is_available()[source]
Returns whether one of the YAML backends is available
Checks only those in
pydrobert.param.config.YAML_MODULE_PRIORITIES