Released v1.1.0.

Author: mentix02

.gitignore

@@ -3,6 +3,9 @@ __pycache__/
 *.py[cod]
 *$py.class
 
+# IDE files
+.idea/
+
 # C extensions
 *.so
 

README.md

@@ -0,0 +1,63 @@
+# HellPy
+
+HellPy is a connector for HellDB - a key value store database.
+
+## Installation
+
+Install it using pip.
+
+```shell script
+$ pip install hellpy
+```
+
+## Documentation
+
+### Initialize
+
+```python
+from hellpy import Store
+
+store = Store()
+
+# To connect to different service.
+remote = Store(port=5555, host='222.31.43.43')
+```
+
+### PUT
+
+Writes using a PUT call to the HellDB instance store connected to.
+
+```python
+store.put('age', 18)
+store.put('name', 'Manan')
+store.put('posts', [1, 2, 'not found'])
+store.put('bitmap', [
+    [False, False, True],
+    [False, True, False],
+    [True, False, False],
+])
+```
+
+### GET
+
+Reads using a GET call.
+
+```python
+store.get('name')
+# returns ["Manan"]
+store.get('name', 'age')
+# returns ["Manan", 18]
+store.get('invalid_key')
+# returns [None]
+```
+
+### DEL
+
+Deletes pair using a DEL call
+
+```python
+store.delete('name', 'age')
+# returns [{'bool': True}, {'bool': True}]
+store.delete('invalid_key')
+# returns [{'bool': False}]
+```

hellpy/__init__.py

@@ -0,0 +1 @@
+from hellpy.store import Store

hellpy/exceptions.py

@@ -0,0 +1,10 @@
+class Error(Exception):
+    pass
+
+
+class InvalidTypeError(Error):
+    pass
+
+
+class InvalidArgumentError(Error):
+    pass

hellpy/requests.py

@@ -0,0 +1,30 @@
+from typing import List
+
+import logging
+import urllib.parse
+import urllib.request
+
+from .tokens import ILLEGAL
+from hellpy.structures import Statement
+
+
+def get(url: str) -> str:
+    try:
+        with urllib.request.urlopen(url) as r:
+            return r.read().decode('utf-8')
+    except Exception as e:
+        logging.error(e)
+        return ILLEGAL
+
+
+def post(url: str, queries: List[Statement]) -> str:
+    values = {'query': '\n'.join(map(str, queries))}
+    data = urllib.parse.urlencode(values)
+    data = data.encode('ascii')
+    req = urllib.request.Request(url, data)
+    try:
+        with urllib.request.urlopen(req) as r:
+            return r.read().decode('utf-8')
+    except Exception as e:
+        logging.error(e)
+        return ILLEGAL

hellpy/store.py

@@ -0,0 +1,91 @@
+from typing import List
+
+import json
+import logging
+
+from hellpy import requests
+from hellpy.structures import (
+    BaseType,
+    UrlBuilder,
+    GetStatement,
+    PutStatement,
+    DelStatement,
+)
+
+
+class Store(object):
+    """
+    Store is the main connector for HellDB from where all the
+    reads and writes take place using an API designed to replicate
+    the syntax of Latin, the query language developed for HellDB.
+    """
+
+    def __init__(self, port: int = 8080, host: str = '127.0.0.1'):
+
+        """ Constructor for Store to build HellDB's url. """
+
+        self.url: str = f'http://{host}:{port}'
+        self.url_store: UrlBuilder = UrlBuilder(self.url)
+
+        if not self.ok():
+            logging.fatal(f"cannot connect to HellDB instance on {self.url}")
+
+    @staticmethod
+    def extract(resp_text: str) -> List[BaseType]:
+
+        """ Helper method to return response's BaseType list generically. """
+
+        response = json.loads(resp_text)
+        if len(response['errors']) != 0:
+            logging.fatal('\n'.join(response['errors']))
+        else:
+            return response['results'][0]
+
+    def ok(self) -> bool:
+
+        """ Checks whether HellDB is running healthy. """
+
+        resp = requests.get(self.url_store.status_url)
+        return resp == "ok"
+
+    def get(self, *keys: str) -> List[BaseType]:
+
+        """ GET api for reading keys. """
+
+        get_statement = GetStatement(*keys)
+        return Store.extract(
+            requests.post(
+                self.url_store.query_url,
+                [get_statement],
+            ),
+        )
+
+    def delete(self, *keys: str) -> List[BaseType]:
+
+        """ DEL api for deleting key value pairs. """
+
+        del_statement = DelStatement(*keys)
+        return Store.extract(
+            requests.post(
+                self.url_store.query_url,
+                [del_statement],
+            )
+        )
+
+    def put(self, key: str, value: BaseType) -> List[BaseType]:
+
+        """ PUT api for writing value to a key. """
+
+        put_statement = PutStatement(key, value)
+        return Store.extract(
+            requests.post(
+                self.url_store.query_url,
+                [put_statement],
+            )
+        )
+
+    def __len__(self) -> int:
+
+        """ Gets number of key-value pairs in HellDB. """
+
+        return int(requests.get(self.url_store.length_url))

