nosqlapi common

In this package you will find the modules that contain common interfaces and ODMs (Object-Data Mapping), shared by all four types of NOSQL database.

core module

In the core module, we find the abstract classes that form the basis of the classes of all four NOSQL database types.

Note

In theory, you shouldn’t use these classes to build your class module for the NOSQL database you plan to build, but you could; in all classes you have the necessary methods to iterate with the database server.

Module that contains the core objects.

class nosqlapi.common.core.Batch(batch, session=None)

Bases: abc.ABC

Batch abstract class

The abstract class Batch is used to create batch-type classes that represent a collection of operations to be performed at the same time.

__init__(batch, session=None)

Instantiate Batch object

Parameters

• batch – List of commands

• session – Session object or other compliant object

__repr__()

Return repr(self).

__str__()

Return str(self).

__weakref__

list of weak references to the object (if defined)

property batch

String batch operation

abstract execute(*args, **kwargs)

Execute some batch statement

Returns

Union[tuple, Response]

property session

Session object

class nosqlapi.common.core.Connection(host=None, user=None, password=None, database=None, port=None, bind_address=None, read_timeout=None, write_timeout=None, ssl=None, ssl_ca=None, ssl_cert=None, tls=None, ssl_key=None, ssl_verify_cert=None, max_allowed_packet=None)

Bases: abc.ABC

Server connection abstract class

The abstract class Connection is used to create connection-type classes that will allow you to work directly on the layer at the database level.

__init__(host=None, user=None, password=None, database=None, port=None, bind_address=None, read_timeout=None, write_timeout=None, ssl=None, ssl_ca=None, ssl_cert=None, tls=None, ssl_key=None, ssl_verify_cert=None, max_allowed_packet=None)

Instantiate Connection object

Parameters

• host – Name of host that contains database

• user – Username for connect to the host

• password – Password for connect to the host

• database – Name of database

• port – Tcp port

• bind_address – Hostname or an IP address for multiple network interfaces

• read_timeout – Timeout for reading from the connection in seconds

• write_timeout – Timeout for writing from the connection in seconds

• ssl – Ssl connection established

• ssl_ca – Ssl CA file specified

• ssl_cert – Ssl certificate file specified

• tls – Tls connection established

• ssl_key – Ssl private key file specified

• ssl_verify_cert – Verify certificate file

• max_allowed_packet – Max size of packet sent to server in bytes

__repr__()

Return repr(self).

__str__()

Return str(self).

__weakref__

list of weak references to the object (if defined)

abstract close(*args, **kwargs)

Close connection

Returns

None

abstract connect(*args, **kwargs)

Connect database server

Returns

Session object

property connected

Boolean representing the database connection

Returns

bool

abstract create_database(*args, **kwargs)

Create new database on server

Returns

Union[bool, Response]

abstract databases(*args, **kwargs)

Get all databases

Returns

Union[tuple, list, Response]

abstract delete_database(*args, **kwargs)

Delete database on server

Returns

Union[bool, Response]

abstract has_database(*args, **kwargs)

Check if database exists

Returns

Union[bool, Response]

abstract show_database(*args, **kwargs)

Show a database information

:return : Union[Any, Response]

class nosqlapi.common.core.Response(data, code=None, header=None, error=None)

Bases: abc.ABC

Server response abstract class

The abstract class Response is used to create response-type classes that represent response data to an operation.

__init__(data, code=None, header=None, error=None)

Instantiate Response object

Parameters

• data – Data from operation

• code – Exit code of operation

• header – Header of operation

• error – Error string or Exception class

__repr__()

Return repr(self).

__str__()

Return str(self).

property code

Number code of error or success in an operation

property data

The effective data than returned

property dict

dict format for Response object

property error

Error of an operation

property header

Information (header) of an operation

throw()

Raise or throw exception from error property

Returns

Exception

class nosqlapi.common.core.Selector(selector=None, fields=None, partition=None, condition=None, order=None, limit=None)

Bases: abc.ABC

Selector abstract class

The abstract class Selector is used to create selector-type classes, which represent a query in the specific language of the database.

__init__(selector=None, fields=None, partition=None, condition=None, order=None, limit=None)

Instantiate Selector object

Parameters

