# config_tpg
## Table of Contents
- [Overview](#overview)
- [Project Structure](#project-structure)
- [Setup](#setup)
- [Implementation](#implementation)
- <a href="https://gitlab.com/tpgllc/config_tpg/-/blob/main/doc/customizing.md" target="_blank">Customization</a>
## Overview
Provide a configuration namespace module from a configuration file. The config module can be imported into each python program which permits the passing of varibles between programs. The variables can be references as `cfg.varname`. Reading and writing of the config file is based upon the standard library configparser module.
Examples to list the variables in the cfg madule and demostrate referencing the variables in an application follow:
myapp.py
```
from src import config as cfg
print(cfg.myvariable)
```
or to list config file variables:
```
from src import config as cfg
for s, v in cfg.cfg_values.items():
print(f"{s}: {v}")
for var in v:
print(f" {var[0]}: {getattr(cfg, var[0])}")
```
### Features
* Allow values to be changed in a config file and passed into the system - no changing of source code
* Manage the config file, reading parameters into the application, creating the initial file with defaults, updating existing config file if parameters are added or names change in the config module. Pre-defined comments and config file values are preserved.
* Creates a config module that can be used to pass paramters to other modules. The values in this module are updated by the values in the config file and can be modified by the application.
* Internal objects can be added to the config module and passed to each module in application.
### Requirements
This module requires python 3.10 due to use of case statement. The case statement can be changed to if/else structure.
Standard Python packages are utilized and no special packages are needed.
## Project structure
The default implementation assumes the following project structure ***(but this can be altered, see customization)***:
```
proj_name/
data/
src/
config.py
configparms_ext.py (if used)
proj_main.py
```
If you have a different project structure, then the configparms_ext.py method ```set_directrories``` can be modified to set the path to the data folder and src folder of your project.
## Setup
1. Install the package in your environment:
```pip install config_tpg```
1. Change directories to your src folder:
```cd src```
1. Copy the config file into the current directory:
```config_tpg-init```
This command copies two file into the current directory: config.py and configparms_ext.py
If you do not need to modify the paths, then configparms_ext.py can be deleted.
Rerunning ```config_tpg-init``` will not overwrite existing files.
1. Modify the config file to meet your application needs. Be sure to change the value of the variable *cfg_flnm* to the name of your config file.
1. In each module, add the import for the config. This should be the first application import, after the standard python module imports,
```
import os
import sys
from src import config as cfg
from src import myapp
```
1. In ```config.py``` set the autorun flag or call the run method `cfg.run()` in your application. See the comments at the bottom of the config file.
1. The first time you run a program with the config import, it will look for a config file in the data directory and if does not exist, it will create one.
All set!
## Implementation
In each of your application programs, the ```src.config``` module should be imported as the first application import in each application module.
*`import src.config as cfg`*
The first import reads the config file (`data/xxxxx.cfg`) and loads the runtime values. If the cfg file, as named in the variable *cfg.cfg_flnm*, does not exist, it is created with the default values.
The config module creates a module as a namespace so variables can be referenced as cfg.var. Each variable is defined with its default value in the namespace, unless overridden by the config file. A config file, *`xxxxx.cfg`* is created on the first import of config if it does not exist, where *xxxxx* is name as set in the variable `cfg.cfg_flnm`.
Any changes to the cfg file in the data folder are local and override the defaults.
If a new variable is added in the *`src.config`* module or if the variable name changes in the config module, then the version number should be updated in the config module (not the config file). When the cfg module version and the config file version differ, a rewrite the local cfg file with the new variable, perserving any values set in the file, will be triggered.
### Modifying config.py ###
Two programs from this repo are provided for use by your application:
* scr/config.py
* src/configparms_ext.py (optional for customization)
#### config.py
It is intended for the *`config.py`* file to be modified for the application. Parameters unique to the application are defined with their defaults. Replace the *var1-3* and *m1-2* variables with the variables needed by the application. Also set the cfg filename (*cfg_flnm*).
The *`sys_cfg_version`* variable must not be deleted, it will be updated as new parameters are added to the config file and the change in this value triggers the rewrite of the file.
##### Variables
The *`cfg_values`* is a dictionary that defines the sections and variables to be written to the config file. The key to the dictionary is the section and the value is a list of lists with variable name and variable type (see sample in config.py).
Be sure all variables to be in the config file are defined in the *`cfg_values`* variable.
Valid types supported are
- integer
- float
- boolean
- string
- list
##### Comments
The variable *`cfg_comments`* contains any comment to be written to the config file to explain a variable or section.
Section comments are written after the section label and variable comments are written before the variable in the config file.
The *`cfg_comments`* variable is a dictionary and the key is the variable or section name and the value is a list with each item in the list being written as a seperate comment line.
#### configparms_ext.py
To override setting of path variables, the *configparm_ext.py* module is provided.
Modify the method *`set_directories`* to support the structure of your project.
See the customization doc to modidify standard processing.
### Summary of set up ###
* Install the package
* Run config_tpg-init to extract the src/config.py and configparms_ext.py and place in your project src file
* Modify these modules for your application (set the config file name and variables)
* import the module into your application
Raw data
{
"_id": null,
"home_page": null,
"name": "config-tpg",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "config, config file, config module, config generator, application config, application config file, app config, app config file, tpg",
"author": null,
"author_email": "Criss Swaim <cswaim@tpginc.net>",
"download_url": "https://files.pythonhosted.org/packages/f9/79/f8a27d2c28c4a4642bdbd8c77cea359fc6a8e981aed21ca4db692ddbee63/config_tpg-0.1.1.tar.gz",
"platform": null,
"description": "# config_tpg\r\n\r\n## Table of Contents\r\n- [Overview](#overview)\r\n- [Project Structure](#project-structure)\r\n- [Setup](#setup)\r\n- [Implementation](#implementation)\r\n - <a href=\"https://gitlab.com/tpgllc/config_tpg/-/blob/main/doc/customizing.md\" target=\"_blank\">Customization</a>\r\n\r\n## Overview\r\n\r\nProvide a configuration namespace module from a configuration file. The config module can be imported into each python program which permits the passing of varibles between programs. The variables can be references as `cfg.varname`. Reading and writing of the config file is based upon the standard library configparser module.\r\n\r\nExamples to list the variables in the cfg madule and demostrate referencing the variables in an application follow:\r\n\r\nmyapp.py\r\n```\r\n from src import config as cfg\r\n print(cfg.myvariable)\r\n``` \r\nor to list config file variables:\r\n```\r\n from src import config as cfg\r\n for s, v in cfg.cfg_values.items():\r\n print(f\"{s}: {v}\")\r\n for var in v:\r\n print(f\" {var[0]}: {getattr(cfg, var[0])}\")\r\n```\r\n\r\n### Features\r\n\r\n* Allow values to be changed in a config file and passed into the system - no changing of source code\r\n* Manage the config file, reading parameters into the application, creating the initial file with defaults, updating existing config file if parameters are added or names change in the config module. Pre-defined comments and config file values are preserved.\r\n* Creates a config module that can be used to pass paramters to other modules. The values in this module are updated by the values in the config file and can be modified by the application.\r\n* Internal objects can be added to the config module and passed to each module in application.\r\n\r\n### Requirements\r\n\r\nThis module requires python 3.10 due to use of case statement. The case statement can be changed to if/else structure.\r\n\r\nStandard Python packages are utilized and no special packages are needed.\r\n\r\n## Project structure\r\n\r\nThe default implementation assumes the following project structure ***(but this can be altered, see customization)***:\r\n\r\n```\r\nproj_name/\r\n data/\r\n src/\r\n config.py\r\n configparms_ext.py (if used)\r\n proj_main.py\r\n```\r\n\r\nIf you have a different project structure, then the configparms_ext.py method ```set_directrories``` can be modified to set the path to the data folder and src folder of your project. \r\n\r\n## Setup\r\n\r\n1. Install the package in your environment:\r\n\r\n ```pip install config_tpg```\r\n\r\n1. Change directories to your src folder:\r\n\r\n ```cd src```\r\n\r\n1. Copy the config file into the current directory:\r\n\r\n ```config_tpg-init```\r\n \r\n This command copies two file into the current directory: config.py and configparms_ext.py\r\n\r\n If you do not need to modify the paths, then configparms_ext.py can be deleted. \r\n\r\n Rerunning ```config_tpg-init``` will not overwrite existing files.\r\n\r\n1. Modify the config file to meet your application needs. Be sure to change the value of the variable *cfg_flnm* to the name of your config file.\r\n\r\n1. In each module, add the import for the config. This should be the first application import, after the standard python module imports, \r\n ```\r\n import os\r\n import sys\r\n from src import config as cfg\r\n from src import myapp\r\n ```\r\n1. In ```config.py``` set the autorun flag or call the run method `cfg.run()` in your application. See the comments at the bottom of the config file.\r\n\r\n1. The first time you run a program with the config import, it will look for a config file in the data directory and if does not exist, it will create one.\r\n\r\nAll set!\r\n\r\n\r\n## Implementation\r\n\r\nIn each of your application programs, the ```src.config``` module should be imported as the first application import in each application module.\r\n\r\n*`import src.config as cfg`*\r\n\r\nThe first import reads the config file (`data/xxxxx.cfg`) and loads the runtime values. If the cfg file, as named in the variable *cfg.cfg_flnm*, does not exist, it is created with the default values.\r\n\r\nThe config module creates a module as a namespace so variables can be referenced as cfg.var. Each variable is defined with its default value in the namespace, unless overridden by the config file. A config file, *`xxxxx.cfg`* is created on the first import of config if it does not exist, where *xxxxx* is name as set in the variable `cfg.cfg_flnm`.\r\n\r\nAny changes to the cfg file in the data folder are local and override the defaults.\r\n\r\nIf a new variable is added in the *`src.config`* module or if the variable name changes in the config module, then the version number should be updated in the config module (not the config file). When the cfg module version and the config file version differ, a rewrite the local cfg file with the new variable, perserving any values set in the file, will be triggered.\r\n\r\n### Modifying config.py ###\r\n\r\nTwo programs from this repo are provided for use by your application:\r\n* scr/config.py\r\n* src/configparms_ext.py (optional for customization)\r\n\r\n#### config.py\r\n\r\nIt is intended for the *`config.py`* file to be modified for the application. Parameters unique to the application are defined with their defaults. Replace the *var1-3* and *m1-2* variables with the variables needed by the application. Also set the cfg filename (*cfg_flnm*).\r\n\r\nThe *`sys_cfg_version`* variable must not be deleted, it will be updated as new parameters are added to the config file and the change in this value triggers the rewrite of the file.\r\n\r\n##### Variables\r\n\r\nThe *`cfg_values`* is a dictionary that defines the sections and variables to be written to the config file. The key to the dictionary is the section and the value is a list of lists with variable name and variable type (see sample in config.py).\r\n\r\nBe sure all variables to be in the config file are defined in the *`cfg_values`* variable.\r\n\r\nValid types supported are \r\n- integer\r\n- float\r\n- boolean\r\n- string\r\n- list\r\n\r\n##### Comments \r\n\r\nThe variable *`cfg_comments`* contains any comment to be written to the config file to explain a variable or section.\r\n\r\nSection comments are written after the section label and variable comments are written before the variable in the config file.\r\n\r\nThe *`cfg_comments`* variable is a dictionary and the key is the variable or section name and the value is a list with each item in the list being written as a seperate comment line.\r\n\r\n#### configparms_ext.py\r\n\r\nTo override setting of path variables, the *configparm_ext.py* module is provided.\r\n\r\nModify the method *`set_directories`* to support the structure of your project.\r\n\r\nSee the customization doc to modidify standard processing.\r\n\r\n### Summary of set up ###\r\n* Install the package\r\n* Run config_tpg-init to extract the src/config.py and configparms_ext.py and place in your project src file\r\n* Modify these modules for your application (set the config file name and variables)\r\n* import the module into your application\r\n \r\n\r\n\r\n",
"bugtrack_url": null,
"license": null,
"summary": "Read a config file and create a config module which can be passed throughout an application. Reading and writing of the config file are based on configparser.",
"version": "0.1.1",
"project_urls": {
"Changelog": "https://gitlab.com/tpgllc/config_tpg/-/blob/main/doc/changelog.md",
"Customization": "https://gitlab.com/tpgllc/config_tpg/-/blob/main/doc/customizing.md",
"Issues": "https://gitlab.com/tpgllc/config_tpg/issues",
"Repository": "https://gitlab.com/tpgllc/config_tpg"
},
"split_keywords": [
"config",
" config file",
" config module",
" config generator",
" application config",
" application config file",
" app config",
" app config file",
" tpg"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d670fe6ba89a5d8c013fc809e6cd8a2e7b480ce519f1144667982080775e5c7e",
"md5": "1d60174cbe28619612a5ea16b225eed9",
"sha256": "f913f5c19ddbf92ee1cad654f0e6397a351a5e9457a4c7f2abf694e902900e6b"
},
"downloads": -1,
"filename": "config_tpg-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1d60174cbe28619612a5ea16b225eed9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 16157,
"upload_time": "2025-01-07T21:49:16",
"upload_time_iso_8601": "2025-01-07T21:49:16.363216Z",
"url": "https://files.pythonhosted.org/packages/d6/70/fe6ba89a5d8c013fc809e6cd8a2e7b480ce519f1144667982080775e5c7e/config_tpg-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f979f8a27d2c28c4a4642bdbd8c77cea359fc6a8e981aed21ca4db692ddbee63",
"md5": "519b382853c53ce3e029d778fee40a35",
"sha256": "27f3865098d27205c4271cae60f306be621f3f9bbd2a1a13b2e2bc37f832d80d"
},
"downloads": -1,
"filename": "config_tpg-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "519b382853c53ce3e029d778fee40a35",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 27581,
"upload_time": "2025-01-07T21:49:18",
"upload_time_iso_8601": "2025-01-07T21:49:18.539810Z",
"url": "https://files.pythonhosted.org/packages/f9/79/f8a27d2c28c4a4642bdbd8c77cea359fc6a8e981aed21ca4db692ddbee63/config_tpg-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-07 21:49:18",
"github": false,
"gitlab": true,
"bitbucket": false,
"codeberg": false,
"gitlab_user": "tpgllc",
"gitlab_project": "config_tpg",
"lcname": "config-tpg"
}
JSON