ic-py

logo

Inspiration

DFINITY foundation only provides Rust and Typescript agent libraries. Both of them have sharp learning curves which are not suitable for newbies. Python is one of the most popular and easy-to-use programming languages. It has extremely large user base and is friendly to developers.

A python agent library will attract more developers to the IC ecosystem and help bloom the Internet Computer network.

What it does

support secp256k1 and ed2219 identity
decode/encode candid parameters into/from python variable type
raw query/update/read_state request to IC network
parse candid description file into python-format and instantiate a canister to support easy-to-use request
common canister interfaces (ledger, governance, cycle-wallet …)
implement the synchronous and asynchronous requests to match different scenery requirements

How we built it

Mainly referring to Internet Computer Specification, agent-rs, and agent-js, we implement the basic modules below:

Identity: handle cryptography issues to support secp256k1 and ed25519 identity
Principal: Principal construction and authentication from str or bytes
Candid: encode(serialize) and decode(deserialize) candid parameters to interact with Internet computer canisters. Support both basic types(nat, int, text..) and composed types(record, variant…).
Client: HTTP client to handle communications with the IC
Agent: Combine identity and client, provides query, update, and read_state request methods to Internet Computer network

For the convenience of developers, we support the following enhanced features:

Candid parser: Referring to candid specification, we implement a parser using antlr4 tools, which parse candid description into a python-format variable. Then it can be used to instantiate a canister.
Canister instance: Leveraging candid parsing, we can instantiate a canister class with a did file. With a canister, a developer can call methods easily while it handles parameter encode/decode internally.
Asynchronous request: During development, we found that asynchronous call is a fundamental requirement as it can improve the efficiency of the program. Thanks to httpx library we can implement the asynchronous call by requesting to IC endpoint asynchronously.

Challenges we ran into

candid serialization and deserialization: the data format of candid is unique and we need to deal with it carefully, meanwhile understanding how leb128 and cbor work.
candid parsing: To parse the grammar of candid, we need the prerequisite knowledge of grammar parsing and abstract syntax tree. Understanding how candid is described, we implement a candid parser using antlr4 and parse candid into python types.

Accomplishments that we're proud of

canister instantiate: Canister instantiating helps simplify the request to IC canisters. Instead of using raw requests and getting obfuscating value returned, the canister instance tackle encode/decode issues inside it and provide convenience for developers.
community usage: ic-py is used by many community projects and got good feedback.

What we learned

During the development of ic-py, we understand more about how IC works, how candid is encoded/decoded, and how IC uses a system tree to track the system states.
Communication with the community is important. Several bugs and features are handled through GitHub issues. Continuously communication can help improve the project and provide a great user experience.

What's next for ic-py

increase test coverage and test automation
optimize user experience
collaborate with developers in the community to fix bugs, and provide more easy-to-use features