{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Sequences Client tutorial\n",
    "\n",
    "## Introduction \n",
    "\n",
    "This tutorial will show you how to use the `refget.SequenceClient` class to interact with a remote Refget sequences API.\n",
    "\n",
    "<div class=\"admonition success\">\n",
    "  <p class=\"admonition-title\">Learning objectives</p>\n",
    "  <ul>\n",
    "    <li>How do I connect to a remote refget sequences API?</li>\n",
    "    <li>How do I retrieve sequences by their digest?</li>\n",
    "    <li>How do I get sequence metadata and service information?</li>\n",
    "    <li>How does error handling work when sequences are not found?</li>\n",
    "  </ul>\n",
    "</div>\n",
    "\n",
    "First, record some versions used in this tutorial:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-01-23T01:48:38.149217Z",
     "iopub.status.busy": "2026-01-23T01:48:38.149092Z",
     "iopub.status.idle": "2026-01-23T01:48:38.155493Z",
     "shell.execute_reply": "2026-01-23T01:48:38.155131Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'3.12.3'"
      ]
     },
     "execution_count": 1,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from platform import python_version \n",
    "python_version()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-01-23T01:48:38.213966Z",
     "iopub.status.busy": "2026-01-23T01:48:38.213799Z",
     "iopub.status.idle": "2026-01-23T01:48:38.218547Z",
     "shell.execute_reply": "2026-01-23T01:48:38.218267Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'0.10.0'"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "import refget\n",
    "refget.__version__"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Connecting to a remote API\n",
    "\n",
    "The refget package provides a simple Python wrapper around a remote hosted refget sequences API. Provide the base url when construction a `SequenceClient` object and you can retrieve sequences from the remote server."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-01-23T01:48:38.219803Z",
     "iopub.status.busy": "2026-01-23T01:48:38.219700Z",
     "iopub.status.idle": "2026-01-23T01:48:38.258361Z",
     "shell.execute_reply": "2026-01-23T01:48:38.257881Z"
    }
   },
   "outputs": [],
   "source": [
    "from refget.clients import SequenceClient\n",
    "\n",
    "seq_client = SequenceClient(urls=[\"https://beta.ensembl.org/data/refget/\"])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-01-23T01:48:38.260430Z",
     "iopub.status.busy": "2026-01-23T01:48:38.260325Z",
     "iopub.status.idle": "2026-01-23T01:48:38.726561Z",
     "shell.execute_reply": "2026-01-23T01:48:38.725980Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'CCACACCACA'"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "seq_client.get_sequence(\"6681ac2f62509cfc220d78751b8dc524\", start=0, end=10)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-01-23T01:48:38.729426Z",
     "iopub.status.busy": "2026-01-23T01:48:38.729149Z",
     "iopub.status.idle": "2026-01-23T01:48:39.121965Z",
     "shell.execute_reply": "2026-01-23T01:48:39.121288Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'CCACACCACACCCACACACCCACACACCACACCACACACCACACCACACC'"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "seq_client.get_sequence(\"6681ac2f62509cfc220d78751b8dc524\", start=0, end=50)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can also hit the `{digest}/metadata` and `service_info` API endpoints described in the refget API specification:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-01-23T01:48:39.124575Z",
     "iopub.status.busy": "2026-01-23T01:48:39.124269Z",
     "iopub.status.idle": "2026-01-23T01:48:39.556833Z",
     "shell.execute_reply": "2026-01-23T01:48:39.556174Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'metadata': {'id': '6681ac2f62509cfc220d78751b8dc524',\n",
       "  'md5': '6681ac2f62509cfc220d78751b8dc524',\n",
       "  'trunc512': '959cb1883fc1ca9ae1394ceb475a356ead1ecceff5824ae7',\n",
       "  'ga4gh': 'SQ.lZyxiD_ByprhOUzrR1o1bq0ezO_1gkrn',\n",
       "  'length': 230218,\n",
       "  'aliases': []}}"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "seq_client.get_metadata(\"6681ac2f62509cfc220d78751b8dc524\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-01-23T01:48:39.559557Z",
     "iopub.status.busy": "2026-01-23T01:48:39.559295Z",
     "iopub.status.idle": "2026-01-23T01:48:39.958132Z",
     "shell.execute_reply": "2026-01-23T01:48:39.957633Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'id': 'refget.infra.ebi.ac.uk',\n",
       " 'name': 'Refget server',\n",
       " 'type': {'group': 'org.ga4gh', 'artifact': 'refget', 'version': '2.0.0'},\n",
       " 'description': None,\n",
       " 'organization': {'name': 'EMBL-EBI', 'url': 'https://ebi.ac.uk/'},\n",
       " 'contactUrl': None,\n",
       " 'documentationUrl': None,\n",
       " 'createdAt': None,\n",
       " 'updatedAt': None,\n",
       " 'environment': None,\n",
       " 'version': '1.0.1',\n",
       " 'refget': {'circular_supported': False,\n",
       "  'subsequence_limit': None,\n",
       "  'algorithms': ['md5', 'ga4gh', 'trunc512'],\n",
       "  'identifier_types': None}}"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "seq_client.service_info()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Error handling\n",
    "\n",
    "When requesting a sequence that doesn't exist, a compliant server should return a 404 error. The client will raise a `ConnectionError` if all URLs fail:\n",
    "\n",
    "Note: Some servers may return different error codes (e.g., 500) for invalid digests. The client handles this by trying all configured URLs before failing."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-01-23T01:48:39.960054Z",
     "iopub.status.busy": "2026-01-23T01:48:39.959951Z",
     "iopub.status.idle": "2026-01-23T01:48:40.361196Z",
     "shell.execute_reply": "2026-01-23T01:48:40.360540Z"
    }
   },
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "All URLs failed:\n",
      "Error from https://beta.ensembl.org/data/refget: 404 Client Error: Not Found for url: https://beta.ensembl.org/data/refget/sequence/BogusDigest\n"
     ]
    }
   ],
   "source": [
    "seq_client.get_sequence('BogusDigest')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": "<div class=\"admonition success\">\n  <p class=\"admonition-title\">Summary</p>\n  <ul>\n    <li><code>SequenceClient(urls)</code> connects to a remote refget sequences API</li>\n    <li><code>client.get_sequence(digest)</code> retrieves sequences, with optional <code>start</code>/<code>end</code> positions</li>\n    <li><code>client.get_metadata(digest)</code> returns sequence length and aliases</li>\n  </ul>\n</div>"
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "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.12.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}