Python TransIP

python-transip is an Python wrapper for the TransIP REST API V6.

Introduction
General
Account
- Invoices
- SSH Keys
Domain
VPS
HA-IP
Colocation
- Colocations

Introduction

Welcome to the Python TransIP documentation.

REST API V6

python-transip implements the new TransIP REST API to manage all products in a RESTful way, this means that for most products you can make simple create, update and delete calls.

The wrapper tries to stay close to the naming convention of the official API documentation.

SOAP V5 API (deprecated)

Users are strongly advised to use the new REST API because the SOAP API has been deprecated. If you still depend on functionality that has not yet been implemented in python-transip consider raising a feature request and using transip-api (deprecated) in the meanwhile.

Installation

python-transip is available on PyPI:

$ python -m pip install python-transip

python-transip officially supports Python 3.6+.

Documentation

The full API Reference and User Guide is available on Read the Docs.

Authentication

In order to manage TransIP products via python-transip you will need to be authenticated. The REST API V6 requires an access token that makes use of the JSON Web Token standard.

To get an access token, you should first generate a key pair using the control panel. You can than pass the private key to the python-transip client to allow the client to generate a new access token, e.g.:

import transip

# You can initialize a TransIP client using a private key directly.
PRIVATE_KEY = '''-----BEGIN PRIVATE KEY-----
...
'''
client = transip.TransIP(login='demouser', private_key=PRIVATE_KEY)

# You can also initialize a TransIP client by telling it where to find the
# private key file on the system.
client = transip.TransIP(login='demouser', private_key_file='/path/to/private.key')

Alternatively you can also authenticate by providing an access token. This is especially useful when testing the API with the demo token, e.g.:

import transip
from transip.v6 import DEMO_TOKEN

# You can initialize a TransIP client using an access token directly.
client = transip.TransIP(access_token=DEMO_TOKEN)

General

The general TransIP API resources allow you to manage products, availability zones and call the API test resource.

Products

Manage available TransIP products and product specifications.

The Product class

When listing all products available on TransIP, a list of transip.v6.objects.Product objects is returned.

class Product

The Product class makes the following attributes available:

name: The name of the product.
description: The product description.
price: The price in cents.
recurringPrice: The recurring price for the product in cents.
elements: The service to list detailed information on the product elements.

The ProductElement class

When listing all product elements of a transip.v6.objects.Product object, a list of transip.v6.objects.ProductElement objects is returned.

class ProductElement

The ProductElement class makes the following attributes available:

name: The name of the product element.
description: The product element description.
amount: The amount.

List all products

Retrieve al list of products with, there name, description and price.

import transip
# Initialize a client using the TransIP demo token.
client = transip.TransIP(access_token=transip.v6.DEMO_TOKEN)

# List all available TransIP products.
products = client.products.list()
# Show product information on the screen.
for product in products:
    print((
        f"Product {product.name} ({product.description}) costs "
        f"{product.price} (cents), after which it costs "
        f"{product.recurringPrice} (cents)"
    ))

List specifications for product

Get the specification for a product. This will list all the different elements for a product with the amount that it comes with, e.g. a a vps-bladevps-x4 has 2 CPU-core elements.

import transip
# Initialize a client using the TransIP demo token.
client = transip.TransIP(access_token=transip.v6.DEMO_TOKEN)

# Show product specification information on the screen for all available
# TransIP products.
for product in client.products.list():
    print(f"Product {product.name} ({product.description}):")
    elements = product.elements.list()
    for element in elements:
        print(f"- Has {element.amount} {element.name}: {element.description}")

Availability Zones

Manage TransIP availability zones.

The AvailabilityZone class

When listing all the available availability zones on TransIP, a list of transip.v6.objects.AvailabilityZone objects is returned.

class AvailabilityZone

The AvailabilityZone class makes the following attributes available:

name: The name of the availability zone.
country: The 2 letter code for the country the AvailabilityZone is in.
isDefault: If true this is the default zone new VPSes and clones are created in

List availability zones

Retrieve the available availability zones:

import transip
# Initialize a client using the TransIP demo token.
client = transip.TransIP(access_token=transip.v6.DEMO_TOKEN)

# List all available availability zones.
zones = client.availability_zones.list()
# Show availability zone information on the screen.
for zone in zones:
    print((
        f"Availability zone {zone.name} in {zone.country} "
        f"(default: {zone.isDefault})"
    ))

API Test

A simple test resource to make sure everything is working.

import transip
# Initialize a client using the TransIP demo token.
client = transip.TransIP(access_token=transip.v6.DEMO_TOKEN)

# Check if everything is working by calling the API test resource.
if client.api_test.test():
    print("Everthing is working!")

Account

The account TransIP API resources allow you to manage invoices and SSH keys.

Invoices

Manage invoices attached to your TransIP account.

The Invoice class

When listing all invoices attached to your TransIP account, a list of transip.v6.objects.Invoice objects is returned.

class Invoice

