Feature: full API refactoring (#2)

* Internal: user session class

Problem: we often pass 2-3 objects to each function that represent
information on how to connect to the Aleph network:

* the user account
* the API server URL
* the aiohttp session.

This can be simplified to improve the user experience and reduce
the complexity of the SDK.

Solution: introduce a new state class: `UserSession`. This object
is now passed as the first parameter of every public function.
It is initialized with the user account and the API server URL.
It is in charge of configuring and managing the aiohttp session object.

The typical usage of the library now looks like this:

```
account = load_my_account()
api_server = "https://aleph.cloud"  # example
async with UserSession(account=account, api_server=api_server) as session:
  message, status = await create_post(
    session=session,
    ...
  )
```

This enables the following improvements:

* Less clutter in function signatures: all public SDK functions now
  have 1 or 2 fewer arguments.
* The API server URL is now managed when initializing the aiohttp
  session inside the user session object. Implementations can
  simply specify the endpoint URL. Ex:
  `f"{api_server}/api/v0/messages.json` can now be expressed
  as `"/api/v0/messages.json"`.

Breaking changes:

* The signatures of all public functions of the SDK have been
  modified. The user must now initialize the user session object
  and pass it as parameter.

* UserSession + AuthenticatedUserSession

* Feature: full API refactoring

The session classes now provide all the SDK functionalities.
The `synchronous` and `asynchronous` modules are removed in
favor of the `UserSession` and `AuthenticatedUserSession` classes.

`UserSession` is intended as a read-only session to access public
API endpoints, while `AuthenticatedUserSession` requires a chain
account and allows the user to post messages to the Aleph network.

Example usage:

```
from aleph_client import AuthenticatedUserSession

async def post_message():
  async with AuthenticatedUserSession(
    account=fixture_account, api_server=emitter_node
  ) as session:
    post_message, message_status = await session.create_post(
      post_content={"Hello": "World"},
    )
```

Both classes provide a synchronous context manager and an equivalent
sync class for non-async code.

Breaking changes:
- Everything: the SDK API is entirely modified.

Author: odesenfans

examples/httpgateway.py

@@ -2,22 +2,14 @@
 """
 # -*- coding: utf-8 -*-
 
-import os
-
-# import requests
-import platform
-
-# import socket
-import time
 import asyncio
+
 import click
-from aleph_client.asynchronous import create_post
+from aiohttp import web
 
-# from aleph_client.chains.nuls1 import NULSAccount, get_fallback_account
-from aleph_client.chains.ethereum import ETHAccount
 from aleph_client.chains.common import get_fallback_private_key
-
-from aiohttp import web
+from aleph_client.chains.ethereum import ETHAccount
+from aleph_client.user_session import AuthenticatedUserSession
 
 app = web.Application()
 routes = web.RouteTableDef()
@@ -42,13 +34,14 @@ async def source_post(request):
             return web.json_response(
                 {"status": "error", "message": "unauthorized secret"}
             )
-    message, _status = await create_post(
-        app["account"],
-        data,
-        "event",
-        channel=app["channel"],
-        api_server="https://api2.aleph.im",
-    )
+    async with AuthenticatedUserSession(
+        account=app["account"], api_server="https://api2.aleph.im"
+    ) as session:
+        message, _status = await session.create_post(
+            post_content=data,
+            post_type="event",
+            channel=app["channel"],
+        )
 
     return web.json_response({"status": "success", "item_hash": message.item_hash})
 

examples/metrics.py

@@ -5,11 +5,16 @@
 import os
 import platform
 import time
+from typing import Tuple
 
 import psutil
+from aleph_message.models import AlephMessage
 
+from aleph_client import AuthenticatedUserSession
 from aleph_client.chains.ethereum import get_fallback_account
-from aleph_client.synchronous import create_aggregate
+from aleph_client.conf import settings
+from aleph_client.types import MessageStatus
+from aleph_client.user_session import AuthenticatedUserSessionSync
 
 
 def get_sysinfo():
@@ -49,8 +54,10 @@ def get_cpu_cores():
     return [c._asdict() for c in psutil.cpu_times_percent(0, percpu=True)]
 
 
-def send_metrics(account, metrics):
-    return create_aggregate(account, "metrics", metrics, channel="SYSINFO")
+def send_metrics(
+    session: AuthenticatedUserSessionSync, metrics
+) -> Tuple[AlephMessage, MessageStatus]:
+    return session.create_aggregate(key="metrics", content=metrics, channel="SYSINFO")
 
 
 def collect_metrics():
@@ -64,11 +71,14 @@ def collect_metrics():
 
 def main():
     account = get_fallback_account()
-    while True:
-        metrics = collect_metrics()
-        message, status = send_metrics(account, metrics)
-        print("sent", message.item_hash)
-        time.sleep(10)
+    with AuthenticatedUserSession(
+        account=account, api_server=settings.API_HOST
+    ) as session:
+        while True:
+            metrics = collect_metrics()
+            message, status = send_metrics(session, metrics)
+            print("sent", message.item_hash)
+            time.sleep(10)
 
 
 if __name__ == "__main__":

examples/mqtt.py

@@ -10,7 +10,8 @@
 
 from aleph_client.chains.common import get_fallback_private_key
 from aleph_client.chains.ethereum import ETHAccount
-from aleph_client.main import create_aggregate
+from aleph_client import AuthenticatedUserSession
+from aleph_client.conf import settings
 
 
 def get_input_data(value):
@@ -26,7 +27,12 @@ def get_input_data(value):
 
 
 def send_metrics(account, metrics):
-    return create_aggregate(account, "metrics", metrics, channel="SYSINFO")
+    with AuthenticatedUserSession(
+        account=account, api_server=settings.API_HOST
+    ) as session:
+        return session.create_aggregate(
+            key="metrics", content=metrics, channel="SYSINFO"
+        )
 
 
 def on_disconnect(client, userdata, rc):
@@ -95,10 +101,15 @@ async def gateway(
         if not userdata["received"]:
             await client.reconnect()
 
-        for key, value in state.items():
-            message, status = create_aggregate(account, key, value, channel="IOT_TEST")
-            print("sent", message.item_hash)
-            userdata["received"] = False
+        async with AuthenticatedUserSession(
+            account=account, api_server=settings.API_HOST
+        ) as session:
+            for key, value in state.items():
+                message, status = await session.create_aggregate(
+                    key=key, content=value, channel="IOT_TEST"
+                )
+                print("sent", message.item_hash)
+                userdata["received"] = False
 
 
 @click.command()

examples/store.py

@@ -1,13 +1,13 @@
 import asyncio
 
-import aiohttp
 import click
 from aleph_message.models import StoreMessage
 
-from aleph_client.asynchronous import create_store
 from aleph_client.chains.common import get_fallback_private_key
 from aleph_client.chains.ethereum import ETHAccount
+from aleph_client.conf import settings
 from aleph_client.types import MessageStatus
+from aleph_client.user_session import AuthenticatedUserSession
 
 DEFAULT_SERVER = "https://api2.aleph.im"
 
@@ -23,7 +23,9 @@ async def print_output_hash(message: StoreMessage, status: MessageStatus):
 
 
 async def do_upload(account, engine, channel, filename=None, file_hash=None):
-    async with aiohttp.ClientSession() as session:
+    async with AuthenticatedUserSession(
+        account=account, api_server=settings.API_HOST
+    ) as session:
         print(filename, account.get_address())
         if filename:
             try:
@@ -33,24 +35,20 @@ async def do_upload(account, engine, channel, filename=None, file_hash=None):
                     if len(content) > 4 * 1024 * 1024 and engine == "STORAGE":
                         print("File too big for native STORAGE engine")
                         return
-                    message, status = await create_store(
-                        account,
+                    message, status = await session.create_store(
                         file_content=content,
                         channel=channel,
                         storage_engine=engine.lower(),
-                        session=session,
                     )
             except IOError:
                 print("File not accessible")
                 raise
 
         elif file_hash:
-            message, status = await create_store(
-                account,
+            message, status = await session.create_store(
                 file_hash=file_hash,
                 channel=channel,
                 storage_engine=engine.lower(),
-                session=session,
             )
 
         await print_output_hash(message, status)

setup.cfg

@@ -60,6 +60,7 @@ testing =
     pytest
     pytest-cov
     pytest-asyncio
+    pytest-mock
     mypy
     secp256k1
     pynacl
@@ -69,6 +70,7 @@ testing =
     httpx
     requests
     aleph-pytezos==0.1.0
+    types-certifi
     types-setuptools
     black
 mqtt =

src/aleph_client/__init__.py

@@ -1,4 +1,5 @@
 from pkg_resources import get_distribution, DistributionNotFound
+from .user_session import AuthenticatedUserSession, UserSession
 
 try:
     # Change here if project is renamed and does not equal the package name
@@ -8,3 +9,6 @@
     __version__ = "unknown"
 finally:
     del get_distribution, DistributionNotFound
+
+
+__all__ = ["AuthenticatedUserSession", "UserSession"]