| Name | object-settings JSON |
| Version |
4.4
JSON |
| download |
| home_page | |
| Summary | Simple object-oriented config library, where your settings are objects |
| upload_time | 2023-10-30 17:47:52 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | |
| license | MIT License |
| keywords |
settings
setting
config
oop
gui
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
object-settings
===============
Simple-to-use object-oriented Python config library, where your settings are objects.
Their values have automatic validation and get saved to a file that's seamlessly written and read in the background, so you don't have to worry about any of it. This makes it quick to define and use settings (see examples below).
## Installation & usage
This package is on PyPi, so you can just do `pip install object-settings`
After which it will be available with just the module name `settings`
```python
import settings
settings.setup("Your app name")
your_option1 = settings.Toggle("Your first option label")
your_option2 = settings.Number("Your second option label")
```
## Just simple objects
For example, you can set a font size at the top of your ui file:
```python
font = settings.Number(default=14)
...
someuilib.Label("Bababooey", size=font.value)
...
someuilib.Textbox("Lorem ipsum dolor...", font_size=font.value)
...
```
Or if a setting is only checked in one place, it can be used without defining a variable:
```python
if settings.Toggle("Update app automatically", default=True):
# do update
```
(it doesn't matter if the same setting is initialized multiple times)
## Integration
The setting objects support "equals"-checking with actual values:
```python
speed = settings.Number("Speed limit", 5)
print(speed == 5)
>> True
print(speed == 3)
>> False
```
In addition, they work with many type-specific operations:
```python
for selection in settings.Multichoice():
...
if settings.Toggle():
...
```
## Automatic storing
When a setting's value is read/set, object-settings automatically creates and updates a config file on the disk in the background. It can read many file types, like `.cfg`, `.json` and `.yaml`. Any file deletions or unparsable external modifications are also handled.
By default, the files are saved to a standard config location, depending on the platform (uses [appdirs](https://github.com/ActiveState/appdirs) package for paths). You can also set a custom directory for e.g. running in a Docker container.
Setting values are also automatically read from the environment, like from env vars or command line options. The under-the-hood parser system is also very extensible, so you can create and add custom ones for e.g. a custom database.
## Value validation
When a new value is set, it automatically gets validated and raises a `ValueError` if it doesn't pass:
```python
update_interval = settings.Number("Update interval", default=5)
update_interval.set("Daily")
>> ValueError
```
This validation includes more than just datatypes, for example numbers can have min/max limits, or a path setting can be set to require an existing path:
```python
path = settings.Path("Download path", has_to_exist=True)
path.set("/nonexistent/directory")
>> ValueError
```
## Listen for changes
If you have some update function that you want to be called when a setting is changed, you can add that function as a listener:
```python
some_setting.add_listener(your_function)
```
Now the function will be called every time when a new value is set.
## Sections
Optionally, if you have a lot of settings, you can organize them into sections (which also works well with UIs):
```python
download_options = settings.Section("Downloader settings")
speed = settings.Number("Speed limit", 5, section=download_options)
dir = settings.Path("Target directory", '/home/yomama/Downloads', section=download_options)
server = settings.Choice("Mirror", ["Europe", "Asia", "America", "Africa"], "Asia", section=download_options)
```
## Did I mention free GUIs?
That's right, this library also includes a separate `settings_gui` package that has pre-made settings menus for various GUI toolkits. They have full integration with the aforementioned systems, like validation and sections.
Here's an example of some dummy settings with both libraries:
*(notice the warning for the misspelt download path)*
*Nice-looking ttk (theme: Sun Valley dark)*
*Bare tkinter works too*
`settings_gui` has subpackages for tkinter and ttk, with at least GTK coming in the future.
You can import the subpackage for your toolkit and then use a frame or a full settings window.
Example with tkinter:
```python
import tkinter, settings, settings_gui.tkinter
settings.setup("Crazy app")
settings.Toggle("I'm graphical baby!", True)
root = tkinter.Tk()
settings_gui.tkinter.SettingsWindow(root)
root.mainloop()
```
You can also configure some parameters for the gui package to make it fit in:
- Change options like widget padding by calling `settings_gui.config.config()`
- Change the strings the widgets use (save button, file chooser, ...) by calling `settings_gui.config.strings()`
Or, if you want to get more custom/contextual, you can also use the individual setting widgets and place them around your app (submodule `type_frames`).
## All setting types
List of currently available setting types:
- `Toggle`:
A boolean True/False
- `Choice`:
Choose an option (str) from a list
- `MappedChoice`:
Choose an option (str) from a list, but have a different internal value mapped to it
- `Multichoice`:
Choose multiple options (str) from a list
- `MappedMultichoice`:
Choose multiple options (str) from a list, but have different internal values mapped to them
- `Array`:
An iterable of any arbitrary strings
- `Text`:
Just a basic text value
- `Path`:
A file path whose existence can be checked
- `Number`:
An integer that can be set or incremented and decremented
- `Float`:
Like Number but, you know, as a float (with adjustable decimal precision)
You can also inherit from the `BaseSetting` class to easily create custom ones.
Raw data
{
"_id": null,
"home_page": "",
"name": "object-settings",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "settings,setting,config,OOP,GUI",
"author": "",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/b4/9d/7548beb6fbe7307068b88ce813823eaba8f03be87158c19f19da7517f6b2/object-settings-4.4.tar.gz",
"platform": null,
"description": "\nobject-settings\n===============\n\nSimple-to-use object-oriented Python config library, where your settings are objects.\n\nTheir values have automatic validation and get saved to a file that's seamlessly written and read in the background, so you don't have to worry about any of it. This makes it quick to define and use settings (see examples below).\n\n\n\n## Installation & usage\n\nThis package is on PyPi, so you can just do `pip install object-settings`\n\nAfter which it will be available with just the module name `settings`\n\n```python\nimport settings\nsettings.setup(\"Your app name\")\n \nyour_option1 = settings.Toggle(\"Your first option label\")\nyour_option2 = settings.Number(\"Your second option label\")\n```\n\n\n\n## Just simple objects\n\nFor example, you can set a font size at the top of your ui file:\n\n```python\nfont = settings.Number(default=14)\n\n...\nsomeuilib.Label(\"Bababooey\", size=font.value)\n...\nsomeuilib.Textbox(\"Lorem ipsum dolor...\", font_size=font.value)\n...\n```\n\nOr if a setting is only checked in one place, it can be used without defining a variable:\n\n```python\nif settings.Toggle(\"Update app automatically\", default=True):\n # do update\n```\n\n(it doesn't matter if the same setting is initialized multiple times)\n\n\n\n## Integration\n\nThe setting objects support \"equals\"-checking with actual values:\n\n```python\nspeed = settings.Number(\"Speed limit\", 5)\n\nprint(speed == 5)\n>> True\nprint(speed == 3)\n>> False\n```\n\nIn addition, they work with many type-specific operations:\n\n```python\nfor selection in settings.Multichoice():\n ...\n\nif settings.Toggle():\n ...\n```\n\n\n\n## Automatic storing\n\nWhen a setting's value is read/set, object-settings automatically creates and updates a config file on the disk in the background. It can read many file types, like `.cfg`, `.json` and `.yaml`. Any file deletions or unparsable external modifications are also handled.\n\nBy default, the files are saved to a standard config location, depending on the platform (uses [appdirs](https://github.com/ActiveState/appdirs) package for paths). You can also set a custom directory for e.g. running in a Docker container.\n\nSetting values are also automatically read from the environment, like from env vars or command line options. The under-the-hood parser system is also very extensible, so you can create and add custom ones for e.g. a custom database.\n\n\n\n## Value validation\n\nWhen a new value is set, it automatically gets validated and raises a `ValueError` if it doesn't pass:\n\n```python\nupdate_interval = settings.Number(\"Update interval\", default=5)\nupdate_interval.set(\"Daily\")\n>> ValueError\n```\n\nThis validation includes more than just datatypes, for example numbers can have min/max limits, or a path setting can be set to require an existing path:\n\n```python\npath = settings.Path(\"Download path\", has_to_exist=True)\npath.set(\"/nonexistent/directory\")\n>> ValueError\n```\n\n\n\n## Listen for changes\n\nIf you have some update function that you want to be called when a setting is changed, you can add that function as a listener:\n\n```python\nsome_setting.add_listener(your_function)\n```\n\nNow the function will be called every time when a new value is set.\n\n\n\n## Sections\n\nOptionally, if you have a lot of settings, you can organize them into sections (which also works well with UIs):\n\n```python\ndownload_options = settings.Section(\"Downloader settings\")\nspeed = settings.Number(\"Speed limit\", 5, section=download_options)\ndir = settings.Path(\"Target directory\", '/home/yomama/Downloads', section=download_options)\nserver = settings.Choice(\"Mirror\", [\"Europe\", \"Asia\", \"America\", \"Africa\"], \"Asia\", section=download_options)\n```\n\n\n\n## Did I mention free GUIs?\n\nThat's right, this library also includes a separate `settings_gui` package that has pre-made settings menus for various GUI toolkits. They have full integration with the aforementioned systems, like validation and sections.\n\nHere's an example of some dummy settings with both libraries: \n\n*(notice the warning for the misspelt download path)*\n\n\n*Nice-looking ttk (theme: Sun Valley dark)*\n\n\n*Bare tkinter works too*\n\n\n`settings_gui` has subpackages for tkinter and ttk, with at least GTK coming in the future.\n\nYou can import the subpackage for your toolkit and then use a frame or a full settings window.\n\nExample with tkinter:\n```python\nimport tkinter, settings, settings_gui.tkinter\n\nsettings.setup(\"Crazy app\")\nsettings.Toggle(\"I'm graphical baby!\", True)\n\nroot = tkinter.Tk()\nsettings_gui.tkinter.SettingsWindow(root)\nroot.mainloop()\n```\n\nYou can also configure some parameters for the gui package to make it fit in:\n- Change options like widget padding by calling `settings_gui.config.config()`\n- Change the strings the widgets use (save button, file chooser, ...) by calling `settings_gui.config.strings()`\n\n\nOr, if you want to get more custom/contextual, you can also use the individual setting widgets and place them around your app (submodule `type_frames`).\n\n\n\n## All setting types\n\nList of currently available setting types:\n\n- `Toggle`:\n A boolean True/False\n- `Choice`:\n Choose an option (str) from a list\n- `MappedChoice`:\n Choose an option (str) from a list, but have a different internal value mapped to it\n- `Multichoice`:\n Choose multiple options (str) from a list\n- `MappedMultichoice`:\n Choose multiple options (str) from a list, but have different internal values mapped to them\n- `Array`:\n An iterable of any arbitrary strings\n- `Text`:\n Just a basic text value\n- `Path`:\n A file path whose existence can be checked\n- `Number`:\n An integer that can be set or incremented and decremented\n- `Float`:\n Like Number but, you know, as a float (with adjustable decimal precision)\n\nYou can also inherit from the `BaseSetting` class to easily create custom ones.\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "Simple object-oriented config library, where your settings are objects",
"version": "4.4",
"project_urls": {
"Homepage": "https://github.com/SamuLumio/object-settings"
},
"split_keywords": [
"settings",
"setting",
"config",
"oop",
"gui"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e2bba00de143d912beeaf88ae99518b3b7f460bd06fd362480fac8e656dc5063",
"md5": "4c4afd017e05428645ea30bf1d95fc43",
"sha256": "ddcef95a9bce16bd1f88570f26c54b80a18d253764b2f0ef69ebd469cd9131dc"
},
"downloads": -1,
"filename": "object_settings-4.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4c4afd017e05428645ea30bf1d95fc43",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 27468,
"upload_time": "2023-10-30T17:47:50",
"upload_time_iso_8601": "2023-10-30T17:47:50.047264Z",
"url": "https://files.pythonhosted.org/packages/e2/bb/a00de143d912beeaf88ae99518b3b7f460bd06fd362480fac8e656dc5063/object_settings-4.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b49d7548beb6fbe7307068b88ce813823eaba8f03be87158c19f19da7517f6b2",
"md5": "257e5e2f8da9c9fd30414f7e957dd36b",
"sha256": "81b9f8bd10cf9ec6c89a9f54fb2e7707f0df1349270f17a9aaa628061af7af2e"
},
"downloads": -1,
"filename": "object-settings-4.4.tar.gz",
"has_sig": false,
"md5_digest": "257e5e2f8da9c9fd30414f7e957dd36b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 25131,
"upload_time": "2023-10-30T17:47:52",
"upload_time_iso_8601": "2023-10-30T17:47:52.096375Z",
"url": "https://files.pythonhosted.org/packages/b4/9d/7548beb6fbe7307068b88ce813823eaba8f03be87158c19f19da7517f6b2/object-settings-4.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-30 17:47:52",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "SamuLumio",
"github_project": "object-settings",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "object-settings"
}
