Add API to test installation, and better documentation.

buildcat/__init__.py

@@ -23,6 +23,5 @@
 
 __version__ = "0.1.0-dev"
 
-log = logging.getLogger(__name__)
-log.addHandler(logging.NullHandler())
+log = logging.getLogger("rq.worker")
 

buildcat/hou.py

@@ -23,6 +23,7 @@
 import subprocess
 
 def get_version():
+    """Return version and path information describing the worker's local Houdini installation."""
     command = ["hython", "-c", "print(hou.applicationVersionString())"]
     return subprocess.check_output(command).strip().decode("utf-8")
 

buildcat/test.py

@@ -0,0 +1,46 @@
+# Copyright 2018 Timothy M. Shead
+#
+# This file is part of Buildcat.
+#
+# Buildcat is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# Buildcat is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with Buildcat.  If not, see <http://www.gnu.org/licenses/>.
+
+"""Functionality for testing the buildcat installation and setup.
+"""
+
+from __future__ import absolute_import, division, print_function
+
+import buildcat
+
+def log_message(message):
+    """Log a message.
+
+    Parameters
+    ----------
+    message: str, required
+        The message to be logged.
+    """
+    buildcat.log.info(message)
+
+def raise_exception(e):
+    """Raise an exception.
+
+    Useful for testing the reliability of workers.
+
+    Parameters
+    ----------
+    e: exception object, required
+        The exception to be raised.
+    """
+    raise e
+

buildcat/worker.py

@@ -15,6 +15,8 @@
 # You should have received a copy of the GNU General Public License
 # along with Buildcat.  If not, see <http://www.gnu.org/licenses/>.
 
+"""Custom RQ worker class for Windows portability.
+"""
 
 from __future__ import absolute_import, division, print_function
 
@@ -27,6 +29,11 @@
 
 
 class NeverTimeout(rq.timeouts.BaseDeathPenalty):
+    """Do-nothing object that never times out.
+
+    This is part of the :class:`buildcat.worker.NoForkWorker` implementation,
+    since the latter provides no way to interrupt a running job.
+    """
     def setup_death_penalty(self):
         log.warning("Job will never timeout.")
 
@@ -35,5 +42,15 @@ def cancel_death_penalty(self):
 
 
 class NoForkWorker(rq.worker.SimpleWorker):
+    """RQ worker class that does not fork.
+
+    The default RQ worker class forks to handle each job for reliability, so that
+    the worker process can keep running even if the job causes the child process to crash.
+
+    Unfortunately, Python does not support :func:`os.fork` on Windows, making this alternative
+    implementation necessary.  You should use this class when starting workers on Windows for use with Buildcat:
+
+        $ rq worker -w buildcat.worker.NoForkWorker
+    """
     death_penalty_class = NeverTimeout
 

docs/buildcat.test.rst

@@ -0,0 +1,7 @@
+buildcat.test module
+====================
+
+.. automodule:: buildcat.test
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/reference.rst

@@ -12,4 +12,5 @@ Contents:
 
    buildcat.rst
    buildcat.hou.rst
+   buildcat.test.rst
    buildcat.worker.rst