From 2c924c9e3af6fe0df75a1fc53f90c8fff623e221 Mon Sep 17 00:00:00 2001 From: Philipp Gesang Date: Fri, 1 Dec 2017 11:40:29 +0100 Subject: [PATCH] extend cnfvar.py description Also amend the formatting that got distorted by autopep8 in Autotest. --- src/cnfvar.py | 68 ++++++++++++++++++++++++++++++++++++--------------------- 1 files changed, 43 insertions(+), 25 deletions(-) diff --git a/src/cnfvar.py b/src/cnfvar.py index 397661b..fe29150 100644 --- a/src/cnfvar.py +++ b/src/cnfvar.py @@ -20,37 +20,55 @@ """ -SUMMARY ------------------------------------------------------- +summary +------------------------------------------------------------------------------- +Represent CNF_VARs as recursive structures. -Copyright: Intra2net AG +Copyright: 2014–2017 Intra2net AG License: GPLv2+ -CONTENTS ------------------------------------------------------- -Represent CNF_VARs as recursive structures. +contents +------------------------------------------------------------------------------- + +This module provides read and write functionality for the Intra2net *CNF* +format. Two different syntaxes are available: classical *CNF* and a JSON +representation. Both versions are commonly understood by Intra2net software. +For example, the :: + + # get_cnf routing 2 + 1 ROUTING,2: "192.168.55.0" + 2 (1) ROUTING_COMMENT,0: "" + 3 (1) ROUTING_DNS_RELAYING_ALLOWED,0: "1" + 4 (1) ROUTING_EMAIL_RELAYING_ALLOWED,0: "1" + 5 (1) ROUTING_FIREWALL_RULESET_REF,0: "9" + 6 (1) ROUTING_GATEWAY,0: "10.0.254.1" + 7 (1) ROUTING_NAT_INTO,0: "0" + 8 (1) ROUTING_NETMASK,0: "255.255.255.0" + 9 (1) ROUTING_PROXY_PROFILE_REF,0: "2" -.. todo:: Decide on some facility for automatic fixup of line number values. The +.. todo:: + Decide on some facility for automatic fixup of line number values. The internal representation is recursive so line numbers are not needed to - establish a variable hierarchy. They might as well be omitted from the - json input and only added when writing cnf. For the time being a lack - of the "number" field is interpreted as an error. Though it should at - least optionally be possible to omit the numbers entirely and have a - function add them after the fact. This might as well be added to - :py:func:`is_cnf` though it would be counterintuitive to have a predicate - mutate its argument. So maybe it could return a second argument to - indicate a valid structure that needs fixup or something like that. - -.. note:: The variable values of get_cnf seems to be encoded in latin1, and - set_cnf seems to require latin1-encoded values (not var names). - Function :py:func:`read_cnf` converts this to unicode and functions - :py:func:`dump_cnf_string`, :py:func:`print_cnf`, and - :py:func:`write_cnf` convert unicode back to latin1. - - -INTERFACE ------------------------------------------------------- + establish a variable hierarchy. They might as well be omitted from the json + input and only added when writing cnf. For the time being a lack of the + "number" field is interpreted as an error. Though it should at least + optionally be possible to omit the numbers entirely and have a function add + them after the fact. This might as well be added to :py:func:`is_cnf` + though it would be counterintuitive to have a predicate mutate its + argument. So maybe it could return a second argument to indicate a valid + structure that needs fixup or something like that. + +.. note:: + The variable values of get_cnf seems to be encoded in latin1, and set_cnf + seems to assume latin1-encoded values (not var names). Function + :py:func:`read_cnf` converts this to unicode and functions + :py:func:`dump_cnf_string`, :py:func:`print_cnf`, and :py:func:`write_cnf` + convert unicode back to latin1. + + +implementation +------------------------------------------------------------------------------- """ import functools -- 1.7.1