Merge pull request #24 from escapewindow/master

0.2.0 prep

docs/build_docs.py

@@ -12,7 +12,7 @@
 import subprocess
 import sys
 
-RELEASE_DATE = "2015-05-25 00:00 PDT"
+RELEASE_DATE = "2015-06-21 00:00 PDT"
 READTHEDOCS_LINK = """
 .. image:: https://readthedocs.org/projects/python-scriptharness/badge/?version=latest
     :target: https://readthedocs.org/projects/python-scriptharness/?badge=latest

docs/config.rst

@@ -7,7 +7,7 @@ Configuration Overview
 
 The runtime configuration of a Script_ is built from several layers.
 
-* There is a ConfigTemplate_ that can have default values for certain config variables.  These defaults are the basis of the config dict.  (See :ref:`Config-Templates` for more details on ConfigTemplate_).
+* There is a ConfigTemplate_ that can have default values for certain config variables.  These defaults are the basis of the config dict.  (See :ref:`ConfigTemplates` for more details on ConfigTemplate_).
 
 * The script can define an ``initial_config`` dict that is laid on top of the ConfigTemplate_ defaults, so any shared config variables are overwritten by the ``initial_config``.
 
@@ -22,7 +22,7 @@ The runtime configuration of a Script_ is built from several layers.
 After the config is built, the script logs the config, and saves it to a ``localconfig.json`` file.  This file can be inspected or reused for a later script run.
 
 
-.. _Config-Templates:
+.. _ConfigTemplates:
 
 ###############
 ConfigTemplates

docs/quickstart.rst

@@ -125,7 +125,7 @@ output
 If you run this without any arguments, you might get output like this::
 
     $ ./quickstart.py
-    00:00:00     INFO - Starting at 2015-05-25 00:00 PDT.
+    00:00:00     INFO - Starting at 2015-06-21 00:00 PDT.
     00:00:00     INFO - Enabled actions:
     00:00:00     INFO -  pull, build, package
     00:00:00     INFO - {'new_argument': None,
@@ -168,7 +168,7 @@ The same output is written to the file ``artifacts/log.txt``.
 You can change which actions are run via the ``--actions`` option::
 
     $ ./quickstart.py --actions package upload notify
-    00:00:05     INFO - Starting at 2015-05-25 00:00 PDT.
+    00:00:05     INFO - Starting at 2015-06-21 00:00 PDT.
     00:00:05     INFO - Enabled actions:
     00:00:05     INFO -  package, upload, notify
     00:00:05     INFO - {'new_argument': None,
@@ -239,31 +239,30 @@ see what the config is without running anything, you can use the
 You can always use the ``--help`` option::
 
     $ ./quickstart.py --help
-    usage: quickstart.py [-h] [--dump-config] [--config-file CONFIG_FILE]
-                         [--opt-config-file CONFIG_FILE]
-                         [--action-group {none,all}] [--list-actions]
+    usage: quickstart.py [-h] [--opt-config-file CONFIG_FILE]
+                         [--config-file CONFIG_FILE] [--dump-config]
                          [--actions ACTION [ACTION ...]]
-                         [--add-actions ACTION [ACTION ...]]
                          [--skip-actions ACTION [ACTION ...]]
-                         [--new-argument NEW_ARGUMENT]
+                         [--add-actions ACTION [ACTION ...]] [--list-actions]
+                         [--action-group {none,all}] [--new-argument NEW_ARGUMENT]
     
     optional arguments:
       -h, --help            show this help message and exit
-      --dump-config         Log the built configuration and exit.
-      --config-file CONFIG_FILE, --cfg CONFIG_FILE, -c CONFIG_FILE
-                            Specify required config files/urls
       --opt-config-file CONFIG_FILE, --opt-cfg CONFIG_FILE
                             Specify optional config files/urls
-      --action-group {none,all}
-                            Specify the action group to use.
-      --list-actions        List all actions (default prepended with '*') and
-                            exit.
+      --config-file CONFIG_FILE, --cfg CONFIG_FILE, -c CONFIG_FILE
+                            Specify required config files/urls
+      --dump-config         Log the built configuration and exit.
       --actions ACTION [ACTION ...]
                             Specify the actions to run.
-      --add-actions ACTION [ACTION ...]
-                            Specify the actions to add to the default set.
       --skip-actions ACTION [ACTION ...]
                             Specify the actions to skip.
+      --add-actions ACTION [ACTION ...]
+                            Specify the actions to add to the default set.
+      --list-actions        List all actions (default prepended with '*') and
+                            exit.
+      --action-group {none,all}
+                            Specify the action group to use.
       --new-argument NEW_ARGUMENT
                             help message for --new-argument
 

docs/releasenotes/0.2.0.rst

@@ -1,28 +1,33 @@
 Scriptharness 0.2.0 Release Notes
 =================================
 
-**UNRELEASED**
+:date: 2015/06/21
 
-.. :date: DATE
+Highlights
+----------
+
+This release adds :ref:`Command-and-run`, :ref:`ParsedCommand-and-parse`, and :ref:`Output-get_output-and-get_text_output` with output_timeout and max_timeout support.  ParsedCommand supports context lines (see :ref:`OutputBuffer-and-context-lines`).
 
-Changelog for the unreleased 0.2.0 version.
+It also adds :ref:`ConfigTemplates`, which allow for specifying what a well-formed configuration looks like for a script, as well as config validation.
 
 What's New
 ----------
 * More ways to enable and disable actions.  Now, in addition to ``--actions``, there's ``--add-actions``, ``--skip-actions``, and ``--action-group`` to change the set of default actions to run.  (See :ref:`Enabling-and-Disabling-Actions`.)
 
-* Added ``Command`` object with cross-platform output_timeout and max_timeout support, with a ``run()`` wrapper function for easier use.  This is for running external tools with timeouts.  (See :ref:`Command-and-run`.)
+* Added Command_ object with cross-platform output_timeout and max_timeout support, with a `run()`_ wrapper function for easier use.  This is for running external tools with timeouts.  (See :ref:`Command-and-run`.)
+
+    * Added ScriptHarnessTimeout_ exception
 
-    * Added ``ScriptHarnessTimeout`` exception
+* Added ParsedCommand_ subclass of Command_.  Also added a `parse()`_ wrapper function for easier use.  This is for running external tools, and parsing the output of those tools to detect errors. (See :ref:`ParsedCommand-and-parse`.)
 
-* Added ``ParsedCommand`` subclass of ``Command``.  Also added a ``parse()`` wrapper function for easier use.  This is for running external tools, and parsing the output of those tools to detect errors. (See :ref:`ParsedCommand-and-parse`.)
+    * Added ErrorList_, OutputParser_ objects for ParsedCommand_ error parsing.  (See :ref:`ErrorLists-and-OutputParser`.)
+    * Added OutputBuffer_ object for ParsedCommand_ context lines support.  (See :ref:`OutputBuffer-and-context-lines`.)
 
-    * Added ``ErrorList``, ``OutputParser`` objects for ``ParsedCommand`` error parsing.  (See :ref:`ErrorLists-and-OutputParser`.)
-    * Added ``OutputBuffer`` object for ``ParsedCommand`` context lines support.  (See :ref:`OutputBuffer-and-context-lines`.)
+* Added Output_ object with cross-platform output_timeout and max_timeout support.  Also added `get_output()`_, and `get_text_output()`_ wrapper functions for easier use.  This is for capturing the output of an external tool for later use.  (See :ref:`Output-get_output-and-get_text_output`.)
 
-* Added ``Output`` object with cross-platform output_timeout and max_timeout support.  Also added ``get_output()``, and ``get_text_output()`` wrapper functions for easier use.  This is for capturing the output of an external tool for later use.  (See :ref:`Output-get_output-and-get_text_output`.)
+* Added ConfigVariable_ and ConfigTemplate_ objects for configuration definition and validation support.  See :ref:`ConfigTemplates`.
 
-* Added ``ConfigVariable`` and ``ConfigTemplate`` objects for configuration definition and validation support.  See :ref:`Config-Templates`.
+* Added documentation.
 
 * Script.actions is now a namedtuple
 
@@ -34,10 +39,22 @@ What's New
 
 * pylint 10.00
 
-Known Issues
-------------
-* Current issues are tracked here_.
-
-.. _here: https://github.com/scriptharness/python-scriptharness/issues
+* `Current issues`_ are tracked on GitHub.
 
 .. note:: If you've cloned python-scriptharness 0.1.0, you may need to remove the ``scriptharness/commands`` directory, as it will conflict with the new ``scriptharness/commands.py`` module.
+
+
+.. _Command: scriptharness.commands.html#scriptharness.commands.Command
+.. _ConfigTemplate: scriptharness.config.html#scriptharness.config.ConfigTemplate
+.. _ConfigVariable: scriptharness.config.html#scriptharness.config.ConfigVariable
+.. _Current issues: https://github.com/scriptharness/python-scriptharness/issues
+.. _ErrorList: scriptharness.errorlists.html#scriptharness.errorlists.ErrorList
+.. _Output: scriptharness.commands.html#scriptharness.commands.Output
+.. _OutputBuffer: scriptharness.log.html#scriptharness.log.OutputBuffer
+.. _OutputParser: scriptharness.log.html#scriptharness.log.OutputParser
+.. _ParsedCommand: scriptharness.commands.html#scriptharness.commands.ParsedCommand
+.. _ScriptHarnessTimeout: scriptharness.exceptions.html#scriptharness.exceptions.ScriptHarnessTimeout
+.. _get_output(): scriptharness.commands.html#scriptharness.commands.get_output
+.. _get_text_output(): scriptharness.commands.html#scriptharness.commands.get_text_output
+.. _parse(): scriptharness.commands.html#scriptharness.commands.parse
+.. _run(): scriptharness.commands.html#scriptharness.commands.run

docs/releasenotes/releasenotes_template

@@ -5,10 +5,9 @@ Scriptharness 0.X.Y Release Notes
 
 COMMENT
 
-What's New
+Highlights
 ----------
-*
 
-Known Issues
-------------
+What's New
+----------
 *

scriptharness/commands.py

@@ -76,11 +76,15 @@ def check_output(command, logger_name="scriptharness.commands.check_output",
 
     Args:
       command (str or list): The command to run.
+
       logger_name (Optional[str]): the logger name to log with.
+
       level (Optional[int]): the logging level to log with.  Defaults to
         logging.INFO
+
       log_output (Optional[bool]): When true, log the output of the command.
         Defaults to True.
+
       **kwargs: sent to `subprocess.check_output()`
     """
     logger = logging.getLogger(logger_name)
