async

Author: vvaezian

CHANGELOG.md

@@ -1,3 +1,9 @@
+## 3.5
+### Added
+- Asynchronous API support using `aiohttp`
+- New class `Metabase_API_Async` for async operations
+- Async versions of core API methods
+
 ## 3.4.5.1
 ### Changed
 - Fix [#59](https://github.com/vvaezian/metabase_api_python/issues/59)

README.md

@@ -19,11 +19,40 @@ mb = Metabase_API('https://...', 'username', 'password')  # if password is not g
 # authentication using API key
 mb = Metabase_API('https://...', api_key='YOUR_API_KEY')
 ```
+
+## Asynchronous Usage
+The library now supports asynchronous operations using `aiohttp`:
+
+```python
+import asyncio
+from metabase_api import Metabase_API_Async
+
+async def main():
+    # authentication using username/password
+    mb_async = Metabase_API_Async('https://...', 'username', 'password')
+    
+    # authentication using API key
+    # mb_async = Metabase_API_Async('https://...', api_key='YOUR_API_KEY')
+    
+    # Get data from a card
+    data = await mb_async.get_card_data_async(card_id=123)
+    print(data)
+    
+    # Search for items
+    search_results = await mb_async.search_async('query_term')
+    print(search_results)
+
+# Run the async function
+asyncio.run(main())
+```
+
 ## Functions
 ### REST functions (get, post, put, delete)
 Calling Metabase API endpoints (documented [here](https://github.com/metabase/metabase/blob/master/docs/api-documentation.md)) can be done using the corresponding REST function in the wrapper.  
 E.g. to call the [endpoint](https://github.com/metabase/metabase/blob/master/docs/api-documentation.md#get-apidatabase) `GET /api/database/`, use `mb.get('/api/database/')`.
 
+For async operations, use `await mb_async.get('/api/database/')`.
+
 ### Helper Functions
 You usually don't need to deal with these functions directly (e.g. [get_item_info](https://github.com/vvaezian/metabase_api_python/blob/77ef837972bc169f96a3ca520da769e0b933e8a8/metabase_api/metabase_api.py#L89), [get_item_id](https://github.com/vvaezian/metabase_api_python/blob/77ef837972bc169f96a3ca520da769e0b933e8a8/metabase_api/metabase_api.py#L128), [get_item_name](https://github.com/vvaezian/metabase_api_python/blob/77ef837972bc169f96a3ca520da769e0b933e8a8/metabase_api/metabase_api.py#L116))
 

metabase_api/__init__.py

@@ -1 +1,2 @@
 from .metabase_api import Metabase_API
+from .metabase_api_async import Metabase_API_Async

metabase_api/_helper_methods_async.py

@@ -0,0 +1,120 @@
+async def get_item_info(self, item_type, item_id=None, item_name=None,
+                            collection_id=None, collection_name=None,
+                            params=None):
+    """Async version of get_item_info"""
+    assert item_type in ['database', 'table', 'card', 'collection', 'dashboard', 'pulse', 'segment']
+
+    if params:
+        assert type(params) == dict
+
+    if not item_id:
+        if not item_name:
+            raise ValueError(f'Either the name or id of the {item_type} must be provided.')
+        item_id = await self.get_item_id(item_type, item_name, collection_id=collection_id, collection_name=collection_name)
+
+    res = await self.get(f"/api/{item_type}/{item_id}", params=params)
+    if res:
+        return res
+    else:
+        raise ValueError(f'There is no {item_type} with the id "{item_id}"')
+
+
+
+async def get_item_name(self, item_type, item_id):
+    """Async version of get_item_name"""
+    assert item_type in ['database', 'table', 'card', 'collection', 'dashboard', 'pulse', 'segment']
+
+    res = await self.get(f"/api/{item_type}/{item_id}")
+    if res:
+        return res['name']
+    else:
+        raise ValueError(f'There is no {item_type} with the id "{item_id}"')
+
+
+
+async def get_item_id(self, item_type, item_name, collection_id=None, collection_name=None, db_id=None, db_name=None, table_id=None):
+    """Async version of get_item_id"""
+    assert item_type in ['database', 'table', 'card', 'collection', 'dashboard', 'pulse', 'segment']
+
+    if item_type in ['card', 'dashboard', 'pulse']:
+        if not collection_id:
+            if not collection_name:
+                # Collection name/id is not provided. Searching in all collections 
+                items = await self.get(f"/api/{item_type}/")
+                item_IDs = [i['id'] for i in items if i['name'] == item_name and i['archived'] == False]
+            else:
+                collection_id = await self.get_item_id('collection', collection_name) if collection_name != 'root' else None
+                items = await self.get(f"/api/{item_type}/")
+                item_IDs = [i['id'] for i in items if i['name'] == item_name 
+                            and i['collection_id'] == collection_id 
+                            and i['archived'] == False]
+        else:
+            collection_name = await self.get_item_name('collection', collection_id)
+            items = await self.get(f"/api/{item_type}/")
+            item_IDs = [i['id'] for i in items if i['name'] == item_name 
+                        and i['collection_id'] == collection_id 
+                        and i['archived'] == False]
+
+        if len(item_IDs) > 1:
+            if not collection_name:
+                raise ValueError(f'There is more than one {item_type} with the name "{item_name}".\n\
+                        Provide collection id/name to limit the search space')
+            raise ValueError(f'There is more than one {item_type} with the name "{item_name}" in the collection "{collection_name}"')
+        if len(item_IDs) == 0:
+            if not collection_name:
+                    raise ValueError(f'There is no {item_type} with the name "{item_name}"')
+            raise ValueError(f'There is no item with the name "{item_name}" in the collection "{collection_name}"')
+
+        return item_IDs[0]
+
+    if item_type == 'collection':
+        collections = await self.get("/api/collection/")
+        collection_IDs = [i['id'] for i in collections if i['name'] == item_name]
+
+        if len(collection_IDs) > 1:
+            raise ValueError(f'There is more than one collection with the name "{item_name}"')
+        if len(collection_IDs) == 0:
+            raise ValueError(f'There is no collection with the name "{item_name}"')
+
+        return collection_IDs[0]
+
+    if item_type == 'database':
+        res = await self.get("/api/database/")
+        if type(res) == dict:  # in Metabase version *.40.0 the format of the returned result for this endpoint changed
+            res = res['data']
+        db_IDs = [i['id'] for i in res if i['name'] == item_name]
+
+        if len(db_IDs) > 1:
+            raise ValueError(f'There is more than one DB with the name "{item_name}"')
+        if len(db_IDs) == 0:
+            raise ValueError(f'There is no DB with the name "{item_name}"')
+
+        return db_IDs[0]
+
+    if item_type == 'table':
+        tables = await self.get("/api/table/")
+
+        if db_id:
+            table_IDs = [i['id'] for i in tables if i['name'] == item_name and i['db']['id'] == db_id]
+        elif db_name:
+            table_IDs = [i['id'] for i in tables if i['name'] == item_name and i['db']['name'] == db_name]
+        else:
+            table_IDs = [i['id'] for i in tables if i['name'] == item_name]
+
+        if len(table_IDs) > 1:
+            raise ValueError(f'There is more than one table with the name {item_name}. Provide db id/name.')
+        if len(table_IDs) == 0:
+            raise ValueError(f'There is no table with the name "{item_name}" (in the provided db, if any)')
+
+        return table_IDs[0]
+
+    if item_type == 'segment':
+        segments = await self.get("/api/segment/")
+        segment_IDs = [i['id'] for i in segments if i['name'] == item_name and (not table_id or i['table_id'] == table_id)]
+        
+        if len(segment_IDs) > 1:
+            raise ValueError(f'There is more than one segment with the name "{item_name}"')
+        if len(segment_IDs) == 0:
+            raise ValueError(f'There is no segment with the name "{item_name}"')
+
+        return segment_IDs[0]

metabase_api/_rest_methods_async.py

@@ -0,0 +1,72 @@
+import aiohttp
+
+async def get(self, endpoint, *args, **kwargs):
+    """Async version of GET request"""
+    await self.validate_session_async()
+    auth = aiohttp.BasicAuth(self.email, self.password) if self.auth else None
+    
+    async with aiohttp.ClientSession() as session:
+        async with session.get(
+            self.domain + endpoint, 
+            headers=self.header, 
+            auth=auth,
+            **kwargs
+        ) as res:
+            if 'raw' in args:
+                return res
+            else:
+                return await res.json() if res.status == 200 else False
+
+
+async def post(self, endpoint, *args, **kwargs):
+    """Async version of POST request"""
+    await self.validate_session_async()
+    auth = aiohttp.BasicAuth(self.email, self.password) if self.auth else None
+    
+    async with aiohttp.ClientSession() as session:
+        async with session.post(
+            self.domain + endpoint, 
+            headers=self.header, 
+            auth=auth,
+            **kwargs
+        ) as res:
+            if 'raw' in args:
+                return res
+            else:
+                return await res.json() if res.status == 200 else False
+
+
+async def put(self, endpoint, *args, **kwargs):
+    """Async version of PUT request for updating objects"""
+    await self.validate_session_async()
+    auth = aiohttp.BasicAuth(self.email, self.password) if self.auth else None
+    
+    async with aiohttp.ClientSession() as session:
+        async with session.put(
+            self.domain + endpoint, 
+            headers=self.header, 
+            auth=auth,
+            **kwargs
+        ) as res:
+            if 'raw' in args:
+                return res
+            else:
+                return res.status
+
+
+async def delete(self, endpoint, *args, **kwargs):
+    """Async version of DELETE request"""
+    await self.validate_session_async()
+    auth = aiohttp.BasicAuth(self.email, self.password) if self.auth else None
+    
+    async with aiohttp.ClientSession() as session:
+        async with session.delete(
+            self.domain + endpoint, 
+            headers=self.header, 
+            auth=auth,
+            **kwargs
+        ) as res:
+            if 'raw' in args:
+                return res
+            else:
+                return res.status