Metadata-Version: 2.1
Name: pop-config
Version: 6.9
Summary: UNKNOWN
Home-page: https://www.saltstack.com
Author: Thomas S Hatch
Author-email: thatch45@gmail.com
License: UNKNOWN
Description: ==========
        Pop Config
        ==========
        
        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.
        
        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.
        
        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.
        
Platform: UNKNOWN
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Development Status :: 5 - Production/Stable
Requires-Python: >=3.6
Description-Content-Type: text/x-rst
