🌟Sync TSV: The Power Tool for URL Management at Scale 🚀¶

Introduction¶

Managing dozens, hundreds, or even thousands of shortened URLs can quickly become overwhelming. That’s where PyShortIO’s Sync TSV feature comes in - a powerful tool that lets you manage your Short.io links in bulk using simple spreadsheets. This document will showcase how this feature can revolutionize your URL management workflow and provide step-by-step guidance on how to use it effectively.

What is Sync TSV? 🤔¶

Sync TSV is a specialized feature of PyShortIO that allows you to:

Create multiple shortened links in one operation
Update existing links in bulk
Delete links no longer needed
Organize links into folders automatically
Maintain a single source of truth for all your shortened URLs

Think of it as a synchronization bridge between your local data (in a TSV file) and your Short.io account.

TSV File Format 📊¶

A TSV (Tab-Separated Values) file defines all the links you want to manage. Each row represents a link with its properties:

Using Google Sheets as Your TSV Editor¶

For convenient editing and collaboration, you can use Google Sheets as your TSV editor:

Example Short.io Links Template

To use this template:

Click the link above to open the example spreadsheet
Make a copy for your own use (File > Make a copy)
Edit your link data in the spreadsheet
When ready to sync, Just select all and copy paste it to a .tsv file.
Use the .tsv file with the sync_tsv() method

This approach makes it easy to collaborate with team members on link management while maintaining a structured format for PyShortIO.

Getting Started with Sync TSV 🚀¶

Step 1: Create a Simple TSV File

Create your first TSV file (links1.tsv) with a few links:

Step 2: Run Your First Sync

# Install with sync dependencies
# pip install pyshortio[sync]
from pathlib import Path
import pyshortio.api as pyshortio

# Initialize client with your API token
client = pyshortio.Client(token="your_api_token")

# Your short.io domain
hostname = "yourdomain.short.gy"

# Sync from TSV file
with open("links1.tsv", "r") as file:
    client.sync_tsv(
        hostname=hostname,
        file=file,
        update_if_not_the_same=True,
        delete_if_not_in_file=False, # Set to True to delete links not in the TSV file
        real_run=True,
    )

The output log would looks like this:

log1.txt

+----- 🕑 🔄 Start 'Sync links from TSV file to short.io' -----------------------+
🔄
🔄 hostname = 'pyshortio.short.gy'
🔄 update_if_not_the_same = True
🔄 delete_if_not_in_file = True
🔄 +----- 🕑 📄 Start 'Read link data from TSV file' -----------------------------+
🔄 📄
🔄 📄 Read data ...
🔄 📄 Check original_url column ...
🔄 📄 Process tags column ...
🔄 📄 Got 5 rows
🔄 📄 Got 2 unique folder names
🔄 📄
🔄 +----- ⏰ ✅ 📄 End 'Read link data from TSV file', elapsed = 0.04 sec ---------+
🔄 +----- 🕑 📂 Start 'Create folder if they do not exists' ----------------------+
🔄 📂
🔄 📂 Read existing folder info from short.io ...
🔄 📂 Got 2 existing folders
🔄 📂 'Python' folder already exists
🔄 📂 'Short IO' folder already exists
🔄 📂
🔄 +----- ⏰ ✅ 📂 End 'Create folder if they do not exists', elapsed = 0.17 sec -----+
🔄 +----- 🕑 🔍 Start 'Identify link to create, update and delete' ---------------+
🔄 🔍
🔄 🔍 Read existing link info from short.io ...
🔄 🔍 Got 0 existing links
🔄 🔍 🟢 got 5 links to create
🔄 🔍 🟡 got 0 links to update
🔄 🔍 🔴 got 0 links to delete
🔄 🔍 To create: link_data = {'original_url': 'https://short.io/pricing/', 'title': 'Short io pricing', 'tags': ['pricing', 'short.io'], 'folder_id': 'BgG2lQ2kQwLHa4TepHU8P'}
🔄 🔍 To create: link_data = {'original_url': 'https://short.io/features/', 'title': 'Short io features', 'tags': ['features', 'short.io'], 'folder_id': 'BgG2lQ2kQwLHa4TepHU8P'}
🔄 🔍 To create: link_data = {'original_url': 'https://short.io/integrations/', 'title': 'Short io integrations', 'tags': ['integrations', 'short.io'], 'folder_id': 'BgG2lQ2kQwLHa4TepHU8P'}
🔄 🔍 To create: link_data = {'original_url': 'https://www.python.org/', 'title': 'Python Org', 'tags': ['python'], 'folder_id': 'JR_S7CWHpfBqNZCYa2EzO'}
🔄 🔍 To create: link_data = {'original_url': 'https://example.com/'}
🔄 🔍
🔄 +----- ⏰ ✅ 🔍 End 'Identify link to create, update and delete', elapsed = 0.16 sec -----+
🔄 +----- 🕑 🟢 Start 'Create links' ---------------------------------------------+
🔄 🟢
🔄 🟢 create link for original_url = https://short.io/pricing/
🔄 🟢 create link for original_url = https://short.io/features/
🔄 🟢 create link for original_url = https://short.io/integrations/
🔄 🟢 create link for original_url = https://www.python.org/
🔄 🟢 create link for original_url = https://example.com/
🔄 🟢
🔄 +----- ⏰ ✅ 🟢 End 'Create links', elapsed = 0.66 sec -------------------------+
🔄
+----- ⏰ ✅ 🔄 End 'Sync links from TSV file to short.io', elapsed = 1.20 sec -----+