• selector – Selector part of the query string

• fields – Return fields

• partition – Partition or collection of data

• condition – Condition of query

• order – Order by specific selector

• limit – Limit result

__repr__()

Return repr(self).

__str__()

Return str(self).

__weakref__

list of weak references to the object (if defined)

abstract build(*args, **kwargs)

Build string query selector

Returns

string

property condition

Other condition to apply a selectors

property fields

Key that returned from find operations

property limit

Limit number of objects returned from find operations

property order

Order returned from find operations

property partition

The name of partition or collection in a database

property selector

Value than you want search

class nosqlapi.common.core.Session(connection, database=None)

Bases: abc.ABC

Server session abstract class

The abstract class Session is used to create session-type classes that will allow you to work directly on the layer at the data level.

__init__(connection, database=None)

Instantiate Session object

Parameters

• connection – Connection object or other object to serve connection

• database – database name

__repr__()

Return repr(self).

__str__()

Return str(self).

__weakref__

list of weak references to the object (if defined)

abstract property acl

Access Control List in the current session

abstract add_index(*args, **kwargs)

Add index to database

Returns

Union[bool, Response]

static call(batch, *args, **kwargs)

Call a batch

Returns

Union[Any, Response]

abstract close(*args, **kwargs)

Close session

Returns

None

property connection

Connection of server in current session

property database

Name of database in current session

abstract delete(*args, **kwargs)

Delete one value

Returns

Union[bool, Response]

abstract delete_index(*args, **kwargs)

Delete index to database

Returns

Union[bool, Response]

abstract delete_user(*args, **kwargs)

Delete exist user

Returns

Union[bool, Response]

abstract property description

Contains the session parameters

abstract find(*args, **kwargs)

Find data

Returns

Union[tuple, Response]

abstract get(*args, **kwargs)

Get one or more value

Returns

Union[tuple, Response]

abstract grant(*args, **kwargs)

Grant users ACLs

Returns

Union[Any, Response]

abstract property indexes

Name of indexes of the current database

abstract insert(*args, **kwargs)

Insert one value

Returns

Union[bool, Response]

abstract insert_many(*args, **kwargs)

Insert one or more value

Returns

Union[bool, Response]

abstract property item_count

Number of item returned from latest CRUD operation

abstract new_user(*args, **kwargs)

Create new user

Returns

Union[bool, Response]

abstract revoke(*args, **kwargs)

Revoke users ACLs

Returns

Union[Any, Response]

abstract set_user(*args, **kwargs)

Modify exist user

Returns

Union[bool, Response]

abstract update(*args, **kwargs)

Update one value

Returns

Union[bool, Response]

abstract update_many(*args, **kwargs)

Update one or more value

Returns

Union[bool, Response]

core example

Classes on this module are abstract (interfaces), therefore, they cannot be instantiated as objects, but inherit them in their own classes.

# mymodule.py
import nosqlapi

# this module is my library of NOSQL database

class Connection(nosqlapi.common.Connection):
    def __init__(host=None, port=None, database=None, username=None, password=None, ssl=None, tls=None, cert=None,
                 ca_cert=None, ca_bundle=None): ...
    def close(self, force=False): ...
    def connect(self, retry=1): ...
    def create_database(self, database, exists=False): ...
    def has_database(self, database): ...
    def databases(self, return_obj=None): ...
    def delete_database(self, force=False): ...
    def show_database(self, database): ...

conn = Connection('server.local', 1241, 'new_db', username='admin', password='pa$$w0rd', ssl=True)
conn.create_database(conn.database)     # use 'database' attribute equals 'new_db'
if conn.has_database('new_db'):         # check if database exists
    sess = conn.connect()               # Session object
else:
    raise nosqlapi.common.exception.ConnectError(f'Connection error with database {conn.database}')
...

exception module

In the exception module, we find the exceptions listed in the exceptions table in the interface documentation.

Note

You should never use the Error exception class as it is the basis for all exceptions. If you have a generic or unknown error, use UnknownError instead.

Exception module.

This module contains the hierarchy of exceptions included in the NOSQL API.

exception nosqlapi.common.exception.CloseError

Bases: nosqlapi.common.exception.ConnectError

