1This is the README file for pyral, a package implementing a
2Pythonic interface to the Rally REST API
3
4Description
5-----------
6
7The Rally REST Tookit for Python consists of a package that provides a means
8to interact with entities and artifacts in your Rally subscription.  The full
9spectrum of CRUD operations is available in your Rally Workspaces and Projects,
10providing of course that your Rally subscription credentials enable you to perform
11those operations.  The toolkit insulates the package user from having to make
12multiple requests to obtain the full set of qualifying items by performing any
13subsequent "page" requests automatically.
14An additional key feature is the ability to obtain entity sub fields
15that may be references or collections via the familiar dot '.' notation.
16
17Requirements
18------------
19
20The pyral package requires the use of Kenneth Reitz's requests package using version 2.12.0 or better.
21As of requests version 2.0.0, there is support for HTTPS over HTTP proxy via the CONNECT request.
22The requests package can be found via the Python Package Index site (http://pypi/python.org/index).
23The most recent release of pyral (1.5.2) has been tested with requests 2.22.0.
24The six module is also required.
25
26
27Installation
28------------
29
30If you want to pull down the latest release from standard Python package repository
31(pypi.python.org) and install the package, the easiest way is to use
32pip, the Python package installation utility.::
33
34    pip install pyral
35
36Alternatively if you've got the tar.gz or zip distribution on hand, as long as you've
37satisfied the dependency requirements on the six and requests packages, you can use
38the setup mechanism.
39Once requests and six has been installed, run the setup.py program supplied with
40this distribution as::
41
42    python setup.py install
43
44
45Validation
46----------
47
48Copy the template.cfg file to a file named my.cfg.
49Edit my.cfg.  Uncomment and replace the values for SERVER, USER, PASSWORD.
50Leave the WORKSPACE and PROJECT entries commented out for now.
51
52Run the rallyfire.py program as:
53
54$ python rallyfire.py --config=my.cfg
55
56Documentation
57-------------
58
59Obtain the zip file containing the HTML and CSS files comprising the document set for pyral.
60Unzip in a suitable location and point your web browser to the doc/build/html/index.html file.
61
62The rendered documentation is also available at http://pyral.readthedocs.io/en/latest/
63and http://pythonhosted.org/pyral
64
65