python-scripttease/docs/source/introduction.rst

.. _introduction:

************
Introduction
************

Overview
========

The Script Tease package takes plain text instructions in INI or YAML (currently untested) format and converts them into valid command line statements for a given platform (currently CentOS and Ubuntu are supported). It does *not* provide support for executing these statements.

Architecture
============

The provided command line interface (the ``tease`` command) loads configuration files containing instructions and may output these as a Bash script or as documentation.

However, it is possible to create your own implementation to provide input and gather output from the Script Tease library.

.. image:: _static/images/architecture-diagram.png

Concepts
========

Loaders
-------

A Loader instance is responsible for reading configuration files and parsing the contents into a) a command name, b) arguments, c) keyword arguments.

Command instances are *not* created by the loader. This is the job of the :py:func:`scriptease.lib.factories.command_factory`.

Separating Command generation from loading configuration files makes the loader classes simpler, and keeps the overall system more flexible.

Command Functions
-----------------

Commands are represented by Python functions. All functions return either a :py:class:`scripttease.lib.commands.base.Command` instance, or in some cases an instance of :py:class:`scripttease.lib.commands.base.MultipleCommands`. (The Template command may also be returned; it is handled specially.)

.. code-block:: python

    def copy(from_path, to_path, overwrite=False, recursive=False, **kwargs):
        # ...

You could of course use this function directly:

.. code-block:: python

    command = copy("/etc", "/tmp/", recursive=True)
    print(command.get_statement())

But the point of Script Tease is to take plain text instructions and turn them into command line statements.

Mappings
--------

So the `copy` function is mapped to a name that may be used in a configuration file:

.. code-block:: python

    MAPPINGS = {
        # ...
        'copy': copy,
        # ...
    }

Such mappings are used by the :py:func:`scriptease.lib.factories.command_factory` to match a command name in a configuration file to the Python function that instantiates the Command.

Configuration File
------------------

The configuration that invokes this command would like like:

.. code-block:: ini

    [create a copy of the etc directory]
    copy: /etc /tmp/
    recursive: yes

Note that the configuration is self-documenting, and in fact, it is possible to output commands as documentation rather than a script.

Variables File
--------------

Prior to a Loader processing commands, configuration files may be parsed as Jinja2 templates. This allows variables to be loaded from a file and passed to the loader as a Context instance.

.. code-block:: ini

    # variables.ini
    [db_name]
    comment: The name of the database is the same as the domain name.
    value: example_app

In the configuration file:

.. code-block:: ini

    [create the database]
    pgsql.create: {{ db_name }}

Variables are collected in a :py:class:`scripttease.lib.contexts.Context` instance and are passed to the Loader.

Terms and Definitions
=====================

command
    When used in Script Tease documentation, this is a command instance which contains the properties and parameters for a command line statement.

profile
    A profile represents the commands available to a specific operating system.

statement
    A specific statement (string) to be executed. A *statement* is generated by a *command*.

License
=======

Script Tease is released under the BSD 3 clause license.

.. code-block:: text

    Copyright (c) Pleasant Tents, LLC

    All rights reserved.

    Redistribution and use in source and binary forms, with or without modification,
    are permitted provided that the following conditions are met:

        * Redistributions of source code must retain the above copyright notice,
          this list of conditions and the following disclaimer.
        * Redistributions in binary form must reproduce the above copyright notice,
          this list of conditions and the following disclaimer in the documentation
          and/or other materials provided with the distribution.
        * Neither the name of Pleasant Tents, LLC nor the names of its contributors
          may be used to endorse or promote products derived from this software
          without specific prior written permission.

    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
    "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
    A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
    PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
    LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
    NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
    SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.