diff6
/
python-scripttease
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Updated docs.

Browse Source
development
Shawn Davis 4 years ago
parent 23563b48b4
commit a710e228ab
30 changed files with 1903 additions and 894 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Unified View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 1
      Makefile
  2. 3
      docs/Makefile
  3. 99
      docs/generate_command_signatures.py
  4. 440
      docs/source/_command-examples.rst
  5. 4
      docs/source/_data/cloc.csv
  6. 1019
      docs/source/_includes/overlays.rst
  7. 17
      docs/source/_includes/project-dependencies.rst
  8. 14
      docs/source/_includes/project-tests.rst
  9. 39
      docs/source/commands.rst
  10. 27
      docs/source/contact.rst
  11. 47
      docs/source/getting-started.rst
  12. 110
      docs/source/how-to.rst
  13. 20
      docs/source/index.rst
  14. 21
      docs/source/introduction.rst
  15. 155
      docs/source/project.rst
  16. 0
      docs/source/reference.rst
  17. 40
      docs/source/topics-configuration.rst
  18. 22
      docs/source/topics-overlays.rst
  19. 11
      docs/source/topics.rst
  20. 5
      packages.ini
  21. 4
      requirements.pip
  22. 28
      scripttease/library/overlays/common.py
  23. 78
      scripttease/library/overlays/django.py
  24. 173
      scripttease/library/overlays/pgsql.py
  25. 284
      scripttease/library/overlays/posix.py
  26. 75
      scripttease/library/overlays/ubuntu.py
  27. 4
      scripttease/parsers/utils.py
  28. 4
      setup.py
  29. 5
      tests/test_library_overlays_posix.py

1
Makefile
Unescape View File

@ -19,6 +19,7 @@ help:
#> docs - Generate documentation. #> docs - Generate documentation.
docs: lines docs: lines
cd docs && make dirhtml;
cd docs && make html; cd docs && make html;
cd docs && make coverage; cd docs && make coverage;
open docs/build/coverage/python.txt; open docs/build/coverage/python.txt;

3
docs/Makefile
Unescape View File

@ -54,7 +54,8 @@ clean:
.PHONY: html .PHONY: html
html: html:
#./generate_command_signatures.py > source/_command-examples.rst resrc pkg docs -I ../packages.ini -O rst --no-heading > source/_includes/project-dependencies.rst;
./generate_command_signatures.py > source/_includes/overlays.rst
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
@echo @echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html." @echo "Build finished. The HTML pages are in $(BUILDDIR)/html."

99
docs/generate_command_signatures.py
Unescape View File