@@ -160,7 +164,6 @@ def __init__(self, command, logger=None, detect_error_cb=None, **kwargs):
         self.history = {}
         self.kwargs = kwargs or {}
         self.strings = deepcopy(STRINGS['command'])
-        self.process = None
 
     def log_env(self, env):
         """Log environment variables.  Here for subclassing.
@@ -311,8 +314,11 @@ class Output(Command):
 
     Attributes:
       strings (dict): Strings to log.
+
       stdout (NamedTemporaryFile): file to log stdout to
+
       stderr (NamedTemporaryFile): file to log stderr to
+
       + all of the attributes in scriptharness.commands.Command
     """
     def __init__(self, *args, **kwargs):
@@ -378,6 +384,7 @@ def get_output(self, handle_name="stdout", text=True):
         Args:
           handle_name (Optional["stdout" or "stderr"]): the handle to read
             from.  Defaults to "stdout"
+
           text (Optional[bool]): whether the output is text.  If so, run
             output through to_unicode() and rstrip().  Defaults to True.
         """
@@ -454,6 +461,7 @@ def parse(command, **kwargs):
 
     Args:
       command (list or str): Command line to run.
+
       **kwargs: kwargs for run/ParsedCommand.
 
     Returns:

scriptharness/config.py

@@ -6,6 +6,13 @@
 Attributes:
   LOGGER_NAME (str): logging.getLogger name
 
+  OPTION_REGEX (re.compile): regular expression to validate a commandline
+    option
+
+  VALID_ARGPARSE_ACTIONS (tuple): for validating the ConfigVariable action
+
+  STRINGS (dict): strings for ConfigVariable
+
   DEFAULT_CONFIG_DEFINITION (dict): Config definition to create the default
     ConfigTemplate for all scriptharness scripts.
 """
