Merge pull request #3 from UpCloudLtd/master

Add changes

Author: Faustasm

README.md

@@ -50,13 +50,6 @@ python setup.py install
 * Manage firewall (on/off and individual rules)
 	* since 0.2: full management of firewall rules
 
-**TODO:**
-* Cloning of storages
-* Full management of special storage types:
-  * CDROMs, custom OS templates
-  * (custom templates can already be cloned to a disk via UUID)
-* Full management of backups (instant and scheduled)
-
 **Changelog:**
 * See the [Releases page](https://github.com/UpCloudLtd/upcloud-python-api/releases)
 
@@ -240,21 +233,21 @@ Set up environment and install dependencies:
 # run at project root, python3 and virtualenv must be installed
 virtualenv ENV
 source ENV/bin/activate
-pip install -r requirements.txt
+pip install -r requirements.txt or pip install -r requirements-dev.txt if changes to the api need to be made
 ```
 
 Install the package in editable mode, as mentioned in
-[https://pytest.org/latest/goodpractises.html](https://pytest.org/latest/goodpractises.html)
+[https://docs.pytest.org/en/stable/goodpractices.html](https://docs.pytest.org/en/stable/goodpractices.html)
 
 ```python
 # run at project root
 pip install -e .
 ```
 
-Tests located in `project_root/tests/` directory. Run with:
+Tests located in `project_root/test/` directory. Run with:
 
 ```python
-py.test tests/
+py.test test/
 ```
 
 To test against all supported python versions, run:

docs/Storage.md

@@ -81,3 +81,64 @@ Warning: data loss is permanent.
 storage.destroy()
 
 ```
+
+
+## Clone
+
+Clone the storage using StorageManager.
+Returns an object based on the API's response.
+Method requires title and zone to be passed while tier is optional.
+
+```python
+
+storage_clone = storage.clone(title='title of storage clone', zone=ZONE.Helsinki, tier=None)
+
+```
+
+
+## Cancel clone operation
+
+Cancels a running cloning operation and deletes the incomplete copy using StorageManager.
+Needs to be called from the cloned storage (object returned by clone operation) and not the storage that is being cloned.
+
+```python
+
+storage_clone.cancel_cloning()
+
+```
+
+
+## Create backup
+
+Creates a point-in-time backup of a storage resource using StorageManager.
+Method requires title to be passed.
+
+```python
+
+storage_backup = storage.create_backup('Backup title')
+
+```
+
+
+## Restore backup
+
+Restores the origin storage with data from the specified backup storage using StorageManager.
+Must be called from a storage object created by create_backup and not the original one.
+
+```python
+
+storage_backup.restore_backup()
+
+```
+
+
+## Templatize storage
+
+Creates an exact copy of an existing storage resource which can be used as a template for creating new servers using StorageManager.
+Method requires title to be passed.
+
+```python
+
+storage.templatize('Template title')
+
+```

docs/server-mixin.md

@@ -20,7 +20,7 @@ manager.method()
 ```python
 def get_servers(self, populate=False):
 	"""
-	Returns a list of (populated or unpopulated) Server instances. 
+	Returns a list of (populated or unpopulated) Server instances.
 	Populate = False (default) => 1 API request, returns unpopulated Server instances.
 	Populate = True => Does 1 + n API requests (n = # of servers), returns populated Server instances.
 	"""
@@ -36,14 +36,14 @@ def get_server(self, UUID):
 ```python
 def create_server(self, server):
 	"""
-	Creates a server and its storages based on a (locally created) Server object. 
+	Creates a server and its storages based on a (locally created) Server object.
 	Populates the given Server instance with the API response.
 
 	Example:
 	server1 = Server( core_number = 1,
-				memory_amount = 1024, 
-				hostname = "my.example.1", 
-				zone = ZONE.London, 
+				memory_amount = 1024,
+				hostname = "my.example.1",
+				zone = ZONE.London,
 				storage_devices = [
 					Storage(os = "Ubuntu 14.04", size=10, tier=maxiops, title='The OS drive'),
 					Storage(size=10),
@@ -56,7 +56,7 @@ def create_server(self, server):
 	- size defaults to 10,
 	- title defaults to hostname + " OS disk" and hostname + " storage disk id" (id is a running starting from 1)
 	- tier defaults to maxiops
-	- valid operating systems are: 
+	- valid operating systems are:
 		"CentOS 6.5", "CentOS 7.0"
 		"Debian 7.8"
 		"Ubuntu 12.04", "Ubuntu 14.04"
@@ -76,17 +76,25 @@ def modify_server(self, UUID, **kwargs):
 ```python
 def delete_server(self, UUID):
 	"""
-	DELETE '/server/UUID'. Permanently destroys the virtual machine. 
+	DELETE '/server/UUID'. Permanently destroys the virtual machine.
 	DOES NOT remove the storage disks.
 
 	Returns an empty object.
 	"""
 ```
 
+```python
+def get_server_by_ip(self, ip_address):
+		"""
+		Return a (populated) Server instance by its IP.
+		Uses GET '/ip_address/x.x.x.x' to retrieve machine UUID using IP-address.
+		"""
+```
+
 ```python
 def get_server_data(self, UUID):
 	"""
-	Returns '/server/uuid' data in Python dict. 
+	Returns '/server/uuid' data in Python dict.
 	Creates object representations of any IP-address and Storage.
 	"""
-```
+```

docs/storage-mixin.md

@@ -62,4 +62,68 @@ def detach_storage(self, server_uuid, address):
 	"""
 	Detach a Storage object to a Server. Return a list of the server's storages.
 	"""
-```
+```
+
+```python
+def load_cd_rom(self, server, address):
+	"""
+	Loads a storage as a CD-ROM in the CD-ROM device of a server. Returns a list of the server's storages.
+	"""
+```
+
+```python
+def eject_cd_rom(self, server):
+	"""
+Ejects the storage from the CD-ROM device of a server. Returns a list of the server's storages.
+	"""
+```
+
+```python
+def create_storage_backup(self, storage, title):
+	"""
+Creates a point-in-time backup of a storage resource. Returns a storage object.
+	"""
+```
+
+```python
+def restore_storage_backup(self, storage):
+	"""
+Restores the origin storage with data from the specified backup storage. Returns a storage object.
+	"""
+```
+
+```python
+def templatize_storage(self, storage, title):
+	"""
+Creates an exact copy of an existing storage resource which can be used as a template for creating new servers. Returns a storage object.
+	"""
+```
+
+```python
+def create_storage_import(self, storage, source, source_location=None):
+	"""
+	Creates an import task to import data into an existing storage and returns a storage import object.
+	Source types: http_import or direct_upload.
+	"""
+```
+
+```python
+def upload_file_for_storage_import(self, storage_import, file):
+	"""
+	Uploads a file directly to UpCloud's uploader session. Returns written bytes, md5sum and sha256sum.
+	"""
+```
+
+```python
+def get_storage_import_details(self, storage):
+	"""
+	Returns detailed information of an ongoing or finished import task within a storage import object.
+	"""
+```
+
+```python
+def cancel_storage_import(self, storage):
+	"""
+	Cancels an ongoing import task. Returns a storage import object.
+	"""
+```

test/conftest.py

@@ -51,22 +51,25 @@ def mock_get(target, response_file=None):
         return data
 
     @staticmethod
-    def __put_post_callback(request, target, data):
+    def __put_post_callback(request, target, data, ignore_data_field=False, empty_payload=False):
         data_field = target.split("/")[0]
-        payload = json.loads(request.body)
 
-        for field in data[data_field]:
-            if field in payload[data_field]:
-                data[data_field][field] = payload[data_field][field]
+        if not empty_payload:
+            payload = json.loads(request.body)
+
+        if not ignore_data_field:
+            for field in data[data_field]:
+                if field in payload[data_field]:
+                    data[data_field][field] = payload[data_field][field]
         return(200, {}, json.dumps(data))
 
     @staticmethod
-    def mock_post(target, empty_content=False):
+    def mock_post(target, empty_content=False, ignore_data_field=False, empty_payload=False):
 
         def callback(request):
             if not empty_content:
                 data = json.loads(Mock.read_from_file(target + '_post.json'))
-                return Mock.__put_post_callback(request, target, data)
+                return Mock.__put_post_callback(request, target, data, ignore_data_field, empty_payload)
             else:
                 return(200, {}, '{}')
 
@@ -75,13 +78,14 @@ def callback(request):
                                content_type='application/json')
 
     @staticmethod
-    def mock_put(target):
+    def mock_put(target, ignore_data_field=False, empty_payload=False, call_api=True):
         data = json.loads(Mock.read_from_file(target + '.json'))
 
         def callback(request):
-            return Mock.__put_post_callback(request, target, data)
+            return Mock.__put_post_callback(request, target, data, ignore_data_field, empty_payload)
 
-        responses.add_callback(responses.PUT, Mock.base_url + '/' + target,
+        url = Mock.base_url + '/' + target if call_api else target
+        responses.add_callback(responses.PUT, url,
                                callback=callback,
                                content_type='application/json')
 

test/json_data/https:__fi-hel1.img.upcloud.com_uploader_session_07a6c9a3-300e-4d0e-b935-624f3dbdff3f.json

@@ -0,0 +1 @@
+{"written_bytes":909500125,"md5sum":"5cc6f7e7a1c52303ac3137d62410eec5","sha256sum":"bdf14d897406939c11a73d0720ca75c709e756d437f8be9ee26af6b58ede3bd7"}

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

@@ -0,0 +1,53 @@
+{
+	"server" : {
+		"boot_order" : "disk",
+		"core_number" : "0",
+		"firewall" : "on",
+		"hostname" : "fi.example.com",
+		"ip_addresses" : {
+			"ip_address" : [
+				{
+					"access" : "private",
+					"address" : "10.0.0.0",
+					"family": "IPv4"
+				},
+				{
+					"access" : "public",
+					"address" : "0.0.0.0",
+					"family": "IPv4"
+				}
+			]
+		},
+		"license" : 0,
+		"memory_amount" : "1024",
+		"nic_model" : "e1000",
+		"state" : "started",
+		"storage_devices" : {
+			"storage_device" : [
+				{
+					"address" : "virtio:0",
+					"storage" : "012580a1-32a1-466e-a323-689ca16f2d43",
+					"storage_size" : 100,
+					"storage_title" : "Storage for server1.example.com",
+					"type" : "disk"
+				}
+			]
+		},
+		"tags": {
+			"tag": [
+				"web1",
+				"web2"
+			]
+		},
+		"timezone" : "UTC",
+		"title" : "Helsinki server",
+		"uuid" : "00798b85-efdc-41ca-8021-f6ef457b8531",
+		"video_model" : "cirrus",
+		"vnc" : "on",
+		"vnc_host" : "fi-he1l.vnc.upcloud.com",
+		"vnc_password" : "aabbccdd",
+		"vnc_port" : "00000",
+		"zone" : "fi-hel1",
+		"plan": "custom"
+	}
+}