.. -*- coding: utf-8 -*-
   Copyright © 2019-2025, Broadcom, Inc.  All rights reserved.
   SPDX-License-Identifier: BSD-2-Clause

.. _mgmtcmds:

Management Commands
-------------------

YAMLCONF includes three management commands (``django_yamlconf`` needs
to be added to the ``INSTALLED_APPS`` to add these commands):

-  ``ycexplain``: explain where an attribute value was defined

-  ``yclist``: list the attribute values defined via YAMLCONF

-  ``ycsysfiles``: Create system control files based on attribute
   controlled template files

The attributes available to the management commands can be extended
using methods returning dictionaries of values. The method names can be
defined in the ``settings`` file or via a YAMLCONF file via the
attribute ``YAMLCONF_ATTRIBUTE_FUNCTIONS``, e.g.,

.. code:: yaml

    YAMLCONF_ATTRIBUTE_FUNCTIONS:
      - 'health_checks.ycattrs.attributes'

As can be seen from the example method above, these additional attibutes
are primarily used with the ``ycsysfiles`` command.

.. _mgmtcmds-ycexplain:

``ycexplain`` Command
~~~~~~~~~~~~~~~~~~~~~

This ``ycexplain`` gives information on the value defined by the set of
YAML files loaded for an application along with any documentation and
information on eclipsed attribute values lower in the directory tree
structure. For example, for the ``DEBUG`` attribute::

        $ python manage.py ycexplain DEBUG
        ---------------------------
        DEBUG = "False" (via "/u/mrohan/clients/xmpl/buildaudit.yaml")

        Documentation:
            Enable or disable debugging functionality.  On the production
            server this attribute should be set to false

        Eclipsed values:
            "True" via "/u/mrohan/clients/xmpl/buildaudit/buildaudit.yaml"
            "True" via "buildaudit.settings"

.. _mgmtcmds-yclist:

``yclist`` Command
~~~~~~~~~~~~~~~~~~

The ``yclist`` command simply lists the attributes defined via YAML
files, e.g.,:

.. code:: shell

        $ python manage.py yclist
        Listing YAMLCONF managed attributes

        ALLOWED_HOSTS                   ['localhost']
        BACKUP_CONFIG.directory         {BASE_DIR}/backup
        BASE_DIR                        /home/mrohan/clients/osstp-yc/webapps
        CONTROL_FILE                    {WEBAPPS_DIR}/osstpmgt.yaml
        DATABASES.default.CONN_MAX_AGE  600
        DATABASES.default.HOST          {DBHOST}
        DATABASES.default.NAME          {DBNAME}
        DATABASES.default.PASSWORD      {DBPASSWORD}
        DATABASES.default.USER          {DBUSER}
        DBHOST                          localhost
        DBNAME                          osstp
        DBPASSWORD                      A-Password
        DBUSER                          osstp
        INSTALL_DIR                     /var/oss/osstp
        MANAGE_PY                       {WEBAPPS_DIR}/manage.py
        OS_MACHINE                      x86_64
        OS_NODE                         mrohan-osstp-yc
        OS_PROCESSOR                    x86_64
        OS_RELEASE                      4.4.0-101-generic
        OS_SYSTEM                       Linux
        ROOT_URL                        https://{SERVER_NAME}
        SCM_ID                          v2017.07.13-103-gfac514b
        SERVER_NAME                     localhost
        TOP_DIR                         /home/mrohan/clients/osstp-yc
        USER                            mrohan
        VIRTUAL_ENV                     /home/mrohan/clients/venv
        WEBAPPS_DIR                     {BASE_DIR}
        YAMLCONF_SYSFILES_DIR           {BASE_DIR}/osstpmgt/templates/sys

        Use "ycexplain" for more information on individual attributes

.. _mgmtcmds-ycsysfiles:

``ycsysfiles`` Command
~~~~~~~~~~~~~~~~~~~~~~

The ``ycsysfiles`` management command supports the creation of system
control files, e.g., Apache configuration files, based on the attributes
defined via YAMLCONF files. The command scans the directory defined by
by the attribute, e.g.,:

.. code:: yaml

        YAMLCONF_SYSFILES_DIR: '{BASE_DIR}/templates/sys'

for each file found, it

1. Maps it to a file system path by stripping the
   ``YAMLCONF_SYSFILES_DIR`` prefix and expanding attribute references
   (yes, that paths under this directory will contain ``{`` and ``}``
   characters).

2. If the mapped file exists and is writable to the user running the
   ``ycsysfiles`` command, it is updated with the contents generated by
   Django template engine with YAMLCONF defined attributes being
   available for substitution in the templates or use for conditionals.

For example, the Django tutorial implementations under the ``examples``
directory contains, within the ``mysite/templates/sys`` directory, the
template files:

1. ``etc/apache2/sites-available/mysite.conf``, this template would be
   used to create the system file
   ``/etc/apache2/sites-available/mysite.conf`` (the Apache site config
   file on an Ubuntu system).

2. ``{BASE_DIR}/sysfiles.txt``, this template would be used to create
   the file ``sysfiles.txt`` relative the directory where the Django
   application is installed. E.g., if installed in ``/var/mysite``, the
   file ``/var/mysite/sysfiles.txt`` would be created.

The paths under the ``YAMLCONF_SYSFILES_DIR`` directory can reference
YAMLCONF defined attributes via standard Python key based format
references, as with ``BASE_DIR`` above.

The attributes available can be extended using the
``YAMLCONF_ATTRIBUTE_FUNCTIONS`` attribtue. This makes attributes based
on, e.g., the contents of the Django application database available when
processing files. A contrived example would be, in a ``ycattrs.py`` file
(conventionally in the same directory as the ``settings.py`` file):

.. code:: python

    def userlist():
        return {
            'USERS': User.objects.all(),
        }