link_queries¶

Short.io Link query API implementation.

This module provides classes and methods for interacting with the Short.io Link-related API endpoints. It focuses on query operations that retrieve link information from the Short.io service, implementing a comprehensive suite of methods for different query patterns.

he implementation follows three key design patterns:

Return Pattern:

All methods representing Short.io API calls return a tuple of two objects:

First: The raw requests.Response object, allowing users complete access to

HTTP response details (headers, status codes, etc.)

Second: A method-specific result in a Pythonic format (e.g., a list of Link objects)

Each method includes a raise_for_status parameter that controls whether exceptions are raised immediately on HTTP errors, giving users fine-grained control over error handling.

Parameter Handling:

Methods use the NA (Not Applicable) sentinel value for optional parameters, which are filtered out before being sent to the API using the rm_na utility.

Pagination Abstraction Pattern:

Short.io API list methods use next page tokens for pagination. This module implements a universal pagination mechanism that converts any regular API method to an auto-paginating method. These methods are prefixed with pagi_ followed by the original method name and return an iterable of the original method’s return values (typically tuples of response and specialized objects).

class pyshortio.link_queries.LinkQueriesMixin[source]¶

Mixin class providing Link-related query methods for the Client.

This class implements various methods for retrieving link information from the Short.io API. It focuses exclusively on query operations (retrieving existing links) rather than modification operations, which are handled by the LinkManagementMixin class.

All methods follow the Dual Return Pattern, returning both the raw HTTP response and a Pythonic representation of the API result.

Methods prefixed with pagi_ implement the Pagination Abstraction Pattern, automatically handling pagination for list operations.

These methods interact with Link objects which are defined in the model module, providing a clean separation between data models and API operations.

list_links(domain_id: int, limit: int | None = _NOTHING(), id_string: int | None = _NOTHING(), create_at: datetime | None = _NOTHING(), before_date: datetime | None = _NOTHING(), after_date: datetime | None = _NOTHING(), date_sort_order: str | None = _NOTHING(), page_token: str | None = _NOTHING(), folder_id: str | None = _NOTHING(), raise_for_status: bool = True) → tuple[Response, list[Link]][source]¶

List links for a specific domain with optional filtering.

This method retrieves links from the Short.io API with various filtering options. It follows the Dual Return Pattern, providing both raw HTTP access and Pythonic data models.

Example:

>>> # List all links for a domain with a limit of 2
>>> response, link_list = client.list_links(
...     domain_id=45678,
...     limit=2,
... )
>>> print(len(link_list))  # Output: 2
>>>
>>> # List all links for a domain
>>> response, link_list = client.list_links(
...     domain_id=45678,
... )
>>> print(len(link_list))  # Output: 3

Ref:

https://developers.short.io/reference/get_api-domains

pagi_list_links(domain_id: int, limit: int | None = _NOTHING(), id_string: int | None = _NOTHING(), create_at: datetime | None = _NOTHING(), before_date: datetime | None = _NOTHING(), after_date: datetime | None = _NOTHING(), date_sort_order: str | None = _NOTHING(), folder_id: str | None = _NOTHING(), total_max_results: int = 9999, raise_for_status: bool = True) → Iterable[tuple[Response, list[Link]]][source]¶

Auto-paginated version of list_link method.

This method implements the Pagination Abstraction Pattern, automatically handling pagination for listing links. It returns an iterable that yields each page of results, allowing for efficient processing of large result sets.

>>> # Process all links across multiple pages
>>> for response, links in client.pagi_list_links(domain_id=45678):
>>>     for link in links:
>>>         process_link(link)

Note

This method automatically handles fetching subsequent pages until

get_link_opengraph_properties(domain_id: int, link_id: str, raise_for_status: bool = True) → tuple[Response, list | None][source]¶

Get OpenGraph properties for a specific link.

Example:

>>> # Get OpenGraph properties for a specific link
>>> response, properties = client.get_link_opengraph_properties(
...     domain_id=45678,
...     link_id="lnk_abc123def456"
... )
>>> # Properties typically include metadata like title, description, etc.
>>> print(properties)  # Output: {'title': 'Example Page', ...}

Ref:

https://developers.short.io/reference/get_links-opengraph-domainid-linkid