Exception raised for errors that are related to the database close connection.

exception nosqlapi.common.exception.ConnectError

Bases: nosqlapi.common.exception.Error

Exception raised for errors that are related to the database connection.

exception nosqlapi.common.exception.DatabaseCreationError

Bases: nosqlapi.common.exception.DatabaseError

Exception raised for errors that are related to the creation of a database.

exception nosqlapi.common.exception.DatabaseDeletionError

Bases: nosqlapi.common.exception.DatabaseError

Exception raised for errors that are related to the deletion of a database.

exception nosqlapi.common.exception.DatabaseError

Bases: nosqlapi.common.exception.Error

Exception raised for errors that are related to the database, generally.

exception nosqlapi.common.exception.Error

Bases: Exception

Error that is the base class of all other error exceptions. You can use this to catch all errors with one single except statement.

exception nosqlapi.common.exception.SelectorAttributeError

Bases: nosqlapi.common.exception.SelectorError

Exception raised for errors that are related to the selectors attribute.

exception nosqlapi.common.exception.SelectorError

Bases: nosqlapi.common.exception.Error

Exception raised for errors that are related to the selectors in general.

exception nosqlapi.common.exception.SessionACLError

Bases: nosqlapi.common.exception.SessionError

Exception raised for errors that are related to the grant or revoke permission on a database.

exception nosqlapi.common.exception.SessionClosingError

Bases: nosqlapi.common.exception.SessionError

Exception raised for errors that are related to the closing database session.

exception nosqlapi.common.exception.SessionDeletingError

Bases: nosqlapi.common.exception.SessionError

Exception raised for errors that are related to the deletion data on a database session.

exception nosqlapi.common.exception.SessionError

Bases: nosqlapi.common.exception.Error

Exception raised for errors that are related to the session, generally.

exception nosqlapi.common.exception.SessionFindingError

Bases: nosqlapi.common.exception.SessionError

Exception raised for errors that are related to the finding data on a database session.

exception nosqlapi.common.exception.SessionInsertingError

Bases: nosqlapi.common.exception.SessionError

Exception raised for errors that are related to the inserting data on a database session.

exception nosqlapi.common.exception.SessionUpdatingError

Bases: nosqlapi.common.exception.SessionError

Exception raised for errors that are related to the updating data on a database session.

exception nosqlapi.common.exception.UnknownError

Bases: nosqlapi.common.exception.Error

Exception raised when an unspecified error occurred.

exception example

The exceptions stated in this form are used in certain circumstances. See the table of exceptions to find out more.

import nosqlapi

raise nosqlapi.common.exception.UnknownError('I have no idea what the hell happened!')
raise nosqlapi.UnknownError('in short')

odm module

In the odm module, we find generic classes represent real objects present in various NOSQL databases.

Note

These objects are not mandatory for the implementation of their own NOSQL module. Rather they serve to help the end user have some consistency in python.

Module that contains some ODM common objects.

nosqlapi.common.odm.Array

alias of nosqlapi.common.odm.List

class nosqlapi.common.odm.Ascii(value='')

Bases: str

Represents ASCII string

__init__(value='')

ASCII string

Parameters

value – String printable characters

__weakref__

list of weak references to the object (if defined)

class nosqlapi.common.odm.Blob

Bases: bytes

Represents bytes

class nosqlapi.common.odm.Boolean(value)

Bases: object

Represents bool

__init__(value)

Boolean object

Parameters

value – True of False

__repr__()

Return repr(self).

__weakref__

list of weak references to the object (if defined)

class nosqlapi.common.odm.Counter(value=0)

Bases: object

Represents integer counter

__init__(value=0)

Counter object

Parameters

value – Integer (default 0)

__repr__()

Return repr(self).

__weakref__

list of weak references to the object (if defined)

decrement(value=1)

Decrement number

Parameters

value – Number (default 1)

Returns

None

increment(value=1)

Increment number

Parameters

value – Number (default 1)

Returns

None

class nosqlapi.common.odm.Date

Bases: datetime.date

Represents date in format %Y-%m-%d

__repr__()

Return repr(self).

__weakref__

list of weak references to the object (if defined)

class nosqlapi.common.odm.Decimal(value='0', context=None)

