Merge pull request #16 from dragonchain/master

Release 4.2.0

Author: cheeseandcereal

docs/changelog.rst

@@ -1,6 +1,17 @@
 Changelog
 =========
 
+4.2.0
+-----
+
+Features:
+  * Add api key permissioning support
+Documentation:
+  * Modify various client function docstrings to be more accurate
+Development:
+  * Add integration tests for api key permissions
+  * Modify run.sh to only act on code in dragonchain_sdk and tests
+
 4.1.0
 -----
 

dragonchain_sdk/__init__.py

@@ -16,7 +16,7 @@
 from dragonchain_sdk import dragonchain_client
 
 __author__ = "Dragonchain, Inc."
-__version__ = "4.1.0"
+__version__ = "4.2.0"
 
 ASYNC_SUPPORT = False
 

dragonchain_sdk/dragonchain_client.py

@@ -19,7 +19,7 @@
 logger = logging.getLogger(__name__)
 
 if TYPE_CHECKING:
-    from dragonchain_sdk.types import request_response, custom_index_fields_type  # noqa: F401 used by typing
+    from dragonchain_sdk.types import request_response, custom_index_fields_type, permissions_doc  # noqa: F401 used by typing
 
 
 class Client(object):
@@ -549,40 +549,67 @@ def list_api_keys(self) -> "request_response":
         """
         return self.request.get("/v1/api-key")
 
-    def create_api_key(self, nickname: Optional[str] = None) -> "request_response":
+    def create_api_key(self, nickname: Optional[str] = None, permissions_document: Optional["permissions_doc"] = None) -> "request_response":
         """Generate a new HMAC API key
 
+        Args:
+            nickname (str, optional): The nickname to give to this new api key
+            permissions_document (dict, optional): The permissions dictionary to use with this key.
+                Check `the dragonchain core docs <https://dragonchain-core-docs.dragonchain.com/latest/usage/permissioning.html>`_ for more details
+
         Returns:
-            A new API key ID and key
+            The newly created api key
         """
-        body = {}
+        body = cast(Dict[str, Any], {})
         if nickname:
             if not isinstance(nickname, str):
                 raise TypeError('Parameter "nickname" must be of type str.')
-            body.update({"nickname": nickname})
+            body["nickname"] = nickname
+        if permissions_document:
+            if not isinstance(permissions_document, dict):
+                raise TypeError('Parameter "permissions_document" must be of type dict.')
+            body["permissions_document"] = permissions_document
         return self.request.post("/v1/api-key", body)
 
     def delete_api_key(self, key_id: str) -> "request_response":
         """Delete an existing HMAC API key
 
+        Args:
+            key_id (str): The id of the api key to delete
+
         Returns:
-            204 No Content on success
+            Generic success message
         """
         if not isinstance(key_id, str):
             raise TypeError('Parameter "key_id" must be of type str.')
         return self.request.delete("/v1/api-key/{}".format(key_id))
 
-    def update_api_key(self, key_id: str, nickname: str) -> "request_response":
+    def update_api_key(
+        self, key_id: str, nickname: Optional[str] = None, permissions_document: Optional["permissions_doc"] = None
+    ) -> "request_response":
         """Update the nickname of an existing HMAC API key
 
+        Args:
+            key_id (str): The id of the key to update
+            nickname (str, optional): The nickname to set on this api key
+            permissions_document (dict, optional): The permissions dictionary to set with this key.
+                Check `the dragonchain core docs <https://dragonchain-core-docs.dragonchain.com/latest/usage/permissioning.html>`_ for more details
+
         Returns:
-            success: True
+            The updated api key
         """
         if not isinstance(key_id, str):
             raise TypeError('Parameter "key_id" must be of type str.')
-        if not isinstance(nickname, str):
-            raise TypeError('Parameter "nickname" must be of type str.')
-        return self.request.put("/v1/api-key/{}".format(key_id), {"nickname": nickname})
+        body = cast(Dict[str, Any], {})
+        if nickname:
+            if not isinstance(nickname, str):
+                raise TypeError('Parameter "nickname" must be of type str.')
+            body["nickname"] = nickname
+        if permissions_document:
+            if not isinstance(permissions_document, dict):
+                raise TypeError('Parameter "permissions_document" must be of type dict.')
+            body["permissions_document"] = permissions_document
+        return self.request.put("/v1/api-key/{}".format(key_id), body)
 
     def get_smart_contract_object(self, key: str, smart_contract_id: Optional[str] = None) -> "request_response":
         """Retrieve data from the object storage of a smart contract
