{"id":15043073,"url":"https://github.com/pilosus/piny","last_synced_at":"2025-03-17T16:09:43.727Z","repository":{"id":34925427,"uuid":"190712573","full_name":"pilosus/piny","owner":"pilosus","description":"YAML config loader with environment variables interpolation for Python and command line","archived":false,"fork":false,"pushed_at":"2025-02-27T08:12:09.000Z","size":213,"stargazers_count":23,"open_issues_count":5,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-27T11:46:57.415Z","etag":null,"topics":["configuration","docker-compose","environment-variables","kubernetes","kubernetes-secrets","python","yaml"],"latest_commit_sha":null,"homepage":"https://piny.readthedocs.io/en/latest/","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/pilosus.png","metadata":{"files":{"readme":"README.rst","changelog":"CHANGELOG.rst","contributing":"CONTRIBUTING.rst","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-06-07T08:37:06.000Z","updated_at":"2025-02-27T08:11:10.000Z","dependencies_parsed_at":"2024-06-18T18:39:38.951Z","dependency_job_id":"c93f88d7-e6a5-4d6d-9c89-eb92bfe238e8","html_url":"https://github.com/pilosus/piny","commit_stats":{"total_commits":118,"total_committers":4,"mean_commits":29.5,"dds":"0.44067796610169496","last_synced_commit":"ebe915eb73d46e2ddc45bc6f37ed8aa368261875"},"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pilosus%2Fpiny","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pilosus%2Fpiny/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pilosus%2Fpiny/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pilosus%2Fpiny/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pilosus","download_url":"https://codeload.github.com/pilosus/piny/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244066179,"owners_count":20392406,"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":["configuration","docker-compose","environment-variables","kubernetes","kubernetes-secrets","python","yaml"],"created_at":"2024-09-24T20:48:32.311Z","updated_at":"2025-03-17T16:09:43.705Z","avatar_url":"https://github.com/pilosus.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"Piny\n====\n\n|Logo|\n\n|PyPI| |Coverage| |Downloads| |License|\n\n**Piny** is YAML config loader with environment variables interpolation for Python.\n\nKeep your app's configuration in a YAML file.\nMark up sensitive data in the config as *environment variables*.\nSet environment variables on application deployment.\nNow let the *piny* load your config and substitute environment variables\nin it with their values.\n\nPiny is developed with Docker and Kubernetes in mind,\nthough it's not limited to any deployment system.\n\n\nRationale\n---------\n\nPiny combines *readability and versioning* you get when using config files,\nand *security* that environment variables provide. Read more about this approach\nin the `blog post`_.\n\n\nHelp\n----\n\nSee `documentation`_ for more details.\n\n\nInstallation\n------------\n\nJust run::\n\n  pip install -U piny\n\n\nUsage\n-----\n\nSet your environment variables, add them to your YAML configuration file:\n\n.. code-block:: yaml\n\n    db:\n      login: user\n      password: ${DB_PASSWORD}\n    mail:\n      login: user\n      password: ${MAIL_PASSWORD:-my_default_password}\n    sentry:\n      dsn: ${VAR_NOT_SET}\n\nThen load your config:\n\n.. code-block:: python\n\n    from piny import YamlLoader\n\n    config = YamlLoader(path=\"config.yaml\").load()\n    print(config)\n    # {'db': {'login': 'user', 'password': 'my_db_password'},\n    # 'mail': {'login': 'user', 'password': 'my_default_password'},\n    # 'sentry': {'dsn': None}}\n\nYou may want to discourage Bash-style envs with defaults in your configs.\nIn such case, use a ``StrictMatcher``:\n\n.. code-block:: python\n\n    from piny import YamlLoader, StrictMatcher\n\n    config = YamlLoader(path=\"config.yaml\", matcher=StrictMatcher).load()\n\nBoth strict and default matchers produce ``None`` value if environment variable\nmatched is not set in the system (and no default syntax used in the case of\ndefault matcher).\n\nPiny also comes with *command line utility* that works both with files and standard\ninput and output:\n\n.. code-block:: bash\n\n  $ export PASSWORD=mySecretPassword\n  $ echo \"db: \\${PASSWORD}\" | piny\n  db: mySecretPassword\n\n\nValidation\n----------\n\nPiny supports *optional* data validation using third-party libraries:\n`Marshmallow`_, `Pydantic`_, `Trafaret`_.\n\n.. code-block:: python\n\n  import marshmallow as ma\n  from piny import MarshmallowValidator, StrictMatcher, YamlLoader\n\n  class DBSchema(ma.Schema):\n      login = ma.fields.String(required=True)\n      password = ma.fields.String()\n\n  class ConfigSchema(ma.Schema):\n      db = ma.fields.Nested(DBSchema)\n\n  config = YamlLoader(\n      path=\"database.yaml\",\n      matcher=StrictMatcher,\n      validator=MarshmallowValidator,\n      schema=ConfigSchema,\n  ).load(many=False)\n\n\nExceptions\n----------\n\n``LoadingError`` is thrown when something goes wrong with reading or parsing YAML-file.\n``ValidationError`` is a wrapper for exceptions raised by the libraries for optional data validation.\nOriginal exception can be accessed by ``origin`` attribute. It comes in handy when you need more than\njust an original exception message (e.g. a dictionary of validation errors).\n\nBoth exceptions inherit from the ``ConfigError``.\n\n\nBest practices\n--------------\n\n- Maintain a healthy security/convenience balance for your config\n\n- Mark up entity as an environment variable in your YAML if and only if\n  it really is a *secret* (login/passwords, private API keys, crypto keys,\n  certificates, or maybe DB hostname too? You decide)\n\n- When loading config file, validate your data.\n  Piny supports a few popular data validation tools.\n\n- Store your config files in the version control system along with your app’s code.\n\n- Environment variables are set by whoever is responsible for the deployment.\n  Modern orchestration systems like `Kubernetes`_ make it easier to keep envs secure\n  (see `Kubernetes Secrets`_).\n\n\nFun facts\n---------\n\n*Piny* is a recursive acronym for *Piny Is Not YAML*.\nNot only it's a library name, but also a name for YAML marked up\nwith environment variables.\n\n\nChangelog\n---------\n\nSee `CHANGELOG.rst`_.\n\n\nContributing\n------------\n\nSee `CONTRIBUTING.rst`_.\n\n.. |PyPI| image:: https://img.shields.io/pypi/v/piny\n   :alt: PyPI\n   :target: https://pypi.org/project/piny/\n.. |Coverage| image:: https://img.shields.io/codecov/c/github/pilosus/piny.svg\n   :alt: Codecov\n   :target: https://codecov.io/gh/pilosus/piny\n.. |License| image:: https://img.shields.io/github/license/pilosus/piny.svg\n   :alt: MIT License\n   :target: https://github.com/pilosus/piny/blob/master/LICENSE\n.. |Logo| image:: https://piny.readthedocs.io/en/latest/_static/piny_logo_noborder.png\n   :alt: Piny logo\n   :target: https://pypi.org/project/piny/\n.. |Downloads| image:: https://img.shields.io/pypi/dm/piny\n   :alt: PyPI - Downloads\n   :target: https://pypistats.org/packages/piny\n\n.. _blog post: https://blog.pilosus.org/blog/application-configs-files-or-environment-variables-actually-both\n.. _future releases: https://github.com/pilosus/piny/issues/2\n.. _Kubernetes: https://kubernetes.io/\n.. _Kubernetes Secrets: https://kubernetes.io/docs/concepts/configuration/secret/\n.. _Pydantic: https://pydantic-docs.helpmanual.io/\n.. _Marshmallow: https://marshmallow.readthedocs.io/\n.. _Trafaret: https://trafaret.readthedocs.io/\n.. _tests: https://github.com/pilosus/piny/tree/master/tests\n.. _source code: https://github.com/pilosus/piny/tree/master/piny\n.. _coming soon: https://github.com/pilosus/piny/issues/12\n.. _CONTRIBUTING.rst: https://github.com/pilosus/piny/tree/master/CONTRIBUTING.rst\n.. _CHANGELOG.rst: https://github.com/pilosus/piny/tree/master/CHANGELOG.rst\n.. _documentation: https://piny.readthedocs.io/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpilosus%2Fpiny","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpilosus%2Fpiny","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpilosus%2Fpiny/lists"}