Step 3: Verify Your Links in Short.io

Log into your Short.io account and confirm that your links have been created successfully.

Understanding the Sync Process 🔄¶

When you run sync_tsv(), PyShortIO follows these steps:

Read TSV Data: Parses your TSV file into a structured format
Create Folders: Ensures all needed folders exist in your Short.io account
Identify Changes: Compares TSV data with existing Short.io links
Apply Changes: Creates, updates, and/or deletes links as needed

Incremental Updates with Sync TSV 📈¶

One of the most powerful aspects of Sync TSV is the ability to make incremental updates. Let’s see how to update our links with a new TSV file (links2.tsv):

# Second sync with updated TSV file
with open("links2.tsv", "r") as file:
    client.sync_tsv(
        hostname=hostname,
        file=file,
        update_if_not_the_same=True,
        delete_if_not_in_file=True,
        real_run=True,
    )

The output log would looks like this:

log2.txt

+----- 🕑 🔄 Start 'Sync links from TSV file to short.io' -----------------------+
🔄
🔄 hostname = 'pyshortio.short.gy'
🔄 update_if_not_the_same = True
🔄 delete_if_not_in_file = True
🔄 +----- 🕑 📄 Start 'Read link data from TSV file' -----------------------------+
🔄 📄
🔄 📄 Read data ...
🔄 📄 Check original_url column ...
🔄 📄 Process tags column ...
🔄 📄 Got 8 rows
🔄 📄 Got 2 unique folder names
🔄 📄
🔄 +----- ⏰ ✅ 📄 End 'Read link data from TSV file', elapsed = 0.01 sec ---------+
🔄 +----- 🕑 📂 Start 'Create folder if they do not exists' ----------------------+
🔄 📂
🔄 📂 Read existing folder info from short.io ...
🔄 📂 Got 2 existing folders
🔄 📂 'Python' folder already exists
🔄 📂 'Short IO' folder already exists
🔄 📂
🔄 +----- ⏰ ✅ 📂 End 'Create folder if they do not exists', elapsed = 0.15 sec -----+
🔄 +----- 🕑 🔍 Start 'Identify link to create, update and delete' ---------------+
🔄 🔍
🔄 🔍 Read existing link info from short.io ...
🔄 🔍 Got 5 existing links
🔄 🔍 🟢 got 3 links to create
🔄 🔍 🟡 got 1 links to update
🔄 🔍 🔴 got 0 links to delete
🔄 🔍 To create: link_data = {'original_url': 'https://short.io/pricing/?utm_medium=linkedin', 'title': 'Short io pricing', 'tags': ['pricing', 'short.io'], 'utm_medium': 'linkedin', 'folder_id': 'BgG2lQ2kQwLHa4TepHU8P'}
🔄 🔍 To create: link_data = {'original_url': 'https://short.io/pricing/?utm_medium=twitter', 'title': 'Short io pricing', 'tags': ['pricing', 'short.io'], 'utm_medium': 'twitter', 'folder_id': 'BgG2lQ2kQwLHa4TepHU8P'}
🔄 🔍 To create: link_data = {'original_url': 'https://short.io/pricing/?utm_medium=reddit', 'title': 'Short io pricing', 'tags': ['pricing', 'short.io'], 'utm_medium': 'reddit', 'folder_id': 'BgG2lQ2kQwLHa4TepHU8P'}
🔄 🔍 To update: link_id = 'lnk_5Dae_DoultcXz5jO9HSCn26amm', link_data = {'original_url': 'https://www.python.org/', 'title': 'Python Org', 'path': 'python-org', 'tags': ['python'], 'folder_id': 'JR_S7CWHpfBqNZCYa2EzO'}
🔄 🔍
🔄 +----- ⏰ ✅ 🔍 End 'Identify link to create, update and delete', elapsed = 0.18 sec -----+
🔄 +----- 🕑 🟢 Start 'Create links' ---------------------------------------------+
🔄 🟢
🔄 🟢 create link for original_url = https://short.io/pricing/?utm_medium=linkedin
🔄 🟢 create link for original_url = https://short.io/pricing/?utm_medium=twitter
🔄 🟢 create link for original_url = https://short.io/pricing/?utm_medium=reddit
🔄 🟢
🔄 +----- ⏰ ✅ 🟢 End 'Create links', elapsed = 0.26 sec -------------------------+
🔄 +----- 🕑 🟡 Start 'Update links' ---------------------------------------------+
🔄 🟡
🔄 🟡 update link lnk_5Dae_DoultcXz5jO9HSCn26amm, original_url = https://www.python.org/
🔄 🟡
🔄 +----- ⏰ ✅ 🟡 End 'Update links', elapsed = 0.21 sec -------------------------+
🔄
+----- ⏰ ✅ 🔄 End 'Sync links from TSV file to short.io', elapsed = 0.97 sec -----+