hellpy/structures/__init__.py

@@ -0,0 +1,4 @@
+from .types import *
+from .builders import *
+from .response import *
+from .statements import *

hellpy/structures/builders.py

@@ -0,0 +1,28 @@
+import json
+
+from hellpy.utils import valid_type
+from hellpy.structures import BaseType
+from hellpy.exceptions import InvalidTypeError
+
+
+class Builder(object):
+    pass
+
+
+class UrlBuilder(Builder):
+    def __init__(self, base_url: str) -> None:
+        self.query_url = f'{base_url}/query'
+        self.status_url = f'{base_url}/status'
+        self.length_url = f'{base_url}/length'
+
+
+class KeyValueBuilder(Builder):
+    @staticmethod
+    def keys_string(*keys: str) -> str:
+        return ' & '.join(keys)
+
+    @staticmethod
+    def value_string(value: BaseType) -> str:
+        if not valid_type(value):
+            raise InvalidTypeError(f'invalid type "{type(value)}" provided')
+        return json.dumps(value)

hellpy/structures/response.py

@@ -0,0 +1,62 @@
+import abc
+
+from hellpy.tokens import *
+from hellpy.structures import BaseType
+from hellpy.structures import KeyValueBuilder
+from hellpy.exceptions import InvalidArgumentError
+
+
+class Statement(abc.ABC):
+
+    """ A generic Statement class modelled after HellDB's statement interface. """
+
+    @property
+    @abc.abstractmethod
+    def token(self) -> str:
+        pass
+
+    @abc.abstractmethod
+    def __str__(self) -> str:
+        pass
+
+
+class GetStatement(Statement):
+    def __init__(self, *keys: str):
+        if len(keys) == 0:
+            raise InvalidArgumentError('at least one key required to read')
+        self.keys = keys
+
+    @property
+    def token(self) -> str:
+        return GET
+
+    def __str__(self) -> str:
+        keys_str = " & ".join(self.keys)
+        return f'{self.token} {keys_str};'
+
+
+class DelStatement(Statement):
+    def __init__(self, *keys: str):
+        if len(keys) == 0:
+            raise InvalidArgumentError('at least one key required to delete')
+        self.keys_string = KeyValueBuilder.keys_string(*keys)
+
+    @property
+    def token(self) -> str:
+        return DEL
+
+    def __str__(self) -> str:
+        return f'{self.token} {self.keys_string};'
+
+
+class PutStatement(Statement):
+    def __init__(self, key: str, value: BaseType):
+        self.key = key
+        self.value_string: str = KeyValueBuilder.value_string(value)
+
+    @property
+    def token(self) -> str:
+        return PUT
+
+    def __str__(self) -> str:
+        return f'{self.token} {self.key} {self.value_string};'