documentation and minor changes to make code more consistent

Author: Elias Nygren

README.md

@@ -1,6 +1,8 @@
 # UpCloud-python-api
 Python client for [UpCloud's API](https://www.upcloud.com/documentation/api/).
 
+NOTE: This Python client is still work-in-progress and is not considered production ready.
+
 ## Features
 * OOP based management of Servers, Storages and IP-addresses with full CRUD.
 * Clear way to define your infrastructure, emphasis on clear and easy syntax

docs/CloudManager.md

@@ -0,0 +1,50 @@
+# Account / Authentication
+
+```python
+
+# create manager and form a token
+manager = CloudManager("api-username", "password")
+
+# test token
+manager.authenticate() # alias: get_account()
+manager.get_account()
+
+```
+
+# Zone
+
+Zones are already hardcoded as Enums in `upcloud.ZONE`. However, they can be queried from the API too.
+
+```python
+
+manager.get_zones()
+
+```
+
+# TimeZone
+
+Timezone can be given as a parameter to a server during creation and update.
+
+```python
+
+manager.get_timezones()
+
+```
+
+# Pricing
+
+```python
+
+manager.get_pricing()
+
+```
+
+# Server Sizes
+
+List the possible server CPU-ram configurations.
+
+```python
+
+manager.get_server_sizes
+
+```

docs/IP-address-mixin.md

@@ -0,0 +1,56 @@
+## About
+
+```python
+class IPManager():
+	"""
+	Functions for managing IP-addresses. 
+	Intended to be used as a mixin for CloudManager.
+	"""
+```
+
+`IPManager` is a mixed into `CloudManager` and the following methods are available by
+
+```python
+manager = CloudManager("api-username", "password")
+manager.method()
+```
+
+## Methods
+
+
+```python
+def get_IP(self, address):
+	"""
+	Get an IP_address object with the IP address (string) from the API.
+	e.g manager.get_IP("80.69.175.210")
+	"""
+```
+
+```python
+def get_IPs(self):
+	"""
+	Get all IP_address objects from the API.
+	"""
+```
+
+```python
+def attach_IP(self, server):
+	"""
+	Attach a new (random) IP_address to the given server (object or UUID)
+	"""
+```		
+```python
+def modify_IP(self, IP_addr, ptr_record):
+	"""
+	Modify an IP address' ptr-record (Reverse DNS). 
+	Accepts an IP_address instance (object) or its address (string).
+	"""
+```
+
+```python
+def release_IP(self, IP_addr):
+	"""
+	Destroy an IP_address. Returns an empty object.
+	Accepts an IP_address instance (object) or its address (string).
+	"""
+```

docs/IP-address.md

@@ -0,0 +1,63 @@
+
+
+## About
+
+
+```
+Attributes:
+	access 		-- "public" or "private"
+	address 	-- the IP address (string)
+	ptr_record 	-- the reverse DNS name (string)
+	server 		-- the UUID of the server this IP is attached to (string)
+```
+
+The only updateable attribute is the `ptr_record`.   
+`ptr_record` and `server` are present only if /server/uuid endpoint was used.
+
+## List / Get
+
+CloudManager returns IP-address objects.
+
+```python
+
+manager.get_IPs()
+manager.get_IP("185.20.31.125")
+
+```
+
+## Create
+
+The new IP-address must be attached to a server and has a random address.
+
+```python
+
+# param: server uuid or a Server object
+manager.attach_IP(server_uuid)
+manager.attach_IP(Server)
+
+# or use Server instance
+server = manager.get_server(uuid)
+server.add_IP()
+
+```
+
+## Update
+
+At the moment only the ptr_record (reverse DNS) of an IP can be changed.
+
+```python
+
+ip = manager.get_IP("185.20.31.125")
+ip.ptr_record = "the.new.ptr.record"
+ip.save()
+
+```
+
+## Destroy
+
+```python
+
+ip = manager.get_IP("185.20.31.125")
+ip.destroy()
+
+```

docs/Server.md

@@ -0,0 +1,144 @@
+The examples use the following:
+```python
+import upcloud
+from upcloud import Server
+from upcloud import Storage
+from upcloud import ZONE
+
+manager = upcloud.CloudManager("username", "password")
+```
+
+# Start / Stop / Restart
+
+```python
+
+server.stop() 		
+server.start()
+server.restart()
+
+# populate the object with updated information from API
+server.populate()
+
+```
+
+Please note that the server might not be stopped/started/restarted immediately when the API responds. The `.populate()` method updates the object's fields from the API and is thus useful for checking `server.state`.
+
+```
+Server states: 
+	"started","stopped" -- server is shut down or running
+	"maintenance" 		-- when shutting down or (re)starting
+	"error" 			-- erronous state in UpCloud's backend
+```
+
+
+
+## List / Get
+
+The CloudManager returns Server instances.
+
+```python
+
+servers = manager.get_servers()
+server = manager.get_server(servers[0].uuid)
+
+```
+
+## Create
+
+Creation of servers in the API is handled by the CloudManager. It accepts a Server instance, forms the correct POST request and populates the Server instance's fields from the POST response.
+
+```python
+
+server = Server(
+			core_number = 1, 
+			memory_amount = 512, 
+			hostname = "web1.example.com", 
+			zone = ZONE.London, 
+			storage_devices = [
+				Storage(os = "Ubuntu 14.04", size=10),
+				Storage(size=10, tier="hdd")
+			])
+
+manager.create_server( server )
+
+```
+
+Currently available Storage operating systems are the following UpCloud public templates:
+
+```python
+# upcloud/tools.py
+
+Operating Systems:
+	"CentOS 6.5", "CentOS 7.0", 
+	"Debian 7.8", "Ubuntu 12.04", "Ubuntu 14.04", 
+	"Windows 2003", "Windows 2008", "Windows 2012"
+
+```
+
+
+Please refer to the [API documentation](https://www.upcloud.com/static/downloads/upcloud-apidoc-1.1.1.pdf) for the allowed Server attributes.
+
+## Update
+
+### Attributes
+
+Updating a Server's attributes is done with its `.save()` method that does a PUT request. If you want to manage the Server's Storages or IP-addresses, see below.
+
+```python
+
+server = manager.get_server( uuid )
+server.core_number = 4
+server.memory_amount = 4096
+server.save()
+
+```
+
+The following fields of Server instance may be updated, all other fields are read-only. Trying to assign values to other fields leads to an error.  
+	
+```python
+Updateable attributes: 
+	"boot_order", "core_number", "firewall", "hostname", "memory_amount",  
+	"nic_model", "title", "timezone", "video_model", "vnc", "vnc_password"
+```
+
+Please refer to the [API documentation](https://www.upcloud.com/static/downloads/upcloud-apidoc-1.1.1.pdf) for the allowed values.
+
+### Storages
+
+A Server's Storages can be attached and detached with `.add_storage()` and `.remove_storage()`. Both requests issue an API request instantly.
+
+```python
+
+# attach
+storage = manager.create_storage( size=100, zone=ZONE.Helsinki )
+server.add_storage(storage)
+
+# detach
+storage = server.storage_devices[1]
+server.remove_storage(storage)
+
+```
+
+### IP-addresses
+
+A Server's Storages can be attached and detached with `.add_IP()` and `.remove_IP()`. Both requests issue an API request instantly. Note that the attached IP is allocated randomly as UpCloud's does not (yet) support floating IPs.
+
+```python
+
+# attach
+IP = server.add_IP()
+
+# detach
+server.remove_IP(IP)
+
+```
+
+## Destroy
+
+Destroys the Server instance and its IP-addresses. However, does not destroy the Storages.
+
+```python
+
+server.destroy()
+
+```