@ -1,12 +1,22 @@
#! /usr/bin/env python #! /usr/bin/env python
# Imports
from collections import OrderedDict from collections import OrderedDict
import inspect import inspect
import sys import sys
# Set path before importing overlays.
sys.path.append("../") sys.path.append("../")
from script_tease.mappings import MAPPING # Import overlays
from scripttease.library.overlays.common import COMMON_MAPPINGS
from scripttease.library.overlays.django import DJANGO_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 # https://stackoverflow.com/a/52003056/241720
@ -22,44 +32,89 @@ def get_signature(fn):
return args, kwargs return args, kwargs
keys = list(MAPPING.keys()) 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() keys.sort()
_excludes = excludes or dict()
for key in keys: for key in keys:
cls = MAPPING[key] if key in _excludes:
continue
print(key) func = commands[key]
print("." * len(key))
print("")
extra = cls.get_docs() docstring = func.__doc__
if extra is not None: if not docstring:
print(extra) continue
print("")
# if cls.__init__.__doc__: print(key)
# print(cls.__init__.__doc__) print("-" * len(key))
print("")
for i in docstring.split("\n"):
print(i.strip())
# print("") # print("")
print(".. code-block:: cfg") print(".. code-block:: ini")
print("") print("")
print(" [run %s command]" % key)
if cls.__doc__: args, kwargs = get_signature(func)
print(" [%s]" % cls.__doc__.strip().replace(".", "").lower())
else:
print(" [run a %s command]" % cls.__name__.lower())
args, kwargs = get_signature(cls.__init__)
line = list() line = list()
for a in args: for a in args:
if a not in ("self", "kwargs"): if a != "kwargs":
line.append(a) line.append(a)
print(" %s = %s" % (key, " ".join(line))) print(" %s: %s" % (key, " ".join(line)))
for option, value in kwargs.items(): for option, value in kwargs.items():
print(" %s = %s" % (option, value)) if value is True:
_value = "yes"
elif value is False:
_value = "no"
else:
_value = value
print(" %s: %s" % (option, value))
print("") print("")
# Overlay output.
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("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)
exclude_from_ubuntu = COMMON_MAPPINGS.copy()
exclude_from_ubuntu.update(DJANGO_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, Postgres, and POSIX.")
print_mapping(UBUNTU_MAPPINGS, excludes=exclude_from_ubuntu)

440
docs/source/_command-examples.rst
Unescape View File

@ -1,440 +0,0 @@
apache.disable_module
.....................
.. code-block:: ini
[disable an apache module]
apache.disable_module = module_name
apache.disable_site
...................
.. code-block:: ini
[disable a virtual host]
apache.disable_site = domain_name
apache.enable_module
....................
.. code-block:: ini
[enable an apache module]
apache.enable_module = module_name
apache.enable_site
..................
.. code-block:: ini
[enable a virtual host]
apache.enable_site = domain_name
apache.test
...........
.. code-block:: ini
[run an apache config test]
apache: test
append
......
.. code-block:: ini
[append to a file]
append = path
content = None
archive
.......
.. code-block:: ini
[create an archive file]
archive = from_path
absolute = False
exclude = None
file_name = archive.tgz
strip = 0
to_path = .
view = False
certbot
.......
Alias: ssl
.. code-block:: ini
[get new ssl certificate from let's encrypt]
certbot = domain_name
email = None
webroot = None
copy
....
.. code-block:: ini
[copy a file or directory]
copy = from_path to_path
overwrite = False
recursive = False
django
......
.. code-block:: ini
[run a django management command]
django = name
django.dumpdata
...............
.. code-block:: ini
[export django fixtures]
django.dumpdata = app_name
file_name = initial
indent = 4
natural_foreign = False
natural_primary = False
path = None
django.loaddata
...............
.. code-block:: ini
[load django fixtures]
django.loaddata = app_name
file_name = initial
path = None
extract
.......
.. code-block:: ini
[extract an archive]
extract = from_path
absolute = False
exclude = None
file_name = archive.tgz
strip = 0
to_path = None
view = False
install
.......
.. code-block:: ini
[install a package using apt-get]
apt = package
remove = False
makedir
.......
.. code-block:: ini
[create a directory]
makedir = path
mode = None
recursive = True
message
.......
.. code-block:: ini
[run a message command]
message = output
back_title = Message
dialog = False
height = 15
width = 100
mkdir
.....
.. code-block:: ini
[create a directory]
mkdir = path
mode = None
recursive = True
move
....
.. code-block:: ini
[move a file or directory]
move = from_path to_path
perms
.....
.. code-block:: ini
[set permissions on a file or directory]
perms = path
group = None
mode = None
owner = None
recursive = False
pg.createdb
...........
.. code-block:: ini
[create a postgresql database]
pg.createdb = name
admin_pass = None
admin_user = postgres
host = localhost
owner = None
port = 5432
template = None
pg.createuser
.............
.. code-block:: ini
[create a postgresql user]
pg.createuser = name
admin_pass = None
admin_user = postgres
host = localhost
password = None
port = 5432
pg.db
.....
.. code-block:: ini
[create a postgresql database]
pg.db = name
admin_pass = None
admin_user = postgres
host = localhost
owner = None
port = 5432
template = None
pg.dropdb
.........
.. code-block:: ini
[remove a postgresql database]
pg.dropdb = name
admin_pass = None
admin_user = postgres
host = localhost
port = 5432
pg.dropuser
...........
.. code-block:: ini
[remove a postgres user]
pg.dropuser = name
admin_pass = None
admin_user = postgres
host = localhost
port = 5432
pg.dump
.......
.. code-block:: ini
[export a postgres database]
pg.dump = name
admin_pass = None
admin_user = postgres
file_name = None
host = localhost
port = 5432
pg.exists
.........
.. code-block:: ini
[determine if a postgres database exists]
pg.exists = name
admin_pass = None
admin_user = postgres
host = localhost
port = 5432
pip
...
.. code-block:: ini
[install a python package using pip]
pip = package
remove = False
upgrade = False
psql
....
.. code-block:: ini
[execute a psql command]
psql = sql
database = template1
host = localhost
password = None
port = 5432
user = postgres
reload
......
.. code-block:: ini
[reload a service]
reload = service
remove
......
.. code-block:: ini
[remove a file or directory]
remove = path
force = False
recursive = False
restart
.......
.. code-block:: ini
[restart a service]
restart = service
rsync
.....
.. code-block:: ini
[synchronize files from a local to remote directory]
rsync = source target
delete = False
guess = False
host = None
key_file = None
links = True
port = 22
recursive = True
user = None
run
...
.. code-block:: ini
[a command to be executed]
run = statement
comment = None
condition = None
cd = None
environments = None
function = None
prefix = None
register = None
shell = None
stop = False
sudo = None
tags = None
scopy
.....
.. code-block:: ini
[copy a file from the local (machine) to the remote host]
scp = from_path to_path
host = None
key_file = None
port = 22
user = None
sed
...
.. code-block:: ini
[replace text in a file]
sed = path
backup = .b
change = None
delimiter = /
find = None
start
.....
.. code-block:: ini
[start a service]
start = service
stop
....
.. code-block:: ini
[stop a service]
stop = service
symlink
.......
.. code-block:: ini
[create a symlink]
symlink = source
force = False
target = None
touch
.....
.. code-block:: ini
[touch a file or directory]
touch = path
virtualenv
..........
.. code-block:: ini
[create a python virtual environment]
virtualenv = name
write
.....
.. code-block:: ini
[write to a file]
write = path
content = None
overwrite = False

4
docs/source/_data/cloc.csv
Unescape View File

@ -1,3 +1,3 @@
files,language,blank,comment,code files,language,blank,comment,code
17,Python,705,569,1156 18,Python,774,700,1285
17,SUM,705,569,1156 18,SUM,774,700,1285

1 files language blank comment code
2 17 18 Python 705 774 569 700 1156 1285
3 17 18 SUM 705 774 569 700 1156 1285

1019
docs/source/_includes/overlays.rst
View File

File diff suppressed because it is too large Load Diff

17
docs/source/_includes/project-dependencies.rst
Unescape View File

@ -0,0 +1,17 @@
Requirements
------------
superpython
-----------
**URLs**
- `Source Code <https://github.com/develmaycare/superpython>`_
**Install**
.. code-block:: bash
pip install git+https://github.com/develmaycare/superpython;

14
docs/source/tests.rst → docs/source/_includes/project-tests.rst
Unescape View File

@ -1,19 +1,15 @@
*****
Tests
*****
Coverage Requirements Coverage Requirements
===================== ---------------------
100% coverage is required for the ``master`` branch. 100% coverage is required for the ``master`` branch.
See `current coverage report <coverage/index.html>`_. See `current coverage report <coverage/index.html>`_.
.. csv-table:: Lines of Code .. csv-table:: Lines of Code
:file: _data/cloc.csv :file: ../_data/cloc.csv
Set Up for Testing Set Up for Testing
================== ------------------
Install requirements: Install requirements:
@ -22,7 +18,7 @@ Install requirements:
pip install tests/requirements.pip pip install tests/requirements.pip
Running Tests Running Tests
============= .............
.. tip:: .. tip::
You may use the ``tests`` target of the ``Makefile`` to run tests with coverage: You may use the ``tests`` target of the ``Makefile`` to run tests with coverage:
@ -48,7 +44,7 @@ To allow output from print statements within a test method, add the ``-s`` switc
python -m pytest -s tests/units/path/to/test.py python -m pytest -s tests/units/path/to/test.py
Reference Reference
========= ---------
- `coverage <https://coverage.readthedocs.io/en/v4.5.x/>`_ - `coverage <https://coverage.readthedocs.io/en/v4.5.x/>`_
- `pytest <https://pytest.org>`_ - `pytest <https://pytest.org>`_

39
docs/source/commands.rst
Unescape View File

@ -0,0 +1,39 @@
.. _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.

27
docs/source/contact.rst
Unescape View File

@ -0,0 +1,27 @@
.. _contact:
*******
Contact
*******
General Contact
===============
Please use the `contact form at develmaycare.com`_ to inquire about training, commercial development or support, to
report security issues, and other questions or communications.
.. _contact form at develmaycare.com: https://develmaycare.com/contact/?product=ScriptTease
Issue Tracker
=============
Bugs and feature requests are logged with the `issue tracker`_. Do *not* log security issues here.
.. _issue tracker: https://github.com/develmaycare/python-scripttease/issues
Support
=======
Support inquiries and other questions may be answered on StackOverflow `using the python-scripttease tag`_.
.. _using the python-scripttease tag: https://stackoverflow.com/questions/tagged/python-scripttease

47
docs/source/getting-started.rst
Unescape View File

@ -0,0 +1,47 @@
.. _getting-started:
***************
Getting Started
***************
System Requirements
===================
TODO
Install
=======
TODO
Configuration
=============
TODO
Examples
========
TODO
Next Steps
==========
TODO
Resources
=========
TODO
FAQs
====
**Question?**
Answer.
Have a question? `Just ask`_!
.. _Just ask: https://{{ project_domain }}/contact

110
docs/source/how-to.rst
Unescape View File

@ -0,0 +1,110 @@
.. _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.
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)
Export Commands as a Script
===========================
.. code-block:: python
config = Config("commands.ini")
if not config.load():
print("Bummer!")
exit()
script = config.as_script()
print(script)

20
docs/source/index.rst
Unescape View File

@ -1,13 +1,23 @@
Python Script Tease Script Tease
=================== ============
.. raw:: html
<p>
<a href="https://develmaycare.com/products/python/script-tease/">Project Home Page</a>
</p>
.. toctree:: .. toctree::
:maxdepth: 2 :maxdepth: 2
Introduction <introduction> Introduction <introduction>
Configuration <configuration> Getting Started <getting-started>
Developer Reference <developer> How To <how-to>
Tests <tests> Commands <commands>
Topics <topics>
Reference <reference>
Project <project>
Contact <contact>
Indices and tables Indices and tables
================== ==================

21
docs/source/introduction.rst
Unescape View File

@ -4,6 +4,9 @@
Introduction Introduction
************ ************
Overview
========
Script Tease is a library and command line tool for generating commands programmatically or using configuration files. Script Tease is a library and command line tool for generating commands programmatically or using configuration files.
Concepts Concepts
@ -14,9 +17,8 @@ Generating Commands
Script Tease may be used in two (2) ways: Script Tease may be used in two (2) ways:
1. Using the library to programmatically define commands and export them as command line statements. See 1. Using the library to programmatically define commands and export them as command line statements. See :ref:`developer-reference`.
:ref:`developer-reference`. 2. Using the ``tease`` command to generate commands from a configuration file. See :ref:`topics-configuration`.
2. Using the ``tease`` command to generate commands from a configuration file. See :ref:`configuration`.
Overlays Overlays
-------- --------
@ -25,3 +27,16 @@ An *overlay* is a set of command meta functions that define the capabilities of
.. note:: .. note::
At present, the only fully defined overlay is for Ubuntu. At present, the only fully defined overlay is for Ubuntu.
See :ref:`topics-overlays`.
Terms and Definitions
=====================
term
Definition.
License
=======
Script Tease is released under the BSD 3 clause license.

155
docs/source/project.rst
Unescape View File

@ -0,0 +1,155 @@
*******
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.
Translations
------------
TODO: Translations help make Script Tease available to more people around the world.
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=ScriptTease
.. note::
We reserve the right to proof and approve or decline all content posted on our web site.
Development
===========
TODO
Setting Up For Development
--------------------------
TODO
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/
Tips for Successful Development
-------------------------------
TODO
Getting Help
------------
TODO
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
-------
Prior to the 1.0 release, new features may be released at any time. After the 1.0 release, new features 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
docs/source/developer.rst → docs/source/reference.rst
Unescape View File

40
docs/source/configuration.rst → docs/source/topics-configuration.rst
Unescape View File

@ -1,4 +1,4 @@
.. _configuration: .. _topics-configuration:
************* *************
Configuration Configuration
@ -40,6 +40,8 @@ Notes regarding this format:
- ``yes`` and ``no`` are interpreted as boolean values. - ``yes`` and ``no`` are interpreted as boolean values.
- List values, where required, are separated by commas. - List values, where required, are separated by commas.
.. _topics-configuration-common-parameters:
Common Parameters Common Parameters
----------------- -----------------
@ -76,13 +78,6 @@ Example of an "itemized" command:
.. note:: .. note::
Command itemization may vary with the command type. 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 Pre-Parsing Command Files as Templates
====================================== ======================================
@ -121,34 +116,7 @@ Then with a config instance:
Using the Tease Command Using the Tease Command
======================= =======================
The ``tease`` command may be used to parse a configuration file, providing additional utilities for working with The ``tease`` command may be used to parse a configuration file, providing additional utilities for working with commands. See :ref:`commands`.
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``. The ``path`` argument defaults to ``commands.ini``.

22
docs/source/topics-overlays.rst
Unescape View File

@ -0,0 +1,22 @@
.. _topics-overlays:
*******
Overlay
*******
An overlay is a collection of functions that provide an interface to command creation.
There are currently three (3) general and re-usable overlays:
- common
- django
- pgsql
And two (2) overlays that are specific to operating systems:
- posix
- 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

11
docs/source/topics.rst
Unescape View File

@ -0,0 +1,11 @@
.. _topics:
******
Topics
******
.. toctree::
:maxdepth: 2
Configuration <topics-configuration>
Overlays <topics-overlays>

5
packages.ini
Unescape View File

@ -0,0 +1,5 @@
; SuperPython already has many of the required dependencies, including jinja2 and pygments.
[superpython]
comment = Used throughout for its various components and utilities.
scm = https://github.com/develmaycare/superpython
source = https://github.com/develmaycare/superpython

4
requirements.pip
Unescape View File

@ -1,3 +1 @@
coverage superpython
django
sphinx

28
scripttease/library/overlays/common.py
Unescape View File

@ -8,12 +8,21 @@ __all__ = (
"COMMON_MAPPINGS", "COMMON_MAPPINGS",
"python_pip", "python_pip",
"python_virtualenv", "python_virtualenv",
"run",
) )
# Functions # Functions
def python_pip(name, op="install", upgrade=False, venv=None, **kwargs): def python_pip(name, op="install", upgrade=False, venv=None, **kwargs):
"""Use pip to install or uninstall a Python package.
- name (str): The name of the package.
- op (str): The operation to perform; install, uninstall
- upgrade (bool): Upgrade an installed package.
- venv (str): The name of the virtual environment to load.
"""
if upgrade: if upgrade:
statement = "pip install --upgrade -y %s" % name statement = "pip install --upgrade -y %s" % name
else: else:
@ -27,14 +36,31 @@ def python_pip(name, op="install", upgrade=False, venv=None, **kwargs):
return Command(statement, **kwargs) return Command(statement, **kwargs)
def python_virtualenv(name="python", **kwargs): def python_virtualenv(name, **kwargs):
"""Create a Python virtual environment.
- name (str): The name of the environment to create.
"""
kwargs.setdefault("comment", "create %s virtual environment" % name) kwargs.setdefault("comment", "create %s virtual environment" % name)
return Command("virtualenv %s" % name, **kwargs) return Command("virtualenv %s" % name, **kwargs)
def run(statement, **kwargs):
"""Run any statement.
- statement (str): The statement to be executed.
"""
kwargs.setdefault("comment", "run statement")
return Command(statement, **kwargs)
# Mappings # Mappings
COMMON_MAPPINGS = { COMMON_MAPPINGS = {
'pip': python_pip, 'pip': python_pip,
'run': run,
'virtualenv': python_virtualenv, 'virtualenv': python_virtualenv,
} }

78
scripttease/library/overlays/django.py
Unescape View File

@ -19,6 +19,19 @@ __all__ = (
def _django(name, *args, venv=None, **kwargs): def _django(name, *args, venv=None, **kwargs):
"""Process a django-based command.
:param name: The name of the management command.
:type name: str
:param venv: The virtual environment to use.
:type venv: str
args and kwargs are used to instantiate the command instance.
This exists because we need ``django()`` to serve as an interface for any management command.
"""
if venv is not None: if venv is not None:
kwargs['prefix'] = "source %s/bin/activate" % venv kwargs['prefix'] = "source %s/bin/activate" % venv
@ -59,6 +72,14 @@ def _django(name, *args, venv=None, **kwargs):
def django(name, *args, venv=None, **kwargs): def django(name, *args, venv=None, **kwargs):
"""Run any Django management command.
- name (str): The name of the management command.
- venv (str): The of the virtual environment to use.
args are passed as positional arguments, while kwargs are given as switches.
"""
if name == "check": if name == "check":
return django_check(venv=venv, **kwargs) return django_check(venv=venv, **kwargs)
elif name in ("collectstatic", "static"): elif name in ("collectstatic", "static"):
@ -70,6 +91,11 @@ def django(name, *args, venv=None, **kwargs):
def django_check(venv=None, **kwargs): def django_check(venv=None, **kwargs):
"""Run the Django check command.
- venv (str): The of the virtual environment to use.
"""
kwargs.setdefault("comment", "run django checks") kwargs.setdefault("comment", "run django checks")
kwargs.setdefault("register", "django_checks_out") kwargs.setdefault("register", "django_checks_out")
@ -77,6 +103,11 @@ def django_check(venv=None, **kwargs):
def django_collect_static(venv=None, **kwargs): def django_collect_static(venv=None, **kwargs):
"""Collect static files.
- venv (str): The of the virtual environment to use.
"""
kwargs.setdefault("comment", "collect static files") kwargs.setdefault("comment", "collect static files")
return _django("collectstatic", venv=venv, **kwargs) return _django("collectstatic", venv=venv, **kwargs)
@ -84,25 +115,16 @@ def django_collect_static(venv=None, **kwargs):
def django_dumpdata(app_name, base_path="local", file_name="initial", indent=4, natural_foreign=False, def django_dumpdata(app_name, base_path="local", file_name="initial", indent=4, natural_foreign=False,
natural_primary=False, path=None, venv=None, **kwargs): natural_primary=False, path=None, venv=None, **kwargs):
"""Initialize the command. """Dump data from the database.
:param app_name: The name (app label) of the app. ``app_label.ModelName`` may also be given.
:type app_name: str
:param file_name: The file name to which the data will be dumped.
:type file_name: str
:param indent: Indentation of the exported fixtures.
:type indent: int
:param natural_foreign: Use the natural foreign parameter.
:type natural_foreign: bool
:param natural_primary: Use the natural primary parameter. - app_name (str): The name (app label) of the app. ``app_label.ModelName`` may also be given.
:type natural_primary: bool - base_path (str): The path under which apps are located in source.
- file_name (str): The file name to which the data will be dumped.
:param path: The path to the data file. - indent (int): Indentation of the exported fixtures.
:type path: str - natural_foreign (bool): Use the natural foreign parameter.
- natural_primary (bool): Use the natural primary parameter.
- path (str): The path to the data file.
- venv (str): The of the virtual environment to use.
""" """
kwargs.setdefault("comment", "export fixtures for %s" % app_name) kwargs.setdefault("comment", "export fixtures for %s" % app_name)
@ -125,16 +147,13 @@ def django_dumpdata(app_name, base_path="local", file_name="initial", indent=4,
def django_loaddata(app_name, base_path="local", file_name="initial", path=None, venv=None, **kwargs): def django_loaddata(app_name, base_path="local", file_name="initial", path=None, venv=None, **kwargs):
"""Initialize the command. """Load data into the database.
:param app_name: The name (app label) of the app.
:type app_name: str
:param file_name: The file name to which the data will be dumped.
:type file_name: str
:param path: The path to the data file. - app_name (str): The name (app label) of the app. ``app_label.ModelName`` may also be given.
:type path: str - base_path (str): The path under which apps are located in source.
- file_name (str): The file name to which the data will be dumped.
- path (str): The path to the data file.
- venv (str): The of the virtual environment to use.
""" """
kwargs.setdefault("comment", "load fixtures for %s" % app_name) kwargs.setdefault("comment", "load fixtures for %s" % app_name)
@ -147,6 +166,11 @@ def django_loaddata(app_name, base_path="local", file_name="initial", path=None,
def django_migrate(venv=None, **kwargs): def django_migrate(venv=None, **kwargs):
"""Apply database migrations.
- venv (str): The of the virtual environment to use.
"""
kwargs.setdefault("comment", "run django database migrations") kwargs.setdefault("comment", "run django database migrations")
return _django("migrate", venv=venv, **kwargs) return _django("migrate", venv=venv, **kwargs)

173
scripttease/library/overlays/pgsql.py
Unescape View File

@ -19,6 +19,25 @@ __all__ = (
def _get_pgsql_command(name, host="localhost", password=None, port=5432, user="postgres"): def _get_pgsql_command(name, host="localhost", password=None, port=5432, user="postgres"):
"""Get a postgres-related command using commonly required parameters.
:param name: The name of the command.
:type name: str
:param host: The host name.
:type host: str
:param password: The password to use.
:type password: str
:param port: The TCP port number.
:type port: int
:param user: The user name that will be used to execute the command.
:rtype: list[str]
"""
a = list() a = list()
if password: if password:
@ -37,26 +56,13 @@ def pg_create_database(name, admin_pass=None, admin_user="postgres", host="local
template=None, **kwargs): template=None, **kwargs):
"""Create a PostgreSQL database. """Create a PostgreSQL database.
:param name: The database name. - name (str): The database name.
:type name: str - admin_pass (str): The password for the user with sufficient access privileges to execute the command.
- admin_user (str): The name of the user with sufficient access privileges to execute the command.
:param admin_pass: The password for the user with sufficient access privileges to execute the command. - host (str): The database host name or IP address.
:type admin_pass: str - owner (str): The owner (user/role name) of the new database.
- port (int): The port number of the Postgres service running on the host.
:param admin_user: The name of the user with sufficient access privileges to execute the command. - template (str): The database template name to use, if any.
:type admin_user: str
:param host: The database host name or IP address.
:type host: str
:param owner: The owner (user/role name) of the new database.
:type owner: str
:param port: The port number of the Postgres service running on the host.
:type port: int
:param template: The database template name to use, if any.
:type template: str
""" """
_owner = owner or admin_user _owner = owner or admin_user
@ -79,23 +85,11 @@ def pg_create_database(name, admin_pass=None, admin_user="postgres", host="local
def pg_create_user(name, admin_pass=None, admin_user="postgres", host="localhost", password=None, port=5432, **kwargs): def pg_create_user(name, admin_pass=None, admin_user="postgres", host="localhost", password=None, port=5432, **kwargs):
"""Create a PostgreSQL user. """Create a PostgreSQL user.
:param name: The user name. - name (str): The user name.
:type name: str - admin_pass (str): The password for the user with sufficient access privileges to execute the command.
- admin_user (str): The name of the user with sufficient access privileges to execute the command.
:param admin_pass: The password for the user with sufficient access privileges to execute the command. - host (str): The database host name or IP address.
:type admin_pass: str - port (int): The port number of the Postgres service running on the host.
:param admin_user: The name of the user with sufficient access privileges to execute the command.
:type admin_user: str
:param host: The database host name or IP address.
:type host: str
:param password: The password for the new user.
:type password: str
:param port: The port number of the Postgres service running on the host.
:type port: int
""" """
# Postgres commands always run without sudo because the -U may be provided. # Postgres commands always run without sudo because the -U may be provided.
@ -116,20 +110,12 @@ def pg_create_user(name, admin_pass=None, admin_user="postgres", host="localhost
def pg_database_exists(name, admin_pass=None, admin_user="postgres", host="localhost", port=5432, **kwargs): def pg_database_exists(name, admin_pass=None, admin_user="postgres", host="localhost", port=5432, **kwargs):
"""Determine if a Postgres database exists. """Determine if a Postgres database exists.
:param name: The database name. - name (str): The database name.
:type name: str - admin_pass (str): The password for the user with sufficient access privileges to execute the command.
- admin_user (str): The name of the user with sufficient access privileges to execute the command.
:param admin_pass: The password for the user with sufficient access privileges to execute the command. - host (str): The database host name or IP address.
:type admin_pass: str - owner (str): The owner (user/role name) of the new database.
- port (int): The port number of the Postgres service running on the host.
:param admin_user: The name of the user with sufficient access privileges to execute the command.
:type admin_user: str
:param host: The database host name or IP address.
:type host: str
:param port: The port number of the Postgres service running on the host.
:type port: int
""" """
# Postgres commands always run without sudo because the -U may be provided. However, sudo may be required for # Postgres commands always run without sudo because the -U may be provided. However, sudo may be required for
@ -147,20 +133,11 @@ def pg_database_exists(name, admin_pass=None, admin_user="postgres", host="local
def pg_drop_database(name, admin_pass=None, admin_user="postgres", host="localhost", port=5432, **kwargs): def pg_drop_database(name, admin_pass=None, admin_user="postgres", host="localhost", port=5432, **kwargs):
"""Remove a PostgreSQL database. """Remove a PostgreSQL database.
:param name: The database name. - name (str): The database name.
:type name: str - admin_pass (str): The password for the user with sufficient access privileges to execute the command.
- admin_user (str): The name of the user with sufficient access privileges to execute the command.
:param admin_pass: The password for the user with sufficient access privileges to execute the command. - host (str): The database host name or IP address.
:type admin_pass: str - port (int): The port number of the Postgres service running on the host.
:param admin_user: The name of the user with sufficient access privileges to execute the command.
:type admin_user: str
:param host: The database host name or IP address.
:type host: str
:param port: The port number of the Postgres service running on the host.
:type port: int
""" """
# Postgres commands always run without sudo because the -U may be provided. # Postgres commands always run without sudo because the -U may be provided.
@ -176,20 +153,11 @@ def pg_drop_database(name, admin_pass=None, admin_user="postgres", host="localho
def pg_drop_user(name, admin_pass=None, admin_user="postgres", host="localhost", port=5432, **kwargs): def pg_drop_user(name, admin_pass=None, admin_user="postgres", host="localhost", port=5432, **kwargs):
"""Remove a Postgres user. """Remove a Postgres user.
:param name: The user name. - name (str): The user name.
:type name: str - admin_pass (str): The password for the user with sufficient access privileges to execute the command.
- admin_user (str): The name of the user with sufficient access privileges to execute the command.
:param admin_pass: The password for the user with sufficient access privileges to execute the command. - host (str): The database host name or IP address.
:type admin_pass: str - port (int): The port number of the Postgres service running on the host.
:param admin_user: The name of the user with sufficient access privileges to execute the command.
:type admin_user: str
:param host: The database host name or IP address.
:type host: str
:param port: The port number of the Postgres service running on the host.
:type port: int
""" """
# Postgres commands always run without sudo because the -U may be provided. # Postgres commands always run without sudo because the -U may be provided.
@ -206,24 +174,12 @@ def pg_dump_database(name, admin_pass=None, admin_user="postgres", file_name=Non
**kwargs): **kwargs):
"""Export a Postgres database. """Export a Postgres database.
:param name: The database name. - name (str): The database name.
:type name: str - admin_pass (str): The password for the user with sufficient access privileges to execute the command.
- admin_user (str): The name of the user with sufficient access privileges to execute the command.
:param admin_pass: The password for the user with sufficient access privileges to execute the command. - file_name (str): The name/path of the export file. Defaults the database name plus ``.sql``.
:type admin_pass: str - host (str): The database host name or IP address.
- port (int): The port number of the Postgres service running on the host.
:param admin_user: The name of the user with sufficient access privileges to execute the command.
:type admin_user: str
:param host: The database host name or IP address.
:type host: str
:param file_name: The name (including the path, if desired) of the export file. Defaults to the
``database_name`` plus ".sql"
:type file_name: str
:param port: The port number of the Postgres service running on the host.
:type port: int
""" """
_file_name = file_name or "%s.sql" % name _file_name = file_name or "%s.sql" % name
@ -243,23 +199,12 @@ def pg_dump_database(name, admin_pass=None, admin_user="postgres", file_name=Non
def psql(sql, database="template1", host="localhost", password=None, port=5432, user="postgres", **kwargs): def psql(sql, database="template1", host="localhost", password=None, port=5432, user="postgres", **kwargs):
"""Execute a psql command. """Execute a psql command.
:param sql: The SQL to be executed. - sql (str): The SQL to be executed.
:type sql: str - database (str): The database name.
- admin_pass (str): The password for the user with sufficient access privileges to execute the command.
:param database: The database name. - admin_user (str): The name of the user with sufficient access privileges to execute the command.
:type database: str - host (str): The database host name or IP address.
- port (int): The port number of the Postgres service running on the host.
:param password: The password for the user with sufficient access privileges to execute the command.
:type password: str
:param host: The database host name or IP address.
:type host: str
:param port: The port number of the Postgres service running on the host.
:type port: int
:param user: The name of the user with sufficient access privileges to execute the command.
:type user: str
""" """
# Postgres commands always run without sudo because the -U may be provided. # Postgres commands always run without sudo because the -U may be provided.

284
scripttease/library/overlays/posix.py
Unescape View File

@ -20,7 +20,6 @@ __all__ = (
"remove", "remove",
"rename", "rename",
"rsync", "rsync",
"run",
"scopy", "scopy",
"sed", "sed",
"symlink", "symlink",
@ -35,34 +34,12 @@ def archive(from_path, absolute=False, exclude=None, file_name="archive.tgz", st
**kwargs): **kwargs):
"""Create a file archive. """Create a file archive.
:param from_path: The path that should be archived. - from_path (str): The path that should be archived.
:type from_path: str - absolute (bool): Set to ``True`` to preserve the leading slash.
- exclude (str): A pattern to be excluded from the archive.
:param absolute: By default, the leading slash is stripped from each path. Set to ``True`` to preserve the - strip (int): Remove the specified number of leading elements from the path.
absolute path. - to_path (str): Where the archive should be created. This should *not* include the file name.
:type absolute: bool - view (bool): View the output of the command as it happens.
:param bzip2: Compress using bzip2.
:type bzip2: bool
:param exclude: A pattern to be excluded from the archive.
:type exclude: str
:param format: The command to use for the operation.
:type format: str
:param gzip: Compress using gzip.
:type gzip: bool
:param strip: Remove the specified number of leading elements from the path. Paths with fewer elements will be
silently skipped.
:type strip: int
:param to_path: Where the archive should be created. This should *not* include the file name.
:type to_path: str
:param view: View the output of the command as it happens.
:type view: bool
""" """
tokens = ["tar"] tokens = ["tar"]
@ -93,14 +70,9 @@ def archive(from_path, absolute=False, exclude=None, file_name="archive.tgz", st
def certbot(domain_name, email=None, webroot=None, **kwargs): def certbot(domain_name, email=None, webroot=None, **kwargs):
"""Get new SSL certificate from Let's Encrypt. """Get new SSL certificate from Let's Encrypt.
:param domain_name: The domain name for which the SSL certificate is requested. - domain_name (str): The domain name for which the SSL certificate is requested.
:type domain_name: str - email (str): The email address of the requester sent to the certificate authority. Required.
- webroot (str): The directory where the challenge file will be created.
:param email: The email address of the requester sent to the certificate authority. Required.
:type email: str
:param webroot: The directory where the challenge file will be created.
:type webroot: str
""" """
_email = email or os.environ.get("SCRIPTTEASE_CERTBOT_EMAIL", None) _email = email or os.environ.get("SCRIPTTEASE_CERTBOT_EMAIL", None)
@ -122,25 +94,12 @@ def certbot(domain_name, email=None, webroot=None, **kwargs):
def extract(from_path, absolute=False, exclude=None, strip=None, to_path=None, view=False, **kwargs): def extract(from_path, absolute=False, exclude=None, strip=None, to_path=None, view=False, **kwargs):
"""Extract a file archive. """Extract a file archive.
:param from_path: The path to the archive file. - from_path (str): The path that should be archived.
:type from_path: str - absolute (bool): Set to ``True`` to preserve the leading slash.
- exclude (str): A pattern to be excluded from the archive.
:param absolute: By default, the leading slash is stripped from each path. Set to ``True`` to preserve the - strip (int): Remove the specified number of leading elements from the path.
absolute path. - to_path (str): Where the archive should be extracted. This should *not* include the file name.
:type absolute: bool - view (bool): View the output of the command as it happens.
:param exclude: A pattern to be excluded from the archive.
:type exclude: str
:param strip: Remove the specified number of leading elements from the path. Paths with fewer elements will be
silently skipped.
:type strip: int
:param to_path: Where the archive should be extracted.
:type to_path: str
:param view: View the output of the command as it happens.
:type view: bool
""" """
_to_path = to_path or "./" _to_path = to_path or "./"
@ -172,11 +131,8 @@ def extract(from_path, absolute=False, exclude=None, strip=None, to_path=None, v
def file_append(path, content=None, **kwargs): def file_append(path, content=None, **kwargs):
"""Append content to a file. """Append content to a file.
:param path: The path to the file. - path (str): The path to the file.
:type path: str - content (str): The content to be appended.
:param content: The content to be appended.
:type content: str
""" """
kwargs.setdefault("comment", "append to %s" % path) kwargs.setdefault("comment", "append to %s" % path)
@ -187,19 +143,12 @@ def file_append(path, content=None, **kwargs):
def file_copy(from_path, to_path, overwrite=False, recursive=False, **kwargs): def file_copy(from_path, to_path, overwrite=False, recursive=False, **kwargs):
"""Initialize the command. """Copy a file or directory.
:param from_path: The file or directory to be copied.
:type from_path: str
:param to_path: The location to which the file or directory should be copied.
:type to_path: str
:param overwrite: Indicates files and directories should be overwritten if they exist. - from_path (str): The file or directory to be copied.
:type overwrite: bool - to_path (str): The location to which the file or directory should be copied.
- overwrite (bool): Indicates files and directories should be overwritten if they exist.
:param recursive: Copy sub-directories. - recursive (bool): Copy sub-directories.
:type recursive: bool
""" """
kwargs.setdefault("comment", "copy %s to %s" % (from_path, to_path)) kwargs.setdefault("comment", "copy %s to %s" % (from_path, to_path))
@ -220,13 +169,10 @@ def file_copy(from_path, to_path, overwrite=False, recursive=False, **kwargs):
def file_write(path, content=None, **kwargs): def file_write(path, content=None, **kwargs):
"""Initialize the command. """Write to a file.
:param path: The file to be written.
:type path: str
:param content: The content to be written. Note: If omitted, this command is equivalent to :py:class:`Touch`. - path (str): The file to be written.
:type content: str - content (str): The content to be written. Note: If omitted, this command is equivalent to ``touch``.
""" """
_content = content or "" _content = content or ""
@ -246,16 +192,11 @@ def file_write(path, content=None, **kwargs):
def mkdir(path, mode=None, recursive=True, **kwargs): def mkdir(path, mode=None, recursive=True, **kwargs):
"""Initialize the command. """Create a directory.
:param path: The path to be created.
:type path: str
:param mode: The access permissions of the new directory. - path (str): The path to be created.
:type mode: int | str - mode (int | str): The access permissions of the new directory.
- recursive (bool): Create all directories along the path.
:param recursive: Create all directories along the path.
:type recursive: bool
""" """
kwargs.setdefault("comment", "create directory %s" % path) kwargs.setdefault("comment", "create directory %s" % path)
@ -273,6 +214,12 @@ def mkdir(path, mode=None, recursive=True, **kwargs):
def move(from_path, to_path, **kwargs): def move(from_path, to_path, **kwargs):
"""Move a file or directory.
- from_path (str): The current path.
- to_path (str): The new path.
"""
kwargs.setdefault("comment", "move %s to %s" % (from_path, to_path)) kwargs.setdefault("comment", "move %s to %s" % (from_path, to_path))
statement = "mv %s %s" % (from_path, to_path) statement = "mv %s %s" % (from_path, to_path)
@ -280,22 +227,13 @@ def move(from_path, to_path, **kwargs):
def perms(path, group=None, mode=None, owner=None, recursive=False, **kwargs): def perms(path, group=None, mode=None, owner=None, recursive=False, **kwargs):
"""Initialize the command. """Set permissions on a file or directory.
:param path: The path to be changed.
:type path: str
:param group: The name of the group to be applied.
:type group: str
:param mode: The access permissions of the file or directory.
:type mode: int | str
:param owner: The name of the user to be applied. - path (str): The path to be changed.
:type owner: str - group (str): The name of the group to be applied.
- mode (int | str): The access permissions of the file or directory.
:param recursive: Create all directories along the path. - owner (str): The name of the user to be applied.
:type recursive: bool - recursive: Create all directories along the path.
""" """
commands = list() commands = list()
@ -345,16 +283,11 @@ def perms(path, group=None, mode=None, owner=None, recursive=False, **kwargs):
def remove(path, force=False, recursive=False, **kwargs): def remove(path, force=False, recursive=False, **kwargs):
"""Initialize the command. """Remove a file or directory.
:param path: The path to be removed.
:type path: str
:param force: Force the removal. - path (str): The path to be removed.
:type force: bool - force (bool): Force the removal.
- recursive (bool): Remove all directories along the path.
:param recursive: Remove all directories along the path.
:type recursive: bool
""" """
kwargs.setdefault("comment", "remove %s" % path) kwargs.setdefault("comment", "remove %s" % path)
@ -373,13 +306,10 @@ def remove(path, force=False, recursive=False, **kwargs):
def rename(from_name, to_name, **kwargs): def rename(from_name, to_name, **kwargs):
"""Rename of a file or directory. """Rename a file or directory.
:param from_name: The name (or path) of the existing file.
:type from_name: str
:param to_name: The name (or path) of the new file. - from_name (str): The name (or path) of the existing file.
:type to_name: str - to_name (str): The name (or path) of the new file.
""" """
kwargs.setdefault("comment", "rename %s" % from_name) kwargs.setdefault("comment", "rename %s" % from_name)
@ -388,41 +318,21 @@ def rename(from_name, to_name, **kwargs):
def rsync(source, target, delete=False, exclude=None, host=None, key_file=None, links=True, port=22, def rsync(source, target, delete=False, exclude=None, host=None, key_file=None, links=True, port=22,
recursive=True, user=None, **kwargs): recursive=True, user=None, **kwargs):
"""Initialize the command. """Synchronize a directory structure.
:param source: The source directory. - source (str): The source directory.
:type source: str - target (str): The target directory.
- delete (bool): Indicates target files that exist in source but not in target should be removed.
:param target: The target directory. - exclude (str): The path to an exclude file.
:type target: str - host (str): The host name or IP address. This causes the command to run over SSH.
- key_file (str): The privacy SSH key (path) for remote connections. User expansion is automatically applied.
:param delete: Indicates target files that exist in source but not in target should be removed. - links (bool): Include symlinks in the sync.
:type delete: bool - port (int): The SSH port to use for remote connections.
- recursive (bool): Indicates source contents should be recursively synchronized.
:param exclude: The path to an exclude file. - user (str): The user name to use for remote connections.
:type exclude: str
:param host: The host name or IP address. This causes the command to run over SSH and may require a
``key_file``, ``port``, and ``user``.
:type host: str
:param key_file: The path to the private SSH key to use for remove connections. User expansion is
automatically applied.
:type key_file: str
:param links: Include symlinks in the sync.
:type links: bool
:param port: The SSH port to use for remote connections.
:type port: int
:param recursive: Indicates source contents should be recursively synchronized.
:type recursive: bool
:param user: The user name to use for remote connections.
""" """
# :param guess: When ``True``, the ``host``, ``key_file``, and ``user`` will be guessed based on the base name of # - guess: When ``True``, the ``host``, ``key_file``, and ``user`` will be guessed based on the base name of
# the source path. # the source path.
# :type guess: bool # :type guess: bool
# if guess: # if guess:
@ -434,7 +344,7 @@ def rsync(source, target, delete=False, exclude=None, host=None, key_file=None,
# key_file = key_file # key_file = key_file
# user = user # user = user
kwargs.setdefault("comment", "copy %s to remote %s" % (source, target)) kwargs.setdefault("comment", "sync %s with %s" % (source, target))
# rsync -e "ssh -i $(SSH_KEY) -p $(SSH_PORT)" -P -rvzc --delete # rsync -e "ssh -i $(SSH_KEY) -p $(SSH_PORT)" -P -rvzc --delete
# $(OUTPUTH_PATH) $(SSH_USER)@$(SSH_HOST):$(UPLOAD_PATH) --cvs-exclude; # $(OUTPUTH_PATH) $(SSH_USER)@$(SSH_HOST):$(UPLOAD_PATH) --cvs-exclude;
@ -478,32 +388,15 @@ def rsync(source, target, delete=False, exclude=None, host=None, key_file=None,
return Command(statement, **kwargs) return Command(statement, **kwargs)
def run(statement, **kwargs):
"""Run any statement."""
kwargs.setdefault("comment", "run statement")
return Command(statement, **kwargs)
def scopy(from_path, to_path, host=None, key_file=None, port=22, user=None, **kwargs): def scopy(from_path, to_path, host=None, key_file=None, port=22, user=None, **kwargs):
"""Initialize the command. """Copy a file or directory to a remote server.
:param from_path: The source directory.
:type from_path: str
:param to_path: The target directory.
:type to_path: str
:param host: The host name or IP address. Required.
:type host: str
:param key_file: The path to the private SSH key to use for remove connections. User expansion is
automatically applied.
:type key_file: str
:param port: The SSH port to use for remote connections. - from_path (str): The source directory.
:type port: int - to_path (str): The target directory.
- host (str): The host name or IP address. Required.
:param user: The user name to use for remote connections. - key_file (str): The privacy SSH key (path) for remote connections. User expansion is automatically applied.
- port (int): The SSH port to use for remote connections.
- user (str): The user name to use for remote connections.
""" """
kwargs.setdefault("comment", "copy %s to remote %s" % (from_path, to_path)) kwargs.setdefault("comment", "copy %s to remote %s" % (from_path, to_path))
@ -534,19 +427,11 @@ def scopy(from_path, to_path, host=None, key_file=None, port=22, user=None, **kw
def sed(path, backup=".b", delimiter="/", find=None, replace=None, **kwargs): def sed(path, backup=".b", delimiter="/", find=None, replace=None, **kwargs):
"""Find and replace text in a file. """Find and replace text in a file.
:param path: The path to the file to be edited. - path (str): The path to the file to be edited.
:type path: str - backup (str): The backup file extension to use.
- delimiter (str): The pattern delimiter.
:param backup: The backup file extension to use. - find (str): The old text. Required.
:type backup: str - replace (str): The new text. Required.
:param delimiter: The pattern delimiter.
:param find: The old text. Required.
:type find: str
:param replace: The new text. Required.
:type replace: str
""" """
@ -568,16 +453,11 @@ def sed(path, backup=".b", delimiter="/", find=None, replace=None, **kwargs):
def symlink(source, force=False, target=None, **kwargs): def symlink(source, force=False, target=None, **kwargs):
"""Initialize the command. """Create a symlink.
:param source: The source of the link.
:type source: str
:param force: Force the creation of the link.
:type force: bool
:param target: The name or path of the target. Defaults to the base name of the source path. - source (str): The source of the link.
:type target: str - force (bool): Force the creation of the link.
- target (str): The name or path of the target. Defaults to the base name of the source path.
""" """
_target = target or os.path.basename(source) _target = target or os.path.basename(source)
@ -596,10 +476,9 @@ def symlink(source, force=False, target=None, **kwargs):
def touch(path, **kwargs): def touch(path, **kwargs):
"""Initialize the command. """Touch a file or directory.
:param path: The file or directory to touch. - path (str): The file or directory to touch.
:type path: str
""" """
kwargs.setdefault("comment", "touch %s" % path) kwargs.setdefault("comment", "touch %s" % path)
@ -643,14 +522,13 @@ POSIX_MAPPINGS = {
'copy': file_copy, 'copy': file_copy,
'extract': extract, 'extract': extract,
'func': Function, 'func': Function,
'function': Function, # 'function': Function,
'mkdir': mkdir, 'mkdir': mkdir,
'move': move, 'move': move,
'perms': perms, 'perms': perms,
'remove': remove, 'remove': remove,
'rename': rename, 'rename': rename,
'rsync': rsync, 'rsync': rsync,
'run': run,
'scopy': scopy, 'scopy': scopy,
'sed': sed, 'sed': sed,
'ssl': certbot, 'ssl': certbot,

75
scripttease/library/overlays/ubuntu.py
Unescape View File

@ -37,10 +37,23 @@ __all__ = (
def command_exists(name): def command_exists(name):
"""Indicates whether a given command exists in this overaly.
:param name: The name of the command.
:type name: str
:rtype: bool
"""
return name in MAPPINGS return name in MAPPINGS
def apache(op, **kwargs): def apache(op, **kwargs):
"""Execute an Apache-related command.
- op (str): The operation to perform; reload, restart, start, stop, test.
"""
if op == "reload": if op == "reload":
return apache_reload(**kwargs) return apache_reload(**kwargs)
elif op == "restart": elif op == "restart":
@ -56,24 +69,43 @@ def apache(op, **kwargs):
def apache_disable_module(name, **kwargs): def apache_disable_module(name, **kwargs):
"""Disable an Apache module.
- name (str): The module name.
"""
kwargs.setdefault("comment", "disable %s apache module" % name) kwargs.setdefault("comment", "disable %s apache module" % name)
return Command("a2dismod %s" % name, **kwargs) return Command("a2dismod %s" % name, **kwargs)
def apache_disable_site(name, **kwargs): def apache_disable_site(name, **kwargs):
"""Disable an Apache site.
- name (str): The domain name.
"""
kwargs.setdefault("comment", "disable %s apache site" % name) kwargs.setdefault("comment", "disable %s apache site" % name)
return Command("a2dissite %s" % name, **kwargs) return Command("a2dissite %s" % name, **kwargs)
def apache_enable_module(name, **kwargs): def apache_enable_module(name, **kwargs):
"""Enable an Apache module.
- name (str): The module name.
"""
kwargs.setdefault("comment", "enable %s apache module" % name) kwargs.setdefault("comment", "enable %s apache module" % name)
return Command("a2enmod %s" % name, **kwargs) return Command("a2enmod %s" % name, **kwargs)
def apache_enable_site(name, **kwargs): def apache_enable_site(name, **kwargs):
"""Enable an Apache site.
"""
kwargs.setdefault("comment", "enable %s apache module" % name) kwargs.setdefault("comment", "enable %s apache module" % name)
return Command("a2ensite %s" % name, **kwargs) return Command("a2ensite %s" % name, **kwargs)
@ -114,6 +146,11 @@ def apache_test(**kwargs):
def service_reload(name, **kwargs): def service_reload(name, **kwargs):
"""Reload a service.
- name (str): The service name.
"""
kwargs.setdefault("comment", "reload %s service" % name) kwargs.setdefault("comment", "reload %s service" % name)
kwargs.setdefault("register", "%s_reloaded" % name) kwargs.setdefault("register", "%s_reloaded" % name)
@ -121,6 +158,11 @@ def service_reload(name, **kwargs):
def service_restart(name, **kwargs): def service_restart(name, **kwargs):
"""Restart a service.
- name (str): The service name.
"""
kwargs.setdefault("comment", "restart %s service" % name) kwargs.setdefault("comment", "restart %s service" % name)
kwargs.setdefault("register", "%s_restarted" % name) kwargs.setdefault("register", "%s_restarted" % name)
@ -128,6 +170,11 @@ def service_restart(name, **kwargs):
def service_start(name, **kwargs): def service_start(name, **kwargs):
"""Start a service.
- name (str): The service name.
"""
kwargs.setdefault("comment", "start %s service" % name) kwargs.setdefault("comment", "start %s service" % name)
kwargs.setdefault("register", "%s_started" % name) kwargs.setdefault("register", "%s_started" % name)
@ -135,6 +182,11 @@ def service_start(name, **kwargs):
def service_stop(name, **kwargs): def service_stop(name, **kwargs):
"""Stop a service.
- name (str): The service name.
"""
kwargs.setdefault("comment", "stop %s service" % name) kwargs.setdefault("comment", "stop %s service" % name)
kwargs.setdefault("register", "%s_stopped" % name) kwargs.setdefault("register", "%s_stopped" % name)
@ -142,6 +194,11 @@ def service_stop(name, **kwargs):
def system(op, **kwargs): def system(op, **kwargs):
"""Perform a system operation.
- op (str): The operation to perform; reboot, update, upgrade.
"""
if op == "reboot": if op == "reboot":
return system_reboot(**kwargs) return system_reboot(**kwargs)
elif op == "update": elif op == "update":
@ -153,6 +210,11 @@ def system(op, **kwargs):
def system_install(name, **kwargs): def system_install(name, **kwargs):
"""Install a system-level package.
- name (str): The name of the package to install.
"""
kwargs.setdefault("comment", "install system package %s" % name) kwargs.setdefault("comment", "install system package %s" % name)
return Command("apt-get install -y %s" % name, **kwargs) return Command("apt-get install -y %s" % name, **kwargs)
@ -165,6 +227,11 @@ def system_reboot(**kwargs):
def system_uninstall(name, **kwargs): def system_uninstall(name, **kwargs):
"""Uninstall a system-level package.
- name (str): The name of the package to uninstall.
"""
kwargs.setdefault("comment", "remove system package %s" % name) kwargs.setdefault("comment", "remove system package %s" % name)
return Command("apt-get uninstall -y %s" % name, **kwargs) return Command("apt-get uninstall -y %s" % name, **kwargs)
@ -183,6 +250,14 @@ def system_upgrade(**kwargs):
def template(source, target, backup=True, parser=None, **kwargs): def template(source, target, backup=True, parser=None, **kwargs):
"""Create a file from a template.
- source (str): The path to the template file.
- target (str): The path to where the new file should be created.
- backup (bool): Indicates whether a backup should be made if the target file already exists.
- parser (str): The parser to use ``jinja`` (the default) or ``simple``.
"""
return Template(source, target, backup=backup, parser=parser, **kwargs) return Template(source, target, backup=backup, parser=parser, **kwargs)

4
scripttease/parsers/utils.py
Unescape View File

@ -27,8 +27,8 @@ def filter_commands(commands, environments=None, tags=None):
:type environments: list[str] :type environments: list[str]
:param tags: Tag names to be matched. :param tags: Tag names to be matched.
:type tags :type tags: list[str]
:return:
""" """
filtered = list() filtered = list()
for command in commands: for command in commands:

4
setup.py
Unescape View File

@ -22,9 +22,8 @@ setup(
url='https://github.com/develmaycare/python-scripttease', url='https://github.com/develmaycare/python-scripttease',
packages=find_packages(exclude=["tests"]), packages=find_packages(exclude=["tests"]),
include_package_data=True, include_package_data=True,
# superpython provides jinja2 and pygments
install_requires=[ install_requires=[
"jinja2",
"pygments",
"superpython", "superpython",
], ],
dependency_links=[ dependency_links=[
@ -43,6 +42,7 @@ setup(
zip_safe=False, zip_safe=False,
tests_require=[ tests_require=[
"coverage", "coverage",
"pytest",
], ],
test_suite='runtests.runtests', test_suite='runtests.runtests',
entry_points={ entry_points={

5
tests/test_library_overlays_posix.py
Unescape View File

@ -107,6 +107,11 @@ def test_remove():
assert "/path/to/dir" in s assert "/path/to/dir" in s
def test_rename():
c = rename("/path/to/file.txt", "/path/to/renamed.txt")
assert "mv /path/to/file.txt /path/to/renamed.txt" in c.get_statement()
def test_rsync(): def test_rsync():
c = rsync( c = rsync(
"/path/to/local/", "/path/to/local/",

Write Preview
Loading…
Cancel
Save