ipfs_dict_chain

ipfs_dict_chain is a Python package that provides IPFSDict and IPFSDictChain objects, which are dictionary-like data structures that store their state on IPFS and keep track of changes, basically creating a mini-blockchain of dicts on IPFS for efficient and secure data management.

Requirements

• Python >= 3.10
• An IPFS node
• aioipfs >= 0.7.1
• multiaddr >= 0.0.9

Installation

To install the ipfs_dict_chain package, run the following command:

pip install ipfs-dict-chain

Usage

By default, ipfs_dict_chain will attempt to connect to an IPFS node running on localhost (127.0.0.1) on port 5001. If your IPFS node is running with these default settings, you can start using the package immediately.

If your IPFS node is running on a different host or port, you must first connect to it using the connect() function:

from ipfs_dict_chain.IPFS import connect

# Connect to a local IPFS node on a different port
connect(host='127.0.0.1', port=8080)

# Or connect to a remote IPFS node
connect(host='192.168.1.100', port=5001)

The connect() function will test the connection using a read-only operation (client.id()). If the connection fails, it will raise an IPFSError with details about the connection failure, and the global connection settings are left unchanged (i.e., connect() does not modify the active IPFS address on failure).

IPFSDict

IPFSDict is a dictionary-like object that stores its data on IPFS. Here's an example of how to use IPFSDict:

from ipfs_dict_chain.IPFSDict import IPFSDict

my_dict = IPFSDict()

# Add data to the dictionary, you can use both dot notation and bracket notation
my_dict.my_key1 = 'value1'
my_dict['my_key2'] = 'value2'

# Save the dictionary to IPFS
cid = my_dict.save()

# Load the dictionary from IPFS
loaded_dict = IPFSDict(cid=cid)

# Access the data
print(loaded_dict.my_key1)  # Output: 'value1'

Note: IPFSDict.load() replaces any existing data with the data loaded from IPFS. Loading into an already-populated IPFSDict will not merge data; it clears the existing keys first.

Note: When using dot notation, class methods (such as save(), load(), and cid()) take precedence over data keys, so data keys cannot shadow these built-in methods. Use bracket notation (e.g. my_dict['save']) to access the raw data value when a key collides with a method name.

IPFSDictChain

IPFSDictChain is a dictionary-like data structure that stores its state on IPFS and keeps track of changes. Here's an example of how to use IPFSDictChain:

from ipfs_dict_chain.IPFSDictChain import IPFSDictChain

my_chain = IPFSDictChain()

# Add data to the dictionary, you can use both dot notation and bracket notation
my_chain.my_key1 = 'value1'
my_chain['my_key2'] = 'value2'

# Save the current state of the dictionary to IPFS
cid1 = my_chain.save()

my_chain.my_key1 = 'value1_changed'
cid2 = my_chain.save()

# Load the dictionary from IPFS
loaded_chain = IPFSDictChain(cid=cid2)

# Access the data
print(loaded_chain.my_key1)  # Output: 'value1_changed'

# Get the changes between the current state and the previous state
changes = loaded_chain.changes()
print(changes)  # Output: {'my_key1': {'old': 'value1', 'new': 'value1_changed'}}

# Get the previous states of the dictionary
previous_states = loaded_chain.get_previous_states()
print(previous_states)  # Output: [{'previous_cid': None, 'my_key1': 'value1', 'my_key2': 'value2'}]

# Get the previous CIDs of the dictionary
previous_cids = loaded_chain.get_previous_cids()
print(previous_cids)  # Output: ['/ipfs/QmSdydVMD2E7taf42gwQNhakBAc379u8y9X4Kbyoig36Fs']

Development and Testing

To install development dependencies:

pip install -e ".[dev]"

To run tests with coverage:

pytest

This will:

• Run all tests in the tests directory
• Generate a coverage report in the terminal
• Create an HTML coverage report in the htmlcov directory

To view specific test coverage details:

# View coverage in terminal with missing lines
pytest --cov=ipfs_dict_chain --cov-report=term-missing

# Generate HTML coverage report
pytest --cov=ipfs_dict_chain --cov-report=html

Documentation

The documentation is built using Sphinx and can be found at GitHub Pages.

To build the documentation locally:

1. Install the documentation dependencies:

   pip install sphinx sphinx-rtd-theme
   

2. Build the documentation:

   cd docs
   python -m sphinx.cmd.build -b html source build/html
   

The documentation will be available in docs/build/html/index.html.

Contributing

If you'd like to contribute to the ipfs_dict_chain package, please submit a pull request, issue, or feature request on the project's GitHub repository.

License

This package is released under the MIT License.

Authors

• Wouter Glorieux - Twitter
• Serendipity - AI Assistant