@ -30,7 +30,7 @@ For overlays that represent an operating system, the ``command_exists()`` functi
2) Define Command Function
--------------------------
The purpose of each function is to provide an interface for instantiating a :py:class`scripttease.library.commands.base.Command` instance. The example below is taken from the ``posix`` module.
The purpose of each function is to provide an interface for instantiating a :py:class:`scripttease.library.commands.base.Command` instance. The example below is taken from the ``posix`` module.
..code-block:: python
@ -62,6 +62,9 @@ The arguments and any specific keyword arguments are automatically used by the p
Each function *must* also accept ``**kwargs`` and should set a default for ``comment`` as above.
..important::
Rather than the usual Spinx-based documentation, define the docstring as shown above. This is used to automatically create the documentation for the command.
3) Add Functions to the Mapping
-------------------------------
@ -96,9 +99,16 @@ Additionally, for an operating system overlay, you may wish to import other mapp
MAPPINGS.update(DJANGO_MAPPINGS)
MAPPINGS.update(PGSQL_MAPPINGS)
4) Update Documentation
-----------------------
Add the command mappings to the ``docs/generate_command_signatures.py`` file. See the script for more details.
Export Commands as a Script
===========================
You can export commands as a read-to-use script. For example:
..code-block:: python
config = Config("commands.ini")
@ -108,3 +118,61 @@ Export Commands as a Script
script = config.as_script()
print(script)
Post a Message to Slack
=======================
The slack function may be used to send a message to a Slack channel. This uses the Incoming Webhooks feature, which requires some additional setup.
..note::
The following steps were accurate as of September 2020.
**1.** Log in to Slack and go to `Your Apps`_.
.._Your Apps: https://api.slack.com/apps
**2.** Create a new Slack app.
**3.** On the next page, select Incoming Webhooks and then toggle activation.
..image:: /_static/images/slack-1.jpg
**4.** Next click Add new Webhook to Workspace and select the channel to which the message will be posted.
..image:: /_static/images/slack-2.jpg
..image:: /_static/images/slack-3.jpg
**5.** Copy the URL for the new webhook to use as the ``url`` parameter for the Slack command.
..code-block:: ini
[send a message to slack]
slack: "This is a test message."
url: the URL you created goes here
Post a Message to Twist
=======================
The twist function may be used to send a message to Twist, which requires some additional setup.
..note::
The following steps were accurate as of September 2020.
**1.** Log in to Twist and from the profile menu go to Add Integrations. Then click on Build and "Add a new integration".
**2.** Provide the requested info.
..image:: _static/images/twist-1.png
**3.** After submitting this info, go to Installation. Select a channel and who to notify. Then click "Install integration".
..image:: _static/images/twist-2.png
**4.** Copy the "Post content manually" URL for use in your configuration file.
- 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 first part of each command 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.
@ -50,16 +50,12 @@ 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.
- ``environments``: A string or list of comma-separated 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).
- ``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.
- ``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
@ -112,23 +108,3 @@ Then with a config instance:
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. See :ref:`commands`.
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``.
An overlay is a collection of functions that provide an interface to command creation.
An overlay is a collection of functions that provide an interface to command creation. An overlay allows configuration files to specify commands in a generic way. When the file is loaded, an overlay may be specified which Script Tease uses to generate commands that are specific to a given operating system.
There are currently four (4) general and re-usable overlays: