Merge pull request #10 from UpCloudLtd/0.3.0-devel

0.3.0 devel

Author: Elias Nygren

README.md

@@ -1,23 +1,23 @@
-# UpCloud-python-api
-Python client for [UpCloud's API](https://www.upcloud.com/documentation/api/).
+# UpCloud's Python API Client
+OOP-based api client for [UpCloud's API](https://www.upcloud.com/documentation/api/). Features most of the API's functionality and some convenience functions that combine several API endpoints and logic.
 
-NOTE: This Python client is still work-in-progress and is not considered production ready.
+NOTE: This Python client is still evolving. Please test all of your use cases thoroughly before actual production use. Using a separate UpCloud account for testing / developing the client is recommended.
 
 ## Installation
 
 ```
-pip install --pre upcloud-api-python
+pip install --pre upcloud-api
 
 # with older pip:
-pip install upcloud-api-python
+pip install upcloud-api
 ```
 
 Alternatively, clone the project and run
 ```
 python setup.py install
 ```
 
-**Supported versions** (offline tests pass with tox):
+**Supported versions as of 0.3.0** (offline tests pass with tox):
 
 * python 2.6
 * python 2.7
@@ -112,6 +112,11 @@ for server in cluster:
 
 ```
 
+New in 0.3.0: servers can now be defined as dicts without using Server or Storage classes.
+The syntax/attributes are exactly like above and under the hood they are converted to Server and Storage classes.
+This feature is mainly for easier usage of the module from Ansible, but may provide useful elsewhere.
+
+
 ### Stop / Start / Destroy Servers
 ```python
 
@@ -126,6 +131,18 @@ for server in cluster:
 
 ```
 
+New in 0.3.0: as the success of server.start() or server.destroy() and storage.destroy() 
+depend on the Server's `state`, new helpers have been added. The helpers may be called regardless of
+the server's current state.
+
+```python
+# makes sure that the server is stopped (blocking wait) and then destroys the server and its storages
+server.stop_and_destroy()
+
+# makes sure that the server is started (blocking wait)
+server.ensure_started()
+```
+
 ### Upgrade a Server
 ```python
 
@@ -138,6 +155,20 @@ server.start()
 
 ```
 
+### Easy access to servers and their information:
+
+New in 0.3.0.
+
+```python
+
+# returns a public IPv4 (preferred) IPv6 (no public IPv4 was attached) address
+server.get_public_ip()
+
+# returns a JSON serializable dict with the server's information (storages and ip-addresses included)
+server.to_dict()
+
+```
+
 ### GET resources:
 ```python
 

setup.py

@@ -3,16 +3,16 @@
 from setuptools import setup
 
 setup(
-    name='upcloud-api-python',
-    version='0.2.0',
+    name='upcloud-api',
+    version='0.3.0',
     description='UpCloud API Client',
     author='Elias Nygren',
     author_email='elias.nygren@upcloud.com',
     maintainer='Elias Nygren',
     maintainer_email='elias.nygren@upcloud.com',
     url='https://github.com/UpCloudLtd/upcloud-python-api',
-    packages=['upcloud', 'upcloud.cloud_manager'],
-    download='https://github.com/UpCloudLtd/upcloud-python-api/tarball/v0.2.0',
+    packages=['upcloud_api', 'upcloud_api.cloud_manager'],
+    download='https://github.com/UpCloudLtd/upcloud-python-api/tarball/v0.3.0',
     license='MIT',
     install_requires=[
     	'future==0.14.3',

test/conftest.py

@@ -2,20 +2,16 @@
 from __future__ import print_function
 from __future__ import division
 from __future__ import absolute_import
-from builtins import open
+from builtins import object, open
 from future import standard_library
 standard_library.install_aliases()
-from builtins import object
-import os
-import pytest
-import responses
-import json
 
+import json, os, pytest, responses
 
 @pytest.fixture(scope='module')
 def manager():
-    import upcloud
-    return upcloud.CloudManager("testuser", "mock-api-password")
+    import upcloud_api
+    return upcloud_api.CloudManager("testuser", "mock-api-password")
 
 
 class Mock(object):

test/json_data/server.json

@@ -8,7 +8,12 @@
 				"hostname" : "fi.example.com",
 				"memory_amount" : "512",
 				"uuid" : "00798b85-efdc-41ca-8021-f6ef457b8531",
-				"state" : "started"
+				"state" : "started",
+				"tags": {
+					"tag": [
+						"web1"
+					]
+				}
 			},
 			{
 				"zone" : "uk-lon1",
@@ -17,8 +22,13 @@
 				"hostname" : "uk.example.com",
 				"memory_amount" : "512",
 				"uuid" : "009d64ef-31d1-4684-a26b-c86c955cbf46",
-				"state" : "stopped"
+				"state" : "stopped",
+				"tags": {
+					"tag": [
+						"web2"
+					]
+				}
 			}
 		]
 	}
-}
+}

