{"id":14985710,"url":"https://github.com/phenobarbital/navconfig","last_synced_at":"2026-02-22T16:36:12.916Z","repository":{"id":41979507,"uuid":"304700017","full_name":"phenobarbital/NavConfig","owner":"phenobarbital","description":"NavConfig: a very simple way to load project configurations","archived":false,"fork":false,"pushed_at":"2025-05-22T20:28:09.000Z","size":695,"stargazers_count":4,"open_issues_count":10,"forks_count":1,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-05-22T22:05:37.601Z","etag":null,"topics":["config","configuration","configuration-files","configuration-management","environ","environment","environment-variables","memcached","python","redis","settings","settings-management","settings-storage","yaml"],"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/phenobarbital.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-10-16T17:50:52.000Z","updated_at":"2025-04-06T09:21:39.000Z","dependencies_parsed_at":"2024-01-03T12:24:46.206Z","dependency_job_id":"308c471c-05a1-462c-a7c8-0293ffb4bf7d","html_url":"https://github.com/phenobarbital/NavConfig","commit_stats":{"total_commits":315,"total_committers":3,"mean_commits":105.0,"dds":0.2857142857142857,"last_synced_commit":"835033e5a39b1f250c41fc53d2a6bb5c063a1167"},"previous_names":[],"tags_count":87,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phenobarbital%2FNavConfig","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phenobarbital%2FNavConfig/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phenobarbital%2FNavConfig/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phenobarbital%2FNavConfig/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/phenobarbital","download_url":"https://codeload.github.com/phenobarbital/NavConfig/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phenobarbital%2FNavConfig/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259114472,"owners_count":22807244,"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":["config","configuration","configuration-files","configuration-management","environ","environment","environment-variables","memcached","python","redis","settings","settings-management","settings-storage","yaml"],"created_at":"2024-09-24T14:11:31.470Z","updated_at":"2026-02-22T16:36:12.835Z","avatar_url":"https://github.com/phenobarbital.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# NavConfig\n\nNavConfig is a configuration management library for Python projects. It is\nthe default configuration layer of the Navigator Framework, but it works\nperfectly as a stand-alone tool for any Python application.\n\nNavConfig can load configuration directives from multiple sources (and\ncombine them):\n\n- Environment files (`.env`)\n- INI files (via `configparser`)\n- TOML and YAML files\n- `pyproject.toml`\n- Redis\n- Memcached\n- HashiCorp Vault\n- Python settings modules (`settings/settings.py`)\n\nThe main goal of NavConfig is to centralize configuration access through a\nsingle, immutable point of truth that can be shared across modules.\n\n\n## Motivation\n\nApplications require many configuration options. Some of those options hold\nsecrets or credentials and must be kept separate from general settings.\nConfiguration also varies between environments (development, staging,\nproduction).\n\nNavConfig addresses this by loading secrets from `.env` files and structured\nsettings from INI/TOML/YAML files, keeping concerns separated. It also\nsupports retrieving configuration from external stores such as Redis,\nMemcached, or HashiCorp Vault.\n\n\n## Installation\n\n```bash\npip install navconfig\n```\n\nTo include optional backends:\n\n```bash\n# Redis and Memcached support\npip install navconfig[redis,memcache]\n\n# All features, including Logstash logging\npip install navconfig[all]\n```\n\n\n## Quickstart\n\n### Bootstrapping a new project with `kardex`\n\nNavConfig ships a small CLI called `kardex` that creates the directory layout\nyour project needs.\n\n```bash\nkardex create --env dev\n```\n\nThis command generates the following structure in the current directory:\n\n```text\n.\n|-- env/\n|   +-- dev/\n|       +-- .env\n|-- etc/\n|   +-- config.ini\n+-- logs/\n```\n\n- `env/dev/.env` -- environment variables (secrets, feature flags, paths).\n- `etc/config.ini` -- INI-based settings consumed by NavConfig, including a\n  `[logging]` section.\n- `logs/` -- default directory where rotating log files are written.\n\nThe generated files come from the bundled samples in\n`navconfig/samples/`. You can inspect or customize those samples before\nrunning `kardex create`.\n\nUse `--path` to point to a different project root:\n\n```bash\nkardex create --env dev --path /srv/myapp\n```\n\n### Creating additional environments\n\nOnce the base structure exists you can add more environments:\n\n```bash\nkardex new-env prod\n```\n\nThis copies `env/.env` (or the bundled sample if no base file exists) into\n`env/prod/.env`, adjusting the `ENV` variable automatically.\n\nTo include HashiCorp Vault connection variables in the new environment, pass\n`--vault`:\n\n```bash\nkardex new-env staging --vault\n```\n\nThe generated `.env` will contain extra variables such as `VAULT_ADDR`,\n`VAULT_TOKEN`, `VAULT_MOUNT_POINT`, and others that NavConfig can use when\n`ENV_TYPE=vault`.\n\n### Directory layout\n\nA typical project looks like this:\n\n```text\nmyapp/\n|-- __init__.py\n|-- pyproject.toml\n|-- env/\n|   |-- .env          (optional base file)\n|   |-- dev/\n|   |   +-- .env\n|   |-- staging/\n|   |   +-- .env\n|   +-- prod/\n|       +-- .env\n|-- etc/\n|   +-- config.ini\n|-- logs/\n+-- settings/\n    |-- __init__.py\n    +-- settings.py   (optional)\n```\n\n### Selecting an environment\n\nSet the `ENV` variable before starting your application:\n\n```bash\nENV=prod python app.py\n```\n\nNavConfig will load `env/prod/.env` and any INI file referenced by its\n`CONFIG_FILE` directive.\n\n### Accessing configuration\n\n```python\nfrom navconfig import config\n\nAPP_NAME = config.get(\"APP_NAME\")\n# \"MyApp\"\n```\n\nAttribute-style access also works:\n\n```python\nAPP_NAME = config.APP_NAME\n```\n\n### Typed accessors\n\n```python\nconfig.get(\"APP_NAME\")                  # str\nconfig.getint(\"PORT\", fallback=8080)    # int\nconfig.getboolean(\"DEBUG\")             # bool\nconfig.getlist(\"ALLOWED_HOSTS\")        # list (comma-separated)\nconfig.getdict(\"EXTRA\")               # dict\n```\n\nAn optional `fallback` argument is returned when the key is not found:\n\n```python\nconfig.get(\"MISSING_KEY\", \"default_value\")\n```\n\n\n## Configuration directories\n\nBy default NavConfig looks for files relative to the project root:\n\n| File type            | Default location            |\n| -------------------- | --------------------------- |\n| `.env`               | `env/` (plus ENV subdirectory) |\n| `.yml` / `.toml`     | `env/`                      |\n| `pyproject.toml`     | project root                |\n| `.ini`               | `etc/`                      |\n\n\n## Configure logging\n\nNavConfig provides a ready-to-use logging facility. Import `logging_config`\nand apply it with `dictConfig`:\n\n```python\nimport logging\nfrom navconfig.logging import logdir, loglevel, logging_config\nfrom logging.config import dictConfig\n\ndictConfig(logging_config)\n```\n\nThen use `logging.getLogger()` as usual:\n\n```python\nlogger = logging.getLogger(\"MY_APP\")\nlogger.info(\"Hello World\")\n```\n\nConsole output uses colored formatting by default:\n\n```\n[INFO] 2024-03-11 19:31:39,408 MY_APP: Hello World\n```\n\nLogging behaviour is controlled by the `[logging]` section in your INI file.\nThe bundled `config.ini.sample` includes all available options.\n\n\n## Custom settings module\n\nYou can create a Python package called `settings` in your project to define\nadditional configuration derived from NavConfig values:\n\n```text\nmyapp/\n+-- settings/\n    |-- __init__.py\n    +-- settings.py\n```\n\nInside `settings/settings.py`:\n\n```python\nimport sys\nfrom navconfig import config, DEBUG\n\nLOCAL_DEVELOPMENT = DEBUG is True and sys.argv[0] == \"run.py\"\nSEND_NOTIFICATIONS = config.get(\"SEND_NOTIFICATIONS\", fallback=True)\n```\n\nVariables defined there are accessible through `navconfig.conf`:\n\n```python\nfrom navconfig.conf import LOCAL_DEVELOPMENT\n\nif LOCAL_DEVELOPMENT:\n    print(\"Running in local development mode.\")\n```\n\n\n## Dependencies\n\n- Python \u003e= 3.10\n- python-dotenv\n- configparser\n- PyYAML\n- pytomlpp\n- orjson\n- cryptography / pycryptodomex\n- hvac (HashiCorp Vault client)\n\nOptional: `redis`, `pylibmc` / `aiomcache`, `python-logstash-async`,\n`uvloop`.\n\n\n## Contribution guidelines\n\nPlease see the Contribution Guide for details on:\n\n- Writing tests\n- Code review process\n- Other guidelines\n\n\n## License\n\nNavConfig is released under the MIT License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphenobarbital%2Fnavconfig","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fphenobarbital%2Fnavconfig","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphenobarbital%2Fnavconfig/lists"}