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.
166 lines
5.5 KiB
166 lines
5.5 KiB
.. _configuration:
|
|
|
|
*************
|
|
Configuration
|
|
*************
|
|
|
|
Generating Commands From a File
|
|
===============================
|
|
|
|
The :py:class:`scripttease.parsers.ini.Config` class may instantiate commands by loading a configuration file.
|
|
|
|
.. note::
|
|
Additional formats such as JSON or YAML may be supported in the future.
|
|
|
|
An example file:
|
|
|
|
.. code-block:: ini
|
|
|
|
[install apache]
|
|
install: apache2
|
|
|
|
[create the web site directory]
|
|
mkdir: /var/www/domains/example_com/www
|
|
recursive: yes
|
|
|
|
[set permissions on the website directory]
|
|
perms: /var/www/domains/example_com/www
|
|
group: www-data
|
|
mode: 775
|
|
owner: www-data
|
|
|
|
Notes regarding this format:
|
|
|
|
- This is the standard format for Python's ConfigParser. If you prefer, you may use ``=`` instead of ``:``.
|
|
- The first line is the INI section and is used as the default comment.
|
|
- The command name must be the *first* option in the section.
|
|
- The arguments for the command appear as the value of the first option in the section. Arguments are separated by a
|
|
space.
|
|
- Arguments that should be treated as a single value should be enclosed in double quotes.
|
|
- ``yes`` and ``no`` are interpreted as boolean values.
|
|
- List values, where required, are separated by commas.
|
|
|
|
Common Parameters
|
|
-----------------
|
|
|
|
All commands support the following common parameters:
|
|
|
|
- ``comment``: A comment regarding the command.
|
|
- ``condition``: A condition for execution. For example, ``! -f /path/to/some/file.txt``
|
|
- ``cd``: The path from which a command should be executed.
|
|
- ``environments``: A string or list of strings indicating the operational environments in which the command runs. This
|
|
is *not* used by default, but may be used to programmatically filter commands for a specific environment. For example,
|
|
development versus live.
|
|
- ``prefix``: A statement to be added prior to executing the command.
|
|
- ``register``: A variable name to which the the success or failure (exit code) of the statement is captured.
|
|
- ``shell``: The shell used to run the commands. For example, ``/bin/bash``. This is generally not important, but can
|
|
be a problem when attempting to execute some commands (such as Django management commands).
|
|
- ``stop``: ``True`` indicates no other commands should be executed if the given command fails.
|
|
- ``sudo``: ``True`` indicates the command should be automatically prefixed with ``sudo``. If provided as a string, the
|
|
command is also prefixed with a specific user name.
|
|
- ``tags``: A list of tags used to classify the command.
|
|
|
|
Defining an "Itemized" Command
|
|
------------------------------
|
|
|
|
Certain command definitions may be repeated by defining a list of items.
|
|
|
|
Example of an "itemized" command:
|
|
|
|
.. code-block:: ini
|
|
|
|
[touch a bunch of files]
|
|
touch = /var/www/domains/example_com/www/$item
|
|
items = index.html, assets/index.html, content/index.html
|
|
|
|
.. note::
|
|
Command itemization may vary with the command type.
|
|
|
|
Available Commands
|
|
------------------
|
|
|
|
The following commands instantiate command instances. Each example is shown with the defaults.
|
|
|
|
.. include:: _command-examples.rst
|
|
|
|
Pre-Parsing Command Files as Templates
|
|
======================================
|
|
|
|
Configuration file may be pre-processed as a Jinja2 template by providing a context dictionary:
|
|
|
|
.. code-block:: ini
|
|
|
|
[install apache]
|
|
install: apache
|
|
|
|
[create the website directory]
|
|
mkdir: /var/www/domains/{{ domain_tld }}/www
|
|
recursive: yes
|
|
|
|
[set permissions on the website directory]
|
|
perms: /var/www/domains/{{ domain_tld }}/www
|
|
group: www-data
|
|
mode: 775
|
|
owner: www-data
|
|
|
|
Then with a config instance:
|
|
|
|
.. code-block:: python
|
|
|
|
context = {
|
|
'domain_tld': "example_com",
|
|
}
|
|
|
|
config = Config("commands.ini", context=context)
|
|
config.load()
|
|
|
|
for command in config.get_commands():
|
|
print(command.get_statement(cd=True))
|
|
print("")
|
|
|
|
Using the Tease Command
|
|
=======================
|
|
|
|
The ``tease`` command may be used to parse a configuration file, providing additional utilities for working with
|
|
commands.
|
|
|
|
.. code-block:: text
|
|
|
|
positional arguments:
|
|
path The path to the configuration file.
|
|
|
|
optional arguments:
|
|
-h, --help show this help message and exit
|
|
-c, --color Enable code highlighting for terminal output.
|
|
-C= VARIABLES, --context= VARIABLES
|
|
Context variables for use in pre-parsing the config and templates. In the form of: name:value
|
|
-d, --docs Output documentation instead of code.
|
|
-D, --debug Enable debug output.
|
|
-f= FILTERS, --filter= FILTERS
|
|
Filter the commands in the form of: attribute:value
|
|
-O= OPTIONS, --option= OPTIONS
|
|
Common command options in the form of: name:value
|
|
-s, --script Output commands as a script.
|
|
-T= TEMPLATE_LOCATIONS, --template-path= TEMPLATE_LOCATIONS
|
|
The location of template files that may be used with the template command.
|
|
-w= OUTPUT_FILE, --write= OUTPUT_FILE
|
|
Write the output to disk.
|
|
-V= VARIABLES_FILE, --variables-file= VARIABLES_FILE
|
|
Load variables from a file.
|
|
-v Show version number and exit.
|
|
--version Show verbose version information and exit.
|
|
|
|
The ``path`` argument defaults to ``commands.ini``.
|
|
|
|
Loading Variables from a File
|
|
-----------------------------
|
|
|
|
Context variables may be loaded from a file:
|
|
|
|
.. code-block:: ini
|
|
|
|
[domain]
|
|
name = example.com
|
|
tld = example_com
|
|
|
|
The variables above are available as ``section_key``. For example, ``domain_name`` is ``example.com``.
|
|
|