Metadata-Version: 2.1
Name: django-configen
Version: 1.0
Summary: A Django app for generating configuration files in a DRY way.
Home-page: https://www.github.com/bhch/django-configen
Author: Bharat Chauhan
Author-email: tell.bhch@gmail.com
License: BSD-3-Clause
Description: # django-configen
        
        A Django app for generating server configuration files, such as for Nginx, 
        uWSGI, Gunicorn etc. in a DRY way. 
        
        ## Introduction
        
        **The problem:**
        
        Configuration files stay pretty much the same for different projects. You're 
        often copying these config files from other projects and then only modifying 
        the file paths, domain name and other variables which are unique to this 
        project.
        
        This process is error-prone and repetitive. 
        
        **The solution:**
        
        This app solves it by generating config files from templates. So, instead 
        of maintaining config files, you maintain their templates. And then use this 
        app to render the templates with the project specific variables.
        
        You can copy the original templates to multiple projects and stay assured that 
        final generated config files will have appropriate paths and other variables.
        
        ## Installation
        
            pip install django-configen
        
        Add `configen` to `INSTALLED_APPS` list:
        
        ```python
        INSTALLED_APPS = [
            # ... 
            'configen',
        ]
        ```
        
        Add these settings to configure configen:
        
        ```python
        # where configen will look for config templates
        CONFIGEN_TEMPLATES_DIR = os.path.join(BASE_DIR, 'configs/templates')
        
        # where configen will keep the generated files
        CONFIGEN_OUTPUT_DIR = os.path.join(BASE_DIR, 'configs/output')
        
        # config context processors
        CONFIGEN_CONFIG_PROCESSORS = [
            'configen.config_processors.common',
        ]
        ```
        
        
        `CONFIGEN_CONFIG_PROCESSORS` is a list of config processor functions. They are 
        similar to Django's context processors and whatever data they return will be 
        made available to the config templates during compiling. 
        
        ## Basic usage
        
        The config processor that you just configured above 
        (`configen.config_processors.common`), 
        makes some common and helpful variables available for you in the config templates.
        
        These variables are:
        
         + `settings`: current settings file.
         + `project_dir_name`: name of the project directory
         + `virtualenv`: path to current virtualenv.
         + `python_interpreter`: path to current python interpreter
        
        Now you can write templates for your config files using Django's template 
        syntax.
        
        For this example, you can create an `nginx.conf` inside `configs/templates/` 
        directory and put this code in it:
        
            server {
        
                location /media  {
                    alias {{ settings.MEDIA_ROOT }};
                }
        
                location /static {
                    alias {{ settings.STATIC_ROOT }};
                } 
            }
        
        Run this command to compile the template:
        
            python manage.py configen
        
        It will generate the configuration file from the given template and populate 
        it with the given variables. The generated file will be inside the 
        `configs/output` directory.
        
        ## Providing extra context variables
        
        A quick way to provide extra context variables is by using 
        `CONFIGEN_DEFAULT_CONTEXT` setting:
        
        ```python
        CONFIGEN_DEFAULT_CONTEXT = {
            '*': {
                # variables listed here will be available to 
                # all templates
                'project_name': 'example',
            },
            'nginx.conf': {
                # variables listed here will be available only to
                # nginx.conf template
                'domain': 'example.com',
            },
            'uwsgi.ini': {
                # variables listed here will be available only to
                # uwsgi.ini template
                'module': 'myproject.wisgi',
            }
        }
        ```
        
        It should be mentioned that the context returned by `CONFIGEN_DEFAULT_CONTEXT` 
        will be overridden by context variables returned by config processors if the 
        names collide.
        
        ## Writing custom config processor functions
        
        Using `CONFIGEN_DEFAULT_CONTEXT` settings gives you a quick and basic way 
        to provide context variables to the templates. However, if you want to do some 
        extra calculations before returning the variables, this pattern becomes limiting.
        
        For those cases, configen supports providing context data from functions. 
        It works  similar to Django's context processors. However, to avoid name 
        confusion, we call them config processors.
        
        This is what a config processor function looks like:
        
        ```python
        def config_processor(template_name, *args):
            return {'var': 'hello'}
        ```
        
        The config processor will be passed a `template_name` argument which will let it 
        it know the name of the template being compiled. This is useful if you want to 
        return different data depending on the template. 
        
        To use your config processor, add this to your settings:
        
        ```python
        CONFIGEN_CONFIG_PROCESSORS = [
            'configen.config_processors.common',
            'path.to.config_processor',
        ]
        ```
        
        The order in which you list the config processors matters. The last config 
        processor will override the context variables from the previous processors in 
        case there are name collisions.
        
        If you run the `configen` command again, the variables returned by your config 
        processor will be available to the config templates.
        
        ### Passing arguments to config processors from command line
        
        You can pass extra arguments to your config processors from command line using 
        the `--extra` command option:
        
            python manage.py configen --extra arg1 arg2
        
        These arguments will be available under `args` argument in your config processor.
        
        See documentation for [`--extra`](#--extra) option for more.
        
        
        ## Changing the name of the output file
        
        Configen will save the output files with same name as the input template files. 
        This is okay if you have a single project but can become problematic if you 
        have multiple projects. 
        
        Suppose, you have two projects and both have a config template called `nginx.conf`. 
        The generated config files will also be called `nginx.conf` for both projects. 
        Now you can't copy both of these files in Nginx's config directory because of 
        the name collision. 
        
        So the general workaround for this problem to rename the files with the project 
        name, like `project1_nginx.conf`, `project2_nginx.conf` and this problem is 
        solved.
        
        Configen provides two ways to change the name of the output file.
        
        First, the simple way: Using `CONFIGEN_DEFAULT_META` setting:
        
        ```python
        CONFIGEN_DEFAULT_META = {
            '*': {
                'outfile': 'project1_{template_name}'
            }
        }
        ```
        
        `{template_name}` will be automatically replaced by the name of the template 
        including the file extension. 
        
        Just like with `CONFIGEN_DEFAULT_CONTEXT` setting, you can create keys 
        with the names of your config templates if you only want to override a particular 
        template's output file name.
        
        Another way to provide the meta data to configen is by returning a second dict from your 
        config processor like this:
        
        ```python
        def config_processor(template_name, *args):
            context = {'var': 'hello'}
        
            meta = {'outfile': 'project1_%s' % template_name}
        
            return (context, meta)
        ```
        
        Currently, there's only one option supported for meta data - `outfile`. 
        
        
        ## Settings
        
        ### `CONFIGEN_TEMPLATES_DIR`
        
        Path to the directory where configen will look for the config templates.
        
        ### `CONFIGEN_OUTPUT_DIR`
        
        Path to the directory where configen will keep the generated config files.
        
        ### `CONFIGEN_CONFIG_PROCESSORS`
        
        A list containing Python path to functions which will be called during generation 
        of each config template.
        
        Example:
        
        ```python
        CONFIGEN_CONFIG_PROCESSORS = [
            'configen.config_processors.common',
        
            'your.custom.processor',
        ]
        ```
        
        The `configen.config_processors.common` config processor provided by configen 
        makes some commonly used variables available to you in your config templates:
        
         + `settings`: current settings file.
         + `project_dir_name`: name of the project directory
         + `virtualenv`: path to current virtualenv.
         + `python_interpreter`: path to current python interpreter
        
        You can override these variables from your custom config processors, or leave 
        this processor out of the setting if you don't want it. 
        
        ### `CONFIGEN_DEFAULT_CONTEXT`
        
        A dictionary containing default context variables for generating config files.
        
        Example:
        
        ```python
        CONFIGEN_DEFAULT_CONTEXT = {
            '*': {
                # will be passed to all templates 
                'project_name': 'Example',
            },
            'nginx.conf': {
                # will be passed only to nginx.conf template
                'domain': 'example.com',
            },
            'uwsgi.ini': {
                'socket': '/tmp/example.sock',
            },
        }
        ```
        
        ### `CONFIGEN_DEFAULT_META`
        
        A dictionary for providing meta configuration information to configen about a 
        template.
        
        Currently only option supported is `outfile`. 
        
        Example:
        
        ```python
        CONFIGEN_DEFAULT_META = {
            '*': {
                # will be used for all templates 
                'outfile': 'myproject_{template_name}',
            },
            'nginx.conf': {
                # will be used only for nginx.conf template
                'outfile': 'myproject_nginx_blah_blah.conf',
            },
        }
        ```
        
        ## Command line options
        
        ### `template`
        
        Optional. Name of the template to compile. It should be relative to the path 
        set in `CONFIGEN_TEMPLATES_DIR` setting. If not provided, all the templates 
        present in the directory set by `CONFIGEN_TEMPLATES_DIR` setting are compiled.
        
        Example:
        
            python manage.py configen nginx.conf
        
        
        ### `--print`
        
        Print the compiled template to stdout. Useful if you want to inspect the output 
        without creating/overwriting the output file.
        
        Example:
        
            python manage.py configen --print
        
        
        ### `--extra`
        
        Extra arguments that you want to pass to your config processor functions.
        
        Example:
        
            python manage.py configen --extra arg1 arg2
        
        
        And then access these arguments like this:
        
        ```python
        def config_processor(template_name, *args):
            print(args)
            # output: ('arg1', 'arg2',)
        ```
        
        **Important:** Doing `--extra arg1=hello arg2=world` will not work like you 
        would expect. `arg1=hello` will be parsed as a whole, instead of argument name 
        and value. 
        
        The value your config processor will recieve is this:
        
        ```python
        def config_processor(template_name, *args):
            print(args)
            # output: ('arg1=hello', 'arg2=world',)
        ```
        
        Hence, we used the word "arguments" and not "keyword-arguments". You can't pass 
        arbitrary named keyword arguments via command line, at least not with `argparse` 
        which is used by Django to parse commands.
        
        If you want to be able to receive named keyword arguments, you'll need to parse 
        these arguments yourself.
        
        
        ### `--verbosity`
        
        The command will print some debug output while compiling templates. You can turn 
        it off like this:
        
            python manage.py configen --verbosity 0
        
        
        ## License
        
        [BSD-3-Clause](LICENSE.txt)
Platform: UNKNOWN
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Requires-Python: >= 3.4
Description-Content-Type: text/markdown
