{"id":15867260,"url":"https://github.com/cidrblock/modelsettings","last_synced_at":"2025-06-14T23:34:02.646Z","repository":{"id":53535169,"uuid":"126364379","full_name":"cidrblock/modelsettings","owner":"cidrblock","description":"Modelsettings is a straight-forward, easy to use python application settings manager that includes ini file, environment variable, and command-line parameter support.","archived":false,"fork":false,"pushed_at":"2021-03-25T21:46:23.000Z","size":21,"stargazers_count":3,"open_issues_count":2,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-02-27T04:47:44.540Z","etag":null,"topics":["argparse","docker","environment-variables","ini-parser","python","twelve-factor"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cidrblock.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-03-22T16:29:34.000Z","updated_at":"2024-06-25T09:58:08.000Z","dependencies_parsed_at":"2022-09-15T23:00:47.128Z","dependency_job_id":null,"html_url":"https://github.com/cidrblock/modelsettings","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cidrblock%2Fmodelsettings","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cidrblock%2Fmodelsettings/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cidrblock%2Fmodelsettings/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cidrblock%2Fmodelsettings/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cidrblock","download_url":"https://codeload.github.com/cidrblock/modelsettings/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243801675,"owners_count":20350108,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["argparse","docker","environment-variables","ini-parser","python","twelve-factor"],"created_at":"2024-10-05T23:41:59.259Z","updated_at":"2025-03-16T02:31:16.763Z","avatar_url":"https://github.com/cidrblock.png","language":"Python","readme":"[![Build Status](https://travis-ci.org/cidrblock/modelsettings.svg?branch=master)](https://travis-ci.org/cidrblock/modelsettings)\n\n\n# Model Settings\n\n## Overview\n\nModelsettings is a straight-forward, easy to use python application settings manager that includes ini file, environment variable, and command-line parameter support.\n\nThe necessary settings variables are declared in a yaml model, which is then used to parse an .ini file, environment variables, and finally command-line arguments.\n\nIn addition to reading settings from the three sources, modelsettings also includes sample configuration generator support for:\n- command-line\n- environment variables (e.g., export statements)\n- ini file\n- docker run\n- docker compose\n- kubernetes\n- drone plugins\n\n## Quick start\n\n### Build the model\n\nModelsettings looks for a `model_settings.yml` in the current working directory.  A simple `model_settings.yml` file might look like this:\n\n```\nenv_prefix: CF\nmodel:\n  cream:\n    choices:\n    - True\n    - False\n    default: False\n    example: True\n    help: Would you like cream in your coffee?\n    required: True\n  sugar:\n    choices:\n    - True\n    - False\n    default: True\n    example: True\n    help: Would you like sugar in your coffee?\n    required: True\n  size:\n    choices:\n    - 10\n    - 12\n    - 16\n    default: 12\n    example: 16\n    help: What size cup would you like in ounces?\n    required: True\n```\n`env_prefix` is used as a prefix for the environment variables, this helps avoid name collision when running multiple python applications in the same shell.\n\n`model` is a dictionary of required settings values.\n\n### Import and use the module\n\nIn your application, simply import modelsettings.\n\n```\n$ python3 -m venv venv\n$ source venv/bin/activate\n$ pip install modelsettings\n```\napp.py\n```\nfrom modelsettings import settings\n\ndef main():\n    output = f\"You ordered a {settings.SIZE} oz. cup of coffee\"\n    modifiers = []\n    if settings.CREAM: modifiers.append(\"cream\")\n    if settings.SUGAR: modifiers.append(\"sugar\")\n    if modifiers:\n        output += \" with \" + \" and \".join(modifiers)\n    output += \".\"\n    print(output)\n\nif __name__ == \"__main__\":\n    main()\n\n```\nAll settings are converted to uppercase and available as `settings.XXXXX`\n\n## Additional command-line parameters\n\n### `--help`\n\nArgparse help is generated from the model:\n\n```\n$ python app.py --help\nusage: app.py [-h]\n              [--generate {command,docker-run,docker-compose,ini,env,kubernetes,readme,drone-plugin}]\n              [--settings SETTINGS] [--cream {True,False}]\n              [--sugar {True,False}] [--size {10,12,16}]\n\noptional arguments:\n  -h, --help            show this help message and exit\n  --generate {command,docker-run,docker-compose,ini,env,kubernetes,readme,drone-plugin}\n                        Generate a template\n  --settings SETTINGS   Specify a settings file. (ie settings.dev)\n  --cream {True,False}  Would you like cream in your coffee? e.g., True\n  --sugar {True,False}  Would you like sugar in your coffee? e.g., True\n  --size {10,12,16}     What size cup would you like in ounces? e.g., 16\n```\n\n### `--generate`\n\nA command-line parameter of generate is added to the application which, when used, will generate sample settings in a number of formats.\n\n```\n$ python app.py --generate env\nexport CF_CREAM=True\nexport CF_SIZE=16\nexport CF_SUGAR=True\n```\n\n### `--generate readme`\n\nMarkdown can be generated which includes all the available generate formats.\n\n```\n$ python app.py --generate readme \u003e\u003e README.md\n```\n## Order of operations\n\nThe .ini file is read first, then the environment variables, then the command-line parameters.\n\n### .ini file support\n\nThe application will now support loading settings from a `settings.ini` file.\n\n```\n$ cat settings.ini\n[settings]\ncream=True\nsize=16\nsugar=True\n$ python app.py\nYou ordered a 16 oz. cup of coffee with cream and sugar.\n```\nAn alternate settings file can be specified with the command line, this is useful during development of the application.\n\n```\n$ cat settings.dev\n[settings]\ncream=True\nsize=10\nsugar=False\n$ python app.py --settings settings.dev\nYou ordered a 10 oz. cup of coffee with cream.\n$ python app.py --settings settings.dev --size 16\nYou ordered a 16 oz. cup of coffee with cream.\n```\n\n### Environment variable support\n\nAll settings can be stored as environment variables.  The environment variables should be prefaced with the `env_prefix` from the `model_settings.yml` file and capitalized.\n\n```\n$ export CF_CREAM=False\n$ export CF_SIZE=12\n$ export CF_SUGAR=True\n$ python app.py\nYou ordered a 12 oz. cup of coffee with sugar.\n$ export CF_CREAM=True\n$ python app.py\nYou ordered a 12 oz. cup of coffee with cream and sugar.\n```\n\n### Command-line parameter support\n\nCommand line parameters take precedence over `.ini` files and environment variables.\n\n```\n$ python app.py --size 10 --sugar False --cream False\nYou ordered a 10 oz. cup of coffee.\n$ python app.py --size 12 --sugar True --cream False\nYou ordered a 12 oz. cup of coffee with sugar.\n$ python app.py --size 16 --sugar True --cream True\nYou ordered a 16 oz. cup of coffee with cream and sugar.\n```\n\n## model_settings.yml\n\n1) The model support 5 basic python types:\n  - `bool`\n  - `int`\n  - `float`\n  - `string`\n  - `list`\n  - `dict`\n\nThe type is derived from the example given, and the settings variable is cast to that type.\n\nIn the example below, each supported type is shown with a corresponding yaml native example.\n\n`example` is therefore a required property for every entry in the model.\n\n```\nbool:\n  choices:\n  - True\n  - False\n  default: False\n  help: This is an integer setting\n  required: False\n  example: True\ninteger:\n  choices:\n  - 10\n  - 20\n  default: 60\n  help: This is an integer setting\n  required: False\n  example: 30\nfloat:\n  default: 60.5\n  help: This is an integer setting\n  required: False\n  example: 30.5\nstring:\n  default: string\n  help: This is a string setting\n  required: False\n  example: string\ndictionary:\n  default:\n    key: value\n  help: This is a dict setting\n  required: False\n  example:\n    key: value\nlist:\n  default:\n  - item1\n  - item2\n  help: This is a list setting\n  required: False\n  example:\n  - item1\n  - item2\n```\n\n## Dictionaries and lists objects in `.ini` and environment variables.\n\nDictionary and lists should be represented as json in `.ini` files and environment variables:\n\n```\n$ more complex.yml\nenv_prefix: RM\nmodel:\n  dictionary:\n    default:\n      key: value\n    help: This is a dict setting\n    required: False\n    example:\n      key: value\n  list:\n    default:\n    - item1\n    - item2\n    help: This is a list setting\n    required: False\n    example:\n    - item1\n    - item2\n$ export MODEL_SETTINGS=complex.yml\n\n$ python app.py --generate env\nexport RM_DICTIONARY='{\"key\": \"value\"}'\nexport RM_LIST='[\"item1\", \"item2\"]'\n\n$ python app.py --generate ini\n[settings]\ndictionary={\"key\": \"value\"}\nlist=[\"item1\", \"item2\"]\n```\n\n## Docker\n\nBecause all settings are supported as environment variables, transitioning a python application to a docker container is simple.\n\nDockerfile\n```\nFROM python:3.6.4-alpine\n\nRUN apk add -U \\\n\tca-certificates \\\n \u0026\u0026 rm -rf /var/cache/apk/* \\\n \u0026\u0026 pip install --no-cache-dir --upgrade pip\n\nWORKDIR /usr/src/app/\nADD model_settings.yml .\nADD app.py .\nADD requirements.txt .\nRUN pip install -r requirements.txt\n\nENTRYPOINT [\"python\", \"app.py\"]\n```\n\nBuild\n```\n$ docker build -t coffee .\n\u003c...\u003e\nSuccessfully built 74938ac5902a\nSuccessfully tagged coffee:latest\n```\nGenerate\n```\n$ python app.py --generate docker-run\ndocker run -it \\\n     -e CF_CREAM=True \\\n     -e CF_SIZE=16 \\\n     -e CF_SUGAR=True \\\n     \u003ccontainer-name\u003e\n```\nRun\n```\n$ docker run -it \\\n     -e CF_CREAM=True \\\n     -e CF_SIZE=16 \\\n     -e CF_SUGAR=True \\\n     coffee\nYou ordered a 16 oz. cup of coffee with cream and sugar.\n\n$ docker run -it \\\n     -e CF_CREAM=False \\\n     -e CF_SIZE=12 \\\n     -e CF_SUGAR=True \\\n     coffee\nYou ordered a 12 oz. cup of coffee with sugar.  \n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcidrblock%2Fmodelsettings","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcidrblock%2Fmodelsettings","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcidrblock%2Fmodelsettings/lists"}