Manage data using Python

Manage data using Python and the JSON DB API tutorials

Abstract

Manage data using Python and the JSON DB API tutorials

The JSON DB API allows users to access rich database functionality using JSON messages over HTTP(S) without any local binary dependencies.

While the API is simple to use, and writing a driver from scratch is very easy, FairCom provides drivers for the most common programming languages to make usage even easier.

This document goes over the Python driver for the JSON DB API and how to use it.

The Python driver for the JSON DB API makes requests using an HTTP client library as its only direct dependency.

First steps

Note

These procedures were written and tested using Windows 11 and Python 3.9.1.

Prerequisites:

Ensure you have FairCom DB installed and running.
Ensure that Python 3.9.1 or later is installed and executable from your command line.

Establish FairCom DB server communication:

Open the driver folder that is inside the FairCom DB folder.
navigate to and open the folder named python.json.db in your command prompt.
Run the >pip install -r requirements.txt to install the request library.
Run >cd tutorials.
Run >python ping.py.
Observe the ping successful message.
This indicates that your FairCom DB server is running, the JSON DB API is accessible, and the Python driver can communicate successfully with the server.

Create some test data:

Run the following commands in this order:
- python createDatabase.py
- python createTable.py
- python createIndex.py
- python insertRecords.py
- python getRecordsByTable.py
Observe the results:
[4, 13358, 'Ian Nepomniachtchi', 2789]
[1, 13358, 'Magnus Carlsen', 2847]
[2, 13358, 'Fabiano Caruana', 2820]
[3, 13358, 'Ding Liren', 2791]
[5, 13358, 'Levon Aronian', 2781]
[6, 13358, 'Alexander Grischuk', 2777]
[7, 13358, 'Anish Giri', 2776]
Confirm the successful creation of the table inside the FairCom Data Explorer.

Example source code

Example 1. Source code

from JNAClient import JNAClient, JNAClientException

client = JNAClient("http://localhost:8080/api")
client.login("ADMIN", "ADMIN")

try:
    client.createDatabase("test_py")
    print("created database: " + "test_py")
except JNAClientException as e:
    print(e)

client.logout()

About the Example 1, “Source code”:

In the example source code, a new JNAClient is instantiated.
We pass in the URL of the server that runs the FairCom DB server. If you want to use HTTPS you need a real SSL certificate.
Attempt to login to the server using username and password ADMIN. This is the default and it should be changed for servers in production.
If the login was successful the high-level API function createDatabase inside of a try/catch/finally block is called.
If the call is successful a success message is printed.
If the call is NOT successful a JsonDBException is thrown and caught and a failure message is printed.
Finally, the logout function is called. This is important because the server caches a lot of resources associated with every session. Always make sure that you log out when you are done with the JSON DB API or that you keep the session alive using ping calls. A ping call once per minute should be enough for long-running tasks.

Debug

To look at the messages that are passed back and forth between the client and the server, set the second parameter to true , to view debug information when calling JNAClient.

Example 2. JNAClient

client = JNAClient("http://localhost:8080/api", True)

Use the Python driver for the JSON DB API in your own projects

This procedure outlines the steps to use the Python driver for the JSON DB API in your own projects.

Create a new empty folder called my_test .
Open the new empty folder using a command prompt.
Copy JNAClient.py from the python.json.db folder into the new folder.
Create a new file named my_test.py.
Open my_test.py in a text editor.

Edit the my_test.py to match the following:

from JNAClient import JNAClient, JNAClientException

client = JNAClient("http://localhost:8080/api", False)

try:
    client.ping()
    print("ping successful.")
except JNAClientException as e:
    print(e)

Using the command prompt, run > python my_test.py.
Observe the ping successful message.
> ping successful.
This indicates that you have successfully created your own project using the Python driver for the JSON DB API.

Enable HTTP on port 8080

This FairCom tutorial uses HTTP to communicate with the server on port 8080. Because HTTP is insecure, this port is typically disabled.

Do the following to enable the HTTP protocol on port 8080:

Shut down the FairCom server.
Edit the services.json file located in the <faircom>/config folder.
Find the listener service named "http8080".
Change "enabled":false to "enabled":true.
Restart the FairCom server.

The modified listener configuration object in services.json should look something like this:

{
  "serviceName": "http8080",
  "description": "Port 8080 using insecure HTTP protocol...",
  "port": 8080,
  "protocol": "http",
  "enabled": true
}