You must include at least one section header in your settings.ini file
(like ``[default]``). The configparser will raise a
MissingSectionHeaderError if no headers are defined.
If you have any additional section headers, each parsed section will
only contain things defined in that section, plus anything defined in
the special/optional ``[default]`` section.
The values of any variable names in any sections can be overwritten by
the value set for an environment variable of the same name (or it’s
ALLCAPS name).
Any variables that have multiple values separated by a comma will be
converted to a list.
The parsed values will be converted to their basic types (int, float,
None, bool, str) via the ``from_string`` or ``string_to_converted_list``
functions from `input-helper <https://pypi.org/project/input-helper>`__
for easy use.
You can comment out any variables in the settings.ini file with a
leading ``#``.
Setup for a one-off script
--------------------------
Create a ``settings.ini`` file next to your script with at least one
section header in square brackets (like ``[my stuff]``).
::
[my stuff]
something = 100
things = none, true, false, 1, 2.5, dogs and cats, grapes
# other = 500
Use the simple ``get_all_settings`` function to get a dict of all
settings by section header.
::
import settings_helper as sh
settings = sh.get_all_settings()
For our settings.ini file example, the settings dict from
``get_all_settings()`` would be the following:
::
{
'my stuff': {
'something': 100,
'things': [None, True, False, 1, 2.5, 'dogs and cats', 'grapes']
}
}
When dealing with settings where values are numbers, but you don’t want
them converted (i.e. version numbers like “3.10”), you can set kwarg
``keep_num_as_string`` to ``True`` when calling ``get_all_settings`` (or
``settings_getter``).
::
import settings_helper as sh
settings = sh.get_all_settings(keep_num_as_string=True)
For our settings.ini file example, the settings dict from
``get_all_settings(keep_num_as_string=True)`` would be the following:
::
{
'my stuff': {
'something': '100',
'things': [None, True, False, '1', '2.5', 'dogs and cats', 'grapes']
}
}
Setup in your package
---------------------
Create a default/sample ``settings.ini`` file in the module directory of
your package, with a ``[default]`` section and any other ``[sections]``
you want (i.e. app environments)
::
[default]
something = 100
[dev]
redis_url = redis://localhost:6379/1
something = 500
[test]
redis_url = redis://localhost:6379/9
things = none, true, false, 1, 2.5, dogs
For this settings.ini file example, the settings dict from
``get_all_settings()`` would be the following:
::
{
'dev': {
'something': 500,
'redis_url': 'redis://localhost:6379/1'
},
'default': {
'something': 100
},
'test': {
'something': 100,
'redis_url': 'redis://localhost:6379/9',
'things': [None, True, False, 1, 2.5, 'dogs']
}
}
Create a ``MANIFEST.in`` file in your package directory with the
following
::
include settings.ini
Update the ``setup.py`` file of the package to include the
``setting.ini`` file and add ``settings-helper`` to ``install_requires``
list
::
from setuptools import setup, find_packages
setup(
name='package-name',
version='0.0.1',
...
packages=find_packages(),
install_requires=[
'settings-helper',
...
],
include_package_data=True,
package_dir={'': '.'},
package_data={
'': ['*.ini'],
},
...
)
Note, your package directory tree will be something like the following
::
package-name
├── .gitignore
├── LICENSE.txt
├── MANIFEST.in
├── README.md
├── README.rst
├── package_name/
│ ├── __init__.py
│ └── settings.ini
└── setup.py
Usage
-----
Use in ``__init__.py`` of package
::
import settings_helper as sh
get_setting = sh.settings_getter(__name__)
something = get_setting('something')
something_else = get_setting('something_else', 'default_val')
Set ``APP_ENV`` environment variable to be one of your section names
when starting your Python interpreter/server. **``APP_ENV`` defaults to
``dev`` if it is not set.**
- The ``get_setting`` func will return the value of the requested
variable if it is set in the section specified in ``APP_ENV``.
- If the variable is not in the section, it will pull the value from
the ``[default]`` section
- If the varialbe is not in the ``[default]`` section either, then
return the optional fallback value passed in the ``default`` keyword
argument to ``get_setting`` (which defaults to an empty string)
- **If the requested variable exists in the environment (or its
uppercase equivalent), it will be used instead of getting from
settings.ini**
- The value is automatically converted to a bool, None, int, or float
if it should be
- If the value contains any of (, ; \|) then a list of converted values
will be returned
The first time that ``settings_getter`` func is invoked, it looks for a
``settings.ini`` file in ``~/.config/<package-name>/settings.ini``.
- If it does not find it, it will copy the default settings.ini from
the module’s install directory to that location
- If the settings.ini file does not exist in the module’s install
directory, an exception is raised
Alternate Usage
---------------
::
import settings_helper as sh
settings = sh.get_all_settings(__name__)
or
::
import settings_helper as sh
settings = sh.get_all_settings(__name__).get(sh.APP_ENV, {})
The ``get_all_settings`` func returns a dict containing all section
headers. ‘default’ .
- If a setting is defined in ‘default’, but not in a particular
section, the setting in ‘default’ will appear under the section
- If a setting (or upper-case equivalent) is defined as an environment
variable, that value will be used for all sections that use it
Tip
---
In your ``<package-name>/tests/__init__.py`` file, add the following so
the ``test`` section of settings is automatically used
::
import os
os.environ['APP_ENV'] = 'test'
Raw data
{
"_id": null,
"home_page": "https://github.com/kenjyco/settings-helper",
"name": "settings-helper",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "settings, config, environment variables, ini, ini file, ini parser, helper, kenjyco",
"author": "Ken",
"author_email": "kenjyco@gmail.com",
"download_url": "https://github.com/kenjyco/settings-helper/tarball/v0.0.14",
"platform": null,
"description": "You must include at least one section header in your settings.ini file\n(like ``[default]``). The configparser will raise a\nMissingSectionHeaderError if no headers are defined.\n\nIf you have any additional section headers, each parsed section will\nonly contain things defined in that section, plus anything defined in\nthe special/optional ``[default]`` section.\n\nThe values of any variable names in any sections can be overwritten by\nthe value set for an environment variable of the same name (or it\u2019s\nALLCAPS name).\n\nAny variables that have multiple values separated by a comma will be\nconverted to a list.\n\nThe parsed values will be converted to their basic types (int, float,\nNone, bool, str) via the ``from_string`` or ``string_to_converted_list``\nfunctions from `input-helper <https://pypi.org/project/input-helper>`__\nfor easy use.\n\nYou can comment out any variables in the settings.ini file with a\nleading ``#``.\n\nSetup for a one-off script\n--------------------------\n\nCreate a ``settings.ini`` file next to your script with at least one\nsection header in square brackets (like ``[my stuff]``).\n\n::\n\n [my stuff]\n something = 100\n things = none, true, false, 1, 2.5, dogs and cats, grapes\n # other = 500\n\nUse the simple ``get_all_settings`` function to get a dict of all\nsettings by section header.\n\n::\n\n import settings_helper as sh\n\n settings = sh.get_all_settings()\n\nFor our settings.ini file example, the settings dict from\n``get_all_settings()`` would be the following:\n\n::\n\n {\n 'my stuff': {\n 'something': 100,\n 'things': [None, True, False, 1, 2.5, 'dogs and cats', 'grapes']\n }\n }\n\nWhen dealing with settings where values are numbers, but you don\u2019t want\nthem converted (i.e.\u00a0version numbers like \u201c3.10\u201d), you can set kwarg\n``keep_num_as_string`` to ``True`` when calling ``get_all_settings`` (or\n``settings_getter``).\n\n::\n\n import settings_helper as sh\n\n settings = sh.get_all_settings(keep_num_as_string=True)\n\nFor our settings.ini file example, the settings dict from\n``get_all_settings(keep_num_as_string=True)`` would be the following:\n\n::\n\n {\n 'my stuff': {\n 'something': '100',\n 'things': [None, True, False, '1', '2.5', 'dogs and cats', 'grapes']\n }\n }\n\nSetup in your package\n---------------------\n\nCreate a default/sample ``settings.ini`` file in the module directory of\nyour package, with a ``[default]`` section and any other ``[sections]``\nyou want (i.e. app environments)\n\n::\n\n [default]\n something = 100\n\n [dev]\n redis_url = redis://localhost:6379/1\n something = 500\n\n [test]\n redis_url = redis://localhost:6379/9\n things = none, true, false, 1, 2.5, dogs\n\nFor this settings.ini file example, the settings dict from\n``get_all_settings()`` would be the following:\n\n::\n\n {\n 'dev': {\n 'something': 500,\n 'redis_url': 'redis://localhost:6379/1'\n },\n 'default': {\n 'something': 100\n },\n 'test': {\n 'something': 100,\n 'redis_url': 'redis://localhost:6379/9',\n 'things': [None, True, False, 1, 2.5, 'dogs']\n }\n }\n\nCreate a ``MANIFEST.in`` file in your package directory with the\nfollowing\n\n::\n\n include settings.ini\n\nUpdate the ``setup.py`` file of the package to include the\n``setting.ini`` file and add ``settings-helper`` to ``install_requires``\nlist\n\n::\n\n from setuptools import setup, find_packages\n\n setup(\n name='package-name',\n version='0.0.1',\n ...\n packages=find_packages(),\n install_requires=[\n 'settings-helper',\n ...\n ],\n include_package_data=True,\n package_dir={'': '.'},\n package_data={\n '': ['*.ini'],\n },\n ...\n )\n\nNote, your package directory tree will be something like the following\n\n::\n\n package-name\n \u251c\u2500\u2500 .gitignore\n \u251c\u2500\u2500 LICENSE.txt\n \u251c\u2500\u2500 MANIFEST.in\n \u251c\u2500\u2500 README.md\n \u251c\u2500\u2500 README.rst\n \u251c\u2500\u2500 package_name/\n \u2502\u00a0\u00a0 \u251c\u2500\u2500 __init__.py\n \u2502\u00a0\u00a0 \u2514\u2500\u2500 settings.ini\n \u2514\u2500\u2500 setup.py\n\nUsage\n-----\n\nUse in ``__init__.py`` of package\n\n::\n\n import settings_helper as sh\n\n get_setting = sh.settings_getter(__name__)\n something = get_setting('something')\n something_else = get_setting('something_else', 'default_val')\n\nSet ``APP_ENV`` environment variable to be one of your section names\nwhen starting your Python interpreter/server. **``APP_ENV`` defaults to\n``dev`` if it is not set.**\n\n- The ``get_setting`` func will return the value of the requested\n variable if it is set in the section specified in ``APP_ENV``.\n- If the variable is not in the section, it will pull the value from\n the ``[default]`` section\n- If the varialbe is not in the ``[default]`` section either, then\n return the optional fallback value passed in the ``default`` keyword\n argument to ``get_setting`` (which defaults to an empty string)\n- **If the requested variable exists in the environment (or its\n uppercase equivalent), it will be used instead of getting from\n settings.ini**\n- The value is automatically converted to a bool, None, int, or float\n if it should be\n- If the value contains any of (, ; \\|) then a list of converted values\n will be returned\n\nThe first time that ``settings_getter`` func is invoked, it looks for a\n``settings.ini`` file in ``~/.config/<package-name>/settings.ini``.\n\n- If it does not find it, it will copy the default settings.ini from\n the module\u2019s install directory to that location\n- If the settings.ini file does not exist in the module\u2019s install\n directory, an exception is raised\n\nAlternate Usage\n---------------\n\n::\n\n import settings_helper as sh\n\n settings = sh.get_all_settings(__name__)\n\nor\n\n::\n\n import settings_helper as sh\n\n settings = sh.get_all_settings(__name__).get(sh.APP_ENV, {})\n\nThe ``get_all_settings`` func returns a dict containing all section\nheaders. \u2018default\u2019 .\n\n- If a setting is defined in \u2018default\u2019, but not in a particular\n section, the setting in \u2018default\u2019 will appear under the section\n- If a setting (or upper-case equivalent) is defined as an environment\n variable, that value will be used for all sections that use it\n\nTip\n---\n\nIn your ``<package-name>/tests/__init__.py`` file, add the following so\nthe ``test`` section of settings is automatically used\n\n::\n\n import os\n\n os.environ['APP_ENV'] = 'test'\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Helpers to get specific settings from a particular section of a settings.ini file",
"version": "0.0.14",
"project_urls": {
"Download": "https://github.com/kenjyco/settings-helper/tarball/v0.0.14",
"Homepage": "https://github.com/kenjyco/settings-helper"
},
"split_keywords": [
"settings",
" config",
" environment variables",
" ini",
" ini file",
" ini parser",
" helper",
" kenjyco"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "034714b76ddf834f88a24d94eabbfdcab063950b11c41202922e93a03c05775e",
"md5": "26588fc92df2c096290e41ae5e522b17",
"sha256": "03fcd671d18e32cedcc1fd2271430386899157fbc3771d6e642977a5fe13395d"
},
"downloads": -1,
"filename": "settings_helper-0.0.14-py3-none-any.whl",
"has_sig": false,
"md5_digest": "26588fc92df2c096290e41ae5e522b17",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 7815,
"upload_time": "2024-11-28T19:56:07",
"upload_time_iso_8601": "2024-11-28T19:56:07.997380Z",
"url": "https://files.pythonhosted.org/packages/03/47/14b76ddf834f88a24d94eabbfdcab063950b11c41202922e93a03c05775e/settings_helper-0.0.14-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-28 19:56:07",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "kenjyco",
"github_project": "settings-helper",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "bg-helper",
"specs": []
},
{
"name": "input-helper",
"specs": []
}
],
"lcname": "settings-helper"
}
JSON