Bases: decimal.Decimal

Represents decimal number

__weakref__

list of weak references to the object (if defined)

class nosqlapi.common.odm.Double(x=0, /)

Bases: float

Represents float

__weakref__

list of weak references to the object (if defined)

class nosqlapi.common.odm.Duration

Bases: datetime.timedelta

Represents duration ISO 8601 format: P[n]Y[n]M[n]DT[n]H[n]M[n]S

__repr__()

Return repr(self).

__weakref__

list of weak references to the object (if defined)

string_format()

ISO 8601 format: P[n]Y[n]M[n]DT[n]H[n]M[n]S

Returns

str

class nosqlapi.common.odm.Float(x=0, /)

Bases: float

Represents float

__weakref__

list of weak references to the object (if defined)

class nosqlapi.common.odm.Inet(ip)

Bases: object

Represents ip address version 4 or 6 like string

__init__(ip)

Network ip address object

Parameters

ip – String ip value

__repr__()

Return repr(self).

__weakref__

list of weak references to the object (if defined)

class nosqlapi.common.odm.Int(number)

Bases: int

Represents integer

__init__(number)

Integer object

Parameters

number – Integer

__repr__()

Return repr(self).

class nosqlapi.common.odm.List(iterable=(), /)

Bases: list

Represents list of objects

__weakref__

list of weak references to the object (if defined)

class nosqlapi.common.odm.Map

Bases: dict

Represents dict of objects

__weakref__

list of weak references to the object (if defined)

class nosqlapi.common.odm.Null

Bases: object

Represents None

__repr__()

Return repr(self).

__weakref__

list of weak references to the object (if defined)

class nosqlapi.common.odm.SmallInt(number)

Bases: nosqlapi.common.odm.Int

Represents small integer: -32767 to 32767

__init__(number)

Integer number from -32767 to 32767

Parameters

number – Integer

class nosqlapi.common.odm.Text

Bases: str

Represents str

__weakref__

list of weak references to the object (if defined)

class nosqlapi.common.odm.Time

Bases: datetime.time

Represents time

__repr__()

Return repr(self).

__weakref__

list of weak references to the object (if defined)

class nosqlapi.common.odm.Timestamp

Bases: datetime.datetime

Represents datetime timestamp

__repr__()

Return repr(self).

__weakref__

list of weak references to the object (if defined)

class nosqlapi.common.odm.Uuid

Bases: object

Represents uuid version 1

__init__()

Uuid1 object

__repr__()

Return repr(self).

__weakref__

list of weak references to the object (if defined)

nosqlapi.common.odm.Varchar

alias of nosqlapi.common.odm.Text

nosqlapi.common.odm.Varint

alias of nosqlapi.common.odm.Int

odm example

The classes within the module are python representations of real objects in the database.

import nosqlapi

null = nosqlapi.common.odm.Null()     # compare with null object into database
null = nosqlapi.Null()                # in short
map_ = nosqlapi.Map()                 # like dict
inet = nosqlapi.Inet('192.168.1.1')   # ipv4/ipv6 addresses

utils module

In the utils module, we find classes and functions that help the end user’s work.

Note

The functions and classes in this module are meant for the work of the end user and not for those who build libraries.

Utils function and classes for any type of NOSQL database

class nosqlapi.common.utils.Manager(connection, *args, **kwargs)

Bases: object

Manager class for api compliant nosql database connection

__init__(connection, *args, **kwargs)

__repr__()

Return repr(self).

__str__()

Return str(self).

__weakref__

list of weak references to the object (if defined)

add_index(*args, **kwargs)

Add index to database

Returns

Union[bool, Response]

call(*args, **kwargs)

Call a batch

Returns

Union[Any, Response]

change(connection, *args, **kwargs)

Change connection type

Parameters

• connection – Connection object

• args – positional args of Connection object

• kwargs – keywords args of Connection object

Returns

None

close(*args, **kwargs)

Close session

Returns

None

create_database(*args, **kwargs)

Create new database

Returns

Union[bool, Response]

databases(*args, **kwargs)

Get all databases

Returns

Union[tuple, list, Response]

delete(*args, **kwargs)

Delete one value

Returns

Union[bool, Response]

