Shawn Davis
2 years ago
parent
0d93018a00
commit
29c40cf1f1
36 changed files with 903 additions and 2286 deletions
@ -1,139 +0,0 @@ |
||||
#! /usr/bin/env python |
||||
|
||||
# Imports |
||||
|
||||
from collections import OrderedDict |
||||
import inspect |
||||
import sys |
||||
|
||||
# Set path before importing overlays. |
||||
sys.path.append("../") |
||||
|
||||
# Import overlays |
||||
from scripttease.library.overlays.common import COMMON_MAPPINGS |
||||
from scripttease.library.overlays.centos import MAPPINGS as CENTOS_MAPPINGS |
||||
from scripttease.library.overlays.django import DJANGO_MAPPINGS |
||||
from scripttease.library.overlays.mysql import MYSQL_MAPPINGS |
||||
from scripttease.library.overlays.pgsql import PGSQL_MAPPINGS |
||||
from scripttease.library.overlays.posix import POSIX_MAPPINGS |
||||
from scripttease.library.overlays.ubuntu import MAPPINGS as UBUNTU_MAPPINGS |
||||
|
||||
# Functions |
||||
|
||||
|
||||
# https://stackoverflow.com/a/52003056/241720 |
||||
def get_signature(fn): |
||||
params = inspect.signature(fn).parameters |
||||
args = [] |
||||
kwargs = OrderedDict() |
||||
for p in params.values(): |
||||
if p.default is p.empty: |
||||
args.append(p.name) |
||||
else: |
||||
kwargs[p.name] = p.default |
||||
return args, kwargs |
||||
|
||||
|
||||
def print_description(text): |
||||
print(text) |
||||
print("") |
||||
|
||||
|
||||
def print_heading(title): |
||||
print(title) |
||||
print("=" * len(title)) |
||||
print("") |
||||
|
||||
|
||||
def print_mapping(commands, excludes=None): |
||||
keys = list(commands.keys()) |
||||
keys.sort() |
||||
|
||||
_excludes = excludes or dict() |
||||
|
||||
for key in keys: |
||||
if key in _excludes: |
||||
continue |
||||
|
||||
func = commands[key] |
||||
|
||||
docstring = func.__doc__ |
||||
if not docstring: |
||||
continue |
||||
|
||||
print(key) |
||||
print("-" * len(key)) |
||||
print("") |
||||
for i in docstring.split("\n"): |
||||
print(i.strip()) |
||||
# print("") |
||||
|
||||
print(".. code-block:: ini") |
||||
print("") |
||||
print(" [run %s command]" % key) |
||||
|
||||
args, kwargs = get_signature(func) |
||||
|
||||
line = list() |
||||
for a in args: |
||||
if a != "kwargs": |
||||
line.append(a) |
||||
|
||||
print(" %s: %s" % (key, " ".join(line))) |
||||
|
||||
for option, value in kwargs.items(): |
||||
if value is True: |
||||
_value = "yes" |
||||
elif value is False: |
||||
_value = "no" |
||||
else: |
||||
_value = value |
||||
|
||||
print(" %s: %s" % (option, value)) |
||||
|
||||
print("") |
||||
|
||||
|
||||
# Overlay output. |
||||
print(".. generated by generate_command_signatures.py") |
||||
print("") |
||||
|
||||
print_heading("Common") |
||||
print_description("Common commands are available to all overlays.") |
||||
print_mapping(COMMON_MAPPINGS) |
||||
|
||||
print_heading("Django") |
||||
print_description("Django commands are available to all overlays.") |
||||
print_mapping(DJANGO_MAPPINGS) |
||||
|
||||
print_heading("MySQL") |
||||
print_description("MySQL commands.") |
||||
print_mapping(MYSQL_MAPPINGS) |
||||
|
||||
print_heading("Postgres") |
||||
print_description("Postgres commands.") |
||||
print_mapping(PGSQL_MAPPINGS) |
||||
|
||||
print_heading("POSIX") |
||||
print_description("Posix commands form the basis of overlays for *nix platforms.") |
||||
print_mapping(POSIX_MAPPINGS, excludes=["func"]) |
||||
|
||||
exclude_from_centos = COMMON_MAPPINGS.copy() |
||||
exclude_from_centos.update(DJANGO_MAPPINGS) |
||||
exclude_from_centos.update(MYSQL_MAPPINGS) |
||||
exclude_from_centos.update(PGSQL_MAPPINGS) |
||||
exclude_from_centos.update(POSIX_MAPPINGS) |
||||
print_heading("Cent OS") |
||||
print_description("The Cent OS overlay incorporates commands specific to that platform as well as commands from " |
||||
"common, Django, MySQL, Postgres, and POSIX.") |
||||
print_mapping(CENTOS_MAPPINGS, excludes=exclude_from_centos) |
||||
|
||||
exclude_from_ubuntu = COMMON_MAPPINGS.copy() |
||||
exclude_from_ubuntu.update(DJANGO_MAPPINGS) |
||||
exclude_from_ubuntu.update(MYSQL_MAPPINGS) |
||||
exclude_from_ubuntu.update(PGSQL_MAPPINGS) |
||||
exclude_from_ubuntu.update(POSIX_MAPPINGS) |
||||
print_heading("Ubuntu") |
||||
print_description("The Ubuntu overlay incorporates commands specific to that platform as well as commands from " |
||||
"common, Django, MySQL, Postgres, and POSIX.") |
||||
print_mapping(UBUNTU_MAPPINGS, excludes=exclude_from_ubuntu) |
||||
|
File diff suppressed because it is too large
Load Diff
|
After Width: | Height: | Size: 33 KiB |
|
Before Width: | Height: | Size: 301 KiB |
|
Before Width: | Height: | Size: 393 KiB |
|
Before Width: | Height: | Size: 33 KiB |
|
Before Width: | Height: | Size: 111 KiB |
|
Before Width: | Height: | Size: 181 KiB |
@ -1,86 +0,0 @@ |
||||
.. _commands: |
||||
|
||||
******** |
||||
Commands |
||||
******** |
||||
|
||||
.. code-block:: text |
||||
|
||||
usage: tease [-h] [-c] [-C= VARIABLES] [-d] [-D] [-f= FILTERS] [-O= OPTIONS] [-s] [-T= TEMPLATE_LOCATIONS] [-w= OUTPUT_FILE] [-V= VARIABLES_FILE] |
||||
[-v] [--version] |
||||
[path] |
||||
|
||||
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. |
||||
|
||||
NOTES |
||||
|
||||
This command is used to parse configuration files and output the commands. |
||||
|
||||
Using the Tease Command |
||||
======================= |
||||
|
||||
The ``tease`` command may be used to parse a configuration file, providing additional utilities for working with commands. |
||||
|
||||
The ``path`` argument defaults to ``commands.ini``. |
||||
|
||||
Context Variables May be Provided on the Command Line |
||||
----------------------------------------------------- |
||||
|
||||
To supply context variables on the command line: |
||||
|
||||
.. code-block:: bash |
||||
|
||||
tease -C domain_name:example.com -C domain_tld:example_com |
||||
|
||||
Loading Context 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``. |
||||
|
||||
.. code-block:: bash |
||||
|
||||
tease -V variables.ini |
||||
|
||||
Setting Common Options for All Commands |
||||
--------------------------------------- |
||||
|
||||
Rather than include a common parameter in the configuration file, it is possible to specify a common option on the command line. |
||||
|
||||
.. code-block:: bash |
||||
|
||||
tease -O sudo:yes |
||||
|
||||
The Difference Between Variables and Options |
||||
-------------------------------------------- |
||||
|
||||
Variables are used to pre-process configuration files as templates, while common options are passed to *all* command instances. |
||||
@ -0,0 +1,77 @@ |
||||
************ |
||||
Contributing |
||||
************ |
||||
|
||||
We welcome contributions to this and any of `our open source projects`_. There are a number of ways to participate and contribute. See :ref:`contact`. |
||||
|
||||
.. _our open source projects: https://docs.diff6.com |
||||
|
||||
Issue Management |
||||
================ |
||||
|
||||
Reporting Issues |
||||
---------------- |
||||
|
||||
If you have found a bug or error in the documentation, please submit a request. See :ref:`contact`. |
||||
|
||||
.. important:: |
||||
Do **not** report security issues using the issue tracker. Instead, send an email to security@develmaycare.com with details on the issue you've discovered. |
||||
|
||||
Submitting Feature Requests |
||||
--------------------------- |
||||
|
||||
Although we reserve the right to decline new features, we welcome all feature requests. See :ref:`contact`. |
||||
|
||||
Testing and Quality Control |
||||
--------------------------- |
||||
|
||||
Testing involves using Script Tease in real life or in development. Feel free to report any issues you find, or to improve the unit tests. |
||||
|
||||
Pull Requests |
||||
------------- |
||||
|
||||
Pull requests are welcome. Such requests should be associated with an issue. We may ignore pull requests that do not have a corresponding issue, so create an issue if one does not already exist. |
||||
|
||||
Promotion |
||||
========= |
||||
|
||||
You may help spread awareness of Script Tease by writing blog posts. We are happy to link out to reviews and tutorials from our web site. `Let us know if you've created a blog post`_ that we can share. Be sure to include a link to the post. |
||||
|
||||
You may also provide us with a guest post to be included on our blog. |
||||
|
||||
.. _Let us know if you've created a blog post: https://develmaycare.com/contact/?product=Script%20Tease |
||||
|
||||
.. note:: |
||||
We reserve the right to proof and approve or decline all content posted on our web site. |
||||
|
||||
Development |
||||
=========== |
||||
|
||||
Setting Up For Development |
||||
-------------------------- |
||||
|
||||
1. Clone the repo at https://github.com/develmaycare/python-scripttease |
||||
2. Create a virtual environment and install the requirements from ``requirements.pip`` |
||||
|
||||
Style Guide |
||||
----------- |
||||
|
||||
Script Tease follows `PEP8`_ and (where appropriate) the `Django style guide`_ and `JavaScript Standard Style`_. |
||||
|
||||
.. _Django style guide: https://docs.djangoproject.com/en/stable/internals/contributing/writing-code/coding-style/ |
||||
.. _JavaScript Standard Style: https://standardjs.com |
||||
.. _PEP8: https://www.python.org/dev/peps/pep-0008/ |
||||
|
||||
We *do* make a few exceptions and provide additional guidance which is documented in our `developer docs`_. |
||||
|
||||
.. _developer docs: https://docs.develmaycare.com/en/developer/ |
||||
|
||||
Dependencies |
||||
------------ |
||||
|
||||
.. include:: _includes/dependencies.rst |
||||
|
||||
Testing |
||||
------- |
||||
|
||||
.. include:: _includes/tests.rst |
||||
@ -1,32 +0,0 @@ |
||||
.. _getting-started: |
||||
|
||||
*************** |
||||
Getting Started |
||||
*************** |
||||
|
||||
System Requirements |
||||
=================== |
||||
|
||||
Python 3.6 or greater is required. |
||||
|
||||
Install |
||||
======= |
||||
|
||||
To install: |
||||
|
||||
.. code-block:: bash |
||||
|
||||
pip install python-scripttease; |
||||
|
||||
Configuration |
||||
============= |
||||
|
||||
See :ref:`topics-configuration` for creating a command configuration file. |
||||
|
||||
FAQs |
||||
==== |
||||
|
||||
Have a question? `Just ask`_! |
||||
|
||||
.. _Just ask: https://develmaycare.com/contact/?product=Script%20Tease |
||||
|
||||
@ -1,236 +0,0 @@ |
||||
.. _how-to: |
||||
|
||||
****** |
||||
How To |
||||
****** |
||||
|
||||
Create a New Command Overlay |
||||
============================ |
||||
|
||||
:ref:`topics-overlays` are used to define the commands supported by a given application, service, or operating system. Commands are defined as a function. |
||||
|
||||
1) Define a Module |
||||
------------------ |
||||
|
||||
The first step is to create a new module in which functions will be defined. |
||||
|
||||
.. code-block:: python |
||||
|
||||
# module_name.py |
||||
from ..commands import Command |
||||
|
||||
For overlays that represent an operating system, the ``command_exists()`` function is required: |
||||
|
||||
.. code-block:: python |
||||
|
||||
def command_exists(name): |
||||
return name in MAPPINGS |
||||
|
||||
|
||||
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. |
||||
|
||||
.. code-block:: python |
||||
|
||||
# module_name.py |
||||
# ... |
||||
|
||||
def mkdir(path, mode=None, recursive=True, **kwargs): |
||||
"""Create a directory. |
||||
|
||||
- path (str): The path to be created. |
||||
- mode (int | str): The access permissions of the new directory. |
||||
- recursive (bool): Create all directories along the path. |
||||
|
||||
""" |
||||
kwargs.setdefault("comment", "create directory %s" % path) |
||||
|
||||
statement = ["mkdir"] |
||||
if mode is not None: |
||||
statement.append("-m %s" % mode) |
||||
|
||||
if recursive: |
||||
statement.append("-p") |
||||
|
||||
statement.append(path) |
||||
|
||||
return Command(" ".join(statement), **kwargs) |
||||
|
||||
The arguments and any specific keyword arguments are automatically used by the parser, but also serve as a simple interface for programmatic use. |
||||
|
||||
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 |
||||
------------------------------- |
||||
|
||||
The final step adds the function to the mapping. This makes it available to the command factory. |
||||
|
||||
.. code-block:: python |
||||
|
||||
# module_name.py |
||||
# ... |
||||
|
||||
MAPPINGS = { |
||||
'mkdir': mkdir, |
||||
} |
||||
|
||||
For overlays that represent an operating system, ``MAPPINGS`` is required -- in addition to ``command_exists()`` above. For commands that are specific to service or application, the name of the dictionary may be anything that is appropriate. For example, ``DJANGO_MAPPINGS``. |
||||
|
||||
Additionally, for an operating system overlay, you may wish to import other mappings and incorporate them into ``MAPPINGS``. |
||||
|
||||
.. code-block:: python |
||||
|
||||
# module_name.py |
||||
from ..commands import Command |
||||
from .common import COMMON_MAPPINGS |
||||
from .django import DJANGO_MAPPINGS |
||||
from .pgsql import PGSQL_MAPPINGS |
||||
|
||||
MAPPINGS = { |
||||
# ... |
||||
} |
||||
|
||||
MAPPINGS.update(COMMON_MAPPINGS) |
||||
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") |
||||
if not config.load(): |
||||
print("Bummer!") |
||||
exit() |
||||
|
||||
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. |
||||
|
||||
.. code-block:: ini |
||||
|
||||
[post a message to twist] |
||||
twist: "This is a test message." |
||||
url: the URL you created goes here |
||||
|
||||
Use Script Tease With Common Kit |
||||
================================ |
||||
|
||||
Since the focus of Script Tease is to convert plain text instructions into valid command line statements, it does *not* provide support for executing those statements either locally or remotely. However, The shell component of `python-commonkit`_ *does* provide support for executing commands in local POSIX environments. |
||||
|
||||
.. _python-commonkit: https://docs.develmaycare.com/en/python-commonkit/stable/components/#module-commonkit.shell |
||||
|
||||
Here is an example of how to use these packages together: |
||||
|
||||
.. code-block:: python |
||||
|
||||
from commonkit.shell import Command |
||||
from scripttease.parsers.utils import load_commands |
||||
|
||||
def execute(step): |
||||
command = Command( |
||||
step.statement, |
||||
comment=step.comment, |
||||
path=step.cd, |
||||
prefix=step.prefix, |
||||
shell=step.shell |
||||
) |
||||
|
||||
# Sudo is a different class, but identical in behavior. |
||||
command.sudo = step.sudo |
||||
|
||||
if command.run(): |
||||
print("[success] %s" % step.comment) |
||||
else: |
||||
print("[failure] %s" % step.comment) |
||||
if step.stop: |
||||
print("I can't go on: %s" % command.error) |
||||
exit(command.code) |
||||
|
||||
# Load SCRIPT TEASE commands from an INI file. These are instances of either Command or ItemizedCommand found in |
||||
# scripttease.library.commands |
||||
steps = load_commands("path/to/steps.ini") |
||||
|
||||
# A failure to load results in None. |
||||
if steps is None: |
||||
print("Failed to load steps.") |
||||
exit(1) |
||||
|
||||
# Iterate through each step to create a COMMON KIT command. |
||||
for step in steps: |
||||
|
||||
# To preview ... |
||||
# print(step.get_statement(cd=True)) |
||||
|
||||
if step.is_itemized: |
||||
for substep in step.get_commands(): |
||||
execute(substep) |
||||
else: |
||||
execute(step) |
||||
|
||||
Common Kit is already a dependency of Script Tease so it is installed by default. The ``execute()`` function is a shortcut that helps deal with itemized commands. The path (``step.cd``) is automatically handled by Common Kit's Command class. |
||||
|
||||
@ -1,140 +0,0 @@ |
||||
******* |
||||
Project |
||||
******* |
||||
|
||||
Contributing |
||||
============ |
||||
|
||||
We welcome contributions to this and any of `our open source projects`_. There are a number of ways to participate and contribute. See :ref:`contact`. |
||||
|
||||
.. _our open source projects: https://develmaycare.com/products/ |
||||
|
||||
Reporting Issues |
||||
---------------- |
||||
|
||||
Perhaps the easiest way to contribute is to submit an issue. If you have found a bug or error in the documentation, please submit a request. See :ref:`contact`. |
||||
|
||||
.. important:: |
||||
Do **not** report security issues using the issue tracker. Instead, send an email to security@develmaycare.com with details on the issue you've discovered. |
||||
|
||||
Submitting Feature Requests |
||||
--------------------------- |
||||
|
||||
Although we reserve the right to decline new features, we welcome all feature requests. See :ref:`contact`. |
||||
|
||||
Testing and Quality Control |
||||
--------------------------- |
||||
|
||||
Testing involves using Script Tease in real life or in development. Feel free to report any issues you find, or to improve the unit tests. |
||||
|
||||
Pull Requests |
||||
------------- |
||||
|
||||
Pull requests are welcome. Such requests should be associated with an issue. We may ignore pull requests that do not have a corresponding issue, so create an issue if one does not already exist. |
||||
|
||||
Blogging |
||||
-------- |
||||
|
||||
You may help spread awareness of Script Tease by writing blog posts. We are happy to link out to reviews and tutorials from our web site. `Let us know if you've created a blog post`_ that we can share. Be sure to include a link to the post. |
||||
|
||||
You may also provide us with a guest post to be included on our blog. |
||||
|
||||
.. _Let us know if you've created a blog post: https://develmaycare.com/contact/?product=Script%20Tease |
||||
|
||||
.. note:: |
||||
We reserve the right to proof and approve or decline all content posted on our web site. |
||||
|
||||
Development |
||||
=========== |
||||
|
||||
Setting Up For Development |
||||
-------------------------- |
||||
|
||||
1. Clone the repo at https://github.com/develmaycare/python-scripttease |
||||
2. Create a virtual environment and install the requirements from ``requirements.pip`` |
||||
3. See :ref:`how-to`. |
||||
|
||||
Style Guide |
||||
----------- |
||||
|
||||
Script Tease follows `PEP8`_ and (where appropriate) the `Django style guide`_ and `JavaScript Standard Style`_. |
||||
|
||||
.. _Django style guide: https://docs.djangoproject.com/en/stable/internals/contributing/writing-code/coding-style/ |
||||
.. _JavaScript Standard Style: https://standardjs.com |
||||
.. _PEP8: https://www.python.org/dev/peps/pep-0008/ |
||||
|
||||
We *do* make a few exceptions and provide additional guidance which is documented in our `developer docs`_. |
||||
|
||||
.. _developer docs: https://docs.develmaycare.com/en/developer/ |
||||
|
||||
Dependencies |
||||
============ |
||||
|
||||
.. include:: _includes/project-dependencies.rst |
||||
|
||||
Tests |
||||
===== |
||||
|
||||
.. include:: _includes/project-tests.rst |
||||
|
||||
Releasing |
||||
========= |
||||
|
||||
Versioning |
||||
---------- |
||||
|
||||
Script Tease follows a loose form of `semantic versioning`_. The use of semantic versioning makes it clear when deprecation occurs and backward compatibility is removed. Documented incompatibilities may still exist where deprecation is not feasible (technically or financially). |
||||
|
||||
.. _semantic versioning: https://semver.org/ |
||||
|
||||
Cadence |
||||
------- |
||||
|
||||
New features (and especially new overlays) are planned for release every 3 months. Patch-level changes (to fix bugs or security issues) are always released as needed. |
||||
|
||||
Long-Term Support |
||||
----------------- |
||||
|
||||
Some releases may be designated as long-term support (LTS) releases. Such releases will have security and critical bug fixes applied for 6 months. |
||||
|
||||
Deprecation Policy |
||||
------------------ |
||||
|
||||
Minor releases may deprecate features from a previous minor release. For example, if a feature is deprecated in release 1.1, it will continue to work in the 1.2 release, though warnings may be raised. However, the deprecated feature may be removed in release 1.3 and may not function as previously expected or will raise errors. |
||||
|
||||
Major releases may *always* remove deprecated features. |
||||
|
||||
Patch-level releases *never* remove deprecated features. |
||||
|
||||
Legal |
||||
===== |
||||
|
||||
.. 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. |
||||
@ -0,0 +1,29 @@ |
||||
******** |
||||
Releases |
||||
******** |
||||
|
||||
Versioning |
||||
========== |
||||
|
||||
Script Tease follows a loose form of `semantic versioning`_. The use of semantic versioning makes it clear when deprecation occurs and backward compatibility is removed. Documented incompatibilities may still exist where deprecation is not feasible (technically or financially). |
||||
|
||||
.. _semantic versioning: https://semver.org/ |
||||
|
||||
Cadence |
||||
======= |
||||
|
||||
New features (and especially new overlays) are planned for release every 3 months. Patch-level changes (to fix bugs or security issues) are always released as needed. |
||||
|
||||
Long-Term Support |
||||
================= |
||||
|
||||
Some releases may be designated as long-term support (LTS) releases. Such releases will have security and critical bug fixes applied for 6 months. |
||||
|
||||
Deprecation Policy |
||||
================== |
||||
|
||||
Minor releases may deprecate features from a previous minor release. For example, if a feature is deprecated in release 1.1, it will continue to work in the 1.2 release, though warnings may be raised. However, the deprecated feature may be removed in release 1.3 and may not function as previously expected or will raise errors. |
||||
|
||||
Major releases may *always* remove deprecated features. |
||||
|
||||
Patch-level releases *never* remove deprecated features. |
||||
@ -1,115 +0,0 @@ |
||||
.. _topics-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 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. |
||||
- ``yes`` and ``no`` are interpreted as boolean values. |
||||
- List values, where required, are separated by commas. |
||||
|
||||
.. _topics-configuration-common-parameters: |
||||
|
||||
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 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). |
||||
- ``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 |
||||
|
||||
[create multiple directories] |
||||
mkdir: /var/www/domains/example_com/$item |
||||
items: www, www/assets, www/content |
||||
recursive: yes |
||||
|
||||
[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. |
||||
|
||||
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("") |
||||
@ -1,24 +0,0 @@ |
||||
.. _topics-overlays: |
||||
|
||||
******** |
||||
Overlays |
||||
******** |
||||
|
||||
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 (5) general and re-usable overlays: |
||||
|
||||
- common |
||||
- django |
||||
- mysql |
||||
- pgsql |
||||
- posix |
||||
|
||||
And two (2) overlays that are specific to operating systems: |
||||
|
||||
- centos |
||||
- ubuntu |
||||
|
||||
The examples that follow instantiate command instances from an INI file. Each example is shown with the defaults. All commands support a number of :ref:`topics-configuration-common-parameters`. |
||||
|
||||
.. include:: _includes/overlays.rst |
||||
@ -1,11 +0,0 @@ |
||||
.. _topics: |
||||
|
||||
****** |
||||
Topics |
||||
****** |
||||
|
||||
.. toctree:: |
||||
:maxdepth: 2 |
||||
|
||||
Configuration <topics-configuration> |
||||
Overlays <topics-overlays> |
||||
Loading…
Reference in new issue