@@ -663,23 +690,25 @@ def create_transaction_type(
     ) -> "request_response":
         """Creates a new custom transaction type.
 
-        Transaction Types can optionally link custom search index fields to your transactions for easier querying later.
-        A custom_index_field is a dictionary with 'path', 'field_name', 'type', and an optional 'options' dictionary:
-
-        path (str): the JSONPath of your transaction payload you would like to result form a search on the "key".
-        field_name (str): The field for this custom extracted value to be indexed under
-        type ('text', 'tag', or 'number'): The type of redisearch index to use for this field
-        options: (object) The redisearch options for this field
-        - no_index (bool) (all types) whether or not to index on this field, or simply make it sortable only if false
-        - separator (str) (tag only) what string should be used for the tag separator
-        - weight (number) (text only) The weight to give this text field when doing text queries
-        - no_stem (bool) (text only) Whether or not to allow search stemming in text searches on this field
-        - sortable (bool) (text and number only) Whether or not a search on the index can be sortable by this field
-        See redisearch for more details on these options: https://oss.redislabs.com/redisearch/Commands.html#field_options
-
         Args:
             transaction_type (str): transaction_type to update
-            custom_index_fields (optional): custom_index_fields to update. Ex.: [{"path":"a.b","field_name":"myField","type":"text","options":{"no_index":True}}]
+            custom_index_fields (optional): custom index fields to create. Ex.: ``[{"path":"a.b","field_name":"myField","type":"text","options":{"no_index":True}}]``
+
+                Transaction Types can optionally link custom search index fields to your transactions for easier querying later.
+                A custom_index_field is a dictionary with 'path', 'field_name', 'type', and an optional 'options' dictionary:
+
+                - path (str): the JSONPath of your transaction payload you would like to result form a search on the "key"
+                - field_name (str): The field for this custom extracted value to be indexed under
+                - type ('text', 'tag', or 'number'): The type of redisearch index to use for this field
+                - options: (object) The redisearch options for this field
+
+                    - no_index (bool) (all types) whether or not to index on this field, or simply make it sortable only if false
+                    - separator (str) (tag only) what string should be used for the tag separator
+                    - weight (number) (text only) The weight to give this text field when doing text queries
+                    - no_stem (bool) (text only) Whether or not to allow search stemming in text searches on this field
+                    - sortable (bool) (text and number only) Whether or not a search on the index can be sortable by this field
+
+                See `the redisearch docs <https://oss.redislabs.com/redisearch/Commands.html#field_options>`_ for more details on these options
 
         Raises:
             TypeError: with bad parameter types
@@ -691,8 +720,8 @@ def create_transaction_type(
             custom_index_fields = []
         if not isinstance(transaction_type, str):
             raise TypeError('Parameter "transaction_type" must be of type str.')
-        if not isinstance(custom_index_fields, list):
-            raise TypeError('Parameter "custom_index_fields" must be of type list.')
+        if not isinstance(custom_index_fields, (list, set, tuple)):
+            raise TypeError('Parameter "custom_index_fields" must be iterable.')
         params = cast(Dict[str, Any], {"version": "2", "txn_type": transaction_type})
         if custom_index_fields:
             params["custom_indexes"] = _validate_and_build_custom_index_fields_array(custom_index_fields)

dragonchain_sdk/types.py

@@ -20,3 +20,4 @@
 custom_index_fields_type = mypy_extensions.TypedDict(
     "custom_index_fields_type", {"path": str, "field_name": str, "type": str, "options": Dict[str, Any]}
 )
+permissions_doc = mypy_extensions.TypedDict("permissions_doc", {"version": str, "default_allow": bool, "permissions": Dict[str, Any]})

run.sh

@@ -48,13 +48,16 @@ elif [ "$1" = "tests" ]; then
     fi
 elif [ "$1" = "lint" ]; then
     if [ "$2" = "no-async" ]; then
-        find . -name "*.py" -not -name "*async*" -exec python3 -m flake8 {} +
+        find dragonchain_sdk -name "*.py" -not -name "*async*" -exec python3 -m flake8 {} +
+        find tests -name "*.py" -not -name "*async*" -exec python3 -m flake8 {} +
     else
-        find . -name "*.py" -exec python3 -m flake8 {} +
-        if [ "$2" != "no-format" ]; then python3 -m black --check -l 150 -t py34 .; fi
+        find dragonchain_sdk -name "*.py" -exec python3 -m flake8 {} +
+        find tests -name "*.py" -exec python3 -m flake8 {} +
+        if [ "$2" != "no-format" ]; then python3 -m black --check -l 150 -t py34 dragonchain_sdk; python3 -m black --check -l 150 -t py34 tests; fi
     fi
 elif [ "$1" = "format" ]; then
-    python3 -m black -l 150 -t py34 .
+    python3 -m black -l 150 -t py34 dragonchain_sdk
+    python3 -m black -l 150 -t py34 tests
 elif [ "$1" = "bandit" ]; then
     python3 -m bandit -r dragonchain_sdk/
 elif [ "$1" = "build" ]; then

tests/integration/run.py

@@ -19,9 +19,19 @@
 from tests.integration import test_api_keys
 from tests.integration import test_misc
 from tests.integration import test_interchain
+from tests.integration import test_permissioning
 
 if __name__ == "__main__":
-    test_suites = [test_transaction_types, test_transactions, test_smart_contracts, test_blocks, test_api_keys, test_misc, test_interchain]
+    test_suites = [
+        test_transaction_types,
+        test_transactions,
+        test_smart_contracts,
+        test_blocks,
+        test_api_keys,
+        test_misc,
+        test_interchain,
+        test_permissioning,
+    ]
     # Make one suite and add all our tests
     suite = unittest.TestSuite()
     for test in test_suites:

tests/integration/schema.py

@@ -72,31 +72,43 @@
 
 create_transaction_response_schema = {"type": "object", "properties": {"transaction_id": {"type": "string"}}}
 
+permissions_document_schema = {
+    "type": "object",
+    "properties": {"version": {"type": "string", "enum": ["1"]}, "default_allow": {"type": "boolean"}, "permissions": {"type": "object"}},
+    "required": ["version", "default_allow", "permissions"],
+    "additionalProperties": False,
+}
+
 api_key_create_schema = {
     "type": "object",
-    "properties": {"key": {"type": "string"}, "id": {"type": "string"}, "registration_time": {"type": "integer"}, "nickname": {"type": "string"}},
-    "required": ["key", "id", "registration_time"],
+    "properties": {
+        "key": {"type": "string"},
+        "id": {"type": "string"},
+        "registration_time": {"type": "integer"},
+        "nickname": {"type": "string"},
+        "root": {"type": "boolean"},
+        "permissions_document": permissions_document_schema,
+    },
+    "required": ["key", "id", "registration_time", "nickname", "root", "permissions_document"],
     "additionalProperties": False,
 }
 
-api_key_list_schema = {
+api_key_generic_schema = {
     "type": "object",
     "properties": {
-        "keys": {
-            "type": "array",
-            "items": {
-                "type": "object",
-                "properties": {
-                    "id": {"type": "string"},
-                    "registration_time": {"type": "integer"},
-                    "nickname": {"type": "string"},
-                    "root": {"type": "boolean"},
-                },
-                "required": ["id", "registration_time"],
-                "additionalProperties": False,
-            },
-        }
+        "id": {"type": "string"},
+        "registration_time": {"type": "integer"},
+        "nickname": {"type": "string"},
+        "root": {"type": "boolean"},
+        "permissions_document": permissions_document_schema,
     },
+    "required": ["id", "registration_time", "nickname", "root", "permissions_document"],
+    "additionalProperties": False,
+}
+
+api_key_list_schema = {
+    "type": "object",
+    "properties": {"keys": {"type": "array", "items": api_key_generic_schema}},
     "required": ["keys"],
     "additionalProperties": False,
 }