Add README (s2technologies#8)

Author: jaschultz

README.md

@@ -1,2 +1,143 @@
 # testspace-python
-Library to interact with Testspace api.
+
+Python module to use Testspace API and client. Provides a python object that can manage the following Testspace items:  url, token, project name and space name. It also provides functions to push results and handle most common API requests.
+
+## Usage
+To use the module the items listed below are needed.
+* Organization url (organization.testspace.com)
+* [Testspace token](https://help.testspace.com/docs/dashboard/admin-user#account)
+* Project name (optional)
+* Space name (optional)
+
+Project and Space names do not have to be set on instantiation of the Testspace object and can be passed as parameters to any function call that requires them. They can also be passed into any of the functions to override, but not update the objects stored values, otherwise the stored values for project and space will be used.
+```
+from testspace import testspace as ts
+token = "access token"
+url = "organization.testspace.com"
+project = "project name"
+space= "space name"
+testspace = ts.Testspace(token=token, url=url, project=project, space=space)
+```
+
+## Testspace Client
+Provides a python wrapper to use the [Testspace client](https://help.testspace.com/docs/reference/testspace-client) for pushing content to [Testspace](https://www.testspace.com/). Optional parameters to this function are available to provide the name of file to push, name of the result set and how.
+
+### Example
+```
+testspace = ts.Testspace(token=token, url=url, project=project, space=space)
+testspace.push(file="testresults.xml", result_name="build.1", how="full")
+```
+The following Testspace client [options](https://help.testspace.com/docs/reference/testspace-client#push) are also supported as parameters to the push function.
+
+|Client Option   | Function Parameter   |
+|---|---|
+|build-url|build_url|
+|repo|repo|
+|link|link|
+|message|message|
+
+
+## Testspace API
+Provides a python wrapper for the [Testspace API](https://help.testspace.com/docs/reference/web-api). The available functions mirror the structure of the documented API endpoints, with GET, POST, PATCH, and DELETE options available as appropriate for the endpoint. Where names in addition to id's are supported in the API, they can be used interchangably here as well. All functions return any JSON response as a result of the request, see Testspace API [help](https://help.testspace.com/docs/reference/web-api) for details of each response. For any Testspace API that returns a list, the page size default limit of 30 is used, for any of these function the `limit` parameter can be added with an integer value for the desired maximum number of returned items. All requests are checked with raise_for_status with the expectation that any exceptions will be appropriately handled by user of the module.
+
+### Projects
+##### Get List of Projects
+```
+testspace.get_projects(limit=30)
+```
+##### Get a Project
+ ```
+testspace.get_project(project=None)
+```
+##### Create a Project
+ ```
+payload = {"name": "new project name"}
+testspace.post_projects(payload=payload)
+```
+##### Update a Project
+```
+payload = {"description": "Awesome project"}
+testspace.patch_project(payload, project=None):
+```
+##### Delete a Project
+```
+testspace.delete_project(project=None)
+```
+### Spaces
+##### Get List of Spaces for a Project
+```
+testspace.get_spaces(project=None, limit=30)
+```
+##### Get specific space
+ ```
+testspace.get_space(project=None, space=None)
+```
+##### Create a Space
+ ```
+payload = {"name": "new space name"}
+testspace.post_spaces(payload=payload, project=None)
+```
+##### Update a Space
+```
+payload = {"description": "Awesome project"}
+testspace.patch_project(payload, project=None, space=None):
+```
+##### Delete a Space
+```
+testspace.delete_space(project=None, space=None)
+```
+### Results
+##### Get list of Results
+```
+testspace.get_results(project=None, space=None, limit=30)
+```
+#### Get Result
+```
+testspace.get_result(result, project=None, space=None)
+```
+#### Failures
+##### Get list of Result Failures
+```
+testspace.get_result_failures(result, project=None, space=None, limit=30)
+```
+#### Contents
+##### Get Result Contents
+```
+# contents_path is used to obtain contents that are not at the root of the result
+testspace.get_result_contents(result, contents_path=None, project=None, space=None, limit=30)
+```
+#### Metric Dataset
+##### Get Metric Dataset
+```
+# Id must be as name resolution is not supported for metrics.
+testspace.get_metric_datasets(metric, project=None, space=None, limit=30)
+```
+### Metrics
+##### Get List of Metrics for a Space
+```
+testspace.get_metrics(project=None, space=None, limit=30)
+```
+##### Get Metric for a Space
+```
+# metric must be id as name resolution is not supported for this.
+testspace.get_metric(metric, project=None, space=None)
+```
+##### Create a Space Metric
+```
+payload = {
+  "name": "MyMetric",
+  "data_source": "/path/to/suite[dataset_label]"
+}
+testspace.post_metrics(payload, project=None, space=None)
+```
+##### Update a Space Metric
+```
+payload = {
+  "data_source": "/path/to/suite[dataset_label]"
+}
+testspace.patch_metrics(payload, metric, project=None, space=None)
+```
+##### Delete a Space Metric
+```
+testspace.delete_metric(metric, project=None, space=None)
+```

testspace/testspace.py

@@ -117,8 +117,6 @@ def get_metrics(self, project=None, space=None, limit=30):
         return self.get_request_json(self.get_metrics_path(project, space), limit=limit)
 
     def get_metric(self, metric, project=None, space=None):
-        if type(metric) is not int:
-            raise ValueError
         return self.get_request_json(self.get_metric_path(metric, project, space))
 
     def get_metric_datasets(self, metric, project=None, space=None, limit=30):
@@ -130,14 +128,20 @@ def get_metric_datasets(self, metric, project=None, space=None, limit=30):
     def post_projects(self, payload):
         return self.post_request_json(path=self.get_projects_path(), payload=payload)
 
-    def post_spaces(self, payload):
-        return self.post_request_json(path=self.get_spaces_path(), payload=payload)
+    def post_spaces(self, payload, project=None):
+        return self.post_request_json(
+            path=self.get_spaces_path(project=project), payload=payload
+        )
 
-    def post_results(self, payload):
-        return self.post_request_json(path=self.get_results_path(), payload=payload)
+    def post_results(self, payload, project=None, space=None):
+        return self.post_request_json(
+            path=self.get_results_path(project=project, space=space), payload=payload
+        )
 
-    def post_metrics(self, payload):
-        return self.post_request_json(path=self.get_metrics_path(), payload=payload)
+    def post_metrics(self, payload, project=None, space=None):
+        return self.post_request_json(
+            path=self.get_metrics_path(project=project, space=space), payload=payload
+        )
 
     def patch_project(self, payload, project=None):
         return self.patch_request(
@@ -149,8 +153,11 @@ def patch_space(self, payload, project=None, space=None):
             path=self.get_space_path(project=project, space=space), payload=payload
         )
 
-    def patch_metric(self, payload, metric):
-        return self.patch_request(path=self.get_metric_path(metric), payload=payload)
+    def patch_metric(self, payload, metric, project=None, space=None):
+        return self.patch_request(
+            path=self.get_metric_path(metric, project=project, space=space),
+            payload=payload,
+        )
 
     def patch_result(self, payload, result):
         return self.patch_request(path=self.get_result_path(result), payload=payload)
@@ -163,11 +170,15 @@ def delete_space(self, project=None, space=None):
             path=self.get_space_path(project=project, space=space)
         )
 
-    def delete_result(self, result):
-        return self.delete_request(path=self.get_result_path(result))
+    def delete_result(self, result, project=None, space=None):
+        return self.delete_request(
+            path=self.get_result_path(result, project=project, space=space)
+        )
 
-    def delete_metric(self, metric):
-        return self.delete_request(path=self.get_metric_path(metric))
+    def delete_metric(self, metric, project=None, space=None):
+        return self.delete_request(
+            path=self.get_metric_path(metric, project=project, space=space)
+        )
 
     def get_request(self, path=None):
         response = self._api_request("GET", path=path)
@@ -232,7 +243,6 @@ def get_space_path(self, project=None, space=None):
                 space = self.space
             else:
                 raise ValueError
-
         return "/".join([self.get_spaces_path(project), str(space)])
 
     def get_results_path(self, project=None, space=None):
@@ -245,7 +255,10 @@ def get_metrics_path(self, project=None, space=None):
         return "/".join([self.get_space_path(project, space), "metrics"])
 
     def get_metric_path(self, metric, project=None, space=None):
-        return "/".join([self.get_metrics_path(project, space), str(metric)])
+        metric_str = str(metric)
+        if str.isdigit(metric_str) is not True:
+            raise ValueError
+        return "/".join([self.get_metrics_path(project, space), metric_str])
 
     def _api_request(self, method, path, payload=None):
         if path is None: