| Name | loadconf JSON |
| Version |
0.0.13
JSON |
| download |
| home_page | |
| Summary | Give users an easy way to define settings and personalize their use of your program. |
| upload_time | 2023-08-24 16:28:26 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | |
| license | GNU General Public License v3 (GPLv3) |
| keywords |
shell
scripting
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# loadconf
Config files make it easy for users to use your program the way they
want to. With loadconf you can easily give users that power.
## Install
The usual way:
`pip install loadconf`
Requires python3
# Usage
I think this module is best explained through example, so here you go!
## user = Config("my_program")
``` python
>>> from loadconf import Config
>>> user = Config("my_program")
>>> user._program
'my_program'
>>> user._platform
'linux' # or macos, or windows
```
To initialize the `Config` object you only need to give the name of your
program, or whatever name you like. As you can see there are some
reserved values after initialization.
## user.define_settings()
``` python
>>> settings = { "fav_color": "Orange", "fav_int": 1, "fav_bool": True }
>>> user.define_settings(settings)
>>> user.settings["fav_color"]
'Orange'
```
Users may not provide all settings that are relevant to your program. If
you want to set some defaults, this makes it easy.
## user.define_files()
``` python
>>> user_files = { "conf": "my_program.conf" }
>>> user.define_files(user_files)
>>> user.files["conf"]
'/home/user/.config/my_program/my_program.conf' # on Linux
'/home/user/Library/Preferences/my_program.conf' # on MacOS
'C:\\Users\\user\\AppData\\Local\\my_program.conf' # on Windows
>>> user.files # on Linux
{'conf': '/home/user/.config/my_program/my_program.conf'}
```
Why you might use this:
- Finds where config files should get installed by default
- Gives a quick way to access a file by it's key
- Allows for access via keys when calling other methods like:
- `create_files()`
- `read_conf()`
- `store_files()`
- `associate_settings()`
- `create_template()`
## user.associate_settings()
``` python
# same settings dict used for user.define_settings()
>>> settings = { "fav_color": "Orange", "fav_int": 1, "fav_bool": True }
>>> user.associate_settings(list(setting.keys()), "conf")
>>> user.settings_files
# Formatted for legibility
{
'conf': {
'fav_bool': True,
'fav_color': 'Orange',
'fav_int': 1
}
}
```
This method is necessary if you plan on using the `create_template()`
method. The purpose is to associate some settings with a particular
file.
**Parameters**:
- settings: List
- file: Str
**settings** should be a list of keys set by `define_settings()`.
**file** should a key for a file set by `define_files()`.
## user.create_files()
``` python
>>> file_list = ["conf", "/path/to/file/to/create.txt"]
>>> user.create_files(file_list)
```
If you've run `user.define_files` then you can pass a key that is
relevant to `user.defined_files`. That will create the file value of
that key. If an item in the given list is not a key then it will get
created if it is an absolute file path.
## user.create_template()
``` python
# same settings dict used for user.define_settings()
>>> settings = { "fav_color": "Orange", "fav_int": 1, "fav_bool": True }
>>> user.create_template(list(settings), "conf")
```
The above fill the the `conf` file like so:
``` conf
fav_color = Orange
fav_int = 1
fav_bool = True
```
This method allows for an easy way to create a default user file with
predefined settings. This method will only create templates for files
created by `create_files()`. The `create_files()` method only creates
files not found when running the program.
## user.read_conf()
Let's assume the config file we are reading looks like this:
``` conf
# my_program.conf
setting_name = setting value
fav_color = Blue
int_val = 10
bool_val = true
good_line = My value with escaped delimiter \= good time
```
To read the file we run this:
``` python
>>> settings = ["fav_color", "good_line", "int_val", "bool_val"]
>>> files = ["conf"]
>>> user.read_conf(settings, files)
>>> user.settings["fav_color"]
'Blue'
>>> user.settings["good_line"]
'My value with escaped delimiter = good time'
>>> user.settings["int_val"]
10
>>> user.settings["bool_val"]
True
```
Things to note:
- `read_conf()` will make effort to determine int and bool values for
settings instead of storing everything as a string.
- If the user has a value that has an unescaped delimiter then
`csv.Error` will get raised with a note about the line number that
caused the error.
- The default delimiter is the equal sign `=` but you can set something
different
- The default comment character is pound `#` but you can set it to
something different
- For users to escape the delimiter character they can use a backslash.
That backslash will not get included in the stored value.
## user.store_files()
``` python
>>> user.store_files({"other": "/path/to/unknown_file.txt"})
>>> user.stored["other"]
['line1', 'line2 with some text', 'line3', 'etc.']
>>> user.store_files(["conf"])
>>> user.stored["conf"]
['conf_line1', 'conf_line2 with some text', 'conf_line3', 'etc.']
```
The purpose of this method is to allow you to store each line of a file
in a list accessible through `user.stored["key"]`. Why might you want
this? Instead of forcing a brittle syntax on the user you can give them
an entire file to work with. If a variable is useful as a list then this
gives users an easy way to define that list.
If you've run `user.define_files()` then you can give
`user.store_files()` a list of keys that correspond to a defined file.
If you haven't defined any files then you can give a dict of files to
store and a key to store them under.
Storing json data can be nice too though:
``` python
>>> user.store_files({"json_file": "/path/to/data.json"}, json_file=True)
>>> user.stored["json_file"]
{'my_json_info': True}
```
Raw data
{
"_id": null,
"home_page": "",
"name": "loadconf",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "shell,scripting",
"author": "",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/96/30/8929a8948a44267537529a5561ed937455e3887bccc2beed34101bdf09d4/loadconf-0.0.13.tar.gz",
"platform": null,
"description": "# loadconf\n\nConfig files make it easy for users to use your program the way they\nwant to. With loadconf you can easily give users that power.\n\n## Install\n\nThe usual way:\n\n`pip install loadconf`\n\nRequires python3\n\n# Usage\n\nI think this module is best explained through example, so here you go!\n\n## user = Config(\"my_program\")\n\n``` python\n>>> from loadconf import Config\n>>> user = Config(\"my_program\")\n>>> user._program\n'my_program'\n>>> user._platform\n'linux' # or macos, or windows\n```\n\nTo initialize the `Config` object you only need to give the name of your\nprogram, or whatever name you like. As you can see there are some\nreserved values after initialization.\n\n## user.define_settings()\n\n``` python\n>>> settings = { \"fav_color\": \"Orange\", \"fav_int\": 1, \"fav_bool\": True }\n>>> user.define_settings(settings)\n>>> user.settings[\"fav_color\"]\n'Orange'\n```\n\nUsers may not provide all settings that are relevant to your program. If\nyou want to set some defaults, this makes it easy.\n\n## user.define_files()\n\n``` python\n>>> user_files = { \"conf\": \"my_program.conf\" }\n>>> user.define_files(user_files)\n>>> user.files[\"conf\"]\n'/home/user/.config/my_program/my_program.conf' # on Linux\n'/home/user/Library/Preferences/my_program.conf' # on MacOS\n'C:\\\\Users\\\\user\\\\AppData\\\\Local\\\\my_program.conf' # on Windows\n>>> user.files # on Linux\n{'conf': '/home/user/.config/my_program/my_program.conf'}\n```\n\nWhy you might use this:\n\n- Finds where config files should get installed by default\n- Gives a quick way to access a file by it's key\n- Allows for access via keys when calling other methods like:\n - `create_files()`\n - `read_conf()`\n - `store_files()`\n - `associate_settings()`\n - `create_template()`\n\n## user.associate_settings()\n\n``` python\n# same settings dict used for user.define_settings()\n>>> settings = { \"fav_color\": \"Orange\", \"fav_int\": 1, \"fav_bool\": True }\n>>> user.associate_settings(list(setting.keys()), \"conf\")\n>>> user.settings_files\n# Formatted for legibility\n{\n 'conf': {\n 'fav_bool': True,\n 'fav_color': 'Orange',\n 'fav_int': 1\n }\n}\n```\n\nThis method is necessary if you plan on using the `create_template()`\nmethod. The purpose is to associate some settings with a particular\nfile.\n\n**Parameters**:\n\n- settings: List\n- file: Str\n\n**settings** should be a list of keys set by `define_settings()`.\n**file** should a key for a file set by `define_files()`.\n\n## user.create_files()\n\n``` python\n>>> file_list = [\"conf\", \"/path/to/file/to/create.txt\"]\n>>> user.create_files(file_list)\n```\n\nIf you've run `user.define_files` then you can pass a key that is\nrelevant to `user.defined_files`. That will create the file value of\nthat key. If an item in the given list is not a key then it will get\ncreated if it is an absolute file path.\n\n## user.create_template()\n\n``` python\n# same settings dict used for user.define_settings()\n>>> settings = { \"fav_color\": \"Orange\", \"fav_int\": 1, \"fav_bool\": True }\n>>> user.create_template(list(settings), \"conf\")\n```\n\nThe above fill the the `conf` file like so:\n\n``` conf\nfav_color = Orange\nfav_int = 1\nfav_bool = True\n```\n\nThis method allows for an easy way to create a default user file with\npredefined settings. This method will only create templates for files\ncreated by `create_files()`. The `create_files()` method only creates\nfiles not found when running the program.\n\n## user.read_conf()\n\nLet's assume the config file we are reading looks like this:\n\n``` conf\n# my_program.conf\nsetting_name = setting value\nfav_color = Blue\nint_val = 10\nbool_val = true\ngood_line = My value with escaped delimiter \\= good time\n```\n\nTo read the file we run this:\n\n``` python\n>>> settings = [\"fav_color\", \"good_line\", \"int_val\", \"bool_val\"]\n>>> files = [\"conf\"]\n>>> user.read_conf(settings, files)\n>>> user.settings[\"fav_color\"]\n'Blue'\n>>> user.settings[\"good_line\"]\n'My value with escaped delimiter = good time'\n>>> user.settings[\"int_val\"]\n10\n>>> user.settings[\"bool_val\"]\nTrue\n```\n\nThings to note:\n\n- `read_conf()` will make effort to determine int and bool values for\n settings instead of storing everything as a string.\n- If the user has a value that has an unescaped delimiter then\n `csv.Error` will get raised with a note about the line number that\n caused the error.\n- The default delimiter is the equal sign `=` but you can set something\n different\n- The default comment character is pound `#` but you can set it to\n something different\n- For users to escape the delimiter character they can use a backslash.\n That backslash will not get included in the stored value.\n\n## user.store_files()\n\n``` python\n>>> user.store_files({\"other\": \"/path/to/unknown_file.txt\"})\n>>> user.stored[\"other\"]\n['line1', 'line2 with some text', 'line3', 'etc.']\n>>> user.store_files([\"conf\"])\n>>> user.stored[\"conf\"]\n['conf_line1', 'conf_line2 with some text', 'conf_line3', 'etc.']\n```\n\nThe purpose of this method is to allow you to store each line of a file\nin a list accessible through `user.stored[\"key\"]`. Why might you want\nthis? Instead of forcing a brittle syntax on the user you can give them\nan entire file to work with. If a variable is useful as a list then this\ngives users an easy way to define that list.\n\nIf you've run `user.define_files()` then you can give\n`user.store_files()` a list of keys that correspond to a defined file.\nIf you haven't defined any files then you can give a dict of files to\nstore and a key to store them under.\n\nStoring json data can be nice too though:\n\n``` python\n>>> user.store_files({\"json_file\": \"/path/to/data.json\"}, json_file=True)\n>>> user.stored[\"json_file\"]\n{'my_json_info': True}\n```\n",
"bugtrack_url": null,
"license": "GNU General Public License v3 (GPLv3)",
"summary": "Give users an easy way to define settings and personalize their use of your program.",
"version": "0.0.13",
"project_urls": {
"repository": "https://codeberg.org/johndovern/loadconf"
},
"split_keywords": [
"shell",
"scripting"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "aa6266950267a2acd6ce1cf36a0f72035d05a3ab6decd6610ca077ac4e711639",
"md5": "9ee3b8509d0ba2103b655c5b37379b5d",
"sha256": "2620a46f40904b50dec74529efe1f6c959fe2483102b1e64c6c06328ef0815c2"
},
"downloads": -1,
"filename": "loadconf-0.0.13-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9ee3b8509d0ba2103b655c5b37379b5d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 18946,
"upload_time": "2023-08-24T16:28:25",
"upload_time_iso_8601": "2023-08-24T16:28:25.022750Z",
"url": "https://files.pythonhosted.org/packages/aa/62/66950267a2acd6ce1cf36a0f72035d05a3ab6decd6610ca077ac4e711639/loadconf-0.0.13-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "96308929a8948a44267537529a5561ed937455e3887bccc2beed34101bdf09d4",
"md5": "9ba9e7768bb5f46b15ba61541fc87439",
"sha256": "d8c4bcb92f2bb335caf770f2c909b6292665f28898094ae6d5ee90a3af5bc4ee"
},
"downloads": -1,
"filename": "loadconf-0.0.13.tar.gz",
"has_sig": false,
"md5_digest": "9ba9e7768bb5f46b15ba61541fc87439",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 18085,
"upload_time": "2023-08-24T16:28:26",
"upload_time_iso_8601": "2023-08-24T16:28:26.232085Z",
"url": "https://files.pythonhosted.org/packages/96/30/8929a8948a44267537529a5561ed937455e3887bccc2beed34101bdf09d4/loadconf-0.0.13.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-08-24 16:28:26",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": true,
"codeberg_user": "johndovern",
"codeberg_project": "loadconf",
"lcname": "loadconf"
}
