{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "2574e472-5bed-42ba-9c06-8b214b4da57f",
   "metadata": {},
   "source": [
    "# PyShortIO: A Pythonic Client for Short.io URL Shortening Service\n",
    "\n",
    "## Introduction\n",
    "\n",
    "This notebook provides a comprehensive walkthrough of the [PyShortIO](https://github.com/MacHu-GWU/pyshortio-project>) library, a Python client for interacting with the [Short.io](https://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.\n",
    "\n",
    "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.\n",
    "\n",
    "Let's explore the key features and functionality of the PyShortIO library through practical examples.\n",
    "\n",
    "## Prerequisites\n",
    "\n",
    "To use PyShortIO, you'll need:\n",
    "\n",
    "1. A Short.io account with API access\n",
    "2. Your Short.io API token\n",
    "3. A registered domain in your Short.io account\n",
    "\n",
    "## Installation\n",
    "\n",
    "First, let's install the PyShortIO library:\n",
    "\n",
    "```bash\n",
    "pip install pyshortio\n",
    "```\n",
    "\n",
    "## Setting Up the Client\n",
    "\n",
    "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."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "05ed99fe-c606-4457-a689-47040e95851c",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-04-21T03:16:55.157243Z",
     "start_time": "2025-04-21T03:16:55.102222Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Client initialized with endpoint: https://api.short.io\n"
     ]
    }
   ],
   "source": [
    "from pathlib import Path\n",
    "import pyshortio.api as pyshortio\n",
    "\n",
    "# Replace with your actual Short.io API token\n",
    "# API_TOKEN = \"your_api_token_here\"\n",
    "API_TOKEN = Path.home().joinpath(\".short.io\", \"sanhehu_esc\", \"sanhe-dev.txt\").read_text().strip()\n",
    "\n",
    "# Create a client instance\n",
    "client = pyshortio.Client(token=API_TOKEN)\n",
    "\n",
    "print(f\"Client initialized with endpoint: {client.endpoint}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "80ba3ae37aa20e97",
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "source": [
    "## Finding Your Domain\n",
    "\n",
    "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.\n",
    "\n",
    "In this example, we'll find a domain by its hostname and retrieve its ID, which we'll need for various operations."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "5705cb71e4a609f1",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-04-21T03:16:55.636554Z",
     "start_time": "2025-04-21T03:16:55.390166Z"
    },
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Domain found: pyshortio.short.gy\n",
      "Domain ID: 1342190\n",
      "Domain state: configured\n",
      "Domain created at: 2025-04-20 16:07:15+00:00\n"
     ]
    }
   ],
   "source": [
    "# Replace with your actual Short.io domain\n",
    "HOSTNAME = \"pyshortio.short.gy\"\n",
    "\n",
    "# Get domain by hostname\n",
    "response, domain = client.get_domain_by_hostname(hostname=HOSTNAME)\n",
    "\n",
    "if domain:\n",
    "    print(f\"Domain found: {domain.hostname}\")\n",
    "    print(f\"Domain ID: {domain.id}\")\n",
    "    print(f\"Domain state: {domain.state}\")\n",
    "    print(f\"Domain created at: {domain.created_at}\")\n",
    "    \n",
    "    # Store the domain ID for later use\n",
    "    domain_id = domain.id\n",
    "else:\n",
    "    print(f\"Domain {HOSTNAME} not found\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "70e7c5b814ea82a0",
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "source": [
    "## Cleaning Up Existing Links\n",
    "\n",
    "To start with a clean slate for our examples, we'll delete any existing links on our domain. This is a good practice for testing and demonstration purposes."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "23252b05b527f44d",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-04-21T03:16:56.236603Z",
     "start_time": "2025-04-21T03:16:55.687425Z"
    },
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Deleted 2 existing links. Success: True\n"
     ]
    }
   ],
   "source": [
    "# Fetch all existing links\n",
    "link_ids = []\n",
    "for _, link_list in client.pagi_list_links(\n",
    "    domain_id=domain_id,\n",
    "    limit=100,  # Fetch up to 100 links per page\n",
    "):\n",
    "    for link in link_list:\n",
    "        link_ids.append(link.id)\n",
    "\n",
    "# Delete all existing links if any were found\n",
    "if len(link_ids):\n",
    "    response, success = client.batch_delete_links(link_ids=link_ids)\n",
    "    print(f\"Deleted {len(link_ids)} existing links. Success: {success}\")\n",
    "else:\n",
    "    print(\"No existing links found to delete.\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "69945a3fdcb28583",
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "source": [
    "## Getting Domain Information\n",
    "\n",
    "Now that we've set up our environment, let's retrieve detailed information about our domain using its ID."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "b0913708fb92de1c",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-04-21T03:16:56.500965Z",
     "start_time": "2025-04-21T03:16:56.234901Z"
    },
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Domain ID: 1342190\n",
      "Hostname: pyshortio.short.gy\n",
      "Unicode Hostname: pyshortio.short.gy\n",
      "State: configured\n",
      "Created At: 2025-04-20 16:07:15+00:00\n",
      "Updated At: 2025-04-20 16:07:15+00:00\n",
      "Team ID: None\n",
      "Has Favicon: False\n"
     ]
    }
   ],
   "source": [
    "# Get domain information using the domain ID\n",
    "response, domain = client.get_domain(domain_id=domain_id)\n",
    "\n",
    "# Display domain information\n",
    "print(f\"Domain ID: {domain.id}\")\n",
    "print(f\"Hostname: {domain.hostname}\")\n",
    "print(f\"Unicode Hostname: {domain.unicode_hostname}\")\n",
    "print(f\"State: {domain.state}\")\n",
    "print(f\"Created At: {domain.created_at}\")\n",
    "print(f\"Updated At: {domain.updated_at}\")\n",
    "print(f\"Team ID: {domain.team_id}\")\n",
    "print(f\"Has Favicon: {domain.has_favicon}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "242d8cb19e9f79d7",
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "source": [
    "## Creating Your First Shortened Link\n",
    "\n",
    "Now let's create our first shortened link. We'll use the create_link method to shorten a URL to the Short.io pricing page."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "1201d13ebbcc761d",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-04-21T03:16:57.741029Z",
     "start_time": "2025-04-21T03:16:57.403747Z"
    },
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Link created successfully!\n",
      "ID: lnk_5Dae_mcadseJwZnuDmoMVoUhYl\n",
      "Title: Short io pricing\n",
      "Original URL: https://short.io/pricing/\n",
      "Shortened URL: https://pyshortio.short.gy/Yl3Hia\n",
      "Path: Yl3Hia\n",
      "Created At: 2025-04-21 03:41:29.569000+00:00\n"
     ]
    }
   ],
   "source": [
    "# Create a shortened link to the Short.io pricing page\n",
    "response, link = client.create_link(\n",
    "    hostname=HOSTNAME,\n",
    "    title=\"Short io pricing\",\n",
    "    original_url=\"https://short.io/pricing/\",\n",
    ")\n",
    "\n",
    "# Store this link for later use\n",
    "link_pricing = link\n",
    "\n",
    "# Display information about the newly created link\n",
    "print(f\"Link created successfully!\")\n",
    "print(f\"ID: {link.id}\")\n",
    "print(f\"Title: {link.title}\")\n",
    "print(f\"Original URL: {link.original_url}\")\n",
    "print(f\"Shortened URL: {link.short_url}\")\n",
    "print(f\"Path: {link.path}\")\n",
    "print(f\"Created At: {link.created_at}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8e2170c0150a348b",
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "source": [
    "## Creating Multiple Links in Batch\n",
    "\n",
    "Instead of creating links one by one, Short.io allows you to create multiple links in a single API call using the batch creation feature. This is more efficient when you need to create several links at once.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "93134db355018003",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-04-21T03:16:58.543994Z",
     "start_time": "2025-04-21T03:16:58.241895Z"
    },
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Batch links created successfully!\n",
      "\n",
      "Link 1:\n",
      "Title: Short io features\n",
      "Original URL: https://short.io/features/\n",
      "Shortened URL: https://pyshortio.short.gy/5fqCe1\n",
      "\n",
      "Link 2:\n",
      "Title: Short io integrations\n",
      "Original URL: https://short.io/integrations/\n",
      "Shortened URL: https://pyshortio.short.gy/EtC1pB\n"
     ]
    }
   ],
   "source": [
    "# Create multiple links in a batch\n",
    "response, links = client.batch_create_links(\n",
    "    hostname=HOSTNAME,\n",
    "    links=[\n",
    "        {\n",
    "            \"title\": \"Short io features\",\n",
    "            \"original_url\": \"https://short.io/features/\",\n",
    "        },\n",
    "        {\n",
    "            \"title\": \"Short io integrations\",\n",
    "            \"original_url\": \"https://short.io/integrations/\",\n",
    "        },\n",
    "    ],\n",
    ")\n",
    "\n",
    "# Store these links for later use\n",
    "link_features = links[0]\n",
    "link_integrations = links[1]\n",
    "\n",
    "# Display information about the newly created links\n",
    "print(\"Batch links created successfully!\")\n",
    "\n",
    "print(\"\\nLink 1:\")\n",
    "print(f\"Title: {link_features.title}\")\n",
    "print(f\"Original URL: {link_features.original_url}\")\n",
    "print(f\"Shortened URL: {link_features.short_url}\")\n",
    "\n",
    "print(\"\\nLink 2:\")\n",
    "print(f\"Title: {link_integrations.title}\")\n",
    "print(f\"Original URL: {link_integrations.original_url}\")\n",
    "print(f\"Shortened URL: {link_integrations.short_url}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "17daf072179fc270",
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "source": [
    "## Listing Links with Pagination\n",
    "\n",
    "Now that we have created some links, let's learn how to list them. First, we'll try listing with a limit to control how many links are returned per page."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "id": "ee04bb8263c23b40",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-04-21T03:17:01.084952Z",
     "start_time": "2025-04-21T03:16:59.802857Z"
    },
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Number of links returned: 2\n",
      "\n",
      "Link 1:\n",
      "ID: lnk_5Dae_3mX7ICtE7IjxdM27NPROw\n",
      "Title: Short io integrations\n",
      "Original URL: https://short.io/integrations/\n",
      "Shortened URL: https://pyshortio.short.gy/EtC1pB\n",
      "\n",
      "Link 2:\n",
      "ID: lnk_5Dae_DTNJvCr1elsn9NqyxoXMU\n",
      "Title: Short io features\n",
      "Original URL: https://short.io/features/\n",
      "Shortened URL: https://pyshortio.short.gy/5fqCe1\n"
     ]
    }
   ],
   "source": [
    "# List links with a limit of 2 per page\n",
    "response, link_list = client.list_links(\n",
    "    domain_id=domain_id,\n",
    "    limit=2,\n",
    ")\n",
    "\n",
    "# Display the number of links returned and their details\n",
    "print(f\"Number of links returned: {len(link_list)}\")\n",
    "\n",
    "for i, link in enumerate(link_list, 1):\n",
    "    print(f\"\\nLink {i}:\")\n",
    "    print(f\"ID: {link.id}\")\n",
    "    print(f\"Title: {link.title}\")\n",
    "    print(f\"Original URL: {link.original_url}\")\n",
    "    print(f\"Shortened URL: {link.short_url}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ecbe472e873e5c5c",
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "source": [
    "## Listing All Links\n",
    "\n",
    "Now let's list all links without specifying a limit. This will return all links on our domain."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "id": "9bee05c09c0e8d38",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-04-21T03:17:06.426667Z",
     "start_time": "2025-04-21T03:17:06.132835Z"
    },
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Total number of links: 3\n",
      "1. Short io integrations - https://pyshortio.short.gy/EtC1pB\n",
      "2. Short io features - https://pyshortio.short.gy/5fqCe1\n",
      "3. Short io pricing - https://pyshortio.short.gy/Yl3Hia\n"
     ]
    }
   ],
   "source": [
    "# List all links on the domain\n",
    "response, link_list = client.list_links(\n",
    "    domain_id=domain_id,\n",
    ")\n",
    "\n",
    "# Display the number of links returned\n",
    "print(f\"Total number of links: {len(link_list)}\")\n",
    "\n",
    "# Show a summarized list of all links\n",
    "for i, link in enumerate(link_list, 1):\n",
    "    print(f\"{i}. {link.title} - {link.short_url}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d86207faf8f56c87",
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "source": [
    "## Using a Higher Limit for Listing\n",
    "\n",
    "Let's try listing with a higher limit to ensure we retrieve all links in a single request."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "id": "96e4002626bf11e5",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-04-21T03:17:16.033503Z",
     "start_time": "2025-04-21T03:17:15.336079Z"
    },
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Number of links with limit=100: 3\n"
     ]
    }
   ],
   "source": [
    "# List links with a higher limit\n",
    "response, link_list = client.list_links(\n",
    "    domain_id=domain_id,\n",
    "    limit=100,\n",
    ")\n",
    "\n",
    "# Display the number of links returned\n",
    "print(f\"Number of links with limit=100: {len(link_list)}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "af145a9013e7dada",
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "source": [
    "## Auto-Pagination with pagi_list_links\n",
    "\n",
    "For cases where you might have many links spread across multiple pages, PyShortIO provides an auto-pagination feature. The pagi_list_links method automatically handles pagination for you."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "id": "8c72a90efccffa19",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-04-21T03:17:33.678170Z",
     "start_time": "2025-04-21T03:17:31.996804Z"
    },
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Number of pages: 2\n",
      "Links in first page: 2\n",
      "Links in second page: 1\n",
      "\n",
      "Links from first page:\n",
      "- Short io integrations (https://pyshortio.short.gy/EtC1pB)\n",
      "- Short io features (https://pyshortio.short.gy/5fqCe1)\n",
      "\n",
      "Links from second page:\n",
      "- Short io pricing (https://pyshortio.short.gy/Yl3Hia)\n"
     ]
    }
   ],
   "source": [
    "# Use auto-pagination to fetch links in multiple pages\n",
    "paginator = client.pagi_list_links(\n",
    "    domain_id=domain_id,\n",
    "    limit=2,  # This will split our 3 links into 2 pages\n",
    ")\n",
    "\n",
    "# Convert the paginator results to a list for easier handling\n",
    "results = list(paginator)\n",
    "\n",
    "# Display pagination results\n",
    "print(f\"Number of pages: {len(results)}\")\n",
    "print(f\"Links in first page: {len(results[0][1])}\")\n",
    "print(f\"Links in second page: {len(results[1][1])}\")\n",
    "\n",
    "# Display links from each page\n",
    "print(\"\\nLinks from first page:\")\n",
    "for link in results[0][1]:\n",
    "    print(f\"- {link.title} ({link.short_url})\")\n",
    "\n",
    "print(\"\\nLinks from second page:\")\n",
    "for link in results[1][1]:\n",
    "    print(f\"- {link.title} ({link.short_url})\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ffafe1bb77801eda",
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "source": [
    "## Getting OpenGraph Properties\n",
    "\n",
    "Short.io can extract OpenGraph metadata from the original URLs. Let's see how to retrieve this information for our pricing link."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "id": "82a30bbdcae3610b",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-04-21T03:18:06.944365Z",
     "start_time": "2025-04-21T03:18:06.540748Z"
    },
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "OpenGraph Properties:\n"
     ]
    }
   ],
   "source": [
    "# Get OpenGraph properties for the pricing link\n",
    "response, result = client.get_link_opengraph_properties(\n",
    "    domain_id=domain_id,\n",
    "    link_id=link_pricing.id,\n",
    ")\n",
    "\n",
    "# Display OpenGraph properties\n",
    "print(\"OpenGraph Properties:\")\n",
    "for value in result:\n",
    "    print(value)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "16e5e95b89f3318d",
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "source": [
    "## Getting Link Information by ID\n",
    "\n",
    "You can retrieve detailed information about a specific link using its ID."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "id": "f9e46130be1726da",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-04-21T03:18:21.407765Z",
     "start_time": "2025-04-21T03:18:21.120256Z"
    },
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Link ID: lnk_5Dae_mcadseJwZnuDmoMVoUhYl\n",
      "Title: Short io pricing\n",
      "Original URL: https://short.io/pricing/\n",
      "Shortened URL: https://pyshortio.short.gy/Yl3Hia\n",
      "Created At: 2025-04-21 03:41:29.569000+00:00\n"
     ]
    }
   ],
   "source": [
    "# Get information about the pricing link by its ID\n",
    "response, link = client.get_link_info_by_link_id(link_id=link_pricing.id)\n",
    "\n",
    "# Display link information\n",
    "print(f\"Link ID: {link.id}\")\n",
    "print(f\"Title: {link.title}\")\n",
    "print(f\"Original URL: {link.original_url}\")\n",
    "print(f\"Shortened URL: {link.short_url}\")\n",
    "print(f\"Created At: {link.created_at}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d52b2e23717f2aa5",
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "source": [
    "## Handling Non-Existent Links\n",
    "\n",
    "It's important to handle cases where a link might not exist. Let's try retrieving a non-existent link."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "id": "fef91c0bc5f144c3",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-04-21T03:18:37.332728Z",
     "start_time": "2025-04-21T03:18:37.076950Z"
    },
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Link not found, as expected.\n"
     ]
    }
   ],
   "source": [
    "# Try to get information about a non-existent link\n",
    "response, link = client.get_link_info_by_link_id(\n",
    "    link_id=\"not-exists\",\n",
    "    raise_for_status=False,  # Prevent raising an exception for 404 responses\n",
    ")\n",
    "\n",
    "# Check if link exists\n",
    "if link is None:\n",
    "    print(\"Link not found, as expected.\")\n",
    "else:\n",
    "    print(\"Unexpected: Link found.\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a8e7ff63e36ba989",
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "source": [
    "## Getting Link Information by Path\n",
    "\n",
    "You can also retrieve link information using the hostname and path components of the shortened URL."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "id": "cef78eda39cb6b17",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-04-21T03:18:51.089427Z",
     "start_time": "2025-04-21T03:18:50.689592Z"
    },
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Link ID: lnk_5Dae_mcadseJwZnuDmoMVoUhYl\n",
      "Path: Yl3Hia\n",
      "Title: Short io pricing\n",
      "Original URL: https://short.io/pricing/\n"
     ]
    }
   ],
   "source": [
    "# Get link information by hostname and path\n",
    "response, link = client.get_link_info_by_path(\n",
    "    hostname=HOSTNAME,\n",
    "    path=link_pricing.path,\n",
    ")\n",
    "\n",
    "# Display link information\n",
    "print(f\"Link ID: {link.id}\")\n",
    "print(f\"Path: {link.path}\")\n",
    "print(f\"Title: {link.title}\")\n",
    "print(f\"Original URL: {link.original_url}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4142a14b5502e18c",
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "source": [
    "## Handling Non-Existent Paths\n",
    "\n",
    "Similar to handling non-existent links, let's see how to handle a non-existent path."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "id": "cc284be2af5a83c",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-04-21T03:19:03.822694Z",
     "start_time": "2025-04-21T03:19:03.569302Z"
    },
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Path not found, as expected.\n"
     ]
    }
   ],
   "source": [
    "# Try to get information about a non-existent path\n",
    "response, link = client.get_link_info_by_path(\n",
    "    hostname=HOSTNAME,\n",
    "    path=\"not-exists\",\n",
    "    raise_for_status=False,  # Prevent raising an exception for 404 responses\n",
    ")\n",
    "\n",
    "# Check if link exists\n",
    "if link is None:\n",
    "    print(\"Path not found, as expected.\")\n",
    "else:\n",
    "    print(\"Unexpected: Path found.\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "782d650895730320",
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "source": [
    "## Finding Links by Original URL\n",
    "\n",
    "Short.io allows you to find all shortened links that point to a specific original URL. This is useful when you want to check if a URL has already been shortened."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "id": "1c03a3191b8651c9",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-04-21T03:19:15.642978Z",
     "start_time": "2025-04-21T03:19:15.188982Z"
    },
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Number of links found: 1\n",
      "ID: lnk_5Dae_mcadseJwZnuDmoMVoUhYl\n",
      "Title: Short io pricing\n",
      "Original URL: https://short.io/pricing/\n",
      "Shortened URL: https://pyshortio.short.gy/Yl3Hia\n"
     ]
    }
   ],
   "source": [
    "# Find links by original URL\n",
    "response, link_list = client.list_links_by_original_url(\n",
    "    hostname=HOSTNAME,\n",
    "    original_url=link_pricing.original_url,\n",
    ")\n",
    "\n",
    "# Display the number of links found\n",
    "print(f\"Number of links found: {len(link_list)}\")\n",
    "\n",
    "# Display information about the found links\n",
    "for link in link_list:\n",
    "    print(f\"ID: {link.id}\")\n",
    "    print(f\"Title: {link.title}\")\n",
    "    print(f\"Original URL: {link.original_url}\")\n",
    "    print(f\"Shortened URL: {link.short_url}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "befc05b11b448054",
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "source": [
    "## Searching for Non-Existent Original URLs\n",
    "\n",
    "Let's try searching for links with an original URL that doesn't exist in our domain."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "id": "7e440a8b32929af",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-04-21T03:19:26.788684Z",
     "start_time": "2025-04-21T03:19:26.499228Z"
    },
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Number of links found: 0\n"
     ]
    }
   ],
   "source": [
    "# Search for links with a non-existent original URL\n",
    "response, link_list = client.list_links_by_original_url(\n",
    "    hostname=HOSTNAME,\n",
    "    original_url=\"https://example.com/not-exists\",\n",
    "    raise_for_status=False,  # Prevent raising an exception for 404 responses\n",
    ")\n",
    "\n",
    "# Display the number of links found\n",
    "print(f\"Number of links found: {len(link_list)}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "be68de59a61184e7",
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "source": [
    "## Listing Folders\n",
    "\n",
    "Short.io allows you to organize your links into folders. Let's list all folders in our domain."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "id": "508ead7ad61bcb40",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-04-21T03:19:38.912071Z",
     "start_time": "2025-04-21T03:19:38.669709Z"
    },
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Number of folders: 0\n",
      "No folders found.\n"
     ]
    }
   ],
   "source": [
    "# List all folders in the domain\n",
    "response, folder_list = client.list_folders(domain_id=domain_id)\n",
    "\n",
    "# Display the number of folders\n",
    "print(f\"Number of folders: {len(folder_list)}\")\n",
    "\n",
    "# Display folder information if any exist\n",
    "if len(folder_list) > 0:\n",
    "    for folder in folder_list:\n",
    "        print(f\"Folder ID: {folder.id}\")\n",
    "        print(f\"Folder Name: {folder.name}\")\n",
    "else:\n",
    "    print(\"No folders found.\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2ddf72fc1fa076a2",
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "source": [
    "## Handling Non-Existent Folders\n",
    "\n",
    "Let's try retrieving a non-existent folder."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "id": "3a9ad850758cca13",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-04-21T03:19:53.600158Z",
     "start_time": "2025-04-21T03:19:53.309421Z"
    },
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Folder not found, as expected.\n"
     ]
    }
   ],
   "source": [
    "# Try to get information about a non-existent folder\n",
    "response, folder = client.get_folder(\n",
    "    domain_id=domain_id,\n",
    "    folder_id=\"not-exists\",\n",
    "    raise_for_status=False,  # Prevent raising an exception for 404 responses\n",
    ")\n",
    "\n",
    "# Check if folder exists\n",
    "if folder is None:\n",
    "    print(\"Folder not found, as expected.\")\n",
    "else:\n",
    "    print(\"Unexpected: Folder found.\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f22bdd90f65cdbe1",
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "source": [
    "## Updating a Link\n",
    "\n",
    "Now that we've explored various ways to retrieve link information, let's update an existing link. We'll modify the title and original URL of our pricing link."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "id": "a145b12e415a9987",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-04-21T03:20:04.363854Z",
     "start_time": "2025-04-21T03:20:04.102096Z"
    },
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Link updated successfully!\n",
      "ID: lnk_5Dae_mcadseJwZnuDmoMVoUhYl\n",
      "Updated Title: Short io pricing updated\n",
      "Updated Original URL: https://short.io/pricing/updated\n",
      "Shortened URL: https://pyshortio.short.gy/Yl3Hia\n"
     ]
    }
   ],
   "source": [
    "# Update the pricing link\n",
    "response, link = client.update_link(\n",
    "    link_id=link_pricing.id,\n",
    "    title=\"Short io pricing updated\",\n",
    "    original_url=\"https://short.io/pricing/updated\",\n",
    ")\n",
    "\n",
    "# Display updated link information\n",
    "print(f\"Link updated successfully!\")\n",
    "print(f\"ID: {link.id}\")\n",
    "print(f\"Updated Title: {link.title}\")\n",
    "print(f\"Updated Original URL: {link.original_url}\")\n",
    "print(f\"Shortened URL: {link.short_url}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "55728ea5615da9a5",
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "source": [
    "## Verifying the Update\n",
    "\n",
    "Let's verify that our link was actually updated by retrieving it again."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "id": "5fc93100af60cdd2",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-04-21T03:20:15.915765Z",
     "start_time": "2025-04-21T03:20:15.538745Z"
    },
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Link ID: lnk_5Dae_mcadseJwZnuDmoMVoUhYl\n",
      "Title: Short io pricing updated\n",
      "Original URL: https://short.io/pricing/updated\n",
      "Shortened URL: https://pyshortio.short.gy/Yl3Hia\n"
     ]
    }
   ],
   "source": [
    "# Get the updated link to verify changes\n",
    "response, link = client.get_link_info_by_link_id(link_id=link_pricing.id)\n",
    "\n",
    "# Display updated link information\n",
    "print(f\"Link ID: {link.id}\")\n",
    "print(f\"Title: {link.title}\")\n",
    "print(f\"Original URL: {link.original_url}\")\n",
    "print(f\"Shortened URL: {link.short_url}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "503741945b7145f6",
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "source": [
    "## Handling Update for Non-Existent Links\n",
    "\n",
    "Let's try updating a non-existent link and see how to handle this scenario."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "id": "52c8f77f2209cd6f",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-04-21T03:20:26.066353Z",
     "start_time": "2025-04-21T03:20:25.754415Z"
    },
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Link not found, update failed as expected.\n"
     ]
    }
   ],
   "source": [
    "# Try to update a non-existent link\n",
    "response, link = client.update_link(\n",
    "    link_id=\"not-exists\",\n",
    "    raise_for_status=False,  # Prevent raising an exception for 404 responses\n",
    ")\n",
    "\n",
    "# Check if link exists\n",
    "if link is None:\n",
    "    print(\"Link not found, update failed as expected.\")\n",
    "else:\n",
    "    print(\"Unexpected: Link updated.\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4a44c8be758f24c9",
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "source": [
    "## Handling Invalid Link IDs\n",
    "\n",
    "Let's try updating a link with an invalid ID format."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "id": "1769896c355fcd7a",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-04-21T03:20:39.404818Z",
     "start_time": "2025-04-21T03:20:39.134489Z"
    },
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Invalid link ID, update failed as expected.\n"
     ]
    }
   ],
   "source": [
    "# Try to update a link with an invalid ID format\n",
    "response, link = client.update_link(\n",
    "    link_id=\"lnk_1a2b_3333cccc4444dddd55555\",  # Invalid ID format\n",
    "    raise_for_status=False,  # Prevent raising an exception for 400 responses\n",
    ")\n",
    "\n",
    "# Check if link exists\n",
    "if link is None:\n",
    "    print(\"Invalid link ID, update failed as expected.\")\n",
    "else:\n",
    "    print(\"Unexpected: Link updated.\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "eadbd1eb1cba9ebb",
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "source": [
    "## Deleting a Link\n",
    "\n",
    "Now let's delete a link. We'll delete the pricing link that we created earlier."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 24,
   "id": "ed0551f87d59048d",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-04-21T03:20:53.636813Z",
     "start_time": "2025-04-21T03:20:53.357566Z"
    },
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Link deleted successfully!\n"
     ]
    }
   ],
   "source": [
    "# Delete the pricing link\n",
    "response, success = client.delete_link(\n",
    "    link_id=link_pricing.id,\n",
    ")\n",
    "\n",
    "# Check if deletion was successful\n",
    "if success:\n",
    "    print(f\"Link deleted successfully!\")\n",
    "else:\n",
    "    print(\"Failed to delete link.\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "cd64af010e48b3c0",
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "source": [
    "## Handling Deletion for Non-Existent Links\n",
    "\n",
    "Let's try deleting a non-existent link and see how to handle this scenario."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 25,
   "id": "4c92525db5216033",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-04-21T03:21:03.607873Z",
     "start_time": "2025-04-21T03:21:03.292948Z"
    },
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Failed to delete link, as expected for a non-existent link.\n"
     ]
    }
   ],
   "source": [
    "# Try to delete a non-existent link\n",
    "response, success = client.delete_link(\n",
    "    link_id=\"not-exists\",\n",
    "    raise_for_status=False,  # Prevent raising an exception for 404 responses\n",
    ")\n",
    "\n",
    "# Check if deletion was successful\n",
    "if success:\n",
    "    print(\"Unexpected: Link deleted.\")\n",
    "else:\n",
    "    print(\"Failed to delete link, as expected for a non-existent link.\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "84fc90eaa475aeb1",
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "source": [
    "## Verifying Remaining Links\n",
    "\n",
    "Finally, let's verify that we now have one less link in our domain after the deletion."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 26,
   "id": "937537b77e12f60e",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-04-21T03:21:20.723151Z",
     "start_time": "2025-04-21T03:21:20.434733Z"
    },
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Number of links after deletion: 2\n",
      "1. Short io integrations - https://pyshortio.short.gy/EtC1pB\n",
      "2. Short io features - https://pyshortio.short.gy/5fqCe1\n"
     ]
    }
   ],
   "source": [
    "# List all links to verify the deletion\n",
    "response, link_list = client.list_links(\n",
    "    domain_id=domain_id,\n",
    "    limit=100,\n",
    ")\n",
    "\n",
    "# Display the number of links\n",
    "print(f\"Number of links after deletion: {len(link_list)}\")\n",
    "\n",
    "# List all links\n",
    "for i, link in enumerate(link_list, 1):\n",
    "    print(f\"{i}. {link.title} - {link.short_url}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "21adf9599b8ec777",
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "source": [
    "## Conclusion\n",
    "\n",
    "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:\n",
    "\n",
    "- Setting up the client\n",
    "- Finding and retrieving domain information\n",
    "- Creating individual and batch links\n",
    "- Listing links with and without pagination\n",
    "- Retrieving link information in various ways\n",
    "- Updating links\n",
    "- Deleting links\n",
    "- Handling various error scenarios\n",
    "\n",
    "[PyShortIO](https://github.com/MacHu-GWU/pyshortio-project) provides a clean, Pythonic interface to Short.io's API, making it easy to integrate URL shortening functionality into your Python applications.\n",
    "\n",
    "For more details, refer to the official documentation and the API reference at the project's GitHub repository: PyShortIO."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.11.8"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}