{
    "info": {
        "author": "Michael Rohan",
        "author_email": "mrohan@vmware.com",
        "bugtrack_url": null,
        "classifiers": [
            "Development Status :: 4 - Beta",
            "Framework :: Django",
            "Framework :: Django :: 1.7",
            "Framework :: Django :: 2.0",
            "Intended Audience :: Developers",
            "License :: OSI Approved :: BSD License",
            "Natural Language :: English",
            "Operating System :: OS Independent",
            "Programming Language :: Python",
            "Programming Language :: Python :: 2.7",
            "Programming Language :: Python :: 3.5",
            "Topic :: Software Development :: Libraries :: Python Modules"
        ],
        "description": "# django-yamlconf\n\n`django_yamlconf` is part of VMware's support of open source development\nand community.\n\nHandle YAML based Django settings: load Django settings from YAML files\nbased on a Django project name.  The YAML files loaded start with a YAML\nfile in the directory containing the Django settings file and then loads\nany other YAMLCONF files up the directory tree from the initial file.  Values\nfrom files higher up the directory tree over-ride lower in the tree.  The\ncontents of the YAML file simply defines values that over-ride (or add to)\nattributes of the standard Django settings file, e.g., for the project\n\"buildaudit\", the settings.py file could contain:\n\n```python\n    DEBUG = True\n```\n\ni.e., the value for development.  This can be redefined via a `buildaudit.yaml`\nfile using the definition:\n\n```python\n    DEBUG: false\n```\n\nIf the environment variable `YAMLCONF_CONFFILE` is defined, it uses as the\nfinal YAML file loaded (in this case, the file name does not need to match\nthe project name and it can be located anywhere in the file system).\n\n## License\n\n`django-yamlconf` is release under the BSD-2 license, see the LICENSE file.\n\nSPDX-License-Identifier: BSD-2-Clause\n\n## Usage\n\nThe YAMLCONF definitions are added to the Django settings file by\nincluding a call to the `load` function in the settings file.  This would\nnormally be towards the end of the settings file.  The simplest, and\nlikely normal usage is to call without arguments.  YAMLCONF will infer\nthe project information from the call stack.  For a standard Django\napplication structure, the settings file:\n\n```\n    myproject/myproject/settings.py\n```\n\nwould contain the development oriented definitions, e.g., database\ndefinitions for user and password for a development database.  The\nsettings file would then end with a call the the `load` function.\nAdditional definitions could be defined after the `load` function\nto update conditional definitions, e.g., if `DEBUG` is enabled.\n\n```python\nimport django_yamlconf\n\nDATABASES = {\n    'default': {\n        'NAME': 'example',\n        'USER': 'example',\n        'PASSWORD': 'example',\n        'HOST': 'localhost',\n        ...\n    }\n}\n...\n\ndjango_yamlconf.load()\n```\n\nOn a production server, for this example, a `myproject.yaml` would be put in\nplace containing the host name for the production database and the password\nfor the example user (assuming production is using the same database name\nand username).  In this example, a random `pwgen` password is used:\n\n```yaml\nDATABASES.default.PASSWORD: 'zibiemohjuD6foh0'\nDATABASES.default.HOST: 'myproject-db.eng.vmware.com'\n```\n\nSee the `load` function for more information on other optional\narguments.\n\n## Management Commands\n\nYAMLCONF includes three management commands (`django_yamlconf` needs to be\nadded to the `INSTALLED_APPS` to add these commands):\n\n* `ycexplain`: explain where an attribute value was defined\n\n* `yclist`: list the attribute values defined via YAMLCONF\n\n* `ycsysfiles`: Create system control files based on attribute controlled\n  template files\n\nThe attributes available to the management commands can be extended using\nmethods returning dictionaries of values.  The method names can be defined\nin the `settings` file or via a YAMLCONF file via the attribute\n`YAMLCONF_ATTRIBUTE_FUNCTIONS`, e.g.,\n\n```yaml\nYAMLCONF_ATTRIBUTE_FUNCTIONS:\n  - 'health_checks.ycattrs.attributes'\n```\n\nAs can be seen from the example method above, these additional attibutes\nare primarily used with the `ycsysfiles` command.\n\n### `ycexplain` Command\n\nThis `ycexplain` gives information on the value defined by the set of YAML\nfiles loaded for an application along with any documentation and information\non eclipsed attribute values lower in the directory tree structure.  For\nexample, for the `DEBUG` attribute:\n\n```\n    $ python manage.py ycexplain DEBUG\n    ---------------------------\n    DEBUG = \"False\" (via \"/u/mrohan/clients/xmpl/buildaudit.yaml\")\n\n    Documentation:\n        Enable or disable debugging functionality.  On the production\n        server this attribute should be set to false\n\n    Eclipsed values:\n        \"True\" via \"/u/mrohan/clients/xmpl/buildaudit/buildaudit.yaml\"\n        \"True\" via \"buildaudit.settings\"\n```\n\n### `yclist` Command\n\nThe `yclist` command simply lists the attributes defined via YAML files,\ne.g.,:\n\n```shell\n    $ python manage.py yclist\n    Listing YAMLCONF managed attributes\n\n    ALLOWED_HOSTS                   ['localhost']\n    BACKUP_CONFIG.directory         {BASE_DIR}/backup\n    BASE_DIR                        /home/mrohan/clients/osstp-yc/webapps\n    CONTROL_FILE                    {WEBAPPS_DIR}/osstpmgt.yaml\n    DATABASES.default.CONN_MAX_AGE  600\n    DATABASES.default.HOST          {DBHOST}\n    DATABASES.default.NAME          {DBNAME}\n    DATABASES.default.PASSWORD      {DBPASSWORD}\n    DATABASES.default.USER          {DBUSER}\n    DBHOST                          localhost\n    DBNAME                          osstp\n    DBPASSWORD                      A-Password\n    DBUSER                          osstp\n    INSTALL_DIR                     /var/oss/osstp\n    MANAGE_PY                       {WEBAPPS_DIR}/manage.py\n    OS_MACHINE                      x86_64\n    OS_NODE                         mrohan-osstp-yc\n    OS_PROCESSOR                    x86_64\n    OS_RELEASE                      4.4.0-101-generic\n    OS_SYSTEM                       Linux\n    ROOT_URL                        https://{SERVER_NAME}\n    SCM_ID                          v2017.07.13-103-gfac514b\n    SERVER_NAME                     localhost\n    TOP_DIR                         /home/mrohan/clients/osstp-yc\n    USER                            mrohan\n    VIRTUAL_ENV                     /home/mrohan/clients/venv\n    WEBAPPS_DIR                     {BASE_DIR}\n    YAMLCONF_SYSFILES_DIR           {BASE_DIR}/osstpmgt/templates/sys\n\n    Use \"ycexplain\" for more information on individual attributes\n```\n\n### `ycsysfiles` Command\n\nThe `ycsysfiles` management command supports the creation of system\ncontrol files, e.g., Apache configuration files, based on the attributes\ndefined via YAMLCONF files.  The command scans the directory defined by\nby the attribute, e.g.,:\n\n```yaml\n    YAMLCONF_SYSFILES_DIR: '{BASE_DIR}/templates/sys'\n```\n\nfor each file found, it\n\n1. Maps it to a file system path by stripping the `YAMLCONF_SYSFILES_DIR`\n   prefix and expanding attribute references (yes, that paths under this\n   directory will contain `{` and `}` characters).\n\n2. If the mapped file exists and is writable to the user running the\n   `ycsysfiles` command, it is updated with the contents generated by\n   Django template engine with YAMLCONF defined attributes being\n   available for substitution in the templates or use for conditionals.\n\nFor example, the Django tutorial implementations under the `examples`\ndirectory contains, within the `mysite/templates/sys` directory, the template\nfiles:\n\n1. `etc/apache2/sites-available/mysite.conf`, this template would be\n   used to create the system file `/etc/apache2/sites-available/mysite.conf`\n   (the Apache site config file on an Ubuntu system).\n\n2. `{BASE_DIR}/sysfiles.txt`, this template would be used to create the\n   file `sysfiles.txt` relative the directory where the Django application\n   is installed.  E.g., if installed in `/var/mysite`, the file\n   `/var/mysite/sysfiles.txt` would be created.\n\nThe paths under the `YAMLCONF_SYSFILES_DIR` directory can reference\nYAMLCONF defined attributes via standard Python key based format\nreferences, as with `BASE_DIR` above.\n\nThe attributes available can be extended using the\n`YAMLCONF_ATTRIBUTE_FUNCTIONS` attribtue.  This makes attributes based\non, e.g., the contents of the Django application database available when\nprocessing files.  A contrived example would be, in a `ycattrs.py` file\n(conventionally in the same directory as the `settings.py` file):\n\n```python\ndef userlist():\n    return {\n        'USERS': User.objects.all(),\n    }\n```\n\n## Support for Dictionaries\n\nYAMLCONF uses the \".\" character to identify attributes defined as part of a\ndictionary, e.g., the DATABASES attribute.  To set, e.g., the password for\na database connection:\n\n```yaml\n    DATABASES.default.PASSWORD: some-secret-password\n```\n\nIt is considered an error if dotted name refers to a settings attribute\nthat is not an dictionary, the setting is ignored by YAMLCONF.\n\nThe dotted notation should be used to update dictionaries already defined\nin the settings file.  To add a new dictionary, a YAML dictionary definition\nshould be used, e.g.,:\n\n```yaml\n    NEW_DICTIONARY:\n        key1: value1\n        key2: value2\n```\n\n## Attribute Substitution\n\nFrequently, attributes values are defined in terms of other attribute values,\nmost commonly using the base directory to define other directories.  The\nYAMLCONF allows other attributes to be referenced using the Python named\nformatting syntax, e.g.,:\n\n```yaml\n    LOG_DIR: \"{BASE_DIR}/log\"\n```\n\nCurrently only attributes defined via YAML files can be used in this way.\nTo disable this on a per-attribute basis, the `:raw` qualifier should\nbe defined to modify the behaviour for attribute, e.g.,:\n\n```yaml\n    LOGGING.formatters.simple.format: '%(asctime)s %(levelname)s %(message)s'\n    LOGGING.formatters.simple.format:raw: True\n```\n\n## Hiding values\n\nThe YAMLCONF includes an experimental view to handle URLs to display\nattributes (should only be used in a debugging context), e.g., adding\nthe URL definition to your application:\n\n    url(r'^yamlconf/', include('django_yamlconf.urls')),\n\nwill display the YAMLCONF attributes.  For older versions of Django, the\n`namespace` needs to be explictly defined:\n\n    url(r'^yamlconf/', include('django_yamlconf.urls', namespace='django_yamlconf')),\n\nAn example of the page displayed is:\n\n![Attributes Index Page](images/yamlconf-list.png \"YAMLCONF Index Page\")\n\nBy default, any attribute value with the string `PASSWORD` in the name\nwill have their values hidden in the HTML displayed.  Other, sensitive,\nvalues can be explicitly hidden by defining the qualifier attribute\n`:hide`, e.g.,:\n\n```yaml\n    APIKEY: 'my-api-key'\n    APIKEY:hide: True\n```\n\n## Extending Values\n\nFor list values, the qualifier attributes `:prepend` and `:append`\ncan be used to extend the underlying definition, e.g., add another admin\nuser, the following definition can be used:\n\n```yaml\n    ADMINS:append: 'someuser@vmware.com'\n```\n\nThe value of `:prepend` or `:append` qualified attribute can be\neither a single value, as above, or a list of values.  When a list is\ngiven, the attribute is extend with the extra values, e.g.,:\n\n```yaml\n    ADMINS:append:\n      - 'someuser1@vmware.com'\n      - 'someuser2@vmware.com'\n```\n\nNormally, list values in the settings file are simply unordered lists.  There\nare, however, some values where the order matters, in particular, the\n`MIDDLEWARE` list.  A middleware that short-circuits the handling of\nrequests would need to be placed at the beginning of the list.  This is the\nrationale for the `:prepend` functionality.\n\n## Pre-defined Attributes\n\nThe YAMLCONF module predefines the following attributes which can be used,\nalong with other attributed defined, via attribute substitution:\n\n`BASE_DIR`\n    The directory containing the `setting.py` file\n\n`PYTHON`\n    This is a dictionary giving the major, minor, micro, releaselevel\n    serial values for the Python interpretor\n\n`OS_MACHINE`\n    The value of the `platform.machine()` function, e.g., `x86_64`\n\n`OS_NODE`\n    The value of the `platform.node()` function, the system short name\n\n`OS_PROCESSOR`\n    The value of the `platform.machine()` function, e.g., `x86_64`\n\n`OS_RELEASE`\n    The value of the `platform.release()` function, e.g., `4.4.0-101-generic`\n\n`OS_SYSTEM`\n    The value of the `platform.system()` function, e.g., `Linux`\n\n`TOP_DIR`\n    The directory above BASE_DIR\n\n`USER`\n    The login name of the current user\n\n`VIRTUAL_ENV`\n    If run within a Python virtual environment, this attribute is defined\n    to be the path to the environment, otherwise it has the value ``None``\n\n## Attribute Documentation\n\nAppending `:doc` to an attribute name in a YAML file defines a documentation\nstring for the attribute.  This should be used to give information on the\nexpected value for the attribute and how the value might differ on production,\nbeta and development servers, e.g., documentation for the DEBUG attribute\nwould be defined using the YAML:\n\n```yaml\n    DEBUG:doc: |\n        Enable or disable debugging functionality.  On the production server\n        this attribute should be set to false\n```\n\n## Typical Structure\n\nOn a typical production system for the \"buildaudit\" app, a local\n`buildaudit.yaml` would exist in, e.g., the `/var/www` directory.  This\nwould contain the production passwords, debug settings, etc.  Under this\ndirectory, a `webapps` directory could contain another `buildaudit.yaml`\nfile possibly generated by a build process which could define attributes\nidentifying the build, the Git Hash for the code, build time, etc. Finally,\na `buildaudit.yaml` file co-located with the settings.py file giving the\nbase attributes and their documentation strings:\n\n```\n    +- /var/www\n        +- buildaudit.yaml\n        +- webapps\n           +- buildaudit.yaml\n           +- buildaudit\n               +- buildaudit.yaml\n               +- settings.py\n```\n\n## Public Methods\n\nThe primary public method is the `load` method which loads the attribute\ndefinitions from YAML file located in the directory tree.  Other methods\nare exported, and are documented here, but it is expected that these\nmethods are only used by the management commands.\n\n### `add_attributes` Function\n\n```python\nadd_attributes(settings, attributes, source)\n```\n\nParameters:\n* `settings`, the Django settings module\n* `attributes`, the dictionary of name/values pairs to add\n* `source`, the name for the source (displayed by `ycexplain`)\n\nAdd a set of name value pairs to the set of attributes, e.g., attributes\ndefined on the command line for management commands.  Since this occurs\nafter Django has loaded the settings, this function *does not*, in general,\nchange behaviour of Django.  It is used to add attribute definitions from\nmanagement command lines.  While this does not impact the behaviour of\nDjango, it does make the attributes available for use in templates for\nthe `ycsysfiles` command.\n\n### `defined_attributes` Function\n\n```python\ndefined_attributes(settings)\n```\n\nParameters:\n* `settings`, the Django settings module\n\nReturn a dictionary giving attribute names and associated values.\nThis dictionary is used as the variables when rendering templates\nfor the `ycsysfiles` command.\n\n### `explain` Function\n\n```python\nexplain(name, settings, stream=sys.stdout)\n```\n\nParameters:\n* `name`, the YAMLCONF controlled setting name\n* `settings`, the Django settings module\n* `stream`, the stream to write the explanation text\n\nExplain the source for an attribute definition including sources that\nwere eclipsed by higher level YAML definition files.  If the attribute\nhas associated documentation, it is also printed.\n\nThis routine is only used by the YAMLCONF management commands.\n\n### `list_attrs` Function\n\n```python\nlist_attrs(settings=None, stream=sys.stdout)\n```\nParameters:\n* `settings`, the Django settings module\n* `stream`, the stream to write the list text\n\nWrite a list of attributes managed by YAMLCONF to the given stream.  Additional\ninformation can be printed using the `explain` routine.\n\n### `load` Function\n\n```python\nload(syntax=\"yaml\", settings=None, base_dir=None, project=None)\n```\n\nParameters:\n* `syntax`, the name a Python module with a `load` method, e.g., the\n  default is `yaml.load`.  Other possibilities could be `json` to use\n  JSON formatted file or, even, `pickle` but that would be strange.  The\n  `syntax` name is also used as the file extension for the YAMLCONF files.\n  The `syntax` argument name a Python module with a `load` method, e.g.,\n  the default, `yaml` support a `load` method to load the definition from\n  a file.  Other possibilities could be `json` to use JSON formatted file\n  or, even, `pickle` but that would be strange.  The `syntax` name is also\n  used as the file extension for the YAMLCONF files.\n* `settings`, the module containing the Django settings.  This is\n  determined from the call stack if no module is given.\n* `base_dir`, the starting directory when searching for YAMLCONF files,\n  defaults to the directory containing the settings module.\n* `project`, the name of the Django project, defaults to the name of\n  the directory containing the settings modules.\n\nLoad the set of YAML files for a Django project.  The simplest usage\nis to call this at the end of a settings file.  In this context, no\narguments are needed.\n\n### `sysfiles` Function\n\n```python\nsysfiles(create, no-op, settings, rootdir=\"\", render=None)\n```\n\nParameters:\n\n* `create`, the template files should be created, normally will only\n  update files that already exist on the system and are writable.\n* `no-op`, no-op mode, print what would be done.\n* `settings`, the Django settings module\n* `rootdir`, the directory to create the system files, defaults to `/`,\n  i.e., the root file system.\n* `render`, the rendering engine, if not given, defaults to Django's\n  `render_to_string`\n\nTraverse the sys templates directory expanding files to the destination\ndirectory.\n\n## Limitations\n\nSome of the current limitations for this implementation are:\n\n* Currently cannot substitute list values, e.g.,:\n\n```yaml\n    ADMINS:\n      - jsmith\n      - auser\n    MANAGER: \"{ADMINS}\"\n```\n\n* The pre-defined attributes should also include the host IP address\n\nThese might be addressed if the need arises.\n\n## Examples\n\nThe examples are based on the `polls` example from the\n[Django Project](https://www.djangoproject.com/) web site.  There are two\nflavors of this example:\n\n1. Under Django version 1.11 in the directory `examples/django-1.11`\n2. Under Django version 2.0 in the directory `examples/django-2.0`\n\nSee the\n[Examples Directory on GitHub](https://github.com/vmware/django-yamlconf/tree/master/examples).\n\nThe examples for both versions of Django behaviour similarly: there are\n`Makefile` targets to:\n\n* `init` initialize a local SQLite database for the application (should\n  be the first target executed, if experimenting.\n* `runserver` to run a local server\n* General utility targets for YAMLCONF: `yclist`, `ycexplain` and\n  `ycsysfiles`.\n\nAn example of the usage of YAMLCONF, would be, e.g., in a production\nenvironment, switching to a PostgreSQL database via the creation of\na `mysite.yaml` file (would need to explicitly install the `psycopg2-binary`\nmodule):\n\n```yaml\nDATABASES.default:\n    ENGINE: django.db.backends.postgresql_psycopg2\n    NAME: mysite\n    USER: mysite\n    PASSWORD: my-password\n    HOST: localhost\n    PORT: ''\n```\n\n## Releases & Major Branches\n\n### Version 1.0.0\n\n* Initial public release (tagged with `v1.0.0`)\n\n## Contributing\n\nThe `django-yamlconf` project team welcomes contributions from the\ncommunity. Before you start working with `django-yamlconf`, please read\nour [Developer Certificate of Origin](https://cla.vmware.com/dco). All\ncontributions to this repository must be signed as described on that\npage. Your signature certifies that you wrote the patch or have the right\nto pass it on as an open-source patch. For more detailed information,\nrefer to [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## Authors\n\nCreated and maintained by Michael Rohan <mrohan@vmware.com>\n\nCopyright \u00a9 2018-2019, VMware, Inc.  All rights reserved.",
        "description_content_type": "",
        "docs_url": null,
        "download_url": "",
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "https://github.com/vmware/django-yamlconf",
        "keywords": "django",
        "license": "BSD-2",
        "maintainer": "",
        "maintainer_email": "",
        "name": "django-yamlconf",
        "package_url": "https://pypi.org/project/django-yamlconf/",
        "platform": "Any",
        "project_url": "https://pypi.org/project/django-yamlconf/",
        "project_urls": {
            "Homepage": "https://github.com/vmware/django-yamlconf"
        },
        "release_url": "https://pypi.org/project/django-yamlconf/1.1.0/",
        "requires_dist": null,
        "requires_python": "",
        "summary": "Define Django settings in local YAML (or JSON) files",
        "version": "1.1.0"
    },
    "last_serial": 4952149,
    "releases": {
        "1.0.0": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "c196de63b86d8101968cadacfe905ce3",
                    "sha256": "38e003388c7adb9ad749fa9d39663b6ad593202a1171b8471600def66f770b7d"
                },
                "downloads": -1,
                "filename": "django-yamlconf-1.0.0.tar.gz",
                "has_sig": false,
                "md5_digest": "c196de63b86d8101968cadacfe905ce3",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 27456,
                "upload_time": "2018-08-13T23:31:25",
                "url": "https://files.pythonhosted.org/packages/dc/7f/2c487eaa6ce4b408bf5dc94237016dff45c4a83055cd9d7050ffab2f0e38/django-yamlconf-1.0.0.tar.gz"
            }
        ],
        "1.1.0": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "0d48c1e2371eee5c21cc8e182204b1af",
                    "sha256": "e51b899d21350804765900ef933bcc9e5ae379cf419db34737e4e9697c83966e"
                },
                "downloads": -1,
                "filename": "django-yamlconf-1.1.0.tar.gz",
                "has_sig": false,
                "md5_digest": "0d48c1e2371eee5c21cc8e182204b1af",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 28153,
                "upload_time": "2019-03-18T03:45:01",
                "url": "https://files.pythonhosted.org/packages/19/0d/b8becc40b71dcab58dec7e4cf8ff09186d8ad8f8abe0f8252024dd0dcf53/django-yamlconf-1.1.0.tar.gz"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "0d48c1e2371eee5c21cc8e182204b1af",
                "sha256": "e51b899d21350804765900ef933bcc9e5ae379cf419db34737e4e9697c83966e"
            },
            "downloads": -1,
            "filename": "django-yamlconf-1.1.0.tar.gz",
            "has_sig": false,
            "md5_digest": "0d48c1e2371eee5c21cc8e182204b1af",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 28153,
            "upload_time": "2019-03-18T03:45:01",
            "url": "https://files.pythonhosted.org/packages/19/0d/b8becc40b71dcab58dec7e4cf8ff09186d8ad8f8abe0f8252024dd0dcf53/django-yamlconf-1.1.0.tar.gz"
        }
    ]
}