@@ -151,7 +158,9 @@ def download_url(url, path=None, timeout=None):
 
     Args:
       url (str): the url to download
+
       path (Optional[str]): the path to write the contents to.
+
       timeout (Optional[float]): how long to wait before timing out.
 
     Returns:
@@ -200,8 +209,11 @@ def get_list_actions_string(action_name, enabled, groups=None):
 
     Args:
       action_name (str):  name of the action
+
       enabled (bool): whether the action is enabled by default
-      groups (list): a list of action_group names that the action belongs to.
+
+      groups (Optional[list]): a list of action_group names that the action
+        belongs to.  Defaults to None.
 
     Returns:
       string (str): a line of --list-actions output.
@@ -438,6 +450,9 @@ def validate_config_definition(name, definition):
     Args:
       name (str): the name of the variable
       definition (dict): the definition to validate
+
+    Raises:
+      ScriptHarnessException: if there are any error messages
     """
     messages = []
     if definition.get('options'):
@@ -493,6 +508,7 @@ class ConfigVariable(object):
                                 # or highly recommended.
         'required': True,
         'default': 'bar',
+        'parent_parser': 'parent',  # this is for argparse --help sorting
         'type': str,  # a python type
         'choices': [],  # enum / list of choices
 

scriptharness/log.py

@@ -338,7 +338,8 @@ def pop_buffer(self, num=1):
         level set for each line.
 
         Args:
-          num (int): The number of lines to pop and log.
+          num (Optional[int]): The number of lines to pop and log.  Defaults
+            to 1.
         """
         for _ in range(0, num):
             self.logger.log(
@@ -406,7 +407,7 @@ def __init__(self, error_list, logger=None, **kwargs):
         Args:
           error_list (list of dicts): list of errors to look for.
 
-          logger (Optional[logging.Logger]): logger to use.
+          logger (Optional[logging.Logger]): logger to use.  Defaults to None.
 
           **kwargs: These are ignored, and are here so we can subclass
             ParsedCommand.

scriptharness/os.py

@@ -18,7 +18,9 @@ def makedirs(path, level=logging.INFO, context=None):
 
     Args:
       path (str): path to the directory
-      level (Optional[int]): the logging level to log with.
+
+      level (Optional[int]): the logging level to log with.  Defaults to
+        logging.INFO.
     """
     if context:
         logger = context.logger

scriptharness/script.py

@@ -144,7 +144,7 @@ def __init__(self, actions, template, name='root', **kwargs):
           actions (tuple): Action objects to run.
           template (ConfigTemplate): template to use
           name (Optional[str]): The name of the Script in
-            scriptharness.ScriptManager
+            scriptharness.ScriptManager.  Defaults to 'root'
           **kwargs: These are passed to self.build_config()
 
         Raises:

scriptharness/structures.py

@@ -180,7 +180,10 @@ def recursively_set_parent(self, name=None, parent=None):
 
         Args:
           name (Optional[str]): set self.name, for later logging purposes.
+            Defaults to None.
+
           parent (Optional[Logging*]): set self.parent, for logging purposes.
+            Defaults to None.
         """
         if name is not None:
             self.name = name

scriptharness/unicode.py

@@ -16,7 +16,7 @@ def to_unicode(obj, encoding='utf-8'):
 
     Args:
         obj (str): the string to encode
-        encoding (Optional[str]): the encoding to use
+        encoding (Optional[str]): the encoding to use.  Defaults to 'utf-8'.
 
     Returns:
         obj (unicode): the encoded string

scriptharness/version.py

@@ -47,7 +47,7 @@ def get_version_string(version):
 
 # 1}}}
 # Semantic versioning 2.0.0  http://semver.org/
-__version__ = (0, 2, 0, 'alpha')
+__version__ = (0, 2, 0)
 __version_string__ = get_version_string(__version__)
 
 

version.json

@@ -2,8 +2,7 @@
     "version": [
         0,
         2,
-        0,
-        "alpha"
+        0
     ],
-    "version_string": "0.2.0-alpha"
+    "version_string": "0.2.0"
 }