A collection of classes and commands for automated command line scripting using Python.
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 

146 lines
5.2 KiB

.. _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.