I've wanted to publish my first article about an encrypted, decentralized chat app running on IPFS. I had already built a private IPFS library, but I wanted to use a public one for the article. I tried out two different public libraries. One of them simply didn't work and the other one was deprecated.
So here I am rebuilding my library publically!
Step 1 - Preparing
Reading the documentation
The last time I've build this, it wasn't in the most elegant way. I used the CLI Tools and extracted the data I needed with regex. I have done many unconventional things, but I was too lazy to read the documentation and wanted to get a mini-project done quickly to show my friends. As I am building this publically now, I will read the IPFS documentation (IPFS Kubo RPC API).
What do I want to achieve with this library?
As far as Version 1 goes, I only want to implement basic functionality, so I can finish my first intended article. In particular, I want to be able to do at least the following things:
Add files to IPFS
Get files from IPFS
Remove files from IPFS
Generate IPNS Keys
List IPNS Keys
Update IPNS values
Creating the folder structure
At this point, I have to create the root folder. This will be the name of my library. I will call it ipfslib, so it's easier to confuse with ipfsapi. Every module has it's own file, this way it is less cluttered and easier to update afterwards.
ipfslib
│ connect.py
│ __init__.py
│
├───IPFS
│ │ add.py
│ │ cat.py
│ │ get.py
│ │ rem.py
│ │ resolve.py
│ │ __init__.py
│
└───Key
│ generate.py
│ list.py
│ publish.py
│ rename.py
│ __init__.py
I included everything I want to have in my first version. This is all I need for my next project.
Creating the Connector
I want the user to be able to specify where the API-endpoint is, instead of assuming standard values. Basically this is all, what connect.py does, it stores the IP-address and the port of the API-endpoint:
class Connect:
def __init__(self, ip_address, port):
self.endpoint = str(ip_address) + ":" + str(port)
But I included some checks to check if the API is responding and I included standard parameters, so users could simply write ipfslib.Connect(), instead of typing ipfslib.Connect('127.0.0.1', 5001).
import requests
class Connect:
def __init__(self, ip_address="localhost", port=5001):
if str(port).isnumeric() == False:
raise TypeError("The given port is not numeric")
elif int(port) <= 0 or int(port) >= 65536:
raise ValueError("Port number has to be between 1 and 65535")
self.endpoint = str(ip_address) + ":" + str(port)
response = requests.post('http://{endpoint}/api/v0/bitswap/stat'.format(endpoint=self.endpoint))
if response.status_code != 200:
raise Exception("The given endpoint isn't working as intended")
Step 2 - Wrapping those APIs up😋
You don't need to be a professional programmer to do this stuff - even I can do it.
Let's say, I want to add a file to IPFS. The way to do it is quite simple, because the IPFS documentation has CURL examples. Here is a quick overview of what I did it:
Go to the documentation, where adding files is specified
Copy the provided CURL example
Paste it at curlconverter.com
Integrate the Python Code into the function
Read out the JSON response and extract relevant values
Example: Generating IPNS key
The CURL example in the IPFS documentation:
curl -X POST "http://127.0.0.1:5001/api/v0/key/gen?arg=<name>&type=ed25519&size=<value>&ipns-base=base36"
Removing unnecessary things and formatting:
curl -X POST "http://{endpoint}/api/v0/key/gen?arg="
Using curlconverter.com:
import requests
params = {
'arg': '',
}
response = requests.post('http://{endpoint}/api/v0/key/gen', params=params)
Implementing it into a function, which takes the JSON response and extracts the ipns_name of the newly created key:
import json
import requests
def generate(api, key_name):
params = {
'arg': key_name,
}
response = requests.post('http://{endpoint}/api/v0/key/gen'.format(api.endpoint), params=params)
ipns_name = json.loads(response.text)["Id"]
return ipns_name
I did this for every feature I wanted to have in my library. Some were more complex than others, I showed you the most simple function there was for this example.
Other modules had more complex JSON responses or more functionality.
Including everything in __init__.py
I don't want the user to import every module separately, so I'll include them in those nice little __init__.py files.
from ipfslib.connect import Connect
from ipfslib import Key
from ipfslib import IPFS
from ipfslib.IPFS.add import add
from ipfslib.IPFS.cat import cat
from ipfslib.IPFS.get import get
from ipfslib.IPFS.rem import rem
from ipfslib.IPFS.resolve import resolve
from ipfslib.Key.generate import generate
from ipfslib.Key.list import list
from ipfslib.Key.publish import publish
from ipfslib.Key.rename import rename
Step 3 - Publishing
Surprisingly this was taking longer than actually programming because it is my first time actually doing this last step of publishing my project. In future projects, this won't take that long anymore, because I've learned everything important now.
Like how to structure a setup.py file or how to use twine, which is fairly easy.
Writing documentation
I explained how to use each module quickly in the README.md file. There is nothing too much to explain here. I had to look at how Markup works, but it was a simple process as a whole.
Creating the setup file
The setup.py file ended up looking like this. I had to change the version from 0.1 to 0.1.0, because I messed up the markup file on my first try uploading. I took inspiration from here to fix the problem with my project description.
from setuptools import setup, find_packages
import codecs
import os
here = os.path.abspath(os.path.dirname(__file__))
with codecs.open(os.path.join(here, "README.md"), encoding="utf-8") as fh:
long_description = "\n" + fh.read()
setup(
name= "ipfslib",
version= "0.1.0",
author= "Christian Remboldt",
author_email= "remboldt@proton.me",
description= "IPFS Library for Python",
long_description_content_type="text/markdown",
long_description=long_description,
packages=find_packages(),
install_requires=[],
keywords=['python', 'ipfs', 'api', 'decentral', 'networking', 'ipns'],
classifiers=[
"Programming Language :: Python :: 3"
]
)
Uploading
First I had to build the setup.py file
py setup.py sdist
After python had created the dist folder, I could upload its contents to PyPi with twine.
py -m pip install twine
py -m twine upload dist/*
AND DONE!
Note
I uploaded some usage examples on GitHub:
https://github.com/remboldt/ipfslib/tree/main/examples
Have a nice day!
PyPi Project Page: https://pypi.org/project/ipfslib/
GitHub Repository: https://github.com/remboldt/ipfslib/