get_link_info_by_link_id(link_id: str, raise_for_status: bool = True) → tuple[Response, Link][source]¶

This method retrieves detailed information about a specific link using its ID.

Example:

>>> # Get information for an existing link
>>> response, link = client.get_link_info_by_link_id(
...     link_id="lnk_abc123def456"
... )
>>> print(link.id)  # Output: lnk_abc123def456
>>>
>>> # Try to get a non-existent link
>>> response, link = client.get_link_info_by_link_id(
...     link_id="non_existent",
...     raise_for_status=False
... )
>>> print(link)  # Output: None

Ref:

https://developers.short.io/reference/get_links-linkid

get_link_info_by_path(hostname: str, path: str, raise_for_status: bool = True) → tuple[Response, Link][source]¶

This method retrieves link information using the hostname and path components of the shortened URL.

Example:

>>> # Get link information by path
>>> response, link = client.get_link_info_by_path(
...     hostname="example.short.gy",
...     path="abc123"
... )
>>> print(link.id)  # Output: lnk_abc123def456
>>> print(link.path)  # Output: abc123
>>>
>>> # Try to get a non-existent path
>>> response, link = client.get_link_info_by_path(
...     hostname="example.short.gy",
...     path="non_existent",
...     raise_for_status=False
... )
>>> print(link)  # Output: None

Ref:

https://developers.short.io/reference/get_links-expand

list_links_by_original_url(hostname: str, original_url: str, raise_for_status: bool = True) → tuple[Response, list[Link]][source]¶

This method finds all shortened links that point to the specified original URL.

Example:

>>> # Find all links pointing to a specific URL
>>> response, link_list = client.list_links_by_original_url(
...     hostname="example.short.gy",
...     original_url="https://example.com/page"
... )
>>> print(len(link_list))  # Output: 1
>>> print(link_list[0].original_url)  # Output: https://example.com/page
>>>
>>> # Search for a URL with no links
>>> response, link_list = client.list_links_by_original_url(
...     hostname="example.short.gy",
...     original_url="https://example.com/not-exists",
...     raise_for_status=False
... )
>>> print(len(link_list))  # Output: 0

Ref:

https://developers.short.io/reference/get_links-multiple-by-url

get_folder(domain_id: int, folder_id: str, raise_for_status: bool = True) → tuple[Response, Folder | None][source]¶

This method retrieves detailed information about a specific folder.

Example:

>>> # Get folder information
>>> response, folder = client.get_folder(
...     domain_id=45678,
...     folder_id="fld_abc123def456"
... )
>>> if folder:
...     print(f"Folder name: {folder.name}")
>>>
>>> # Try to get a non-existent folder
>>> response, folder = client.get_folder(
...     domain_id=45678,
...     folder_id="non_existent",
...     raise_for_status=False
... )
>>> print(folder)  # Output: None

Ref:

https://developers.short.io/reference/get_links-folders-domainid-folderid

list_folders(domain_id: int, raise_for_status: bool = True) → tuple[Response, list[Folder]][source]¶

This method retrieves all folders used to organize links for a domain.

Example:

>>> # List all folders for a domain
>>> response, folder_list = client.list_folders(
...     domain_id=45678
... )
>>> # Print folder information
>>> for folder in folder_list:
...     print(f"ID: {folder.id}, Name: {folder.name}")

Ref:

https://developers.short.io/reference/get_links-folders-domainid

create_folder(domain_id: int, name: str, color: str = _NOTHING(), background_color: str = _NOTHING(), logo_url: str = _NOTHING(), logo_height: str = _NOTHING(), logo_width: str = _NOTHING(), ec_level: str = _NOTHING(), integration_fb: str = _NOTHING(), integration_ga: str = _NOTHING(), integration_gtm: str = _NOTHING(), integration_adroll: str = _NOTHING(), utm_campaign: str = _NOTHING(), utm_medium: str = _NOTHING(), utm_source: str = _NOTHING(), redirect_type: int = _NOTHING(), expires_at_days: int = _NOTHING(), icon: str = _NOTHING(), prefix: str = _NOTHING(), raise_for_status: bool = True) → tuple[Response, Folder | None][source]¶

Create a new folder for organizing links.

Ref:

https://developers.short.io/reference/post_links-folders