Skip to content

Commit 9c1d4cf

Browse files
roaldnefsroaldnefs
committed
Add quickstart section to documentation
Add quickstart section with examples to the documentation. Signed-off-by: Roald Nefs <info@roaldnefs.com>
1 parent 18d969f commit 9c1d4cf

3 files changed

Lines changed: 128 additions & 0 deletions

File tree

‎docs/conf.py‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,10 @@
3737
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
3838
# ones.
3939
extensions = [
40+
"sphinx.ext.autodoc",
41+
"sphinx.ext.intersphinx",
42+
"sphinx.ext.todo",
43+
"sphinx.ext.viewcode",
4044
]
4145

4246
# Add any paths that contain templates here, relative to this directory.

‎docs/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,3 +40,4 @@ The User Guide
4040
:maxdepth: 2
4141

4242
user/install
43+
user/quickstart

‎docs/user/quickstart.rst‎

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
.. _quickstart:
2+
3+
Quickstart
4+
==========
5+
6+
This page gives a introduction in how to get started with **python-transip**.
7+
8+
First, make sure that:
9+
10+
* python-transip is :ref:`installed <install>`
11+
12+
Below you'll find some simple example to get started.
13+
14+
Authentication
15+
--------------
16+
17+
In order to make requests to the TransIP API we need to authenticate yourself
18+
using an access token. To get an access token, you should first login to the
19+
TransIP control panel. You can then generate a new token which will only be
20+
valid for limited time.
21+
22+
TransIP also provide a **demo token** to authenticate yourself as the TransIP
23+
demo user in test mode::
24+
25+
eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6ImN3MiFSbDU2eDNoUnkjelM4YmdOIn0.eyJpc3MiOiJhcGkudHJhbnNpcC5ubCIsImF1ZCI6ImFwaS50cmFuc2lwLm5sIiwianRpIjoiY3cyIVJsNTZ4M2hSeSN6UzhiZ04iLCJpYXQiOjE1ODIyMDE1NTAsIm5iZiI6MTU4MjIwMTU1MCwiZXhwIjoyMTE4NzQ1NTUwLCJjaWQiOiI2MDQ0OSIsInJvIjpmYWxzZSwiZ2siOmZhbHNlLCJrdiI6dHJ1ZX0.fYBWV4O5WPXxGuWG-vcrFWqmRHBm9yp0PHiYh_oAWxWxCaZX2Rf6WJfc13AxEeZ67-lY0TA2kSaOCp0PggBb_MGj73t4cH8gdwDJzANVxkiPL1Saqiw2NgZ3IHASJnisUWNnZp8HnrhLLe5ficvb1D9WOUOItmFC2ZgfGObNhlL2y-AMNLT4X7oNgrNTGm-mespo0jD_qH9dK5_evSzS3K8o03gu6p19jxfsnIh8TIVRvNdluYC2wo4qDl5EW5BEZ8OSuJ121ncOT1oRpzXB0cVZ9e5_UVAEr9X3f26_Eomg52-PjrgcRJ_jPIUYbrlo06KjjX2h0fzMr21ZE023Gw
26+
27+
API Client
28+
----------
29+
30+
Initializing a new TransIP API client with python-transip is very simple.
31+
32+
Begin by importing the module::
33+
34+
>>> import transip
35+
36+
Now, lets initialize a :class:`TransIP <transip.TransIP>` object called
37+
``client``. We need to provide it with our TransIP access token in order to
38+
authenticate the requests to the TransIP API. The example below uses the **demo
39+
token** to authenticate as the TransIP demo user in test mode::
40+
41+
>>> client = transip.TransIP(access_token="eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6ImN3MiFSbDU2eDNoUnkjelM4YmdOIn0.eyJpc3MiOiJhcGkudHJhbnNpcC5ubCIsImF1ZCI6ImFwaS50cmFuc2lwLm5sIiwianRpIjoiY3cyIVJsNTZ4M2hSeSN6UzhiZ04iLCJpYXQiOjE1ODIyMDE1NTAsIm5iZiI6MTU4MjIwMTU1MCwiZXhwIjoyMTE4NzQ1NTUwLCJjaWQiOiI2MDQ0OSIsInJvIjpmYWxzZSwiZ2siOmZhbHNlLCJrdiI6dHJ1ZX0.fYBWV4O5WPXxGuWG-vcrFWqmRHBm9yp0PHiYh_oAWxWxCaZX2Rf6WJfc13AxEeZ67-lY0TA2kSaOCp0PggBb_MGj73t4cH8gdwDJzANVxkiPL1Saqiw2NgZ3IHASJnisUWNnZp8HnrhLLe5ficvb1D9WOUOItmFC2ZgfGObNhlL2y-AMNLT4X7oNgrNTGm-mespo0jD_qH9dK5_evSzS3K8o03gu6p19jxfsnIh8TIVRvNdluYC2wo4qDl5EW5BEZ8OSuJ121ncOT1oRpzXB0cVZ9e5_UVAEr9X3f26_Eomg52-PjrgcRJ_jPIUYbrlo06KjjX2h0fzMr21ZE023Gw")
42+
43+
Availability Zones
44+
------------------
45+
46+
Using the
47+
:class:`AvailabilityZoneService <transip.v6.services.AvailabilityZoneService>`
48+
service we can retrieve all availability zone on TransIP if the form of an
49+
:class:`AvailabilityZone <transip.v6.objects.AvailabilityZone>` object::
50+
51+
>>> zones = client.availability_zones.list()
52+
>>> for zone in zones:
53+
... print(zone)
54+
<class 'transip.v6.objects.availability_zone.AvailabilityZone'> => {'name': 'ams0', 'country': 'nl', 'isDefault': False}
55+
<class 'transip.v6.objects.availability_zone.AvailabilityZone'> => {'name': 'rtm0', 'country': 'nl', 'isDefault': True}
56+
57+
We could for example print information about the default TransIP availability
58+
zone::
59+
60+
>>> for zone in zones:
61+
... if zone.isDefault:
62+
... print(f"{zone.name} is the default zone and is located in {zone.country}")
63+
rtm0 is the default zone and is located in nl
64+
65+
Domains
66+
-------
67+
68+
Using the
69+
:class:`DomainService <transip.v6.services.DomainService>`
70+
service we can retrieve all domains in your TransIP account in the form of a
71+
:class:`Domain <transip.v6.objects.Domain>` object::
72+
73+
>>> domains = client.domains.list()
74+
>>> domains = client.domains.list()
75+
>>> for domain in domains:
76+
... print(domain)
77+
<class 'transip.v6.objects.domain.Domain'> => {'name': 'transipdemo.be', 'authCode': '##########', 'isTransferLocked': False, 'registrationDate': '2011-04-29', 'renewalDate': '2021-04-29', 'isWhitelabel': False, 'isDnsOnly': False, 'cancellationDate': '', 'cancellationStatus': '', 'hasActionRunning': False, 'supportsLocking': True, 'tags': []}
78+
<class 'transip.v6.objects.domain.Domain'> => {'name': 'transipdemo.de', 'authCode': '##########', 'isTransferLocked': False, 'registrationDate': '2011-04-29', 'renewalDate': '2021-04-29', 'isWhitelabel': False, 'isDnsOnly': False, 'cancellationDate': '', 'cancellationStatus': '', 'hasActionRunning': False, 'supportsLocking': False, 'tags': []}
79+
<class 'transip.v6.objects.domain.Domain'> => {'name': 'transipdemo.net', 'authCode': '##########', 'isTransferLocked': True, 'registrationDate': '2011-04-29', 'renewalDate': '2021-04-29', 'isWhitelabel': False, 'isDnsOnly': False, 'cancellationDate': '', 'cancellationStatus': '', 'hasActionRunning': False, 'supportsLocking': True, 'tags': []}
80+
<class 'transip.v6.objects.domain.Domain'> => {'name': 'transipdemonstratie.com', 'authCode': '##########', 'isTransferLocked': True, 'registrationDate': '2011-04-29', 'renewalDate': '2021-04-29', 'isWhitelabel': False, 'isDnsOnly': False, 'cancellationDate': '', 'cancellationStatus': '', 'hasActionRunning': False, 'supportsLocking': True, 'tags': []}
81+
<class 'transip.v6.objects.domain.Domain'> => {'name': 'transipdemonstratie.nl', 'authCode': '##########', 'isTransferLocked': False, 'registrationDate': '2011-04-29', 'renewalDate': '2021-04-29', 'isWhitelabel': False, 'isDnsOnly': False, 'cancellationDate': '', 'cancellationStatus': '', 'hasActionRunning': False, 'supportsLocking': False, 'tags': []}
82+
83+
We could also retrieve a single :class:`Domain <transip.v6.objects.Domain>`
84+
object by its name::
85+
86+
>>> domain = client.domains.get('transipdemonstratie.nl')
87+
>>> print(f"{domain.name} was registered on {domain.registrationDate}")
88+
transipdemonstratie.nl was registered on 2011-04-29
89+
90+
VPSs
91+
----
92+
93+
Using the
94+
:class:`VpsService <transip.v6.services.VpsService>`
95+
service we can retrieve all VPSs in your TransIP account in the form of a
96+
:class:`Vps <transip.v6.objects.Vps>` object::
97+
98+
>>> vpss = client.vpss.list()
99+
>>> for vps in vpss:
100+
... print(vps)
101+
<class 'transip.v6.objects.vps.Vps'> => {'name': 'transipdemo-vps', 'description': '', 'productName': 'vps-bladevps-x1', 'operatingSystem': 'FreeBSD 10.0-RELEASE', 'diskSize': 52428800, 'memorySize': 1048576, 'cpus': 3, 'status': 'running', 'ipAddress': '141.138.136.129', 'macAddress': '52:54:00:19:a7:20', 'currentSnapshots': 1, 'maxSnapshots': 1, 'isLocked': False, 'isBlocked': False, 'isCustomerLocked': False, 'availabilityZone': 'ams0', 'tags': ['customTag', 'anotherTag']}
102+
<class 'transip.v6.objects.vps.Vps'> => {'name': 'transipdemo-vps2', 'description': '', 'productName': 'vps-bladevps-x1', 'operatingSystem': 'Debian 7', 'diskSize': 52428800, 'memorySize': 1048576, 'cpus': 1, 'status': 'stopped', 'ipAddress': '149.210.192.184', 'macAddress': '52:54:00:51:39:ff', 'currentSnapshots': 0, 'maxSnapshots': 0, 'isLocked': False, 'isBlocked': False, 'isCustomerLocked': False, 'availabilityZone': 'ams0', 'tags': []}
103+
<class 'transip.v6.objects.vps.Vps'> => {'name': 'transipdemo-vps3', 'description': '', 'productName': 'vps-bladevps-x1', 'operatingSystem': 'Debian 7', 'diskSize': 52428800, 'memorySize': 1048576, 'cpus': 2, 'status': 'running', 'ipAddress': '149.210.192.185', 'macAddress': '52:54:00:d2:6a:9f', 'currentSnapshots': 1, 'maxSnapshots': 1, 'isLocked': False, 'isBlocked': False, 'isCustomerLocked': True, 'availabilityZone': 'ams0', 'tags': []}
104+
<class 'transip.v6.objects.vps.Vps'> => {'name': 'transipdemo-vps4', 'description': '', 'productName': 'vps-bladevps-x1', 'operatingSystem': 'Ubuntu 14.04 LTS', 'diskSize': 52428800, 'memorySize': 1048576, 'cpus': 1, 'status': 'running', 'ipAddress': '149.210.192.186', 'macAddress': '52:54:00:db:27:25', 'currentSnapshots': 0, 'maxSnapshots': 3, 'isLocked': False, 'isBlocked': False, 'isCustomerLocked': False, 'availabilityZone': 'ams0', 'tags': []}
105+
<class 'transip.v6.objects.vps.Vps'> => {'name': 'transipdemo-vps5', 'description': '', 'productName': 'vps-bladevps-x4', 'operatingSystem': 'DirectAdmin 1.45.0 + CentOS 6.5', 'diskSize': 157286400, 'memorySize': 4194304, 'cpus': 2, 'status': 'running', 'ipAddress': '149.210.192.187', 'macAddress': '52:54:00:0c:0d:f3', 'currentSnapshots': 0, 'maxSnapshots': 1, 'isLocked': False, 'isBlocked': False, 'isCustomerLocked': False, 'availabilityZone': 'ams0', 'tags': []}
106+
<class 'transip.v6.objects.vps.Vps'> => {'name': 'transipdemo-vps6', 'description': '', 'productName': 'vps-bladevps-pro-x32', 'operatingSystem': 'Plesk Onyx Web Pro Edition 17.8.11 + CentOS 7', 'diskSize': 1048576000, 'memorySize': 33554432, 'cpus': 6, 'status': 'running', 'ipAddress': '149.210.192.188', 'macAddress': '52:54:00:7a:96:03', 'currentSnapshots': 0, 'maxSnapshots': 1, 'isLocked': False, 'isBlocked': False, 'isCustomerLocked': False, 'availabilityZone': 'ams0', 'tags': []}
107+
108+
We could also retrieve a single :class:`Vps <transip.v6.objects.Vps>`
109+
object by its name::
110+
111+
>>> vps = client.vpss.get('transipdemo-vps')
112+
>>> print(f"{vps.name} runs {vps.operatingSystem} and has IP address: '{vps.ipAddress}'")
113+
transipdemo-vps runs FreeBSD 10.0-RELEASE and has IP address: '141.138.136.129'
114+
115+
Errors and Exceptions
116+
---------------------
117+
118+
In the event of a API problem (e.g. authentication error, requested resource not
119+
found, etc.) python-transip will raise a :exc:`~transip.exceptions.TransIPHTTPError`
120+
exception.
121+
122+
All exceptions that python-transip explicitly raises inherit from
123+
:exc:`~transip.exceptions.TransIPError`.

0 commit comments

Comments
 (0)