1 # The software in this package is distributed under the GNU General
2 # Public License version 2 (with a special exception described below).
4 # A copy of GNU General Public License (GPL) is included in this distribution,
5 # in the file COPYING.GPL.
7 # As a special exception, if other files instantiate templates or use macros
8 # or inline functions from this file, or you compile this file and link it
9 # with other works to produce a work based on this file, this file
10 # does not by itself cause the resulting work to be covered
11 # by the GNU General Public License.
13 # However the source code for this file must still be made available
14 # in accordance with section (3) of the GNU General Public License.
16 # This exception does not invalidate any other reasons why a work based
17 # on this file might be covered by the GNU General Public License.
19 # Copyright (c) 2016-2022 Intra2net AG <info@intra2net.com>
22 model: Cnf classes, collection of Cnf classes and multiple filtering methods.
25 - Cnf: class representing a CNF variable
26 - CnfList: a collection of `Cnf` instances
28 The classes above inherit from their base types with added mixins which
29 extend them with extra functionality.
31 .. seealso:: Overview Diagram linked to from doc main page
33 .. codeauthor:: Intra2net
39 from .. import arnied_api
41 #: value used to detect unspecified arguments
43 #: encoding used by the get_cnf and set_cnf binaries
47 ###############################################################################
49 ###############################################################################
54 Custom string where comparisons are case-insensitive.
56 With this class we do not have to worry about case when comparing against
57 the name of cnfvars when filtering. The cnfvar backend is already case-
61 def __eq__(self, other):
62 if not isinstance(other, str):
64 return self.lower() == other.lower()
66 def __contains__(self, name):
67 return name.lower() in self.lower()
69 def startswith(self, prefix, *args, **kwargs):
70 return self.lower().startswith(prefix.lower(), *args, **kwargs)
72 def endswith(self, suffix, *args, **kwargs):
73 return self.lower().endswith(suffix.lower(), *args, **kwargs)
75 def replace(self, old, new, *args, **kwargs):
76 return self.lower().replace(old.lower(), new.lower(), *args, **kwargs)
79 ###############################################################################
81 ###############################################################################
84 class BaseCnfList(list):
85 """Base class representing a CNF list with minimal functionality."""
87 def __init__(self, cnf_iter=None, renumber=False):
91 :param cnf_iter: iterator producing CNF elements or arguments for the
92 constructor of the :py:class:`Cnf` class
93 :type: :py:class:`collections.abc.Iterator` producing elements of type
95 :param bool renumber: whether to fix up the number/ids of the CNFs
98 cnf = Cnf("my_cnf", "value")
101 ("other_cnf", "other value"),
102 ("user", "john", instance=3)
105 # Map the values of the iterator to support constructing this list
106 # from Cnf instances or arguments to the Cnf constructor
107 if cnf_iter is not None:
108 iter_ = map(lambda c: c if isinstance(c, Cnf) else Cnf(*c), cnf_iter)
111 super().__init__(iter_)
112 self._renumber_counter = None # initialized and used in renumber
117 """Fix line numbers of CNF variables from this list."""
118 # NOTE: we don't keep track of operations that change the list as this
119 # would require us to reimplement most of the methods. At least for now
120 # this method should be called again when serializing.
121 self._renumber_counter = 0
123 def renumber_fn(cnf):
124 self._renumber_counter += 1
125 cnf.lineno = self._renumber_counter
127 self.for_each_all(renumber_fn)
129 def where(self, where_filter):
131 Filter CNFs matching a given predicate.
133 :param where_filter: predicate to apply against CNFs
134 :type where_filter: function accepting a CNF and returning a boolean
135 :returns: an instance of this class with filtered members
136 :rtype: :py:class:`CnfList`
138 return CnfList(c for c in self if where_filter(c))
140 def where_child(self, where_filter):
142 Filter CNFs with children matching a given predicate.
144 :param where_filter: predicate to apply against children
145 :type where_filter: function accepting a CNF and returning a boolean
146 :returns: an instance of this class with filtered members
147 :rtype: :py:class:`CnfList`
149 def upper_filter(cnf):
150 return any(ch for ch in cnf.children if where_filter(ch))
151 return self.where(upper_filter)
153 def remove_where(self, where_filter):
155 Remove all CNFs from this list matching the given predicate.
157 :param where_filter: predicate to apply against children
158 :type where_filter: function accepting a CNF and returning a boolean
159 :returns: a list of the removed CNF variables
160 :rtype: [:py:class:`Cnf`]
163 # iterate by index for speed and in reverse to keep indexes valid
164 for i in range(len(self) - 1, -1, -1):
166 if where_filter(cnf):
171 def for_each(self, fn):
173 Apply a function to each element of this list.
175 :param fn: function to apply to the elements
176 :type fn: function accepting a CNF (result value is ignored)
177 :returns: this same instance
178 :rtype: :py:class:`CnfList`
180 .. note:: this is mostly the same as the built-in map() function,
181 except that it changes the list in place.
186 except StopIteration:
191 def for_each_child(self, fn):
193 Apply a function to each child of the elements of this list.
195 :param fn: function to apply to the elements
196 :type fn: function accepting a CNF (result value is ignored)
197 :returns: this same instance
198 :rtype: :py:class:`CnfList`
200 .. note:: if a CNF does not have children, it is ignored
203 children = c.children or CnfList()
207 except StopIteration:
210 # apply recursively, too
211 children.for_each_child(fn)
214 def for_each_all(self, fn):
216 Apply a function to every CNF of this list, parent or child.
218 :param fn: function to apply to the elements
219 :type fn: function accepting a CNF (result value is ignored)
220 :returns: this same instance
221 :rtype: :py:class:`CnfList`
226 except StopIteration:
229 children = c.children or CnfList()
230 children.for_each_all(fn)
235 Get a string representation of this instance.
237 :returns: a string in the cnfvar format
240 return "\n".join((str(c) for c in self))
242 def __add__(self, other):
243 return CnfList(super().__add__(other))
245 def add(self, *args, **kwargs):
247 Add a CNF variable to the list.
249 Arguments can either be a single instance of the :py:class:`Cnf`
250 class or a list of arguments to be passed to the constructor of
251 that class. Similar to the :py:func:`add_child` method for a `Cnf`.
253 :returns: the instance that was created
254 :rtype: :py:class:`Cnf`
256 # support passing a Cnf instance
257 if len(args) == 1 and not kwargs:
259 assert isinstance(cnf, Cnf), "A Cnf instance is mandatory with one argument"
261 cnf = Cnf(*args, **kwargs)
268 """Base class representing a CNF variable with minimal functionality."""
270 _PARENT_TEMPLATE = "{lineno} {name},{instance}: \"{value}\""
271 _CHILD_TEMPLATE = "{lineno} {indent}({parent}) {name},{instance}: \"{value}\""
274 def __init__(self, name, value, instance=0, parent=None,
275 lineno=None, comment=None):
277 Create this instance.
279 :param str name: name of the cnfvar (case does not matter)
280 :param str value: value for this cnfvar (will be converted to string
281 if it is not of this type)
282 :param int instance: instance of this cnfvar
283 :param parent: a parent Cnf instance
284 :type parent: :py:class:`BaseCnf`
285 :param int lineno: line number
286 :param str comment: cnfvar comment
288 self.name = CnfName(name)
290 self.instance = int(instance)
292 self.lineno = int(lineno or 0)
293 self.comment = comment
294 self.__children = CnfList()
296 # Use getters and setters to keep internal consistency and fail-fast
297 # preventing invalid data from being sent to the cnfvar backend.
302 def _set_name(self, value):
303 # convert Python strings passed as name to our custom string
304 self.__name = CnfName(value)
305 name = property(_get_name, _set_name)
307 def _get_instance(self):
308 return self.__instance
310 def _set_instance(self, value):
311 # fail-fast and make sure instance is a valid integer
312 self.__instance = int(value)
313 instance = property(_get_instance, _set_instance)
315 def _get_lineno(self):
318 def _set_lineno(self, value):
319 # fail-fast and make sure lineno is a valid integer
320 self.__lineno = int(value)
321 lineno = property(_get_lineno, _set_lineno)
323 def _get_children(self):
324 return self.__children
325 # No setter to sure that the children property will not
326 # be replaced by something other than a `CnfList`
327 children = property(_get_children)
329 def _get_value(self):
332 def _set_value(self, value):
333 # Make sure the value is always stored as a string
334 # (no other types make sense to the cnfvar backend)
335 self.__value = str(value)
336 value = property(_get_value, _set_value)
338 def add_child(self, *args, **kwargs):
340 Add a child CNF variable.
342 Arguments can either be a single instance of the :py:class:`Cnf`
343 class or a list of arguments to be passed to the constructor of
346 :returns: the instance that was created
347 :rtype: :py:class:`Cnf`
351 cnf = Cnf("my_parent_cnf", "parent")
352 cnf2 = Cnf("my_child_cnf", "john")
354 # adding a child as a CNF instance
357 # adding a child passing arguments of the Cnf constructor
358 cnf.add_child("my_child_cnf", "jane", instance=2)
360 # support passing a Cnf instance
361 if len(args) == 1 and not kwargs:
363 assert isinstance(cnf, Cnf), "A Cnf instance is mandatory with one argument"
365 cnf = Cnf(*args, **kwargs)
367 # store a reference to parent to easily access it
370 # It seems the CNF backend (at least using set_cnf as opposed to the varlink
371 # API) only accepts instance with value of -1 for top-level variables, so
372 # just in case fix up instances when adding children with the default value.
373 if cnf.instance == -1:
375 for c in self.children:
376 if c.name == cnf.name:
379 self.children.append(cnf)
382 def add_children(self, *children):
384 Add multiple child CNF variables.
386 Each argument must be either an instance of the :py:class:`Cnf` class
387 or a tuple/list to be expanded and passed to construct that instance.
389 :returns: a list of the instances that were created
390 :rtype: :py:class:`CnfList`
393 cnf = Cnf("my_parent_cnf", "parent")
394 cnf2 = Cnf("my_child_cnf", "john")
397 cnf2, # cnf instance directly
398 ("my_child_cnf", "jane", instance=2), # pass a tuple with args
399 ["my_child_cnf", "jack", instance=3]) # pass a list with args
401 # adding a child passing arguments of the Cnf constructor
402 cnf.add_child("my_child_cnf", "jane", instance=2)
404 added_children = CnfList()
406 if isinstance(c, Cnf):
407 new_child = self.add_child(c)
408 elif isinstance(c, tuple) or isinstance(c, list):
409 new_child = self.add_child(*c)
411 raise ValueError(f"Children item {c} must be either a Cnf, a tuple or a list")
412 added_children.append(new_child)
413 return added_children
415 def __eq__(self, other):
417 Equality implementation.
419 :param other: object to compare this instance against
421 :returns: whether `other` is equal to this instance
424 This is particularly useful when comparing instances of
427 if not isinstance(other, Cnf):
430 # NOTE: we try to define two variables as equal in the same way as the
431 # set_cnf binary would if we were passing it an updated CNF variable.
432 # It does not take comments, children and lineno into account when we
433 # pass it a variable; it will rather compare the data we compare here,
434 # and if it finds a match it will update it with the changed children.
435 return self.name == other.name \
436 and self.value == other.value \
437 and self.instance == other.instance \
438 and self.parent == other.parent
442 Get a string representation of this instance.
444 :returns: a string in the cnfvar format
447 if self.parent is None:
448 this_str = self._PARENT_TEMPLATE.format(
450 name=self.name.upper(),
451 instance=self.instance,
457 while curr.parent is not None:
461 this_str = self._CHILD_TEMPLATE.format(
463 indent=self._NEST_INDENT * depth,
464 parent=self.parent.lineno,
465 name=self.name.upper(),
466 instance=self.instance,
470 if self.comment is not None:
471 this_str += f" # {self.comment}"
473 for child in self.children:
474 this_str += f"\n{child}"
480 Get a printable representation of this instance.
482 :returns: a string in the cnfvar format
485 repr_ = self._PARENT_TEMPLATE.format(
487 name=self.name.upper(),
488 instance=self.instance,
490 ) if self.parent is None else self._CHILD_TEMPLATE.format(
493 parent=self.parent.lineno,
494 name=self.name.upper(),
495 instance=self.instance,
498 return f"Cnf{{ {repr_} [children={len(self.children)}] }}"
501 ###############################################################################
503 ###############################################################################
505 # These mixins add functionality to the base API without polluting it.
508 class CnfListSerializationMixin(BaseCnfList):
509 """Add serialization support to BaseCnfList."""
511 def to_cnf_file(self, path, renumber=True, encoding=ENCODING):
513 Dump a string representation of this list in the cnfvar format to a file.
515 :param str path: path to the file to write to
516 :param bool renumber: whether to fix the lineno of the cnfvars
517 :param str encoding: encoding to use to save the file
521 with open(path, "w", encoding=encoding) as fp:
524 def to_json_string(self, renumber=True):
526 Generate a JSON representation of this list in the cnfvar format.
528 :param bool renumber: whether to fix the lineno of the cnfvars
529 :returns: the JSON string
534 "number": cnf.lineno,
537 "instance": cnf.instance
539 if cnf.parent and cnf.parent.lineno:
540 d["parent"] = cnf.parent.lineno
541 if cnf.comment is not None:
542 d["comment"] = cnf.comment
543 if len(cnf.children) > 0:
544 d["children"] = [_to_dict(c) for c in cnf.children]
548 json_list = [_to_dict(c) for c in self]
549 return json.dumps({"cnf": json_list})
551 def to_json_file(self, path, renumber=True):
553 Dump a JSON representation of this list to a file.
555 :param str path: path to the file to write to
556 :param bool renumber: whether to fix the lineno of the cnfvars
558 with open(path, "w", encoding="utf8") as fp:
559 fp.write(self.to_json_string(renumber=renumber))
562 def _from_cnf_structure(cls, obj):
564 Create a list from a JSON structure obtainable from `get_cnf --json`.
566 :param obj: an object as defined in the :py:mod:`cnfvar`
567 :type obj: {str, {str, str or int}}
568 :returns: a list of cnfvars
569 :rtype: :py:class:`CnfList`
571 return cls(map(Cnf._from_cnf_structure, obj["cnf"]))
574 def from_cnf_string(cls, data):
576 Create a list from a cnfvar string.
578 :param str data: string to generate the list from
579 :returns: a list of cnfvars
580 :rtype: :py:class:`CnfList`
582 cnf_obj = string.read_cnf(data)
583 return CnfList._from_cnf_structure(cnf_obj)
586 def from_json_string(cls, data):
588 Create a list from a json string.
590 :param str data: string to generate the list from
591 :returns: a list of cnfvars
592 :rtype: :py:class:`CnfList`
594 cnf_obj = json.loads(data)
595 return CnfList._from_cnf_structure(cnf_obj)
598 def from_cnf_file(cls, path, encoding=ENCODING):
600 Create a list from a cnfvar file.
602 :param str path: path to the file to read
603 :param str encoding: encoding to use to open the file (defaults to
604 latin1 as this is the default encoding)
605 :returns: a list of cnfvars
606 :rtype: :py:class:`CnfList`
608 with open(path, "r", encoding=encoding) as fp:
609 return CnfList.from_cnf_string(fp.read())
612 def from_json_file(cls, path):
614 Create a list from a json file.
616 :param str path: path to the file to read
617 :returns: a list of cnfvars
618 :rtype: :py:class:`CnfList`
620 with open(path, "r", encoding="utf8") as fp:
621 return CnfList.from_json_string(fp.read())
624 class CnfSerializationMixin(BaseCnf):
625 """Add serialization support to BaseCnf."""
627 def to_json_string(self, renumber=True):
629 Convert this instance to a JSON string.
631 :param bool renumber: whether to fix the lineno of the cnfvars
632 :returns: the JSON string
635 return CnfList([self]).to_json_string(renumber=renumber)
637 def to_cnf_file(self, path, renumber=True, encoding=ENCODING):
639 Dump a string representation of this instance to a file.
641 :param str path: path to the file to write to
642 :param bool renumber: whether to fix the lineno of this cnfvar and its children
643 :param str encoding: encoding to use to save the file
645 CnfList([self]).to_cnf_file(path, renumber=renumber, encoding=encoding)
647 def to_json_file(self, path, renumber=True):
649 Dump a JSON representation of this instance to a file.
651 :param str path: path to the file to write to
652 :param bool renumber: whether to fix the lineno of this cnfvar and its children
654 CnfList([self]).to_json_file(path, renumber=renumber)
657 def _from_cnf_structure(cls, obj):
659 Create an instance from a JSON structure obtainable from `get_cnf --json`.
661 :param obj: dictionary to convert to this instance
662 :type obj: {str, str or int}
663 :returns: the cnf instance created
664 :rtype: :py:class:`Cnf`
666 cnf = Cnf(obj["varname"], obj["data"],
667 instance=obj["instance"], lineno=obj["number"],
668 comment=obj.get("comment", None))
669 for ch_obj in obj.get("children", []):
670 child_cnf = Cnf._from_cnf_structure(ch_obj)
671 cnf.add_child(child_cnf)
675 def from_cnf_string(cls, data):
677 Create an instance of this class from a cnfvar string.
679 :param str data: cnfvar string to convert
680 :returns: the cnf instance created
681 :rtype: :py:class:`Cnf`
683 return CnfListSerializationMixin.from_cnf_string(data).single()
686 def from_json_string(cls, data):
688 Create an instance of this class from a JSON string.
690 :param str data: JSON string to convert
691 :returns: the cnf instance created
692 :rtype: :py:class:`Cnf`
694 return CnfListSerializationMixin.from_json_string(data).single()
697 def from_cnf_file(cls, path, encoding=ENCODING):
699 Create an instance of this class from a cnfvar file.
701 :param str path: path to the file to read
702 :param str encoding: encoding to use to read the file
703 :returns: the cnf instance created
704 :rtype: :py:class:`Cnf`
706 return CnfListSerializationMixin.from_cnf_file(path, encoding=encoding).single()
709 def from_json_file(cls, path):
711 Create an instance of this class from a json file.
713 :param str path: path to the file to read
714 :returns: the cnf instance created
715 :rtype: :py:class:`Cnf`
717 return CnfListSerializationMixin.from_json_file(path).single()
720 class CnfListArniedApiMixin(BaseCnfList):
721 """Add support for converting this class to and from Arnied API classes."""
723 def to_api_structure(self):
725 Convert this list to the corresponding object in the arnied API.
727 :returns: the converted object
728 :rtype: [:py:class:`arnied_api.CnfVar`]
730 return [c.to_api_structure() for c in self]
733 def from_api_structure(cls, cnfvar_list):
735 Convert a list from the arnied API into a list of this type.
737 :param cnfvar_list: list to convert
738 :type cnfvar_list: [:py:class:`arnied_api.CnfVar`]
739 :returns: the list created
740 :rtype: :py:class:`CnfList`
742 return CnfList((Cnf.from_api_structure(c) for c in cnfvar_list),
746 class CnfArniedApiMixin(BaseCnf):
747 """Add support for converting this class to and from Arnied API classes."""
749 def to_api_structure(self):
751 Convert this instance to the corresponding object in the arnied API.
753 :returns: the converted object
754 :rtype: :py:class:`arnied_api.CnfVar`
756 return arnied_api.CnfVar(
760 False, # default here to False
761 children=[c.to_api_structure() for c in self.children])
764 def from_api_structure(cls, cnfobj):
766 Convert an object from the arnied API into an instance of this type.
768 :param cnfobj: object to convert
769 :type cnfobj: :py:class:`arnied_api.CnfVar`
770 :returns: the instance created
771 :rtype: :py:class:`Cnf`
773 cnf = Cnf(cnfobj.name, cnfobj.data, cnfobj.instance)
774 children = CnfList((Cnf.from_api_structure(c) for c in cnfobj.children))
777 cnf.children.extend(children)
781 class CnfShortcutsMixin(BaseCnf):
782 """Extend the base CNF class with useful methods."""
785 """Treat this variable as a boolean var and set its value to 1."""
789 """Treat this variable as a boolean var and set its value to 0."""
792 def is_enabled(self):
793 """Treat this variable as a boolean var and check if its value is 1."""
794 return self.value == "1"
796 def enable_child_flag(self, name):
798 Set the value of the child CNF matching `name` to "1".
800 :param str name: name of the child whose value to enable
802 .. note:: child will be created if it does not exist.
804 cnf = self.children.first_with_name(name, default=None)
806 self.add_child(name, "1")
810 def disable_child_flag(self, name):
812 Set the value of the child CNF matching `name` to "0".
814 :param str name: name of the child whose value to disable
816 .. note:: child will be created if it does not exist.
818 cnf = self.children.first_with_name(name, default=None)
820 self.add_child(name, "0")
824 def child_flag_enabled(self, name):
826 Check if a given child has a value equal to `1`.
828 :param str name: name of the child to check
829 :returns: whether the value of the given child, if it exists, is 1
832 cnf = self.children.first_with_name(name, default=None)
833 return cnf.is_enabled() if cnf is not None else False
836 class CnfListQueryingMixin(BaseCnfList):
837 """Mixing adding shortcuts for common filter operations."""
839 def single(self, where_filter=None, default=DEFAULT):
841 Get the only CNF of this list or raise if none or more than one exist.
843 :param where_filter: predicate to apply against CNFs beforehand
844 :type where_filter: function accepting a CNF and returning a boolean
845 :param default: value to return in case the list is empty
847 :raises: :py:class:`ValueError` if a single value cannot be found and
848 a default value was not specified
849 :returns: the first and only element of this list, or default if set
850 and no element is present
851 :rtype: :py:class:`Cnf`
853 list_ = self.where(where_filter) if where_filter is not None else self
857 elif len(list_) == 0 and default != DEFAULT:
860 raise ValueError(f"CnfList does not contain a single item (len={len(list_)})")
862 def first(self, where_filter=None, default=DEFAULT):
864 Get the first element in this list or raise if the list is empty.
866 :param where_filter: predicate to apply against CNFs beforehand
867 :type where_filter: function accepting a CNF and returning a boolean
868 :param default: value to return in case the list is empty
870 :raises: :py:class:`ValueError` if a single value cannot be found and
871 a default value was not specified
872 :returns: the first element of this list, or default if set and
873 no element is present
874 :rtype: :py:class:`Cnf`
876 list_ = self.where(where_filter) if where_filter is not None else self
879 elif default != DEFAULT:
882 raise ValueError("Cannot get the first item - CnfList is empty")
884 def with_value(self, value):
885 """Shortcut method for filtering by value."""
886 return self.where(lambda c: c.value == value)
888 def with_name(self, name):
889 """Shortcut method for filtering by name."""
890 return self.where(lambda c: c.name == name)
892 def with_instance(self, instance):
893 """Shortcut method for filtering by instance."""
894 return self.where(lambda c: c.instance == instance)
896 def single_with_name(self, name, default=DEFAULT):
897 """Shortcut method for getting the single item with a given name."""
898 return self.with_name(name).single(default=default)
900 def single_with_value(self, value, default=DEFAULT):
901 """Shortcut method for getting the single item with a given value."""
902 return self.with_value(value).single(default=default)
904 def single_with_instance(self, instance, default=DEFAULT):
905 """Shortcut method for getting the single item with a given instance."""
906 return self.with_instance(instance).single(default=default)
908 def first_with_name(self, name, default=DEFAULT):
909 """Shortcut method for getting the first item with a given name."""
910 return self.with_name(name).first(default=default)
912 def first_with_value(self, value, default=DEFAULT):
913 """Shortcut method for getting the first item with a given value."""
914 return self.with_value(value).first(default=default)
916 def first_with_instance(self, instance, default=DEFAULT):
917 """Shortcut method for getting the first item with a given instance."""
918 return self.with_instance(instance).first(default=default)
920 def highest_instance(self):
921 """Shortcut method for getting the next instance in a list of items."""
922 return max([c.instance for c in self]) if len(self) > 0 else -1
925 ###############################################################################
927 ###############################################################################
929 # Set up the classes with the mixins we want to be available by default.
933 class CnfList(CnfListSerializationMixin, CnfListArniedApiMixin, CnfListQueryingMixin):
934 """Collection of Cnf variables."""
939 class Cnf(CnfSerializationMixin, CnfArniedApiMixin, CnfShortcutsMixin):
940 """Class representing a cnfvar."""
945 __all__ = ["CnfList", "Cnf"]