test/json_data/server_00798b85-efdc-41ca-8021-f6ef457b8531.json

@@ -31,6 +31,11 @@
 				}
 			]
 		},
+		"tags": {
+			"tag": [
+				"web1"
+			]
+		},
 		"timezone" : "UTC",
 		"title" : "Helsinki server",
 		"uuid" : "00798b85-efdc-41ca-8021-f6ef457b8531",
@@ -41,4 +46,4 @@
 		"vnc_port" : "00000",
 		"zone" : "fi-hel1"
 	}
-}
+}

test/json_data/server_009d64ef-31d1-4684-a26b-c86c955cbf46.json

@@ -31,6 +31,11 @@
 				}
 			]
 		},
+		"tags": {
+			"tag": [
+				"web2"
+			]
+		},
 		"timezone" : "UTC",
 		"title" : "London server",
 		"uuid" : "009d64ef-31d1-4684-a26b-c86c955cbf46",
@@ -41,4 +46,4 @@
 		"vnc_port" : "00000",
 		"zone" : "uk-lon1"
 	}
-}
+}

test/live_test.py

@@ -5,11 +5,11 @@
 from builtins import input
 from future import standard_library
 standard_library.install_aliases()
-import sys
-from time import sleep
 
-import upcloud
-from upcloud import CloudManager, Server, Storage, FirewallRule, ZONE
+from upcloud_api import CloudManager, Server, Storage, FirewallRule, ZONE
+
+from time import sleep
+import sys
 
 # cluster to be used in live tests
 cluster = {

test/test_cloud_manager.py

@@ -2,18 +2,19 @@
 from __future__ import print_function
 from __future__ import division
 from __future__ import absolute_import
+from builtins import object
 from future import standard_library
 standard_library.install_aliases()
-from builtins import object
-import responses
-import json
+
 from conftest import Mock
+import json, responses
+
 
 class TestCloudManagerBasic(object):
 	@responses.activate
 	def test_get_account(self, manager):
 		data = Mock.mock_get("account")
-		
+
 		res = manager.authenticate()
 		assert json.loads(data) == res
 		res = manager.get_account()

test/test_firewall.py

@@ -2,14 +2,14 @@
 from __future__ import print_function
 from __future__ import division
 from __future__ import absolute_import
+from builtins import object
 from future import standard_library
 standard_library.install_aliases()
-from builtins import object
-from upcloud import FirewallRule
-import responses
-import json
+
+from upcloud_api import FirewallRule
+
 from conftest import Mock
-import pytest
+import json, pytest, responses
 
 
 def firewall_rule_callback(request):

test/test_ip_manager.py

@@ -2,12 +2,12 @@
 from __future__ import print_function
 from __future__ import division
 from __future__ import absolute_import
+from builtins import object
 from future import standard_library
 standard_library.install_aliases()
-from builtins import object
-import responses
-import json
+
 from conftest import Mock
+import json, responses
 
 class TestIP(object):
 	@responses.activate
@@ -52,10 +52,10 @@ def test_modify_ip(self, manager):
 		data = Mock.mock_put("ip_address/10.1.0.101")
 		ip_addr = manager.modify_IP("10.1.0.101", ptr_record="my.ptr.record")
 		assert ip_addr.ptr == "my.ptr.record"
-		
+
 
 	@responses.activate
 	def test_ip_delete(self, manager):
 		Mock.mock_delete("ip_address/10.1.0.101")
 		res = manager.release_IP("10.1.0.101")
-		assert res == {}
+		assert res == {}