Merge pull request #1 from haizaar/master

Public release

.gitignore

@@ -0,0 +1,2 @@
+*.pyc
+*.kdev4

AUTHORS.md

@@ -0,0 +1,4 @@
+
+Krest is written and maintained by Kaminario development team,
+mainly by [Zaar Hai](http://tech.zarmory.com) <[email protected]>.
+

LICENSE

@@ -0,0 +1,7 @@
+
+(c) 2015 Kaminario Technologies, Ltd.
+
+This software is licensed solely under the terms of the Apache 2.0 license,
+the text of which is available at http://www.apache.org/licenses/LICENSE-2.0.
+All disclaimers and limitations of liability set forth in the Apache 2.0 license apply.
+

Makefile

@@ -0,0 +1,40 @@
+
+#
+# (c) 2015 Kaminario Technologies, Ltd.
+#
+# This software is licensed solely under the terms of the Apache 2.0 license,
+# the text of which is available at http://www.apache.org/licenses/LICENSE-2.0.
+# All disclaimers and limitations of liability set forth in the Apache 2.0 license apply.
+#
+
+KREST_VERSION = $(shell grep ^Version: krest.spec | awk '{print $$2}')
+
+TARBALL_DIR = krest-$(KREST_VERSION)
+TARBALL = $(TARBALL_DIR).tar.gz
+
+SPEC_FILE_NAME = krest.spec
+RPMBUILD = /usr/bin/rpmbuild
+
+all: rpm
+
+tarball: clean
+	touch $(TARBALL)  # to stop tar complaining about . being changed while reading
+	tar --exclude .git --exclude $(TARBALL) \
+		--transform='s|^\.|krest-$(KREST_VERSION)|' \
+		-zcvf $(TARBALL) .
+
+rpm: tarball
+	${RPMBUILD} -bb ${SPEC_FILE_NAME} \
+        --define "_sourcedir $$PWD" \
+        --define "_rpmdir $$PWD/RPMS" \
+        --define "_builddir $$PWD" \
+        --define "_tmppath $$PWD/tmp" 
+
+rpm_clean:
+	rm -rf $(TARBALL_DIR) RPMS tmp
+
+clean: rpm_clean
+	rm -rf $(TARBALL)
+
+
+.PHONY: all rpm clean rpm_clean tarball

README.md

@@ -1,2 +1,163 @@
 # krest
-The Kaminario REST (krest) is a client library that provides ORM like interface for working with Kaminario K2 REST API
+
+The Kaminario REST (krest) is a client library that provides ORM like interface for working with 
+[Kaminario K2](http://kaminario.com/flash-array/) 
+REST API.
+
+Krest is written in Python and is aimed to provide rapid enablement of managing
+and monitoring Kaminario K2 all-flash arrays using Python.
+
+This readme file complements the Kaminario K2 REST API guide document. You can request 
+this document from the Kaminario support team.
+
+# Usage
+
+Below are the examples of using krest. Again, we'll mostly explain how the Python interface
+maps to a URL spec which is outlined in K2 REST API guide.
+
+First you need to obtain an endpoint (connection) to your K2 machine:
+```
+import krest
+ep = krest.EndPoint("IP address", "username", "password", ssl_validate=False)
+```
+If you configured your K2 machine with real SSL certificates, set `ssl_validate=True` in the above call.
+
+## Creating and changing objects
+
+Once you've obtained an endpoint, you can use it to CREATE/READ/UPDATE/DELETE objects.
+```
+# create host-group
+hg = ep.new("host_groups")
+hg.name = "hg1"
+hg.save()
+```
+
+Parameters can also be passed inline:
+```
+# save() also returns the updated object
+host = ep.new("hosts", name="h1", type="Linux", host_group=hg).save()
+```
+Note how we can use our `hg` object as host-group reference in newly created volume above.
+
+Changing is simple - just change attributes and hit `.save()`
+```
+host.type = "Windows"
+host.name = "h2"
+host.save()
+```
+
+## Searching stuff
+
+If you know a specific object id, you can `.get()` it:
+```
+vol = ep.get("volumes", 1)
+```
+
+Otherwise use `.search()` to retrieve multiple objects that match search query.
+In the simplest form:
+```
+rv = ep.search("hosts", name="h2") 
+```
+The returned object is a `ResultSet` object that has a `.hits` array containing `RestObject`s.
+The total number of matched objects is recorded in the `ResultSet.total` attribute.
+
+`.search()` method recieves `resource_type`, `options` and query keyword arguments.
+Each query argument is treated as a field name and its value and a requested field value.
+i.e. in the above example, we search for hosts having `name="h2"`. 
+
+You can add search modifiers to field names:
+```
+rv = ep.search("events", level="INFO", message__contains="h1", name__contains="HOST")
+```
+For the full list of search modifiers please refer to the K2 REST API guide.
+
+### Notes on field values
+1. If a field value is an instance of `RestObject`, it is converted to its reference url and `.ref` is added to the field name.
+   This allows native usage of `RestObject` in your code, i.e. `ep.search("hosts", host_group=hg)`
+1. If a field value is instance of `ResultSet`, `list` or `tuple`, then list elements are converted to string by comma-joining
+   and `__in` is added to the field name. This allows doing things like
+   `ep.search("hosts", host_group=[hg1, hg2])
+
+## Working with `ResultSet`s
+`ResultSet`s are returned by the  `.search()` method of `KrestEndPoint`. The number of results returned from the API 
+is limited to 100. You can check the total number of results matching your search query
+by inspecting the `.total` attribute of the result set.
+
+For queries matching a large number of objects, you can use `__limit` and `__offset` query
+parameters to fetch results by chunks.
+
+**NOTE:** Its crucial to sort results to retrieve
+objects in predictable order (use the `__sort` and `__sort_order` query attributes). All objects have an `id` field, to it is a good candidate to be used as a sorting field.
+
+`ResultSet` is iterable, i.e. `for r in rv:...` is similar to
+`for r in rv.hits:...`. It also supports `len(rv)` and *truthy* evaluation.
+
+If you set the `.autofetch` attribute of a `ResultSet` object to 'true' before iterating it,
+it will automatically fetch the next chunk of objects when the current chunk is 
+exhausted. Don't forget to apply the sorting (as in the above note).
+
+
+## Deleting objects
+Once you have a `RestObject` at hand, simply call its `.delete()` method to delete it.
+
+# More examples for object creation and manipulation
+
+
+**NOTE:** All sizes in our K2 REST API are in kilobytes, with performance data being
+the only exception - it returns results in bytes.
+
+Create a volume-group
+```
+vg = ep.new("volume_groups", name="vg1", quota=100*2**20)
+vg.capacity_policy = ep.search("vg_capacity_policies").hits[0]  # search ad-hoc
+vg.save()
+```
+
+Create a volume in the above volume-group
+```
+vol = ep.new("volumes", name="v1", size=10*2**20, volume_group=vg).save()
+```
+
+Map a volume to a host-group
+```
+mapping = ep.new("mappings", volume=vol, host=hg)
+mapping.save()
+```
+
+LUN editing is easy:
+```
+mapping.lun += 10
+mapping.save()
+```
+
+Map a volume to a host
+```
+host2 = ep.new("hosts", name="standalone", type="Linux").save()
+mapping = ep.new("mappings", volume=vol, host=host2).save()
+```
+
+Create a snapshot
+```
+snap = ep.new("snapshots")
+snap.source = vg
+snap.retention_policy = ep.search("retention_policies").hits[0]
+snap.short_name = "s1"   # Note - use short_name, and not just name
+snap.save()
+```
+
+Create a replica from the snapshot and map it
+```
+rep = ep.new("snapshots")
+rep.source = snap
+rep.short_name = "r1"
+rep.retention_policy = ep.search("retention_policies").hits[0]
+rep.is_exposable = True
+rep.save()
+mapping = ep.new("mappings", volume=rep, host=hg).save()
+```
+
+Restoring a volume-group from a snap is a breeze:
+```
+vg.last_restored_from = snap
+vg.save()
+```

bump-version.sh

@@ -0,0 +1,30 @@
+#!/bin/bash
+
+#
+# (c) 2015 Kaminario Technologies, Ltd.
+#
+# This software is licensed solely under the terms of the Apache 2.0 license,
+# the text of which is available at http://www.apache.org/licenses/LICENSE-2.0.
+# All disclaimers and limitations of liability set forth in the Apache 2.0 license apply.
+#
+
+set -e
+
+ver=$1
+if [[ "$ver" == "" ]]; then
+	echo "usage: $0 <new version>"
+	exit 1
+fi
+
+sed -i -r 's/^(__version__ = ")[0-9]+.[0-9]+.[0-9]+/\1'$ver'/' krest.py
+sed -i -r 's/^(Version: +)[0-9]+\.[0-9]+\.[0-9]+/\1'$ver'/' krest.spec
+sed -i -r 's/(version=")[0-9]+\.[0-9]+\.[0-9]+/\1'$ver'/' setup.py
+
+git commit krest.py krest.spec setup.py -m "version bump to $ver"
+git tag -a "v$ver" -m "v$ver"
+
+git push
+git push --tags
+
+echo "Bumped version to $ver and tagged it in git"
+

export-tarball.sh

@@ -0,0 +1,18 @@
+#!/bin/bash
+
+#
+# (c) 2015 Kaminario Technologies, Ltd.
+#
+# This software is licensed solely under the terms of the Apache 2.0 license,
+# the text of which is available at http://www.apache.org/licenses/LICENSE-2.0.
+# All disclaimers and limitations of liability set forth in the Apache 2.0 license apply.
+#
+
+set -e
+
+tag=$1
+if [[ "$tag" == "" ]]; then
+	echo "usage: $0 <tagname>"
+	exit 1
+fi
+git archive --prefix=krest-$tag/ --format=tar v$tag | gzip