Python SDK

The MagicalAPI Python SDK provides seamless access to our services through a fully type-annotated and asynchronous client.

Getting Started

Follow these steps to install and integrate the SDK into your projects.

Installation

Install the package using pip:

pip install magicalapi

Usage

Below are examples demonstrating how to use the SDK for different services.

Initializing the Client

To start, create an instance of AsyncClient:

from magicalapi.client import AsyncClient

API_KEY = "mag_123456"
client = AsyncClient(api_key=API_KEY)

You can either provide the API_KEY directly in your code or store it in a .env file for better security. The client will automatically read from the .env file if the key is not explicitly passed.

Configuring a `.env` File

Example .env file:

# .env
MAG_API_KEY="mag_1234567"

All settings start with the prefix MAG_ and are case-insensitive. For example, MAG_EXAMPLE, Mag_example, and mag_EXAMPLE are treated the same.

Now, you can initialize the client without specifying the api_key parameter:

from magicalapi.client import AsyncClient

client = AsyncClient()

Example: Parsing a Resume with the Resume Parser Service

The following example demonstrates how to use the Resume Parser service:

import asyncio
from magicalapi.client import AsyncClient
from magicalapi.errors import APIServerError, APIServerTimedout
from magicalapi.types.base import ErrorResponse

resume_url = (
    "https://resume-resource.com/wp-content/uploads/00123-sales-professional-resume.pdf"
)
output_file_name = "resume_parser.json"

async def main():
    try:
        # The API key will be loaded from the .env file
        async with AsyncClient() as client:
            response = await client.resume_parser.get_resume_parser(url=resume_url)

            if isinstance(response, ErrorResponse):
                print("Error:", response.message)
            else:
                print("Credits used:", response.usage.credits)
                
                # Save response to a JSON file
                with open(output_file_name, "w") as file:
                    file.write(response.model_dump_json(indent=3))
                    print(f"Response saved to {output_file_name}")
    except (APIServerError, APIServerTimedout) as e:
        print("Server error:", e)
    except Exception as e:
        print("An error occurred:", str(e))

asyncio.run(main())

All client methods include type hints, making them easy to use and integrate into your projects.

For more examples, visit the Examples Directory in the SDK repository on GitHub.

Error Handling

As shown in the example above, this SDK provides predefined Exceptions that you can import and handle using Python's try/except blocks:

from magicalapi.errors import APIServerError, APIServerTimedout

try:
    # Your API call here
    pass
except APIServerError:
    print("A server error occurred.")
except APIServerTimedout:
    print("The request timed out.")
except Exception as e:
    print("An unexpected error occurred:", str(e))

By properly handling errors, you can build more robust applications that gracefully manage API failures.