sync_tsv

Short.io TSV Synchronization Tool

This module provides functionality to synchronize URL shortening data between a TSV (Tab-Separated Values) file and the Short.io service. It enables bulk management of shortened URLs through a single configuration file, automating the creation, updating, and deletion of links to maintain consistency between local definitions and the Short.io service.

class pyshortio.sync_tsv.T_LINK_DATA

his TypedDict defines the expected structure for link data extracted from TSV files, mapping column names to their appropriate types. It includes both required fields (original_url) and various optional fields that correspond to Short.io link properties.

pyshortio.sync_tsv.get_fingerprint_data_from_link(link: Link) → Dict[str, Any]

Extract relevant data from a Link object for fingerprinting purposes.

This function extracts a standardized subset of link properties from a Link object to create a consistent representation for comparison. It removes None values and sorts tags to ensure consistent comparison regardless of order.

pyshortio.sync_tsv.is_same(link_data: T_LINK_DATA, link: Link) → bool

Compare a link data dictionary with a Link object to determine if they are equivalent.

This function checks if the properties in the link_data dictionary match the corresponding properties in the Link object. It handles comparing only the properties that are present in both, ignoring properties that are only in the Link object but not in link_data.

Parameters:

• link_data – Dictionary containing link properties from TSV

• link – Link object retrieved from Short.io

Returns:

True if all matching properties are the same, False otherwise

Note

The comparison is one-directional: it checks if properties in link_data match those in the Link object, but doesn’t require all properties in the Link object to be in link_data.

class pyshortio.sync_tsv.SyncTSVMixin

Mixin class providing TSV synchronization capabilities for the Client.

sync_tsv(hostname: str, file: StringIO, update_if_not_the_same: bool = True, delete_if_not_in_file: bool = False, raise_for_status: bool = True, real_run: bool = True)

Synchronize links from a TSV file to Short.io.

This is the main public method of the SyncTSVMixin class, orchestrating the entire synchronization process. It reads the TSV file, creates folders if needed, identifies necessary operations, and executes them according to the specified options.

Parameters:

• hostname – The hostname of the Short.io domain (e.g., “example.short.gy”)

• file – An open file-like object containing TSV data

• update_if_not_the_same – Whether to update links that have changed. Defaults to True.

• delete_if_not_in_file – Whether to delete links that aren’t in the TSV file. Defaults to False.

• raise_for_status – Whether to raise exceptions for HTTP errors. Defaults to DEFAULT_RAISE_FOR_STATUS.

• real_run – Whether to actually perform the API calls or just simulate them for a dry run. Defaults to True.

Note

• Setting delete_if_not_in_file=True can be destructive, as it will delete any links not defined in the TSV file. Use with caution.

• Setting real_run=False performs a dry run, logging what would happen without making actual API calls. This is useful for testing.

• The method logs detailed information about all operations for auditing and debugging purposes