==========
Pop Config
==========
.. image:: https://img.shields.io/badge/made%20with-pop-teal
:alt: Made with pop, a Python implementation of Plugin Oriented Programming
:target: https://pop.readthedocs.io/
.. image:: https://img.shields.io/badge/docs%20on-vmware.gitlab.io-blue
:alt: Documentation is published with Sphinx on GitLab Pages via vmware.gitlab.io
:target: https://vmware.gitlab.io/pop/pop-config/en/latest/index.html
.. image:: https://img.shields.io/badge/made%20with-python-yellow
:alt: Made with Python
:target: https://www.python.org/
About
=====
Pop-config is the official tool to allow for creating and app-merging
configuration options for ``pop`` projects. Plugin Oriented Programming
presents a means to merge multiple applications together dynamically.
This capabilities requires that the startup of these applications needs
to be managed from within the programming paradigm. Since this is the case
``pop-config`` becomes a critical and hard requirement of ``pop``.
Pop-config is not just about being able to work with ``pop`` projects
to facilitate app-merging, it has also been designed to make the startup
of an application much simpler, and to make the expensive boiler plate
of startup and configuration as transparent as possible. When making
``pop`` projects the idea is that projects are developed in very small
chunks and are then dynamically merged together. So the creation of
these mergeable apps needs to be quick and easy!
Pop-config also solves a problem with configuration of applications,
when making a new application, if you want robust configuration
loading, you need to be able to take options from the command line,
environment variables, and configuration files. Pop-config does all
of this for you, and loads them in the correct order, all behind the
scenes, making your life easier.
* `pop-config source code <https://gitlab.com/vmware/pop/pop-config>`__
* `pop-config documentation <https://vmware.gitlab.io/pop/pop-config/en/latest/index.html>`__
Installation
============
For a basic installation run
.. code-block:: bash
$ pip install pop-config
To enable async logging install with the ``async`` extras
.. code-block:: bash
$ pip install pop-config[async]
Understanding the conf.py
=========================
Pop relies on a configuration file to manage how to merge apps, and
also how to manage and merge configuration data. The data in this file
is presented in 4 Python dictionaries and defines every aspect of
configuration loading.
The 4 dictionaries are called *CONFIG*, *CLI_CONFIG*, *SUBCOMMANDS*
and *DYNE*. Each dictionary serves a specific purpose. Between them
you can define how the cli arguments are presented, all configuration
defaults, documentation, etc.
This project is built with `pop <https://pop.readthedocs.io/>`__, a Python-based
implementation of *Plugin Oriented Programming (POP)*. POP seeks to bring
together concepts and wisdom from the history of computing in new ways to solve
modern computing problems.
For more information:
* `Intro to Plugin Oriented Programming (POP) <https://pop-book.readthedocs.io/en/latest/>`__
* `pop-awesome <https://gitlab.com/saltstack/pop/pop-awesome>`__
* `pop-create <https://gitlab.com/saltstack/pop/pop-create/>`__
The CONFIG Dictionary
=====================
The bulk of the configuration will be present in the *CONFIG* dictionary.
all of your configuration options are defined here. Most entries in the
*CONFIG* dictionary will be very simple and just expose the most basic
values:
.. code-block:: python
CONFIG = {
"name": {
"default": "frank",
"help": "Enter the name to use",
},
}
This simple example presents the documentation for the configuration value
and what the default value should be.
Vertically app-merged projects can add config items to their parent dynes like so:
.. code-block:: python
CONFIG = {
"new_item": {
"type": int,
"default": 1,
"dyne": "idem",
},
}
Many more options can be used, but they will be covered in the reference
document.
The CLI_CONFIG Dictionary
=========================
Adding a configuration value does not make it appear on the command line.
Each application can be extended to include command line options.
Lets extend our earlier example to expose the "name" option as a command
line argument:
.. code-block:: python
CLI_CONFIG = {
"name": {},
}
CONFIG = {
"name": {
"default": "frank",
"help": "Enter the name to use",
},
}
That's it! The "name" option is now available on the command line and can
be used as ``--name bob``.
But what if we want it to be a positional argument? Simple! Just add the
positional option to the *CLI_CONFIG*:
.. code-block:: python
CLI_CONFIG = {
"name": {
"positional": True,
},
}
CONFIG = {
"name": {
"default": "frank",
"help": "Enter the name to use",
},
}
You can inherit cli args from another project. Say, for example that you want to implement the ``--output`` flag
exactly the same way ``rend`` does, you can source it like this:
.. code-block:: python
CLI_CONFIG = {
"output": {
"source": "rend",
},
}
Many more options exist that allow you to control every aspect of the user's
command line experience.
The SUBCOMMANDS Dictionary
==========================
Sometimes it is desirable to have subcommands. Subcommands allow your CLI
to work in a way similar to the git cli, where you have multiple routines
that all can be called from a single command.
Lets add a few more things to our example so that we can have subcommands.
.. code-block:: python
CLI_CONFIG = {
"name": {
"subcommands": ["test", "apply"],
},
"weight": {},
"power": {
"subcommands": ["apply"],
},
}
CONFIG = {
"name": {
"default": "frank",
"help": "Enter the name to use",
},
"weight": {
"default": "150",
"help": "Enter how heavy it should be",
},
"power": {
"default": "100",
"help": "Enter how powerful it should be",
},
}
SUBCOMMANDS = {
"test": {
"help": "Used to test",
"desc": "When running in test mode, things will be tested",
},
"apply": {
"help": "Used to apply",
"desc": "When running in apply mode, things will be applied",
},
}
In this example we see that the option ``name`` will be available under
the subcommands ``test`` and ``apply``. The option ``power`` will be available
only under the subcommand ``apply`` and the option ``weight`` is globally
available.
The DYNE Dictionary
===================
The *DYNE* dictionary allows you to control what dynamic names your app is
presenting to other ``pop`` projects. This name gets used not only inside
of ``pop-config`` but also inside of ``pop`` to determine what plugin subsystems
this application merges with. The *DYNE* system allows for your cli to be
extended by third party code, enabling configuration options to be made
available to your application via external code.
The *DYNE* system is very powerful. But since it is not critical to getting
started with ``pop-config`` it will be covered in more depth in another document.
Log Module
===================
Within the log module of pop-config there are several config options.
If "log_plugin" is set to "rotating", the "log_handler_options" config item can be set to something other than the defaults.
The two options are:
1. maxBytes default: 1024*1024*100
This option specifies the maximum size of each back up log file. Once a log file approaches this value the "rotating" module will save the file and create a new log file.
2. backupCount default: 5
This option tells the rotating module how many backup log files are allowed. As that number increases the oldest files are deleted.
Acknowledgements
================
* `Img Shields <https://shields.io>`__ for making repository badges easy.
Raw data
{
"_id": null,
"home_page": "https://vmware.gitlab.io/pop/pop-config/en/latest/index.html",
"name": "pop-config",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "",
"author": "VMware, Inc.",
"author_email": "idemproject@vmware.com",
"download_url": "https://files.pythonhosted.org/packages/f8/fc/dfa85daffc2fcbba395b1d34b8fe60b4fc2b65c667942ded5e687c8fc740/pop-config-12.0.4.tar.gz",
"platform": null,
"description": "==========\nPop Config\n==========\n\n.. image:: https://img.shields.io/badge/made%20with-pop-teal\n :alt: Made with pop, a Python implementation of Plugin Oriented Programming\n :target: https://pop.readthedocs.io/\n\n.. image:: https://img.shields.io/badge/docs%20on-vmware.gitlab.io-blue\n :alt: Documentation is published with Sphinx on GitLab Pages via vmware.gitlab.io\n :target: https://vmware.gitlab.io/pop/pop-config/en/latest/index.html\n\n.. image:: https://img.shields.io/badge/made%20with-python-yellow\n :alt: Made with Python\n :target: https://www.python.org/\n\nAbout\n=====\n\nPop-config is the official tool to allow for creating and app-merging\nconfiguration options for ``pop`` projects. Plugin Oriented Programming\npresents a means to merge multiple applications together dynamically.\nThis capabilities requires that the startup of these applications needs\nto be managed from within the programming paradigm. Since this is the case\n``pop-config`` becomes a critical and hard requirement of ``pop``.\n\nPop-config is not just about being able to work with ``pop`` projects\nto facilitate app-merging, it has also been designed to make the startup\nof an application much simpler, and to make the expensive boiler plate\nof startup and configuration as transparent as possible. When making\n``pop`` projects the idea is that projects are developed in very small\nchunks and are then dynamically merged together. So the creation of\nthese mergeable apps needs to be quick and easy!\n\nPop-config also solves a problem with configuration of applications,\nwhen making a new application, if you want robust configuration\nloading, you need to be able to take options from the command line,\nenvironment variables, and configuration files. Pop-config does all\nof this for you, and loads them in the correct order, all behind the\nscenes, making your life easier.\n\n* `pop-config source code <https://gitlab.com/vmware/pop/pop-config>`__\n* `pop-config documentation <https://vmware.gitlab.io/pop/pop-config/en/latest/index.html>`__\n\nInstallation\n============\n\nFor a basic installation run\n\n.. code-block:: bash\n\n $ pip install pop-config\n\nTo enable async logging install with the ``async`` extras\n\n.. code-block:: bash\n\n $ pip install pop-config[async]\n\nUnderstanding the conf.py\n=========================\n\nPop relies on a configuration file to manage how to merge apps, and\nalso how to manage and merge configuration data. The data in this file\nis presented in 4 Python dictionaries and defines every aspect of\nconfiguration loading.\n\nThe 4 dictionaries are called *CONFIG*, *CLI_CONFIG*, *SUBCOMMANDS*\nand *DYNE*. Each dictionary serves a specific purpose. Between them\nyou can define how the cli arguments are presented, all configuration\ndefaults, documentation, etc.\n\nThis project is built with `pop <https://pop.readthedocs.io/>`__, a Python-based\nimplementation of *Plugin Oriented Programming (POP)*. POP seeks to bring\ntogether concepts and wisdom from the history of computing in new ways to solve\nmodern computing problems.\n\nFor more information:\n\n* `Intro to Plugin Oriented Programming (POP) <https://pop-book.readthedocs.io/en/latest/>`__\n* `pop-awesome <https://gitlab.com/saltstack/pop/pop-awesome>`__\n* `pop-create <https://gitlab.com/saltstack/pop/pop-create/>`__\n\nThe CONFIG Dictionary\n=====================\n\nThe bulk of the configuration will be present in the *CONFIG* dictionary.\nall of your configuration options are defined here. Most entries in the\n*CONFIG* dictionary will be very simple and just expose the most basic\nvalues:\n\n.. code-block:: python\n\n CONFIG = {\n \"name\": {\n \"default\": \"frank\",\n \"help\": \"Enter the name to use\",\n },\n }\n\nThis simple example presents the documentation for the configuration value\nand what the default value should be.\n\nVertically app-merged projects can add config items to their parent dynes like so:\n\n.. code-block:: python\n\n CONFIG = {\n \"new_item\": {\n \"type\": int,\n \"default\": 1,\n \"dyne\": \"idem\",\n },\n }\n\nMany more options can be used, but they will be covered in the reference\ndocument.\n\nThe CLI_CONFIG Dictionary\n=========================\n\nAdding a configuration value does not make it appear on the command line.\nEach application can be extended to include command line options.\nLets extend our earlier example to expose the \"name\" option as a command\nline argument:\n\n.. code-block:: python\n\n CLI_CONFIG = {\n \"name\": {},\n }\n CONFIG = {\n \"name\": {\n \"default\": \"frank\",\n \"help\": \"Enter the name to use\",\n },\n }\n\nThat's it! The \"name\" option is now available on the command line and can\nbe used as ``--name bob``.\n\nBut what if we want it to be a positional argument? Simple! Just add the\npositional option to the *CLI_CONFIG*:\n\n.. code-block:: python\n\n CLI_CONFIG = {\n \"name\": {\n \"positional\": True,\n },\n }\n CONFIG = {\n \"name\": {\n \"default\": \"frank\",\n \"help\": \"Enter the name to use\",\n },\n }\n\nYou can inherit cli args from another project. Say, for example that you want to implement the ``--output`` flag\nexactly the same way ``rend`` does, you can source it like this:\n\n.. code-block:: python\n\n CLI_CONFIG = {\n \"output\": {\n \"source\": \"rend\",\n },\n }\n\nMany more options exist that allow you to control every aspect of the user's\ncommand line experience.\n\nThe SUBCOMMANDS Dictionary\n==========================\n\nSometimes it is desirable to have subcommands. Subcommands allow your CLI\nto work in a way similar to the git cli, where you have multiple routines\nthat all can be called from a single command.\n\nLets add a few more things to our example so that we can have subcommands.\n\n.. code-block:: python\n\n CLI_CONFIG = {\n \"name\": {\n \"subcommands\": [\"test\", \"apply\"],\n },\n \"weight\": {},\n \"power\": {\n \"subcommands\": [\"apply\"],\n },\n }\n CONFIG = {\n \"name\": {\n \"default\": \"frank\",\n \"help\": \"Enter the name to use\",\n },\n \"weight\": {\n \"default\": \"150\",\n \"help\": \"Enter how heavy it should be\",\n },\n \"power\": {\n \"default\": \"100\",\n \"help\": \"Enter how powerful it should be\",\n },\n }\n\n SUBCOMMANDS = {\n \"test\": {\n \"help\": \"Used to test\",\n \"desc\": \"When running in test mode, things will be tested\",\n },\n \"apply\": {\n \"help\": \"Used to apply\",\n \"desc\": \"When running in apply mode, things will be applied\",\n },\n }\n\n\nIn this example we see that the option ``name`` will be available under\nthe subcommands ``test`` and ``apply``. The option ``power`` will be available\nonly under the subcommand ``apply`` and the option ``weight`` is globally\navailable.\n\nThe DYNE Dictionary\n===================\n\nThe *DYNE* dictionary allows you to control what dynamic names your app is\npresenting to other ``pop`` projects. This name gets used not only inside\nof ``pop-config`` but also inside of ``pop`` to determine what plugin subsystems\nthis application merges with. The *DYNE* system allows for your cli to be\nextended by third party code, enabling configuration options to be made\navailable to your application via external code.\n\nThe *DYNE* system is very powerful. But since it is not critical to getting\nstarted with ``pop-config`` it will be covered in more depth in another document.\n\n\nLog Module\n===================\n\nWithin the log module of pop-config there are several config options.\n\nIf \"log_plugin\" is set to \"rotating\", the \"log_handler_options\" config item can be set to something other than the defaults.\n\nThe two options are:\n\n1. maxBytes default: 1024*1024*100\n This option specifies the maximum size of each back up log file. Once a log file approaches this value the \"rotating\" module will save the file and create a new log file.\n\n2. backupCount default: 5\n This option tells the rotating module how many backup log files are allowed. As that number increases the oldest files are deleted.\n\n\nAcknowledgements\n================\n\n* `Img Shields <https://shields.io>`__ for making repository badges easy.\n",
"bugtrack_url": null,
"license": "Apache Software License 2.0",
"summary": "The official tool to allow for creating and app-merging configuration options for pop projects.",
"version": "12.0.4",
"project_urls": {
"Code": "https://gitlab.com/vmware/pop/pop-config",
"Homepage": "https://vmware.gitlab.io/pop/pop-config/en/latest/index.html",
"Issue tracker": "https://gitlab.com/vmware/pop/pop-config/issues"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2e04b810a7138ac6499888f52f9db6f245be8c44bd5aa8b2f22572fb97b0ab44",
"md5": "601c823f0ab95405369bfd5c33f5ed06",
"sha256": "6623cc1baf8d0708b6baae3cc71545174b5da4037d2d4e1e5ae165869f0f7579"
},
"downloads": -1,
"filename": "pop_config-12.0.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "601c823f0ab95405369bfd5c33f5ed06",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 38051,
"upload_time": "2023-09-26T23:32:50",
"upload_time_iso_8601": "2023-09-26T23:32:50.766331Z",
"url": "https://files.pythonhosted.org/packages/2e/04/b810a7138ac6499888f52f9db6f245be8c44bd5aa8b2f22572fb97b0ab44/pop_config-12.0.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f8fcdfa85daffc2fcbba395b1d34b8fe60b4fc2b65c667942ded5e687c8fc740",
"md5": "b48ed072ecc76616729f56929504a5ad",
"sha256": "15d99233a94345e07b29a19318ef8cea5d176c0d92186ce21146d979d6857844"
},
"downloads": -1,
"filename": "pop-config-12.0.4.tar.gz",
"has_sig": false,
"md5_digest": "b48ed072ecc76616729f56929504a5ad",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 29430,
"upload_time": "2023-09-26T23:32:52",
"upload_time_iso_8601": "2023-09-26T23:32:52.701588Z",
"url": "https://files.pythonhosted.org/packages/f8/fc/dfa85daffc2fcbba395b1d34b8fe60b4fc2b65c667942ded5e687c8fc740/pop-config-12.0.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-09-26 23:32:52",
"github": false,
"gitlab": true,
"bitbucket": false,
"codeberg": false,
"gitlab_user": "vmware",
"gitlab_project": "pop",
"lcname": "pop-config"
}
JSON