Understanding Sync Parameters ⚙️¶

hostname: Your Short.io domain
file: TSV file containing link data
update_if_not_the_same (default: True): Update links that have changed
delete_if_not_in_file (default: False): Delete links not present in TSV file
real_run (default: True): Actually apply changes (set to False for dry-run)

Advanced Use Cases 🔥¶

Dry Run Mode¶

Before applying changes to your production domain, run in dry-run mode:

client.sync_tsv(
    hostname=hostname,
    file=file,
    real_run=False,  # Simulate changes without applying them
)

Automated Link Management¶

Incorporate Sync TSV into your automated workflows:

# Example: Daily sync job
def daily_link_sync():
    # Generate TSV from your database
    generate_tsv_from_database()

    # Sync to Short.io
    with open("generated_links.tsv", "r") as file:
        client.sync_tsv(
            hostname=hostname,
            file=file,
            update_if_not_the_same=True,
            delete_if_not_in_file=True,
        )

Best Practices 🌟¶

Start with Dry Runs: Use real_run=False to preview changes before applying them
Incremental Mode: Set delete_if_not_in_file=False to only add/update links
Full Sync Mode: Set delete_if_not_in_file=True to fully synchronize, removing links not in the TSV
Version Control Your TSVs: Keep TSV files in Git for history tracking
Incremental Updates: Start with delete_if_not_in_file=False until you’re comfortable
Folder Organization: Use the folder_name column to keep links organized
Automated Testing: Validate your TSV files before syncing

Troubleshooting 🔧¶

Common Issues

Missing Required Columns: Ensure your TSV has at least the original_url column
Duplicate URLs: Each original URL must be unique in your TSV
Permission Errors: Verify your API token has write permissions
Folder Creation Failures: Ensure folder names are valid

Reading Logs¶

The sync process produces detailed logs that can help identify issues:

🟢 indicates links to be created
🟡 indicates links to be updated
🔴 indicates links to be deleted

Conclusion¶

Sync TSV transforms how you manage shortened URLs at scale. Whether you’re managing marketing campaigns with dozens of tracking links or maintaining a knowledge base with hundreds of references, this feature makes bulk URL management simple, reliable, and efficient.

Get started today with PyShortIO and leave manual link management behind! 🚀