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