delete_database(*args, **kwargs)

Delete database on server

Returns

Union[bool, Response]

delete_index(*args, **kwargs)

Delete index to database

Returns

Union[bool, Response]

delete_user(*args, **kwargs)

Delete exist user

Returns

Union[bool, Response]

find(*args, **kwargs)

Find data

Returns

Union[tuple, Response]

get(*args, **kwargs)

Get one or more value

Returns

Union[tuple, Response]

grant(*args, **kwargs)

Grant users ACLs

Returns

Union[Any, Response]

has_database(*args, **kwargs)

Check if database exists

Returns

Union[bool, Response]

insert(*args, **kwargs)

Insert one value

Returns

Union[bool, Response]

insert_many(*args, **kwargs)

Insert one or more value

Returns

Union[bool, Response]

new_user(*args, **kwargs)

Create new user

Returns

Union[bool, Response]

revoke(*args, **kwargs)

Revoke users ACLs

Returns

Union[Any, Response]

set_user(*args, **kwargs)

Modify exist user

Returns

Union[bool, Response]

show_database(*args, **kwargs)

Show a database information

:return : Union[Any, Response]

update(*args, **kwargs)

Update one value

Returns

Union[bool, Response]

update_many(*args, **kwargs)

Update one or more value

Returns

Union[bool, Response]

nosqlapi.common.utils.api(**methods)

Decorator function to transform standard classes into API compliant classes

Parameters

methods – method names that you want to bind to the methods of API compliant classes

Returns

class

nosqlapi.common.utils.apply_vendor(name)

Apply new name of api name

Parameters

name – name of vendor

Returns

None

nosqlapi.common.utils.cursor_response(resp)

Transform nosql Response object to list of tuple, like a response of sql cursor object

Parameters

resp – Response object or other compliant object

Returns

List[tuple]

nosqlapi.common.utils.global_session(connection, *args, **kwargs)

Global session

Parameters

• connection – Connection object or other compliant object

• args – positional arguments of connect method on Connection object

• kwargs – keywords arguments of connect method on Connection object

Returns

None

nosqlapi.common.utils.response(data)

Simple response with data only

Parameters

data – Data

Returns

Response

utils example

This is an example of a Manager object, used to change manage multiple sessions to different types of databases.

import nosqlapi
import mymodule
import othermodule

connection = mymodule.Connection('server.local', 1241, 'new_db', username='admin', password='pa$$w0rd', ssl=True)
manager = nosqlapi.common.utils.Manager(connection)

# Change connection and session
new_connection = othermodule.Connection('server2.local', 1241, 'other_db', username='admin', password='pa$$w0rd', ssl=True)
manager.change(new_connection)

# use connection methods
manager.create_database('db')
manager.databases()

# use session methods
manager.acl
manager.get('key')

The api decorator function allows you to return existing classes so that the methods can match the NOSQL api described in this documentation.

import nosqlapi
import pymongo

@nosqlapi.common.utils.api(database_names='databases', drop_database='delete_database', close_cursor='close')
class ApiConnection(pymongo.Connection): ...

connection = ApiConnection('localhost', 27017, 'test_database')

print(hasattr(connection, 'databases'))     # True

The global_session function allows you to instantiate a global connection and session.

import nosqlapi
import mymodule

connection = mymodule.Connection('server.local', 1241, 'new_db', username='admin', password='pa$$w0rd', ssl=True)
nosqlapi.common.utils.global_session(connection)

print(nosqlapi.CONNECTION)  # Connection object
print(nosqlapi.SESSION)     # Session object

The cursor_response function allows you to convert a Response object into a classic list of tuples.

import nosqlapi
import mymodule

connection = mymodule.Connection('server.local', 1241, 'new_db', username='admin', password='pa$$w0rd', ssl=True)
resp = connection.databases()

print(resp)                     # Response object
print(cursor_response(resp))    # [('db1', 'db2')]

The apply_vendor function allows you to rename representation object from nosqlapi to other name

>>> import nosqlapi
>>> class Response(nosqlapi.Response): ...
>>> resp = Response('some data')
>>> resp
<nosqlapi Response object>
>>> nosqlapi.apply_vendor('pymongo')
>>> resp
<pymongo Response object>