README created

1 files changed, 93 insertions, 0 deletions

diff --git a/README b/README
new file mode 100644
index 0000000..4f79fa9
--- /dev/null
+++ b/README
@@ -0,0 +1,93 @@
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+    Python API for the Nitrate test case management system
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+python-nitrate is a Python interface to the Nitrate test case
+management system. The package consists of a high-level Python
+module (provides natural object interface), a low-level driver
+(allows to directly access Nitrate's xmlrpc API) and a command
+line interpreter (useful for fast debugging and experimenting).
+
+Features
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Among the most essential python-nitrate features are:
+
+    * Natural and concise Python interface
+    * Custom level of caching & logging
+    * Automated status coloring
+    * Integrated test suite
+    * Utility functions
+
+The main motivation was to hide unnecessary implementation details
+wherever possible so that using the API is as concise as possible.
+
+Initialize or create an object:
+
+    testcase = TestCase(1234)
+    testrun = TestRun(testplan=<plan>, summary=<summary>)
+
+Default iterators provided for all container objects:
+
+    for case in TestRun(1234):
+        if case.automated:
+            case.status = Status("RUNNING")
+
+Linking case to a plan is as simple as adding an item to a set:
+
+    testplan.testcases.add(testcase)
+
+However, it's still possible to use the low-level driver when a
+specific features is not implemented yet or not efficient enough:
+
+    testcasehash = Nitrate()._server.TestCase.get(46490)
+
+Scripts importing python-nitrate can make use of several useful
+helper functions including info() for logging to stderr, listed()
+which converts list into nice human readable form, color() for
+coloring and of course log.{debug,info,warn,error} for logging.
+
+
+Examples
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+For a quick start you can get some inspiration in the examples
+directory. The 'matrix.py' script demonstrates how to easily
+display a matrix view of the test run results for a specific test
+plan. The 'create.py' script gives a broader overview covering
+object creation, attribute setting, adjusting logs and caching.
+
+
+Documentation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+For a short introduction see the manual page. For more detailed
+and most up-to-date description of all available nitrate module
+features see Python online documentation using 'pydoc nitrate'.
+
+
+Test Suite
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The high-level interface has an integrated test suite, which can
+be easily run against a stage server instance. For this a couple
+of objects needs to be prepared and already existing on the server
+so that we can check valid results. For detailed information about
+what data has to be prepared see the module documentation.
+
+
+Links
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+python-nitrate project page:
+https://fedorahosted.org/python-nitrate/
+
+Nitrate test case management system:
+https://fedorahosted.org/nitrate/
+
+
+Enjoy!
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Hope, the library will save you time and bring some joy when
+writing scripts interacting with the Nitrate server. Looking
+forward to your feedback, comments, suggestions and patches ;-)
+
+
+Petr Šplíchal
+<psplicha@redhat.com>