Package: harperdb
harperdbPython3 implementations of HarperDB API functions. Also provides wrappers for an object-oriented interface.Installationpip3 install harperdbRequirementsPython>=3.4requests~=2.0responses~=0.10(required for testing only)harperdb.HarperDBEach instance ofHarperDBrepresents a running HarperDB instance at a URL, passed to the constructor. Optionally implement Basic Auth as keyword arguments. HarperDB API functions are exposed as instance methods, which produce and consume JSON following the API documentation.import harperdb
db = harperdb.HarperDB(
    url=HARPERDB_URL,
    username=HARPERDB_USERNAME,
    password=HARPERDB_PASSWORD)Instance Parameters:url(string): Full URL of HarperDB instanceusername(string): (optional) Basic Auth usernamepassword(string): (optional) Basic Auth passwordtimeout(float): Seconds to wait for a server response, default 10Instance Attributes:token(string): Value used in Authorization header, orNone. The value
is generated automatically when instantiated with both username and
passwordtimeout(float): Seconds to wait for a server responseurl(string): Full URL of HarperDB instanceInstance Methods:These methods expose the HarperDB API functions, and return JSON from the target database instance atHarperDB.urlSchemas and Tables:describe_all()create_schema(schema)describe_schema(schema)drop_schema(schema)create_table(schema, table, hash_attribute)describe_table(schema, table)drop_table(schema, table)drop_attribute(schema, table, attribute)NoSQL Operations:insert(schema, table, [records])update(schema, table, [records])delete(schema, table, [hashes])search_by_hash(schema, table, [hashes], get_attributes=['*'])search_by_value(schema, table, search_attribute, search_value, get_attributes=['*'])SQL Operations:sql(SQL)CSV Operations:csv_data_load(schema, table, path, action="insert")csv_file_load(schema, table, file_path, action="insert")csv_url_load(schema, table, csv_url, action="insert")Users and Roles:add_user(role id, username, password, active=True)add_role(name, permission)alter_user(role, username, password, active=True)alter_role(id, permission)drop_role(id)drop_user(username)user_info(username)list_roles()list_users()Clustering:add_node(name, host, port, subscriptions=None)update_node(name, host, port, subscriptions=None)remove_node(name)cluster_status()Registration:registration_info()get_fingerprint()set_license(key, company)Utilities:delete_files_before(schema, table, date)export_local(path, search_operation, search_attribute=None, search_value=None, hash_values=None, sql=None, format="json")export_to_s3(aws_access_key_id, aws_secret_access_key, bucket, key, search_operation, search_attribute=None, search_value=None, hash_value=None, sql=None, format="json")read_log(limit=1000, start=0, from_date=None, to_date=None, order="desc")system_information()Jobs:get_job(id)search_jobs_by_start_date(from_date, to_date)harperdb.wrappers.HarperDBWrapperHarperDBWrapperprovides a high-level, object-oriented interface for HarperDB. From this top-level object an application programmer can make references to schemas, tables, and records, while making minimal transactions with the server when values are used or modified. Each instance ofHarperDBWrapperrepresents a running HarperDB instance at a URL, passed to the constructor. Optionally implement Basic Auth as keyword arguments.Schemas are subscriptable by name, and iterating yields instances ofHarperDBSchema. The length of aHarperDBWrapperinstance returns the number of schemas in the target database. HarperDB API functions are implemented as low-level instance methods, which produce and consume JSON following the API documentation.import harperdb
db = harperdb.wrappers.HarperDBWrapper(
    url=HARPERDB_URL,
    username=HARPERDB_USERNAME,
    password=HARPERDB_PASSWORD)
dev_schema = db.create_schema('dev')
len(db)  # returns 1
db['dev']  # returns dev_schema
for schema in db:
    schema.name  # returns "dev"Schemas can be dropped usingHarperDB.drop_schema, or using thedelkeyword andHarperDBSchema.namevalue like a dictionary:db.drop_schema('dev')
# same as
del db['dev']Instance Parameters:url(string): Full URL of HarperDB instanceusername(string): (optional) Basic Auth usernamepassword(string): (optional) Basic Auth passwordtimeout(float): Seconds to wait for a server response, default 10Instance Attributes:token(string): Value used in Authorization header, or None. The value is generated automatically when instantiated with both username and passwordtimeout(float): Seconds to wait for a server responseurl(string): Full URL of HarperDB instanceHigh-Level Instance Methods:create_schema(name): Create a schema, returnsHarperDBSchemadrop_schema(name): Drop a schemaLow-Level Instance Methods:These methods expose the HarperDB API functions, and return JSON from the target database instance atHarperDBWrapper.urlSchemas and Tables:_describe_all()_create_schema(schema)_describe_schema(schema)_drop_schema(schema)_create_table(schema, table, hash_attribute)_describe_table(schema, table)_drop_table(schema, table)_drop_attribute(schema, table, attribute)NoSQL Operations:_insert(schema, table, [records])_update(schema, table, [records])_delete(schema, table, [hashes])_search_by_hash(schema, table, [hashes], get_attributes=['*'])_search_by_value(schema, table, search_attribute, search_value, get_attributes=['*'])SQL Operations:_sql(SQL)CSV Operations:_csv_data_load(schema, table, path, action="insert")_csv_file_load(schema, table, file_path, action="insert")_csv_url_load(schema, table, csv_url, action="insert")Users and Roles:_add_user(role id, username, password, active=True)_add_role(name, permission)_alter_user(role, username, password, active=True)_alter_role(id, permission)_drop_role(id)_drop_user(username)_user_info(username)_list_roles()_list_users()Clustering:_add_node(name, host, port, subscriptions)_update_node(name, host, port, subscriptions)_remove_node(name)_cluster_status()Registration:_registration_info()_get_fingerprint()_set_license(key, company)Utilities:_delete_files_before(schema, table, date)_export_local(path, search_operation, search_attribute=None, search_value=None, hash_values=None, sql=None, format="json")_export_to_s3(aws_access_key_id, aws_secret_access_key, bucket, key, search_operation, search_attribute=None, search_value=None, hash_value=None, sql=None,, format="json")_read_log(limit=100, start=0, from=None, until=None, order="desc")_system_information()Jobs:_get_job(id)harperdb.wrappers.HarperDBSchemaTables are subscriptable by name, and iterating yields instances ofHarperDBTable. The length of aHarperDBSchemainstance returns the number of tables in the schema. Schema metadata is contained in instance attributes.You should never need to instantiate this class directly, useHarperDBWrapper.create_schemainstead.dog_table = dev_schema.create_table(
        name='dog',
        hash_attribute='id')
