/
githubmirror
/
libeconf
Обзор
Документация
Войти
/
githubmirror
/
libeconf
Код
Запросы
0
Пакеты
0
Релизы
0
Аналитика
Безопасность
master
bindings/python3/docs/python-libeconf.3
780 строк
18 KB
Nico Krapp
Update readme with python bindings and usage (#190)
20 дек 2023, 11:29
Не верифицирован
20 дек 2023, 11:29
40a032d
Код
Авторство
О чём код?
.\" Man page generated from reStructuredText. . . .nr rst2man-indent-level 0 . .de1 rstReportMargin \\$1 \\n[an-margin] level \\n[rst2man-indent-level] level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] - \\n[rst2man-indent0] \\n[rst2man-indent1] \\n[rst2man-indent2] .. .de1 INDENT .\" .rstReportMargin pre: . RS \\$1 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] . nr rst2man-indent-level +1 .\" .rstReportMargin post: .. .de UNINDENT . RE .\" indent \\n[an-margin] .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] .nr rst2man-indent-level -1 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. .TH "PYTHON-LIBECONF" "3" "Nov 13, 2023" "" "python-libeconf" .sp \fBpython\-libeconf\fP is a Python Library which offers Python bindings for \fI\%libeconf\fP\&. .sp libeconf is a highly flexible and configurable library to parse and manage key=value configuration files. It reads configuration file snippets from different directories and builds the final configuration file for the application from it. .SH CONTENTS .SS Usage .SS install .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 The recommended way to install this project is to get it via your distro package manager. If you install this project from pypi libeconf will not be automatically installed. To use this project please make sure you have libeconf installed on your system! .UNINDENT .UNINDENT .sp You can install this project from pypi with .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pip install python\-libeconf .ft P .fi .UNINDENT .UNINDENT .sp and then import it into your python project with .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C import econf .ft P .fi .UNINDENT .UNINDENT .sp For information about the functions provided by this library, have a look at the \fI\%API\fP section .SS usage example .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C >>> import econf >>> file = econf.read_file(\(dqexamples/etc/example/example.conf\(dq, \(dq=\(dq, \(dq#\(dq) >>> econf.get_groups(file) [\(aqAnother Group\(aq, \(aqFirst Group\(aq, \(aqGroup\(aq] >>> econf.get_keys(file, \(dqGroup\(dq) [\(aqBla\(aq, \(aqWelcome[la]\(aq, \(aqWelcome\(aq] >>> econf.get_int_value(file, \(dqGroup\(dq, \(dqBla\(dq) 12311 >>> econf.set_int_value(file, \(dqGroup\(dq, \(dqBla\(dq, 5) >>> econf.get_int_value(file, \(dqGroup\(dq, \(dqBla\(dq) 5 >>> econf.write_file(file, \(dqexamples/etc/example\(dq, \(dqexample_new.conf\(dq) >>> .ft P .fi .UNINDENT .UNINDENT .SS API .TS center; ||. _ .TE .SS Functions to interact with config files .INDENT 0.0 .TP .B econf.read_file(file_name: str | bytes, delim: str | bytes, comment: str | bytes) -> EconfFile Read a config file and write the key\-value pairs into a keyfile object .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfile_name\fP – absolute path of file to be parsed .IP \(bu 2 \fBdelim\fP – delimiter of a key/value e.g. ‘=’ .IP \(bu 2 \fBcomment\fP – string that defines the start of a comment e.g. ‘#’ .UNINDENT .TP .B Returns Key\-Value storage object .UNINDENT .UNINDENT .INDENT 0.0 .TP .B econf.read_file_with_callback(file_name: str | bytes, delim: str | bytes, comment: str | bytes, callback: Callable[[any], bool], callback_data: any) -> EconfFile Read a config file and write the key\-value pairs into a keyfile object .sp A user defined function will be called in order e.g. to check the correct file permissions. If the function returns False the parsing will be aborted and an Exception will be raised .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfile_name\fP – absolute path of file to be parsed .IP \(bu 2 \fBdelim\fP – delimiter of a key/value e.g. ‘=’ .IP \(bu 2 \fBcomment\fP – string that defines the start of a comment e.g. ‘#’ .IP \(bu 2 \fBcallback\fP – User defined function which will be called and returns a boolean .IP \(bu 2 \fBcallback_data\fP – argument to be give to the callback function .UNINDENT .TP .B Returns Key\-Value storage object .UNINDENT .UNINDENT .INDENT 0.0 .TP .B econf.new_key_file(delim: str | bytes, comment: str | bytes) -> EconfFile Create a new empty keyfile .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBdelim\fP – delimiter of a key/value e.g. ‘=’ .IP \(bu 2 \fBcomment\fP – string that defines the start of a comment e.g. ‘#’ .UNINDENT .TP .B Returns created EconfFile object .UNINDENT .UNINDENT .INDENT 0.0 .TP .B econf.new_ini_file() -> EconfFile Create a new empty keyfile with delimiter ‘=’ and comment ‘#’ .INDENT 7.0 .TP .B Returns created EconfFile object .UNINDENT .UNINDENT .INDENT 0.0 .TP .B econf.merge_files(usr_file: EconfFile, etc_file: EconfFile) -> EconfFile Merge the content of 2 keyfile objects .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBusr_file\fP – first EconfFile object .IP \(bu 2 \fBetc_file\fP – second EconfFile object .UNINDENT .TP .B Returns merged EconfFile object .UNINDENT .UNINDENT .INDENT 0.0 .TP .B econf.read_config(project: str |bytes, usr_conf_dir: str | bytes, config_name: str | bytes, config_suffix: str | bytes, delim: str | bytes, comment: str | bytes) -> EconfFile Evaluating key/values of a given configuration by reading and merging all needed/available files from different directories. .sp This call fulfills all requirements, defined by the Linux Userspace API (UAPI) Group chapter "Configuration Files Specification". .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBproject\fP – name of the project used as subdirectory .IP \(bu 2 \fBusr_conf_dir\fP – absolute path of the first directory to be searched .IP \(bu 2 \fBconfig_name\fP – basename of the configuration file .IP \(bu 2 \fBconfig_suffix\fP – suffix of the configuration file .IP \(bu 2 \fBdelim\fP – delimiter of a key/value e.g. ‘=’ .IP \(bu 2 \fBcomment\fP – string that defines the start of a comment e.g. ‘#’ .UNINDENT .TP .B Returns merged EconfFile object .UNINDENT .UNINDENT .INDENT 0.0 .TP .B econf.read_config_with_callback(project: str | bytes, usr_conf_dir: str | bytes, config_name: str | bytes, config_suffix: str | bytes, delim: str | bytes, comment: str | bytes, callback: Callable[[any], bool], callback_data: any) -> EconfFile Evaluating key/values of a given configuration by reading and merging all needed/available files from different directories. .sp For every file a user defined function will be called in order e.g. to check the correct file permissions. If the function returns False the parsing will be aborted and an Exception will be raised .sp This call fulfills all requirements, defined by the Linux Userspace API (UAPI) Group chapter "Configuration Files Specification". .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBproject\fP – name of the project used as subdirectory .IP \(bu 2 \fBusr_conf_dir\fP – absolute path of the first directory to be searched .IP \(bu 2 \fBconfig_name\fP – basename of the configuration file .IP \(bu 2 \fBconfig_suffix\fP – suffix of the configuration file .IP \(bu 2 \fBdelim\fP – delimiter of a key/value e.g. ‘=’ .IP \(bu 2 \fBcomment\fP – string that defines the start of a comment e.g. ‘#’ .IP \(bu 2 \fBcallback\fP – User defined function which will be called for each file and returns a boolean .IP \(bu 2 \fBcallback_data\fP – argument to be give to the callback function .UNINDENT .TP .B Returns merged EconfFile object .UNINDENT .UNINDENT .INDENT 0.0 .TP .B econf.comment_tag(ef: EconfFile) -> str Get the comment tag of the specified EconfFile .INDENT 7.0 .TP .B Parameters \fBef\fP – Key\-Value storage object .TP .B Returns The comment tag of the EconfFile .UNINDENT .UNINDENT .INDENT 0.0 .TP .B econf.set_comment_tag(ef: EconfFile, comment: str | bytes) -> None Set the comment tag of the specified EconfFile .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBef\fP – Key\-Value storage object .IP \(bu 2 \fBcomment\fP – The desired comment tag character .UNINDENT .TP .B Returns Nothing .UNINDENT .UNINDENT .INDENT 0.0 .TP .B econf.delimiter_tag(ef: EconfFile) -> str Get the delimiter tag of the specified EconfFile .INDENT 7.0 .TP .B Parameters \fBef\fP – Key\-Value storage object .TP .B Returns the delimiter tag of the EconfFile .UNINDENT .UNINDENT .INDENT 0.0 .TP .B econf.set_delimiter_tag(ef: EconfFile, delimiter: str | bytes) -> None Set the delimiter tag of the specified EconfFile .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBef\fP – Key\-Value storage object .IP \(bu 2 \fBdelimiter\fP – The desired delimiter character .UNINDENT .TP .B Returns Nothing .UNINDENT .UNINDENT .INDENT 0.0 .TP .B econf.write_file(ef: EconfFile, save_to_dir: str, file_name: str) -> None Write content of a keyfile to specified location .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBef\fP – Key\-Value storage object .IP \(bu 2 \fBsave_to_dir\fP – directory into which the file has to be written .IP \(bu 2 \fBfile_name\fP – filename with suffix of the to be written file .UNINDENT .TP .B Returns Nothing .UNINDENT .UNINDENT .INDENT 0.0 .TP .B econf.get_path(ef: EconfFile) -> str Get the path of the source of the given key file .INDENT 7.0 .TP .B Parameters \fBef\fP – Key\-Value storage object .TP .B Returns path of the config file as string .UNINDENT .UNINDENT .SS Functions for getting values .INDENT 0.0 .TP .B econf.get_groups(ef: EconfFile) -> list[str] List all the groups of given keyfile .INDENT 7.0 .TP .B Parameters \fBef\fP – Key\-Value storage object .TP .B Returns list of groups in the keyfile .UNINDENT .UNINDENT .INDENT 0.0 .TP .B econf.get_keys(ef: EconfFile, group: str) -> list[str] List all the keys of a given group or all keys in a keyfile .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBef\fP – Key\-Value storage object .IP \(bu 2 \fBgroup\fP – group of the keys to be returned or None for keys without a group .UNINDENT .TP .B Returns list of keys in the given group .UNINDENT .UNINDENT .INDENT 0.0 .TP .B econf.get_int_value(ef: EconfFile, group: str, key: str) -> int Return an integer value for given group/key .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBef\fP – Key\-Value storage object .IP \(bu 2 \fBgroup\fP – desired group .IP \(bu 2 \fBkey\fP – key of the value that is requested .UNINDENT .TP .B Returns value of the key .UNINDENT .UNINDENT .INDENT 0.0 .TP .B econf.get_uint_value(ef: EconfFile, group: str, key: str) -> int Return an unsigned integer value for given group/key .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBef\fP – Key\-Value storage object .IP \(bu 2 \fBgroup\fP – desired group .IP \(bu 2 \fBkey\fP – key of the value that is requested .UNINDENT .TP .B Returns value of the key .UNINDENT .UNINDENT .INDENT 0.0 .TP .B econf.get_float_value(ef: EconfFile, group: str, key: str) -> float Return a float value for given group/key .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBef\fP – Key\-Value storage object .IP \(bu 2 \fBgroup\fP – desired group .IP \(bu 2 \fBkey\fP – key of the value that is requested .UNINDENT .TP .B Returns value of the key .UNINDENT .UNINDENT .INDENT 0.0 .TP .B econf.get_string_value(ef: EconfFile, group: str, key: str) -> str Return a string value for given group/key .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBef\fP – Key\-Value storage object .IP \(bu 2 \fBgroup\fP – desired group .IP \(bu 2 \fBkey\fP – key of the value that is requested .UNINDENT .TP .B Returns value of the key .UNINDENT .UNINDENT .INDENT 0.0 .TP .B econf.get_bool_value(ef: EconfFile, group: str, key: str) -> bool Return a boolean value for given group/key .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBef\fP – Key\-Value storage object .IP \(bu 2 \fBgroup\fP – desired group .IP \(bu 2 \fBkey\fP – key of the value that is requested .UNINDENT .TP .B Returns value of the key .UNINDENT .UNINDENT .SS Functions for getting values with defaults .INDENT 0.0 .TP .B econf.get_int_value_def(ef: EconfFile, group: str, key: str, default: int) -> int Return an integer value for given group/key or return a default value if key is not found .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBef\fP – Key\-Value storage object .IP \(bu 2 \fBgroup\fP – desired group .IP \(bu 2 \fBkey\fP – key of the value that is requested .IP \(bu 2 \fBdefault\fP – value to be returned if no key is found .UNINDENT .TP .B Returns value of the key .UNINDENT .UNINDENT .INDENT 0.0 .TP .B econf.get_uint_value_def(ef: EconfFile, group: str, key: str, default: int) -> int Return an unsigned integer value for given group/key or return a default value if key is not found .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBef\fP – Key\-Value storage object .IP \(bu 2 \fBgroup\fP – desired group .IP \(bu 2 \fBkey\fP – key of the value that is requested .IP \(bu 2 \fBdefault\fP – value to be returned if no key is found .UNINDENT .TP .B Returns value of the key .UNINDENT .UNINDENT .INDENT 0.0 .TP .B econf.get_float_value_def(ef: EconfFile, group: str, key: str, default: float) -> float Return a float value for given group/key or return a default value if key is not found .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBef\fP – Key\-Value storage object .IP \(bu 2 \fBgroup\fP – desired group .IP \(bu 2 \fBkey\fP – key of the value that is requested .IP \(bu 2 \fBdefault\fP – value to be returned if no key is found .UNINDENT .TP .B Returns value of the key .UNINDENT .UNINDENT .INDENT 0.0 .TP .B econf.get_string_value_def(ef: EconfFile, group: str, key: str, default: str) -> str Return a string value for given group/key or return a default value if key is not found .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBef\fP – Key\-Value storage object .IP \(bu 2 \fBgroup\fP – desired group .IP \(bu 2 \fBkey\fP – key of the value that is requested .IP \(bu 2 \fBdefault\fP – value to be returned if no key is found .UNINDENT .TP .B Returns value of the key .UNINDENT .UNINDENT .INDENT 0.0 .TP .B econf.get_bool_value_def(ef: EconfFile, group: str, key: str, default: bool) -> bool Return a boolean value for given group/key or return a default value if key is not found .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBef\fP – Key\-Value storage object .IP \(bu 2 \fBgroup\fP – desired group .IP \(bu 2 \fBkey\fP – key of the value that is requested .IP \(bu 2 \fBdefault\fP – value to be returned if no key is found .UNINDENT .TP .B Returns value of the key .UNINDENT .UNINDENT .SS Functions for setting values .INDENT 0.0 .TP .B econf.set_value(ef: EconfFile, group: str | bytes, key: str | bytes, value: int | float | str | bool) -> None Dynamically set a value in a keyfile and returns a status code .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBef\fP – EconfFile object to set value in .IP \(bu 2 \fBgroup\fP – group of the key to be changed .IP \(bu 2 \fBkey\fP – key to be changed .IP \(bu 2 \fBvalue\fP – desired value .UNINDENT .TP .B Returns Nothing .UNINDENT .UNINDENT .INDENT 0.0 .TP .B econf.set_int_value(ef: EconfFile, group: str, key: str, value: int) -> None Setting an integer value for given group/key .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBef\fP – Key\-Value storage object .IP \(bu 2 \fBgroup\fP – desired group .IP \(bu 2 \fBkey\fP – key of the value that is requested .IP \(bu 2 \fBvalue\fP – value to be set for given key .UNINDENT .TP .B Returns Nothing .UNINDENT .UNINDENT .INDENT 0.0 .TP .B econf.set_uint_value(ef: EconfFile, group: str, key: str, value: int) -> None Setting an unsigned integer value for given group/key .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBef\fP – Key\-Value storage object .IP \(bu 2 \fBgroup\fP – desired group .IP \(bu 2 \fBkey\fP – key of the value that is requested .IP \(bu 2 \fBvalue\fP – value to be set for given key .UNINDENT .TP .B Returns Nothing .UNINDENT .UNINDENT .INDENT 0.0 .TP .B econf.set_float_value(ef: EconfFile, group: str, key: str, value: float) -> None Setting a float value for given group/key .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBef\fP – Key\-Value storage object .IP \(bu 2 \fBgroup\fP – desired group .IP \(bu 2 \fBkey\fP – key of the value that is requested .IP \(bu 2 \fBvalue\fP – value to be set for given key .UNINDENT .TP .B Returns Nothing .UNINDENT .UNINDENT .INDENT 0.0 .TP .B econf.set_string_value(ef: EconfFile, group: str, key: str, value: str | bytes) -> None Setting a string value for given group/key .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBef\fP – Key\-Value storage object .IP \(bu 2 \fBgroup\fP – desired group .IP \(bu 2 \fBkey\fP – key of the value that is requested .IP \(bu 2 \fBvalue\fP – value to be set for given key .UNINDENT .TP .B Returns Nothing .UNINDENT .UNINDENT .INDENT 0.0 .TP .B econf.set_bool_value(ef: EconfFile, group: str, key: str, value: bool) -> None Setting a boolean value for given group/key .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBef\fP – Key\-Value storage object .IP \(bu 2 \fBgroup\fP – desired group .IP \(bu 2 \fBkey\fP – key of the value that is requested .IP \(bu 2 \fBvalue\fP – value to be set for given key .UNINDENT .TP .B Returns Nothing .UNINDENT .UNINDENT .SS Functions for memory management .INDENT 0.0 .TP .B econf.free_file(ef: EconfFile) Free the memory of a given keyfile .sp This function is called automatically at the end of every objects lifetime and should not be used otherwise .INDENT 7.0 .TP .B Parameters \fBef\fP – EconfFile to be freed .TP .B Returns None .UNINDENT .UNINDENT .SS Functions for handling error codes .INDENT 0.0 .TP .B econf.err_string(error: int) -> str Convert an error code into error message .INDENT 7.0 .TP .B Parameters \fBerror\fP – error code as integer .TP .B Returns error string .UNINDENT .UNINDENT .INDENT 0.0 .TP .B econf.err_location() -> Tuple[str, int] Info about the line where an error happened .INDENT 7.0 .TP .B Returns path to the last handled file and number of last handled line .UNINDENT .UNINDENT .SH AUTHOR Nico Krapp .SH COPYRIGHT 2023, Nico Krapp .\" Generated by docutils manpage writer. .