The Invoice class makes the following attributes available:

invoiceNumber: The invoice number.
creationDate: The invoice creation date.
payDate: The invoice paid date.
dueDate: The invoice deadline.
invoiceStatus: The invoice status.
currency: The currency used for this invoice.
totalAmount: The invoice total (displayed in cents).
totalAmountInclVat: The invoice total including VAT (displayed in cents).
items: The service to list detailed information on the individual invoice items.

The InvoiceItem class

When listing all invoices items attached to a transip.v6.objects.Invoice object, a list of transip.v6.objects.InvoiceItem objects is returned.

class InvoiceItem

The InvoiceItem class makes the following attributes available:

product: The product name.
description: The product description.
isRecurring: Whether or not the payment is recurring.
date: The date when the order line item was up for invoicing.
quantity: The quantity of the invoice item.
price: The price excluding VAT (displayed in cents).
priceInclVat: The price including VAT (displayed in cents).
vat: The amount of VAT charged.
vatPercentage: The percentage used to calculate the VAT.
discounts: The dictionary containing the applied discounts.
- description: The applied discount description.
- amount: The discounted amount (in cents).

The class has the following methods:

pdf(file_path) stores the invoice as a PDF file on a location provided by the file_path keyword argument. When the file_path is a directory, the PDF file will be saved using the invoice number as its basename.

List all invoices

Retrieve all invoices attached to your TransIP account by calling transip.TransIP.invoices.list(). This will return a list of transip.v6.objects.Invoice objects.

For example:

import transip
# Initialize a client using the TransIP demo token.
client = transip.TransIP(access_token=transip.v6.DEMO_TOKEN)

# List all invoices attached to your TransIP account.
invoices = client.invoices.list()
# Show invoice information on the screen.
for invoice in invoices:
    print(f"Invoice {invoice.invoiceNumber} was paid on {invoice.payDate}")

Note: when using the demo access token, the API currently doesn't list any invoices.

List a single invoice

Retrieve a single invoice attached to your TransIP account by its invoice number by calling transip.TransIP.invoices.get(id). This will return a transip.v6.objects.Invoice object.

For example:

import transip
# Initialize a client using the TransIP demo token.
client = transip.TransIP(access_token=transip.v6.DEMO_TOKEN)

# Retrieve a single invoice by its invoice number.
invoice = client.invoices.get('F0000.1911.0000.0004')
# Show invoice information on the screen.
print(f"Invoice {invoice.invoiceNumber} was paid on {invoice.payDate}")

Note: when using the demo access token, the API currently doesn't list any invoices.

List invoice items by invoice number

Retrieve the invoice items of a single invoice attached to your TransIP account by its invoice number by calling items.list() on a transip.v6.objects.Invoice object. This will return a list of transip.v6.objects.InvoiceItem objects.

For example:

import transip
# Initialize a client using the TransIP demo token.
client = transip.TransIP(access_token=transip.v6.DEMO_TOKEN)

# Retrieve a single invoice by its invoice number.
invoice = client.invoices.get('F0000.1911.0000.0004')
# Retrieve all items of a single invoice.
items = invoice.items.list()
# Show invoice information on the screen.
for item in items:
    print(f"Product {item.product} ({item.description})")

Note: when using the demo access token, the API currently doesn't list any invoices.

Retrieve an invoice as PDF file

Any of the invoices can be saved as a PDF file by calling pdf(file_path) on a transip.v6.objects.Invoice object:

import transip
# Initialize a client using the TransIP demo token.
client = transip.TransIP(access_token=transip.v6.DEMO_TOKEN)

# Retrieve a single invoice by its invoice number.
invoice = client.invoices.get('F0000.1911.0000.0004')
# Save the invoice as a PDF file.
invoice.pdf('/path/to/invoices/')

Note: when using the demo access token, the API currently doesn't list any invoices.

SSH Keys

The SshKey class

When listing all SSH keys attached to your TransIP account, a list of transip.v6.objects.SshKey objects is returned.

class SshKey

The SshKey class makes the following attributes available:

id: The SSH key identifier.
key: The SSH key.
description: The SSH key description (max 255 chars).
creationDate: The date when this SSH key was added (timezone: Europe/Amsterdam)
fingerprint: MD5 fingerprint of SSH key.

The class has the following methods:

delete() will delete the SSH key in your TransIP account.
update() will send the updated attributes to the TransIP API.

List all SSH keys

Retrieve all SSH keys attached to your TransIP account by calling transip.TransIP.ssh_keys.list(). This will return a list of transip.v6.objects.SshKey objects.

For example:

import transip
# Initialize a client using the TransIP demo token.
client = transip.TransIP(access_token=transip.v6.DEMO_TOKEN)

# List all SSH keys attached to your TransIP account.
ssh_keys = client.ssh_keys.list()
# Show SSH key information on the screen.
for ssh_key in ssh_keys:
    print(f"SSH key {ssh_key.id} has fingerprint {ssh_key.fingerprint}")