len(dev_schema)  # returns 1
dev_schema.database  # returns dbTables can be dropped usingHarperDBSchema.drop_table, or using thedelkeyword andHarperDBTable.namevalue like a dictionary:dev_schema.drop_table('dog')
# same as
del dev_schema['dog']Schemas can be dropped using the instance methoddev_schema.drop().Instance Attributes:name(string): Name of this schemadatabase(HarperDBWrapper): Instance of the parent databaseInstance Methods:create_table(name): Create a table, returnsHarperDBTabledrop(): Drop this schemadrop_table(name): Drop a tableharperdb.wrappers.HarperDBTableRecords are subscriptable byhash_attribute, butHarperDBTableis not iterable. The length of aHarperDBTableinstance returns the number of records in the table. Table metadata is contained in instance attributes.You should never need to instantiate this class directly, useHarperDBSchema.create_tableinstead.HarperDBTable.upsertinserts a record from a dictionary, and updates records if a value is given for the table'shash_attributeand a matching record is found in the table.penny = dog_table.upsert({
    'id': 1,
    'dog_name': 'Penny',
    'owner_name': 'Kyle',
    'breed_id': 154,
    'age': 5,
    'weight_lbs': 35,
    'adorable': True,
})
dog_table[1]  # returns penny
dog_table.record_count  # same as len(dog_table)
dog_table.__createdtime__  # returns int, Unix time with milliseconds
dog_table.created_time  # returns datetime.datetime
dog_table.hash_attribute  # returns "id"
dog_table.schema  # returns dev_schemaHarperDBTable.upsertaccepts either a dictionary of record data, or a list of such dictionaries, returning an instance ofHarperDBRecordfor each record. Any records skipped by the server are omitted from the return value.UseHarperDBTable.upsert_from_csvto load record data in bulk from a CSV file. Returns an instance ofHarperDBRecordfor each record. Any records skipped by the server are omitted from the return value.Records can be deleted usingHarperDBTable.delete, or using thedelkeyword andHarperDBTable.hash_attributevalue like a dictionary:dog_table.delete(1)
# or
del dog_table[1]Searching by a record value returns a list of matchingHarperDBRecordinstances.dog_table.search_by_value(
    attribute='name',
    value='penny')  # returns a list containing pennyTables can be dropped using the instance methoddog_table.drop().Instance Attributes:attributes(list): All record attributes (string) in this tablecreated_time(datetime.datetime): equal to__createdtime__hash_attribute(string): Primary key of this tableid(string): Unique identifier assigned to this tablename(string): Name of this tablerecord_count(int): Number of records in this tableschema(HarperDBSchema): Instance of the parent schemaupdated_time(datetime.datetime): equal to__updatedtime____createdtime__(int): Epoch time in milliseconds__updatedtime__(int): Epoch time in millisecondsInstance Methods:delete(hash): Delete a record by hash valuedrop(): Drop this tablesearch_by_value(search_attribute, search_value): Return a list of
matchingHarperDBRecordinstances.upsert(record): Insert a record from a dictionary, or list of dictionaries. If a value is given for the table's hash_attribute, and this table has a matching record, that record will be updated. Any records skipped by the server will be omitted from the return value. ReturnsHarperDBRecord, or a list ofHarperDBRecordinstances.upsert_from_csv(path): Insert records from a CSV file, with headers in the first row. Any records which have a value for the table'shash_attributewill be updated. Any records skipped by the server will be omitted from the return value. Returns a list ofHarperDBRecordinstances.harperdb.wrappers.HarperDBRecordRecord data is subscriptable by record data key, and supports item assignment. Record metadata is stored in instance attributes.You should never need to instantiate this class directly, useHarperDBTable.upsertinstead.penny['owner_name']  # returns "Kyle"
penny['age'] = 6  # Happy Birthday!
penny.__updatedtime__  # returns int, Unix time with milliseconds
penny.updated_time  # returns datetime.datetime
penny.table  # returns dog_tableRecords can be deleted using the instance methodpenny.delete().HarperDBRecord.to_dict()returns a dictionary of the record.Instance Attributes:created_time(datetime.datetime): equal to__createdtime__table(HarperDBTable): Instance of parent tableupdated_time(datetime.datetime): equal to__updatedtime____createdtime__(int): Epoch time in milliseconds__updatedtime__(int): Epoch time in millisecondsInstance Methods:delete(): Delete this recordto_dict(): Returns record data as a dictionaryharperdb.exceptions.HarperDBErrorRaised when the server returns an error (500), or a hash is not found.This is the only Exception raised explicitly.