## Python Agent Library for the Internet Computer
`ic-py` provides basic modules to interact with canisters on the DFINITY Internet Computer. Its still under active development.
### Install
```
pip3 install ic-py
```
### Features
1. candid types encode & decode
2. support secp256k1 & ed25519 identity, pem file import
3. canister DID file parsing
4. canister class, initialized with canister id and DID file
5. common canister interfaces: ledger, management, nns, cycles wallet
6. async support
### Modules & Usage
#### 1. Principal
Create an instance:
```python
from ic.principal import Principal
p = Principal() # default is management canister id `aaaaa-aa`
p1 = Principal(bytes=b'') # create an instance from bytes
p2 = Principal.anonymous() # create anonymous principal
p3 = Principal.self_authenticating(pubkey) # create a principal from public key
p4 = Principal.from_str('aaaaa-aa') # create an instance from string
p5 = Principal.from_hex('xxx') # create an instance from hex
```
Class methods:
```python
p.bytes # principal bytes
p.len # byte array length
p.to_str() # convert to string
```
#### 2. Identity
Create an instance:
```python
from ic.identity import Identity
i = Identity() # create an identity instance, key is randomly generated
i1 = Identity(privkey = "833fe62409237b9d62ec77587520911e9a759cec1d19755b7da901b96dca3d42") # create an instance from private key
```
Sign a message:
```python
msg = b”ddaf35a193617abacc417349ae20413112e6fa4e89a97ea20a9eeee64b55d39a2192992a274fc1a836ba3c23a3feebbd454d4423643ce80e2a9ac94fa54ca49f“
sig = i.sign(msg) # sig = (der_encoded_pubkey, signature)
```
#### 3. Client
Create an instance:
```python
from ic.client import Client
client = Client(url = "https://ic0.app")
```
#### 4. Candid
Encode parameters:
```python
from ic.candid import encode, decode, Types
# params is an array, return value is encoded bytes
params = [{'type': Types.Nat, 'value': 10}]
data = encode(params)
```
Decode parameters:
```python
# data is bytes, return value is an parameter array
params = decode(data)
```
#### 5. Agent
Create an instance:
```python
from ic.client import Client
from ic.identity import Identity
from ic.agent import Agent
# Identity and Client are dependencies of Agent
iden = Identity()
client = Client()
agent = Agent(iden, client)
```
Query call:
```python
# query the name of token canister `gvbup-jyaaa-aaaah-qcdwa-cai`
name = agent.query_raw("gvbup-jyaaa-aaaah-qcdwa-cai", "name", encode([]))
```
Update call:
```python
# transfer 100 token to blackhole address `aaaaa-aa`
params = [
{'type': Types.Principal, 'value': 'aaaaa-aa'},
{'type': Types.Nat, 'value': 10000000000}
]
result = agent.update_raw("gvbup-jyaaa-aaaah-qcdwa-cai", "transfer", encode(params))
```
#### 6. Canister
Create a canister instance with candid interface file and canister id, and call canister method with canister instance:
```python
from ic.canister import Canister
from ic.client import Client
from ic.identity import Identity
from ic.agent import Agent
from ic.candid import Types
iden = Identity()
client = Client()
agent = Agent(iden, client)
# read governance candid from file
governance_did = open("governance.did").read()
# create a governance canister instance
governance = Canister(agent=agent, canister_id="rrkah-fqaaa-aaaaa-aaaaq-cai", candid=governance_did)
# call canister method with instance
res = governance.list_proposals(
{
'include_reward_status': [],
'before_proposal': [],
'limit': 100,
'exclude_topic': [],
'include_status': [1]
}
)
```
### 7. Async request
ic-py also supports async requests:
```python
import asyncio
from ic.canister import Canister
from ic.client import Client
from ic.identity import Identity
from ic.agent import Agent
from ic.candid import Types
iden = Identity()
client = Client()
agent = Agent(iden, client)
# read governance candid from file
governance_did = open("governance.did").read()
# create a governance canister instance
governance = Canister(agent=agent, canister_id="rrkah-fqaaa-aaaaa-aaaaq-cai", candid=governance_did)
# async call
async def async_test():
res = await governance.list_proposals_async(
{
'include_reward_status': [],
'before_proposal': [],
'limit': 100,
'exclude_topic': [],
'include_status': [1]
}
)
print(res)
asyncio.run(async_test())
```
Raw data
{
"_id": null,
"home_page": "https://github.com/rocklabs-io/ic-py",
"name": "ic-py",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "dfinity ic agent",
"author": "Rocklabs",
"author_email": "hello@rocklabs.io",
"download_url": "https://files.pythonhosted.org/packages/e3/71/7dd9e1581b28a04b67a22bfa8462da8ef5d83353a46af3b0d8262015eb84/ic-py-1.0.1.tar.gz",
"platform": null,
"description": "## Python Agent Library for the Internet Computer\n\n\n\n`ic-py` provides basic modules to interact with canisters on the DFINITY Internet Computer. Its still under active development.\n\n### Install\n\n```\npip3 install ic-py\n```\n\n### Features\n\n1. candid types encode & decode\n2. support secp256k1 & ed25519 identity, pem file import\n3. canister DID file parsing\n4. canister class, initialized with canister id and DID file\n5. common canister interfaces: ledger, management, nns, cycles wallet\n6. async support\n\n### Modules & Usage\n\n#### 1. Principal\n\nCreate an instance:\n\n```python\nfrom ic.principal import Principal\np = Principal() # default is management canister id `aaaaa-aa`\np1 = Principal(bytes=b'') # create an instance from bytes\np2 = Principal.anonymous() # create anonymous principal\np3 = Principal.self_authenticating(pubkey) # create a principal from public key\np4 = Principal.from_str('aaaaa-aa') # create an instance from string\np5 = Principal.from_hex('xxx') # create an instance from hex\n```\n\nClass methods:\n\n```python\np.bytes # principal bytes\np.len # byte array length\np.to_str() # convert to string\n```\n\n#### 2. Identity\n\nCreate an instance:\n\n```python\nfrom ic.identity import Identity\ni = Identity() # create an identity instance, key is randomly generated\ni1 = Identity(privkey = \"833fe62409237b9d62ec77587520911e9a759cec1d19755b7da901b96dca3d42\") # create an instance from private key\n```\n\nSign a message:\n\n```python\nmsg = b\u201dddaf35a193617abacc417349ae20413112e6fa4e89a97ea20a9eeee64b55d39a2192992a274fc1a836ba3c23a3feebbd454d4423643ce80e2a9ac94fa54ca49f\u201c\nsig = i.sign(msg) # sig = (der_encoded_pubkey, signature)\n```\n\n#### 3. Client\n\nCreate an instance:\n\n```python\nfrom ic.client import Client\nclient = Client(url = \"https://ic0.app\")\n```\n\n#### 4. Candid\n\nEncode parameters:\n\n```python\nfrom ic.candid import encode, decode, Types\n# params is an array, return value is encoded bytes\nparams = [{'type': Types.Nat, 'value': 10}]\ndata = encode(params)\n```\n\nDecode parameters:\n\n```python\n# data is bytes, return value is an parameter array\nparams = decode(data)\n```\n\n#### 5. Agent\n\nCreate an instance:\n\n```python\nfrom ic.client import Client\nfrom ic.identity import Identity\nfrom ic.agent import Agent\n# Identity and Client are dependencies of Agent\niden = Identity()\nclient = Client()\nagent = Agent(iden, client)\n```\n\nQuery call:\n\n```python\n# query the name of token canister `gvbup-jyaaa-aaaah-qcdwa-cai`\nname = agent.query_raw(\"gvbup-jyaaa-aaaah-qcdwa-cai\", \"name\", encode([]))\n```\n\nUpdate call:\n\n```python\n# transfer 100 token to blackhole address `aaaaa-aa`\nparams = [\n\t{'type': Types.Principal, 'value': 'aaaaa-aa'},\n\t{'type': Types.Nat, 'value': 10000000000}\n]\nresult = agent.update_raw(\"gvbup-jyaaa-aaaah-qcdwa-cai\", \"transfer\", encode(params))\n```\n\n#### 6. Canister\n\nCreate a canister instance with candid interface file and canister id, and call canister method with canister instance:\n\n```python\nfrom ic.canister import Canister\nfrom ic.client import Client\nfrom ic.identity import Identity\nfrom ic.agent import Agent\nfrom ic.candid import Types\n\niden = Identity()\nclient = Client()\nagent = Agent(iden, client)\n# read governance candid from file\ngovernance_did = open(\"governance.did\").read()\n# create a governance canister instance\ngovernance = Canister(agent=agent, canister_id=\"rrkah-fqaaa-aaaaa-aaaaq-cai\", candid=governance_did)\n# call canister method with instance\nres = governance.list_proposals(\n {\n 'include_reward_status': [],\n 'before_proposal': [],\n 'limit': 100,\n 'exclude_topic': [],\n 'include_status': [1]\n }\n)\n```\n\n### 7. Async request\n\nic-py also supports async requests:\n\n```python\nimport asyncio\nfrom ic.canister import Canister\nfrom ic.client import Client\nfrom ic.identity import Identity\nfrom ic.agent import Agent\nfrom ic.candid import Types\n\niden = Identity()\nclient = Client()\nagent = Agent(iden, client)\n# read governance candid from file\ngovernance_did = open(\"governance.did\").read()\n# create a governance canister instance\ngovernance = Canister(agent=agent, canister_id=\"rrkah-fqaaa-aaaaa-aaaaq-cai\", candid=governance_did)\n# async call\nasync def async_test():\n res = await governance.list_proposals_async(\n {\n 'include_reward_status': [], \n 'before_proposal': [],\n 'limit': 100, \n 'exclude_topic': [], \n 'include_status': [1]\n }\n )\n print(res)\nasyncio.run(async_test())\n```\n\n\n\n",
"bugtrack_url": null,
"license": "",
"summary": "Python Agent Library for the Internet Computer",
"version": "1.0.1",
"project_urls": {
"Homepage": "https://github.com/rocklabs-io/ic-py"
},
"split_keywords": [
"dfinity",
"ic",
"agent"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "608738763cd1a86f9b31194f045f9079cb2448aab7fa79bb718429daba98a4fa",
"md5": "3442247c7f52b4d5d626ef0029e75676",
"sha256": "d72a214689ed8b2a645e9b5a910f62646b00e3375a1491910590fd5228aa6e9b"
},
"downloads": -1,
"filename": "ic_py-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3442247c7f52b4d5d626ef0029e75676",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 40980,
"upload_time": "2022-06-23T05:49:50",
"upload_time_iso_8601": "2022-06-23T05:49:50.830650Z",
"url": "https://files.pythonhosted.org/packages/60/87/38763cd1a86f9b31194f045f9079cb2448aab7fa79bb718429daba98a4fa/ic_py-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e3717dd9e1581b28a04b67a22bfa8462da8ef5d83353a46af3b0d8262015eb84",
"md5": "9b4c9a8597797fcb5006ad1997be4bff",
"sha256": "d44d3f4d127e928cdc6b898e68d08a826cb43bb19fafe6d429bafc74838d55c9"
},
"downloads": -1,
"filename": "ic-py-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "9b4c9a8597797fcb5006ad1997be4bff",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 37556,
"upload_time": "2022-06-23T05:49:52",
"upload_time_iso_8601": "2022-06-23T05:49:52.563503Z",
"url": "https://files.pythonhosted.org/packages/e3/71/7dd9e1581b28a04b67a22bfa8462da8ef5d83353a46af3b0d8262015eb84/ic-py-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-06-23 05:49:52",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "rocklabs-io",
"github_project": "ic-py",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "ic-py"
}
JSON
