From a4ef1ec050c4f40952d15bc14d29152017cd0912 Mon Sep 17 00:00:00 2001
From: schneider <schneider@blinkenlichts.net>
Date: Wed, 8 Apr 2020 00:52:13 +0200
Subject: [PATCH] doc(config): Add Python docs
---
Documentation/conf.py | 3 +++
Documentation/index.rst | 1 +
Documentation/pycardium/config.rst | 9 +++++++
pycardium/modules/py/config.py | 43 ++++++++++++++++++++++++++++--
4 files changed, 54 insertions(+), 2 deletions(-)
create mode 100644 Documentation/pycardium/config.rst
diff --git a/Documentation/conf.py b/Documentation/conf.py
index d5c08c5f4..b80d8dadd 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -62,6 +62,8 @@ class ColorExample(rst.Directive):
color = self.arguments[0]
html_text = '<div style="width: 30px;height: 30px;background: {};border: black 1px solid;border-radius: 15px;"></div>'
return [nodes.raw("", html_text.format(color), format="html")]
+
+
# }}}
# -- Options for HTML output ------------------------------------------------- {{{
@@ -112,6 +114,7 @@ autodoc_mock_imports = [
"sys_display",
"sys_leds",
"sys_max30001",
+ "sys_config",
"ucollections",
"urandom",
"utime",
diff --git a/Documentation/index.rst b/Documentation/index.rst
index 6693f3c26..f6ce6fcd5 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -27,6 +27,7 @@ Last but not least, if you want to start hacking the lower-level firmware, the
pycardium/max30001
pycardium/buttons
pycardium/color
+ pycardium/config
pycardium/display
pycardium/gpio
pycardium/leds
diff --git a/Documentation/pycardium/config.rst b/Documentation/pycardium/config.rst
new file mode 100644
index 000000000..926098eb1
--- /dev/null
+++ b/Documentation/pycardium/config.rst
@@ -0,0 +1,9 @@
+``config`` - Configuration
+==========================
+The ``config`` module provides functions to interact with card10's
+configuration file (``card10.cfg``).
+
+.. automodule:: config
+ :members:
+
+
diff --git a/pycardium/modules/py/config.py b/pycardium/modules/py/config.py
index 1ac655296..8d70936ff 100644
--- a/pycardium/modules/py/config.py
+++ b/pycardium/modules/py/config.py
@@ -2,8 +2,47 @@ import sys_config
def set_string(key, value):
- sys_config.set_string(key, str(value))
+ """
+ Write a string to the configuration file ``card10.cfg``.
+
+ Both ``key`` and ``value`` must be strings or must be
+ convertible to a string using the ``str()`` function.
+
+ ``key`` must not contain spaces, control characters (including tabs),
+ number signs ans equal signs.
+ ``value` must not contain control characters (including tabs).
+ Neither is allowed to contain the sub-string ``execute_elf``.
+
+ The key/value pair is immediately written to the configuration
+ file (``card10.cfg``). After the file is written, configuration
+ is read again and the new value is available via ``config.get_string``.
+
+ :param str key: Name of the configuration option.
+ :param str value: Value to write.
+ :raises OSError: If writing to the configuration file failed.
+ :raises OSError: If key or value contain illegal characters.
+ :raises ValueError: If key or value contain the sub-string ``execute_elf``.
+
+ .. versionadded:: 1.16
+ """
+
+ sys_config.set_string(str(key), str(value))
def get_string(key):
- return sys_config.get_string(key)
+ """
+ Read a string from the configuration file ``card10.cfg``.
+
+ ``key`` must be a string or must be convertible to a string using
+ the ``str()`` function.
+
+
+ :param str key: Name of the configuration option.
+ :rtype: str
+ :returns: Value of the configuration option.
+ :raises OSError: if the key is not present in the configuration.
+
+ .. versionadded:: 1.16
+ """
+
+ return sys_config.get_string(str(key))
--
GitLab