Merge pull request #266 from bugout-dev/clients-python

Moonstream Python client library

.github/workflows/release.clients.python.yml

@@ -0,0 +1,45 @@
+name: Publish Moonstream Python client library
+
+on:
+  push:
+    tags:
+      - "clients/python/v*"
+
+defaults:
+  run:
+    working-directory: clients/python
+
+jobs:
+  publish:
+    runs-on: ubuntu-20.04
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Python
+        uses: actions/setup-python@v2
+        with:
+          python-version: "3.9"
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .[distribute]
+      - name: Build and publish
+        env:
+          TWINE_USERNAME: ${{ secrets.PYPI_USERNAME }}
+          TWINE_PASSWORD: ${{ secrets.PYPI_PASSWORD }}
+        run: |
+          python setup.py sdist bdist_wheel
+          twine upload dist/*
+  create_release:
+    runs-on: ubuntu-20.04
+    steps:
+      - uses: actions/create-release@v1
+        id: create_release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          tag_name: ${{ github.ref }}
+          release_name: "Moonstream Python client library - ${{ github.ref }}"
+          body: |
+            Version ${{ github.ref }} of the Moonstream Python client library.
+          draft: true
+          prerelease: false

.github/workflows/test.clients.python.yml

@@ -0,0 +1,38 @@
+name: Linting and tests for the Moonstream Python client library
+
+on:
+  pull_request:
+    branches:
+      - "main"
+    paths:
+      - "clients/python/**"
+
+jobs:
+  build:
+    runs-on: ubuntu-20.04
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up python
+        uses: actions/setup-python@v2
+        with:
+          python-version: "3.9"
+      - name: Install test requirements
+        working-directory: ./clients/python
+        run: pip install -e .[dev]
+      - name: Mypy type check
+        working-directory: ./clients/python
+        run: mypy moonstream/
+      - name: Black syntax check
+        working-directory: ./clients/python
+        run: black --check moonstream/
+      - name: Unit tests
+        working-directory: ./clients/python
+        run: python -m unittest discover -v
+      - name: Check that versions are synchronized
+        working-directory: ./clients/python
+        run: |
+          CLIENT_VERSION=$(python -c "from moonstream.client import CLIENT_VERSION; print(CLIENT_VERSION)")
+          SETUP_PY_VERSION=$(python setup.py --version)
+          echo "Client version: $CLIENT_VERSION"
+          echo "setup.py version: $SETUP_PY_VERSION"
+          test "$CLIENT_VERSION" = "$SETUP_PY_VERSION"

clients/python/.gitignore

@@ -0,0 +1,147 @@
+# Created by https://www.toptal.com/developers/gitignore/api/python
+# Edit at https://www.toptal.com/developers/gitignore?templates=python
+
+### Python ###
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# End of https://www.toptal.com/developers/gitignore/api/python
+
+.moonstream-py/
+.venv/

clients/python/README.md

@@ -0,0 +1,13 @@
+# Moonstream Python client
+
+This is the Python client library for the Moonstream API.
+
+## Installation
+
+This library assumes you are using Python 3.6 or greater.
+
+Install using `pip`:
+
+```bash
+pip install moonstream
+```

clients/python/moonstream/client.py

@@ -0,0 +1,424 @@
+from dataclasses import dataclass, field
+import logging
+import os
+from typing import Any, Dict, List, Optional
+
+import requests
+
+logger = logging.getLogger(__name__)
+log_level = logging.INFO
+if os.environ.get("DEBUG", "").lower() in ["true", "1"]:
+    log_level = logging.DEBUG
+logger.setLevel(log_level)
+
+
+# Keep this synchronized with the version in setup.py
+CLIENT_VERSION = "0.0.2"
+
+ENDPOINT_PING = "/ping"
+ENDPOINT_VERSION = "/version"
+ENDPOINT_NOW = "/now"
+ENDPOINT_TOKEN = "/users/token"
+ENDPOINT_SUBSCRIPTIONS = "/subscriptions/"
+ENDPOINT_SUBSCRIPTION_TYPES = "/subscriptions/types"
+ENDPOINT_STREAMS = "/streams/"
+ENDPOINT_STREAMS_LATEST = "/streams/latest"
+ENDPOINT_STREAMS_NEXT = "/streams/next"
+ENDPOINT_STREAMS_PREVIOUS = "/streams/previous"
+
+ENDPOINTS = [
+    ENDPOINT_PING,
+    ENDPOINT_VERSION,
+    ENDPOINT_NOW,
+    ENDPOINT_TOKEN,
+    ENDPOINT_SUBSCRIPTIONS,
+    ENDPOINT_SUBSCRIPTION_TYPES,
+    ENDPOINT_STREAMS,
+    ENDPOINT_STREAMS_LATEST,
+    ENDPOINT_STREAMS_NEXT,
+    ENDPOINT_STREAMS_PREVIOUS,
+]
+
+
+def moonstream_endpoints(url: str) -> Dict[str, str]:
+    """
+    Creates a dictionary of Moonstream API endpoints at the given Moonstream API URL.
+    """
+    url_with_protocol = url
+    if not (
+        url_with_protocol.startswith("http://")
+        or url_with_protocol.startswith("https://")
+    ):
+        url_with_protocol = f"http://{url_with_protocol}"
+
+    normalized_url = url_with_protocol.rstrip("/")
+
+    return {endpoint: f"{normalized_url}{endpoint}" for endpoint in ENDPOINTS}
+
+
+class UnexpectedResponse(Exception):
+    """
+    Raised when a server response cannot be parsed into the appropriate/expected Python structure.
+    """
+
+
+class Unauthenticated(Exception):
+    """
+    Raised when a user tries to make a request that needs to be authenticated by they are not authenticated.
+    """
+
+
+@dataclass(frozen=True)
+class APISpec:
+    url: str
+    endpoints: Dict[str, str]
+
+
+class Moonstream:
+    """
+    A Moonstream client configured to communicate with a given Moonstream API server.
+    """
+
+    def __init__(
+        self,
+        url: str = "https://api.moonstream.to",
+        timeout: Optional[float] = None,
+    ):
+        """
+        Initializes a Moonstream API client.
+
+        Arguments:
+        url - Moonstream API URL. By default this points to the production Moonstream API at https://api.moonstream.to,
+        but you can replace it with the URL of any other Moonstream API instance.
+        timeout - Timeout (in seconds) for Moonstream API requests. Default is None, which means that
+        Moonstream API requests will never time out.
+
+        Returns: A Moonstream client.
+        """
+        endpoints = moonstream_endpoints(url)
+        self.api = APISpec(url=url, endpoints=endpoints)
+        self.timeout = timeout
+        self._session = requests.Session()
+        self._session.headers.update(
+            {"User-Agent": f"Moonstream Python client (version {CLIENT_VERSION})"}
+        )
+
+    def ping(self) -> Dict[str, Any]:
+        """
+        Checks that you have a connection to the Moonstream API.
+        """
+        r = self._session.get(self.api.endpoints[ENDPOINT_PING])
+        r.raise_for_status()
+        return r.json()
+
+    def version(self) -> Dict[str, Any]:
+        """
+        Gets the Moonstream API version information from the server.
+        """
+        r = self._session.get(self.api.endpoints[ENDPOINT_VERSION])
+        r.raise_for_status()
+        return r.json()
+
+    def server_time(self) -> float:
+        """
+        Gets the current time (as microseconds since the Unix epoch) on the server.
+        """
+        r = self._session.get(self.api.endpoints[ENDPOINT_NOW])
+        r.raise_for_status()
+        result = r.json()
+        raw_epoch_time = result.get("epoch_time")
+        if raw_epoch_time is None:
+            raise UnexpectedResponse(
+                f'Server response does not contain "epoch_time": {result}'
+            )
+
+        try:
+            epoch_time = float(raw_epoch_time)
+        except:
+            raise UnexpectedResponse(
+                f"Could not process epoch time as a float: {raw_epoch_time}"
+            )
+
+        return epoch_time
+
+    def authorize(self, access_token: str) -> None:
+        if not access_token:
+            logger.warning("Setting authorization header to empty token.")
+        self._session.headers.update({"Authorization": f"Bearer {access_token}"})
+
+    def requires_authorization(self):
+        if self._session.headers.get("Authorization") is None:
+            raise Unauthenticated(
+                'This method requires that you authenticate to the API, either by calling the "authorize" method with an API token or by calling the "login" method.'
+            )
+
+    def login(self, username: str, password: Optional[str] = None) -> str:
+        """
+        Authorizes this client to act as the given user when communicating with the Moonstream API.
+
+        To register an account on the production Moonstream API, go to https://moonstream.to.
+
+        Arguments:
+        username - Username of the user to authenticate as.
+        password - Optional password for the user. If this is not provided, you will be prompted for
+        the password.
+        """
+        if password is None:
+            password = input(f"Moonstream password for {username}: ")
+
+        r = self._session.post(
+            self.api.endpoints[ENDPOINT_TOKEN],
+            data={"username": username, "password": password},
+        )
+        r.raise_for_status()
+
+        token = r.json()
+        self.authorize(token["id"])
+        return token
+
+    def logout(self) -> None:
+        """
+        Logs the current user out of the Moonstream client.
+        """
+        self._session.delete(self.api.endpoints[ENDPOINT_TOKEN])
+        self._session.headers.pop("Authorization")
+
+    def subscription_types(self) -> Dict[str, Any]:
+        """
+        Gets the currently available subscription types on the Moonstream API.
+        """
+        r = self._session.get(self.api.endpoints[ENDPOINT_SUBSCRIPTION_TYPES])
+        r.raise_for_status()
+        return r.json()
+
+    def list_subscriptions(self) -> Dict[str, Any]:
+        """
+        Gets the currently authorized user's subscriptions from the API server.
+        """
+        self.requires_authorization()
+        r = self._session.get(self.api.endpoints[ENDPOINT_SUBSCRIPTIONS])
+        r.raise_for_status()
+        return r.json()
+
+    def create_subscription(
+        self, subscription_type: str, label: str, color: str, specifier: str = ""
+    ) -> Dict[str, Any]:
+        """
+        Creates a subscription.
+
+        Arguments:
+        subscription_type - The type of subscription you would like to create. To see the available subscription
+        types, call the "subscription_types" method on this Moonstream client. This argument must be
+        the "id" if the subscription type you want.
+        label - A label for the subscription. This will identify the subscription to you in your stream.
+        color - A hexadecimal color to associate with the subscription.
+        specifier - A specifier for the subscription, which must correspond to one of the choices in the
+        subscription type. This is optional because some subscription types do not require a specifier.
+
+        Returns: The subscription resource that was created on the backend.
+        """
+        self.requires_authorization()
+        r = self._session.post(
+            self.api.endpoints[ENDPOINT_SUBSCRIPTIONS],
+            data={
+                "subscription_type_id": subscription_type,
+                "label": label,
+                "color": color,
+                "address": specifier,
+            },
+        )
+        r.raise_for_status()
+        return r.json()
+
+    def delete_subscription(self, id: str) -> Dict[str, Any]:
+        """
+        Delete a subscription by ID.
+
+        Arguments:
+        id - ID of the subscription to delete.
+
+        Returns: The subscription resource that was deleted.
+        """
+        self.requires_authorization()
+        r = self._session.delete(f"{self.api.endpoints[ENDPOINT_SUBSCRIPTIONS]}{id}")
+        r.raise_for_status()
+        return r.json()
+
+    def update_subscription(
+        self, id: str, label: Optional[str] = None, color: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """
+        Update a subscription label or color.
+
+        Arguments:
+        label - New label for subscription (optional).
+        color - New color for subscription (optional).
+
+        Returns - If neither label or color are specified, raises a ValueError. Otherwise PUTs the updated
+        information to the server and returns the updated subscription resource.
+        """
+        if label is None and color is None:
+            raise ValueError(
+                "At least one of the arguments to this method should not be None."
+            )
+        self.requires_authorization()
+        data = {}
+        if label is not None:
+            data["label"] = label
+        if color is not None:
+            data["color"] = color
+
+        r = self._session.put(
+            f"{self.api.endpoints[ENDPOINT_SUBSCRIPTIONS]}{id}", data=data
+        )
+        r.raise_for_status()
+        return r.json()
+
+    def latest_events(self, q: str = "") -> List[Dict[str, Any]]:
+        """
+        Returns the latest events in your stream. You can optionally provide a query parameter to
+        constrain the query to specific subscription types or to specific subscriptions.
+
+        Arguments:
+        - q - Optional query (default is the empty string). The syntax to constrain to a particular
+        type of subscription is "type:<subscription_type>". For example, to get the latest event from
+        your Ethereum transaction pool subscriptions, you would use "type:ethereum_txpool".
+
+        Returns: A list of the latest events in your stream.
+        """
+        self.requires_authorization()
+        query_params: Dict[str, str] = {}
+        if q:
+            query_params["q"] = q
+        r = self._session.get(
+            self.api.endpoints[ENDPOINT_STREAMS_LATEST], params=query_params
+        )
+        r.raise_for_status()
+        return r.json()
+
+    def next_event(
+        self, end_time: int, include_end: bool = True, q: str = ""
+    ) -> Optional[Dict[str, Any]]:
+        """
+        Return the earliest event in your stream that occurred after the given end_time.
+
+        Arguments:
+        - end_time - Time after which you want to retrieve the earliest event from your stream.
+        - include_end - If True, the result is the first event that occurred in your stream strictly
+        *after* the end time. If False, then you will get the first event that occurred in your
+        stream *on* or *after* the end time.
+        - q - Optional query to filter over your available subscriptions and subscription types.
+
+        Returns: None if no event has occurred after the given end time, else returns a dictionary
+        representing that event.
+        """
+        self.requires_authorization()
+        query_params: Dict[str, Any] = {
+            "end_time": end_time,
+            "include_end": include_end,
+        }
+        if q:
+            query_params["q"] = q
+        r = self._session.get(
+            self.api.endpoints[ENDPOINT_STREAMS_NEXT], params=query_params
+        )
+        r.raise_for_status()
+        return r.json()
+
+    def previous_event(
+        self, start_time: int, include_start: bool = True, q: str = ""
+    ) -> Optional[Dict[str, Any]]:
+        """
+        Return the latest event in your stream that occurred before the given start_time.
+
+        Arguments:
+        - start_time - Time before which you want to retrieve the latest event from your stream.
+        - include_start - If True, the result is the last event that occurred in your stream strictly
+        *before* the start time. If False, then you will get the last event that occurred in your
+        stream *on* or *before* the start time.
+        - q - Optional query to filter over your available subscriptions and subscription types.
+
+        Returns: None if no event has occurred before the given start time, else returns a dictionary
+        representing that event.
+        """
+        self.requires_authorization()
+        query_params: Dict[str, Any] = {
+            "start_time": start_time,
+            "include_start": include_start,
+        }
+        if q:
+            query_params["q"] = q
+        r = self._session.get(
+            self.api.endpoints[ENDPOINT_STREAMS_PREVIOUS], params=query_params
+        )
+        r.raise_for_status()
+        return r.json()
+
+    def events(
+        self,
+        start_time: int,
+        end_time: int,
+        include_start: bool = False,
+        include_end: bool = False,
+        q: str = "",
+    ) -> Dict[str, Any]:
+        """
+        Return all events in your stream that occurred between the given start and end times.
+
+        Arguments:
+        - start_time - Time after which you want to query your stream.
+        - include_start - Whether or not events that occurred exactly at the start_time should be included in the results.
+        - end_time - Time before which you want to query your stream.
+        - include_end - Whether or not events that occurred exactly at the end_time should be included in the results.
+        - q - Optional query to filter over your available subscriptions and subscription types.
+
+        Returns: A dictionary representing the results of your query.
+        """
+        self.requires_authorization()
+        query_params: Dict[str, Any] = {
+            "start_time": start_time,
+            "include_start": include_start,
+            "end_time": end_time,
+            "include_end": include_end,
+        }
+        if q:
+            query_params["q"] = q
+
+        r = self._session.get(self.api.endpoints[ENDPOINT_STREAMS], params=query_params)
+        r.raise_for_status()
+        return r.json()
+
+
+def client_from_env() -> Moonstream:
+    """
+    Produces a Moonstream client instantiated using the following environment variables:
+    - MOONSTREAM_API_URL: Specifies the url parameter on the Moonstream client
+    - MOONSTREAM_TIMEOUT_SECONDS: Specifies the request timeout
+    - MOONSTREAM_ACCESS_TOKEN: If this environment variable is defined, the client sets this token as
+    the authorization header for all Moonstream API requests.
+    """
+    kwargs: Dict[str, Any] = {}
+
+    url = os.environ.get("MOONSTREAM_API_URL")
+    if url is not None:
+        kwargs["url"] = url
+
+    raw_timeout = os.environ.get("MOONSTREAM_TIMEOUT_SECONDS")
+    timeout: Optional[float] = None
+    if raw_timeout is not None:
+        try:
+            timeout = float(raw_timeout)
+        except:
+            raise ValueError(
+                f"Could not convert MOONSTREAM_TIMEOUT_SECONDS ({raw_timeout}) to float."
+            )
+
+    kwargs["timeout"] = timeout
+
+    moonstream_client = Moonstream(**kwargs)
+
+    access_token = os.environ.get("MOONSTREAM_ACCESS_TOKEN")
+    if access_token is not None:
+        moonstream_client.authorize(access_token)
+
+    return moonstream_client

clients/python/moonstream/test_client.py

@@ -0,0 +1,138 @@
+from dataclasses import FrozenInstanceError
+import os
+import unittest
+
+from . import client
+
+
+class TestMoonstreamClient(unittest.TestCase):
+    def test_client_init(self):
+        m = client.Moonstream()
+        self.assertEqual(m.api.url, "https://api.moonstream.to")
+        self.assertIsNone(m.timeout)
+        self.assertGreater(len(m.api.endpoints), 0)
+
+    def test_client_init_with_timeout(self):
+        timeout = 7
+        m = client.Moonstream(timeout=timeout)
+        self.assertEqual(m.api.url, "https://api.moonstream.to")
+        self.assertEqual(m.timeout, timeout)
+        self.assertGreater(len(m.api.endpoints), 0)
+
+    def test_client_with_custom_url_and_timeout(self):
+        timeout = 9
+        url = "https://my.custom.api.url"
+        m = client.Moonstream(url=url, timeout=timeout)
+        self.assertEqual(m.api.url, url)
+        self.assertEqual(m.timeout, timeout)
+        self.assertGreater(len(m.api.endpoints), 0)
+
+    def test_client_with_custom_messy_url_and_timeout(self):
+        timeout = 3.5
+        url = "https://my.custom.api.url/"
+        m = client.Moonstream(url=url, timeout=timeout)
+        self.assertEqual(m.api.url, url)
+        self.assertEqual(m.timeout, timeout)
+        self.assertGreater(len(m.api.endpoints), 0)
+
+    def test_client_with_custom_messy_url_no_protocol_and_timeout(self):
+        timeout = 5.5
+        url = "my.custom.api.url/"
+        m = client.Moonstream(url=url, timeout=timeout)
+        self.assertEqual(m.api.url, url)
+        self.assertEqual(m.timeout, timeout)
+        self.assertGreater(len(m.api.endpoints), 0)
+
+    def test_immutable_api_url(self):
+        m = client.Moonstream()
+        with self.assertRaises(FrozenInstanceError):
+            m.api.url = "lol"
+
+    def test_immutable_api_endpoints(self):
+        m = client.Moonstream()
+        with self.assertRaises(FrozenInstanceError):
+            m.api.endpoints = {}
+
+    def test_mutable_timeout(self):
+        original_timeout = 5.0
+        updated_timeout = 10.5
+        m = client.Moonstream(timeout=original_timeout)
+        self.assertEqual(m.timeout, original_timeout)
+        m.timeout = updated_timeout
+        self.assertEqual(m.timeout, updated_timeout)
+
+
+class TestMoonstreamClientFromEnv(unittest.TestCase):
+    def setUp(self):
+        self.old_moonstream_api_url = os.environ.get("MOONSTREAM_API_URL")
+        self.old_moonstream_timeout_seconds = os.environ.get(
+            "MOONSTREAM_TIMEOUT_SECONDS"
+        )
+        self.old_moonstream_access_token = os.environ.get("MOONSTREAM_ACCESS_TOKEN")
+
+        self.moonstream_api_url = "https://custom.example.com"
+        self.moonstream_timeout_seconds = 15.333333
+        self.moonstream_access_token = "1d431ca4-af9b-4c3a-b7b9-3cc79f3b0900"
+
+        os.environ["MOONSTREAM_API_URL"] = self.moonstream_api_url
+        os.environ["MOONSTREAM_TIMEOUT_SECONDS"] = str(self.moonstream_timeout_seconds)
+        os.environ["MOONSTREAM_ACCESS_TOKEN"] = self.moonstream_access_token
+
+    def tearDown(self) -> None:
+        del os.environ["MOONSTREAM_API_URL"]
+        del os.environ["MOONSTREAM_TIMEOUT_SECONDS"]
+        del os.environ["MOONSTREAM_ACCESS_TOKEN"]
+
+        if self.old_moonstream_api_url is not None:
+            os.environ["MOONSTREAM_API_URL"] = self.old_moonstream_api_url
+        if self.old_moonstream_timeout_seconds is not None:
+            os.environ[
+                "MOONSTREAM_TIMEOUT_SECONDS"
+            ] = self.old_moonstream_timeout_seconds
+        if self.old_moonstream_access_token is not None:
+            os.environ["MOONSTREAM_ACCESS_TOKEN"] = self.old_moonstream_access_token
+
+    def test_client_from_env(self):
+        m = client.client_from_env()
+        self.assertEqual(m.api.url, self.moonstream_api_url)
+        self.assertEqual(m.timeout, self.moonstream_timeout_seconds)
+        self.assertIsNone(m.requires_authorization())
+
+        authorization_header = m._session.headers["Authorization"]
+        self.assertEqual(authorization_header, f"Bearer {self.moonstream_access_token}")
+
+
+class TestMoonstreamEndpoints(unittest.TestCase):
+    def setUp(self):
+        self.url = "https://api.moonstream.to"
+        self.normalized_url = "https://api.moonstream.to"
+
+    def test_moonstream_endpoints(self):
+        endpoints = client.moonstream_endpoints(self.url)
+        self.assertDictEqual(
+            endpoints,
+            {
+                client.ENDPOINT_PING: f"{self.normalized_url}{client.ENDPOINT_PING}",
+                client.ENDPOINT_VERSION: f"{self.normalized_url}{client.ENDPOINT_VERSION}",
+                client.ENDPOINT_NOW: f"{self.normalized_url}{client.ENDPOINT_NOW}",
+                client.ENDPOINT_TOKEN: f"{self.normalized_url}{client.ENDPOINT_TOKEN}",
+                client.ENDPOINT_SUBSCRIPTION_TYPES: f"{self.normalized_url}{client.ENDPOINT_SUBSCRIPTION_TYPES}",
+                client.ENDPOINT_SUBSCRIPTIONS: f"{self.normalized_url}{client.ENDPOINT_SUBSCRIPTIONS}",
+                client.ENDPOINT_STREAMS: f"{self.normalized_url}{client.ENDPOINT_STREAMS}",
+                client.ENDPOINT_STREAMS_LATEST: f"{self.normalized_url}{client.ENDPOINT_STREAMS_LATEST}",
+                client.ENDPOINT_STREAMS_NEXT: f"{self.normalized_url}{client.ENDPOINT_STREAMS_NEXT}",
+                client.ENDPOINT_STREAMS_PREVIOUS: f"{self.normalized_url}{client.ENDPOINT_STREAMS_PREVIOUS}",
+            },
+        )
+
+
+class TestMoonstreamEndpointsMessyURL(TestMoonstreamEndpoints):
+    def setUp(self):
+        self.url = "https://api.moonstream.to/"
+        self.normalized_url = "https://api.moonstream.to"
+
+
+class TestMoonstreamEndpointsMessyURLWithNoProtocol(TestMoonstreamEndpoints):
+    def setUp(self):
+        self.url = "api.moonstream.to/"
+        self.normalized_url = "http://api.moonstream.to"

clients/python/setup.py

@@ -0,0 +1,35 @@
+from setuptools import find_packages, setup
+
+long_description = ""
+with open("README.md") as ifp:
+    long_description = ifp.read()
+
+setup(
+    name="moonstream",
+    version="0.0.2",
+    packages=find_packages(),
+    package_data={"moonstream": ["py.typed"]},
+    install_requires=["requests", "dataclasses; python_version=='3.6'"],
+    extras_require={
+        "dev": [
+            "black",
+            "mypy",
+            "wheel",
+            "types-requests",
+            "types-dataclasses",
+        ],
+        "distribute": ["setuptools", "twine", "wheel"],
+    },
+    description="Moonstream: Open source blockchain analytics",
+    long_description=long_description,
+    long_description_content_type="text/markdown",
+    author="Moonstream",
+    author_email="engineering@moonstream.to",
+    classifiers=[
+        "Development Status :: 3 - Alpha",
+        "Programming Language :: Python",
+        "License :: OSI Approved :: Apache Software License",
+        "Topic :: Software Development :: Libraries",
+    ],
+    url="https://github.com/bugout-dev/moonstream",
+)

clients/python/tag.bash

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+set -e
+TAG="clients/python/v$(python setup.py --version)"
+read -r -p "Tag: $TAG -- tag and push (y/n)?" ACCEPT
+if [ "$ACCEPT" = "y" ]
+then
+  echo "Tagging and pushing: $TAG..."
+  git tag "$TAG"
+  git push upstream "$TAG"
+else
+  echo "noop"
+fi