PyShortIO: A Pythonic Client for Short.io URL Shortening Service¶

Introduction¶

This notebook provides a comprehensive walkthrough of the PyShortIO library, a Python client for interacting with the Short.io URL shortening service. Short.io is a popular URL shortening service that provides a robust API for programmatically creating and managing shortened URLs.

PyShortIO is designed with a clean, well-documented API and comprehensive error handling, making it an excellent choice for Python developers looking to integrate Short.io functionality into their applications.

Let’s explore the key features and functionality of the PyShortIO library through practical examples.

Prerequisites¶

To use PyShortIO, you’ll need:

  1. A Short.io account with API access

  2. Your Short.io API token

  3. A registered domain in your Short.io account

Installation¶

First, let’s install the PyShortIO library:

pip install pyshortio

Setting Up the Client¶

The first step in using PyShortIO is to create a client instance with your API token. The client will be our main interface for interacting with the Short.io API.

[1]:

from pathlib import Path
import pyshortio.api as pyshortio

# Replace with your actual Short.io API token
# API_TOKEN = "your_api_token_here"
API_TOKEN = Path.home().joinpath(".short.io", "sanhehu_esc", "sanhe-dev.txt").read_text().strip()

# Create a client instance
client = pyshortio.Client(token=API_TOKEN)

print(f"Client initialized with endpoint: {client.endpoint}")

Client initialized with endpoint: https://api.short.io

Finding Your Domain¶

Before creating shortened links, we need to identify the domain we’ll be working with. Short.io allows you to use your own custom domains for shortened URLs.

In this example, we’ll find a domain by its hostname and retrieve its ID, which we’ll need for various operations.

[2]:

# Replace with your actual Short.io domain
HOSTNAME = "pyshortio.short.gy"

# Get domain by hostname
response, domain = client.get_domain_by_hostname(hostname=HOSTNAME)

if domain:
    print(f"Domain found: {domain.hostname}")
    print(f"Domain ID: {domain.id}")
    print(f"Domain state: {domain.state}")
    print(f"Domain created at: {domain.created_at}")

    # Store the domain ID for later use
    domain_id = domain.id
else:
    print(f"Domain {HOSTNAME} not found")

Domain found: pyshortio.short.gy
Domain ID: 1342190
Domain state: configured
Domain created at: 2025-04-20 16:07:15+00:00

Getting Domain Information¶

Now that we’ve set up our environment, let’s retrieve detailed information about our domain using its ID.

[4]:

# Get domain information using the domain ID
response, domain = client.get_domain(domain_id=domain_id)

# Display domain information
print(f"Domain ID: {domain.id}")
print(f"Hostname: {domain.hostname}")
print(f"Unicode Hostname: {domain.unicode_hostname}")
print(f"State: {domain.state}")
print(f"Created At: {domain.created_at}")
print(f"Updated At: {domain.updated_at}")
print(f"Team ID: {domain.team_id}")
print(f"Has Favicon: {domain.has_favicon}")

Domain ID: 1342190
Hostname: pyshortio.short.gy
Unicode Hostname: pyshortio.short.gy
State: configured
Created At: 2025-04-20 16:07:15+00:00
Updated At: 2025-04-20 16:07:15+00:00
Team ID: None
Has Favicon: False

Using a Higher Limit for Listing¶

Let’s try listing with a higher limit to ensure we retrieve all links in a single request.

[9]:

# List links with a higher limit
response, link_list = client.list_links(
    domain_id=domain_id,
    limit=100,
)

# Display the number of links returned
print(f"Number of links with limit=100: {len(link_list)}")

Number of links with limit=100: 3

Getting OpenGraph Properties¶

Short.io can extract OpenGraph metadata from the original URLs. Let’s see how to retrieve this information for our pricing link.

[11]:

# Get OpenGraph properties for the pricing link
response, result = client.get_link_opengraph_properties(
    domain_id=domain_id,
    link_id=link_pricing.id,
)

# Display OpenGraph properties
print("OpenGraph Properties:")
for value in result:
    print(value)

OpenGraph Properties:

Handling Non-Existent Paths¶

Similar to handling non-existent links, let’s see how to handle a non-existent path.

[15]:

# Try to get information about a non-existent path
response, link = client.get_link_info_by_path(
    hostname=HOSTNAME,
    path="not-exists",
    raise_for_status=False,  # Prevent raising an exception for 404 responses
)

# Check if link exists
if link is None:
    print("Path not found, as expected.")
else:
    print("Unexpected: Path found.")

Path not found, as expected.

Searching for Non-Existent Original URLs¶

Let’s try searching for links with an original URL that doesn’t exist in our domain.

[17]:

# Search for links with a non-existent original URL
response, link_list = client.list_links_by_original_url(
    hostname=HOSTNAME,
    original_url="https://example.com/not-exists",
    raise_for_status=False,  # Prevent raising an exception for 404 responses
)

# Display the number of links found
print(f"Number of links found: {len(link_list)}")

Number of links found: 0

Listing Folders¶

Short.io allows you to organize your links into folders. Let’s list all folders in our domain.

[18]:

# List all folders in the domain
response, folder_list = client.list_folders(domain_id=domain_id)

# Display the number of folders
print(f"Number of folders: {len(folder_list)}")

# Display folder information if any exist
if len(folder_list) > 0:
    for folder in folder_list:
        print(f"Folder ID: {folder.id}")
        print(f"Folder Name: {folder.name}")
else:
    print("No folders found.")

Number of folders: 0
No folders found.

Handling Non-Existent Folders¶

Let’s try retrieving a non-existent folder.

[19]:

# Try to get information about a non-existent folder
response, folder = client.get_folder(
    domain_id=domain_id,
    folder_id="not-exists",
    raise_for_status=False,  # Prevent raising an exception for 404 responses
)

# Check if folder exists
if folder is None:
    print("Folder not found, as expected.")
else:
    print("Unexpected: Folder found.")

Folder not found, as expected.

Verifying the Update¶

Let’s verify that our link was actually updated by retrieving it again.

[21]:

# Get the updated link to verify changes
response, link = client.get_link_info_by_link_id(link_id=link_pricing.id)

# Display updated link information
print(f"Link ID: {link.id}")
print(f"Title: {link.title}")
print(f"Original URL: {link.original_url}")
print(f"Shortened URL: {link.short_url}")

Link ID: lnk_5Dae_mcadseJwZnuDmoMVoUhYl
Title: Short io pricing updated
Original URL: https://short.io/pricing/updated
Shortened URL: https://pyshortio.short.gy/Yl3Hia

Conclusion¶

In this notebook, we’ve explored the key features of the PyShortIO library for interacting with the Short.io URL shortening service. We’ve covered:

  • Setting up the client

  • Finding and retrieving domain information

  • Creating individual and batch links

  • Listing links with and without pagination

  • Retrieving link information in various ways

  • Updating links

  • Deleting links

  • Handling various error scenarios

PyShortIO provides a clean, Pythonic interface to Short.io’s API, making it easy to integrate URL shortening functionality into your Python applications.

For more details, refer to the official documentation and the API reference at the project’s GitHub repository: PyShortIO.