Skip to main content

Vulavula Python SDK

Getting started​

The Vulavula Python SDK offers a tailored library designed to simplify and enhance your interactions with the Vulavula API through Python.

Prerequisites​

Before you start, make sure you have Python installed on your machine. You can download and install Python from python.org.

1. Set Up a Virtual Environment (optional)​

Once you have Python installed, you can create a virtual python environment to install the vulavula Python library. You are not required to use a virtual environment, so skip this step if you do not want to set one up.

Here's how to set it up:

# Create virtual environment
python -m venv vulavula-env

# Activate the virtual environment

# On Windows
vulavula-env\Scripts\activate

# On macOS and UNIX
source vulavula-env/bin/activate

2. Install the Vulavula Python SDK​

Once you have Python 3.7 or newer installed and (optionally) set up a virtual environment, the vulavula Python library can be installed.

You can use both pdm and pip.

# Using PDM
pdm add vulavula

3. Set Up Your API Key​

To interact with the Vulavula API, you'll need an API key. After registering and obtaining your API key from the Vulavula platform, configure it in your project like this:

from vulavula import VulavulaClient

# Initialize the client with your API token
client = VulavulaClient("<INSERT_TOKEN>")

4. Make Your First API Request​

Now that everything is set up, you can make your first API request using the SDK:

# Sentiment analysis example
sentiment_result = client.get_sentiments({'encoded_text': 'Ngijabulile!'})
print(sentiment_result)

SDK error handling​

The vulavula SDK includes VulavulaError, a custom exception class designed to provide detailed information about errors encountered during API interactions. The SDK uses conventional HTTP response codes to indicate the success or failure of an API request:

  • Codes in the 2xx range indicate success.
  • Codes in the 4xx range indicate an error due to issues with the input provided (e.g., a missing required parameter, a request for a non-existent resource, etc.).
  • Codes in the 5xx range indicate an error with Vulavula’s servers.

Here is an example of how to handle these errors using a try-catch block in your code:

from vulavula.common.error_handler import VulavulaError

try:
    entity_result = client.get_entities(
        {'text': 'President Ramaphosa gaan loop by Emfuleni Municipality.'}
    )
    print("Entity Recognition Output:", entity_result)
except VulavulaError as e:
    print("An error occurred:", e.message)
    if 'details' in e.error_data:
        print("Error Details:", e.error_data['details'])
    else:
        print("No additional error details are available.")
except Exception as ex:
    print("An unexpected error occurred:", str(ex))

Next Steps​

To dive deeper into the Vulavula Python SDK and maximize its capabilities:

  • API References: Each product section on our API Documentation offers in-depth usage guides and examples for the SDK.
  • Project Description on PyPI: For a detailed description and additional configuration options, visit the Vulavula project page on PyPI.

These resources will help you effectively utilize the Vulavula Python SDK in your projects, enabling robust interaction with the API.