openblu 1.0

Official Python 3 wrapper around the OpenBlu API

OpenBlu-Python-Wrapper

Official Python wrapper around OpenBlu API

Overview

This wrapper can be used to fetch servers from the OpenBlu API and retrieve their OpenVPN configuration.

To make things easy, the library abstracts the JSON responses from the API inside three objects:

• Server -> Contains more detailed information from the server as described in OpenBlu's Documentation
• ServerListing -> Contains metadata from a server such as ping, country and location
• OpenVPN -> Contained inside a Server object, stores the OpenVPN configuratiom for the server

The ServerListing and Server objects can be printed to get an overview of the server's information.

Installation

To install this wrapper, simply clone this repo with git clone, then run python3 setup.py install

Usage

Fetch multiple servers

To fetch multiple servers, without their OpenVPN configuration, you can use the list_servers() method of the openblu.OpenBluAPI class like shown below

from openblu import OpenBluAPI

api = OpenBluAPI('access_key')  # Get your access key at openblu.intellivoid.net

servers = api.list_servers(filter_by=("germany", "country"))

Below the full documentation for the list_servers method in Sphinx format

Fetches OpenVPN servers from the OpenBlu API

:param filter_by: If not ``None``, filter the results by the given parameter. It must be a tuple containing a country name and either one of these strings (In this order): "country", "country_short". If "country_short" is the second element of the tuple, the country name must be the short form of its name (e.g. 'de' for germany or 'jp' for Japan) otherwise, the full extended form is required. Defaults to ``None``
:type filter_by: tuple, None, optional
:param order_by: If not ``None``, order the results by this order. It can either be ``'ascending'`` or ``'descending'``, defaults to ``None``.
:type order_by: str, None, optional
:param sort_by: Sorts the list by the given condition, defaults to ``None`` (no sorting). Possible choices are "score", "ping", "sessions", "total_sessions", "last_updated" and "created"
:type sort_by: str, None, optional
:param verbose: If ``True``, make the output verbose, default to ``False``
:type verbose: bool, optional
:returns servers_list: A list of class:ServerListing objects
:rtype servers_list: list
:raises OpenBluError: An proper subclass of OpenBluError is raised if something goes wrong. If the error cannot be determined, a generic OpenBluError is raised

Get a single server

As described in OpenBlu's documentation, servers can be identified by a unique ID. That ID can be used to fetch a more detailed server object containing the OpenVPN server configuration from the OpenBlu API as shown below. This server object also contains the server's IP address

from openblu import OpenBluAPI

api = OpenBluAPI('access_key')  # Get your access key at openblu.intellivoid.net

servers = api.list_servers(filter_by=("germany", "country"))

server = servers[0]    # Take the first entry

srv = api.get_server(server.id)   # Retrieve the server's configuration

Below the full documentation for the get_server method in Sphinx format

Fetches a single OpenVPN server from the OpenBlu API, given its unique ID

:param uuid: The unique ID of the desired server
:type uuid: string
:param verbose: If ``True``, make output verbose, default to ``False``
:type verbose: bool, optional
:returns: A class:Server object
:rtype: class: Server
:raises OpenBluError: An proper subclass of OpenBluError is raised if something goes wrong. If the error cannot be determined, a generic OpenBluError is raised

For more examples and a deeper description check the examples.py file in this repo

Objects' overview

Here are some example objects to get you started straight away

Note: All objects, when printed out, show all the information inside the object itself (including None values and such)

ServerListing

When printed out, a ServerListing object should look like the following, although the corresponding parameters may differ.

ServerListing(
id=dbd24ff8e4802f22,
host_name=vpn774575625,
country=Germany,
country_short=DE,
score=366198,
ping=28,
sessions=66,
total_sessions=30926,
last_updated=1576539451,
created=1576529629)

Server

The server object has a similar output to the ServerListing, but (of course) it contains different and more descriptive information about a single server.

Server(
id=dbd24ff8e4802f22,
host_name=vpn774575625,
country=Germany,
country_short=DE,
score=366198,
ping=28,
sessions=66,
total_sessions=30926,
ip_address=78.54.226.91,
openvpn=<OpenVPN object at 0x7b2b706f10>,
last_updated=1576539451,
created=1576529629)

OpenVPN objects

OpenVPN objects' output is much less verbose, because printing all of the object's parameters would literally need pages of output, their attributes are still accessible both via dot notation and via dict-like accessing.

For the sake of completeness, all the object's parameters are listed here; to get detailed info about their meaning refer to OpenBlu's official docs

- parameters
- certificate_authority
- certificate_authority_b64
- certificate
- certificate_b64
- key
- key_b64
- ovpn_configuration

Exceptions

The wrapper implements 3 exceptions:

• OpenBluError -> Generic parent class for all exceptions, also raised when an error other than 401 and 404 is returned by the API
• ServerNotFound -> When an invalid server ID is provided to the API
• UnauthorizedAccess -> When an invalid access key is provided to the API

Other errors, such as JSON decoding errors or HTTP failures, are not catched and must be handled by the end user itself.

Last, but not least

All objects objects support dict-like accessing as well as dot notation, which means that doing server["id"] or server.id yields the same result.