Nimbella SDK for Python

A Python package to interact with nimbella.com services.

Installation

pip install nimbella

Usage

This SDK provides access to the following cloud services on Nimbella.com:

• Redis
• Object Storage

Redis

The nimbella.redis() method returns a pre-configured Redis client for use in your application. See the Redis client library documentation for the methods provided.

import nimbella

# Redis
redis = nimbella.redis()
redis.set("key", "value")
value = redis.get("key")

Object Storage (GCP & S3)

The nimbella.storage() method returns a pre-configured object storage client. This client exposes a high-level storage API (details below) - which hides the underlying storage provider implementation. The storage client is automatically configured to use the storage service for the cloud it is running on - which is GCS on GCP and S3 on AWS.

import nimbella

# Storage
bucket = nimbella.storage()
filename = "test.txt"
file = bucket.file(filename)
file.save('Expected %s contents' % filename, 'text/plain')

The nimbella.storage() constructor takes a single parameter web to determine whether the storage bucket is for a website (nimbella.storage(web=True)) or files (nimbella.storage()). Website buckets can be used for store web content (e.g. HTML & JS files) to host static websites.

Object Storage API

# Storage API
class StorageProvider(web=False):    
    # External bucket URL
    @property
    def url() -> Union[str, None]:

    # Configure website for web storage buckets
    def setWebsite(mainPageSuffix, notFoundPage):

    # Remove all files from the bucket (using optional prefix)    
    def deleteFiles(force, prefix):

    # Upload new file from path to bucket destination.
    def upload(path, destination, contentType, cacheControl):

    # Return storage file instance from bucket
    def file(destination) -> StorageFile:

    # Return all storage files (with optional prefix) instance from bucket
    def getFiles(prefix) -> list:
      
# Storage File Class
class StorageFile():
    # Name of the bucket file
    @property
    def name() -> str:

    # key/value pairs for provider-specific object metadata
    @property
    def metadata() -> dict:

    # does file exist?
    def exists() -> bool:

    # delete file from bucket
    def delete() -> None:

    # update file contents from string or bytes with content-type
    def save(data: Union[str, bytes], contentType: str) -> None:

    # return file contents as bytes
    def download() -> bytes:

    # return pre-signed url from file for external access
    def signed_url(version: str, action: str, expires: int, contentType: str) -> str:

Embedded SQL support

You can access embedded sql with: sql = nimbella.esql()

Available methods are:

sql.exec(sql, *arg)

Excecute an sql statement. The statement is either a string in SQL or an id returned by sql.prep (a prepared statement).

You can also pass multiple additional args, for parametric statementns.

It returns an array of [lastId, changedRows]

Values are significant where relevant (for insert or delete, but not for create for example).

Example:

# single statement
res = sql.exec("create table t(i int)")
# parametric statement
res = sql.exec("insert into t(i) values(?),(?),(?)",1,2,3)
# returns [3,3]

sql.map(sql, *args [,limit=<n>])

Execute an sql statement. The statement is either a string in SQL or an id returned by sql.prep (a prepared statement).

You can also pass multiple additional args, for parametric statementns.

It returns the result of an SQL query (like a SELECT) as an an array of dictionaries. Each dictionary is a record, where the keys are the fields and the values are the field values.

The optional keyword argument is the maximum number of records returned, it will limit the size of the returned array to the first <n>

Examples:

sql.map("select * from t")
# returns [{"i":1},{"i":2},{"i":3}]
sql.map("select * from t where i >?",1)
# returns [{"i":2},{"i":3}]
sql.map("select * from t where i >?",1,limit=1)
# returns [{"i":2}]

sql.arr(sql, *args [,limit=<n>])

Execute an sql statement. The statement is either a string in SQL or an id returned by sql.prep (a prepared statement).

You can also pass multiple additional args, for parametric statements.

It returns the result of an SQL query (like a SELECT) as an an array of arrays. Each array includes the field values of a record.

The optional keyword argument is the maximum number of records returned, it will limit the size of the returned array to the first <n>

Examples:

sql.map("select * from t")
# returns [[1],[2],[3]]
sql.map("select * from t where i >?",1)
# returns [[2],[3]]
sql.map("select * from t where i >?",1,limit=1)
# returns [[2]]

prep(sql)

You can prepare statements to save time from precompiling.

ins =  sql.prep("insert into t(i) values(?)")
sel = sql.prep("select * from t where i>?")

The returned value is a number and can be used to execute the statement with exec, map and arr.

# executing statement
res = sql.exec(ins,1)
# executing query
m = sql.map(sel,1,limit=1)

When you do not need any more you can close the statement running prep again with the returned value.

# closing prepared statements
sql.prep(ins)
sql.prep(sel)

Note that you can prepare up to 10000 statement at the same time without closing them, otherwise you will get an error too many prepared statement. In the unfortunate accident you fill the prepared statement cache, you can clear it with prep("clean_prep_cache")

Support

We're always happy to help you with any issues you encounter. You may want to join our Slack community to engage with us for a more rapid response.

License

Apache-2.0. See LICENSE to learn more.