Skip to content

4.0.0
Compare
Choose a tag to compare
@joowani joowani released this 08 May 12:20
4.0.0
d04f3db

New Features

  • Manage documents using IDs (more examples here):

    col.get('foo/bar')                        # Get by document ID
col.get('bar')                            # Get by document key 
col.get({'_id': 'foo/bar'})               # Get by document body with ID
col.get({'_key': 'bar'})                  # Get by document body with key
col.update({'_id': 'foo/bar', 'val': 1})  # Update by document ID
col.update({'_key': 'bar', 'val': 1})     # Update by document key
col.replace({'_id': 'foo/bar', 'val': 2}) # Replace by document ID
col.replace({'_key': 'bar', 'val': 2})    # Replace by document key
col.delete('foo/bar')                     # Delete by document ID
col.delete('bar')                         # Delete by document key
col.delete({'_id': 'foo/bar'})            # Delete by document body with ID
col.delete({'_key': 'bar'})               # Delete by document body with key

  • Perform basic document operations directly from Database (more examples here):

    db.insert_document('students', {'_key': 'dave'})
db.has_document('students/dave')
db.document('students/dave')
db.update_document({'_id': 'students/dave', 'val': 1})
db.replace_document({'_id': 'students/dave', 'val': 2})
db.delete_document('students/dave')

  • Manage vertices and edges directly from Graph (more examples here):

    graph.insert_vertex('profs', {'_key': 'jon', 'name': 'Jon'})
graph.update_vertex({'_id': 'profs/jon', 'age': 35})
graph.replace_vertex({'_id': 'profs/jon', 'name': 'Jon', 'age':36})
graph.has_vertex('profs/jon')
graph.vertex('profs/jon')
graph.delete_vertex('profs/jon')
graph.insert_edge('teach', {'_id': 'teach/1', '_from': 'profs/jon', '_to': 'lectures/CS101'})
graph.replace_edge({'_id': 'teach/1', '_from': 'profs/jon', '_to': 'lectures/CS101'})
graph.update_edge({'_id': 'teach/1', 'online': True})
graph.has_edge('teach/1')
graph.edge('teach/1')
graph.delete_edge('teach/1')
graph.link('teach', 'profs/jon', 'lectures/CS101')
graph.edges('teach', 'profs/jon', direction='out')

  • Executing a transaction now returns TransactionJob objects, allowing result retrieval after commit (see examples, restrictions and caveats here):

    with db.begin_transaction() as txn_db:
    txn_col = txn_db.collection('students')
    job1 = txn_col.insert({'_key': 'Abby'})
    job2 = txn_col.insert({'_key': 'John'})
    job3 = txn_col.insert({'_key': 'Mary'})

assert job1.result()['_id'] == 'students/Abby'
assert job2.result()['_id'] == 'students/John'
assert job3.result()['_id'] == 'students/Mary'

  • Added new methods to Cursor. Methods Cursor.pop and Cursor.fetch lets you control when new batches are fetched from server. See here for details.

  • Added new methods to AQL. See here for details.

  • Added new methods to Graph. See here for details.

  • Added new methods to EdgeCollection. See here for details.

  • Added new method Database.ping. See here for details.

  • Added support for Foxx. See here for details.

  • Improved error handling: the catch-all exception ArangoError now splits further into ArangoClientError and ArangoServerErrror, allowing you to differentiate errors coming from server vs. client. Server exceptions, furthermore, give you access to HTTP request response metadata (e.g. status code, payload, headers). See here for details.

Non-Backward Compatible Changes

Unfortunately, many updates in 4.0.0 are not backward compatible. If you are upgrading, you will need to change your code in several places (sorry for the inconvenience).

High Level Changes

  • Some APIs were rather awkward and didn't make sense. For example, ArangoClient asks you for username and password before you specify the database. The initialization and the usage of ArangoClient were made simpler and more intuitive. See here for examples.

  • In previous versions of python-arango, attempt to abstract away ArangoDB's _system database did more harm than good. One example is the duplicated set of admin methods in ArangoClient and Database. These admin methods are now accessible from Database only, and you must connect to _system database explicitly. See here for examples.

  • Some method names and signatures were modified for consistency. This is less likely to break your code if you were using keyword arguments over positional ones. Some examples are document management methods such as update, replace and delete. You should carry out a comprehensive review of all methods used in your code with new API specification.

  • Some modules were moved and/or renamed. Imports other than from arango import ArangoClient and from arango.exceptions import * may not work anymore. Python-arango was designed such that the two imports are all you need for complete feature access.

  • Some classes were renamed (e.g. Database to StandardDatabase, Collection to StandardCollection). As long as you are not importing classes directly, this change alone should not break your code. Note that StandardDatabase and StandardCollection are still referred to as Database and Collection in this changelog.

Databases

  • User and access/permission management in python-arango was poorly designed (perhaps "broken" is the better word). It has been completely overhauled with new set of methods. Old methods such as Database.grant_user_access and Database.grant_revoke_access were removed. See here for details.
  • Removed parameter user in method Database.databases (redundant).
  • Removed method Database.sleep (not supported by ArangoDB anymore).
  • Removed method Database.execute (not supported by ArangoDB anymore).
  • Removed parameter names_only in methods Database.collections, Database.graphs and Database.users (redundant).

Async Execution, Batch Execution and Transactions

  • Renamed method Database.async to Database.begin_async_execution. While rest of the API for async execution remains more or less the same, underlying class structures were overhauled. See here for details.
  • Renamed method Database.batch to Database.begin_batch_execution. While rest of the API for batch execution remains more or less the same, underlying class structures were overhauled. See here for details.
  • Renamed method Database.transaction to Database.begin_transaction. While rest of the API for transactions remains more or less the same, underlying class structures were overhauled. See here for details.
  • Removed parameter commit_on_error and method clear from batch execution and transactions.
  • Multiple commits using the same batch execution or transaction objects are not allowed anymore.
  • Removed parameter raise_errors in methods AsyncJob.result and BatchJob.result. Job exceptions are now always raised.

Collections and Documents

  • All document revisions are now checked by default. In other words, all check_rev parameters in document management methods default to True.
  • Method Collection.unload now returns a boolean.
  • Method Collection.load now returns a boolean.
  • Method Collection.rename now returns a boolean.
  • Method Collection.truncate now returns a boolean.
  • Method Collection.checksum now returns a string.
  • Removed parameter inclusive in method Collection.find_in_range. Now it is always inclusive on both ends.
  • Renamed parameter offset to skip in method Collection.find.
  • Renamed parameter offset to skip in method Collection.find_in_range.
  • Parameter limit now defaults to 100 in methods Collection.find, Collection.find_near, Collection.find_in_range, Collection.find_in_box and Collection.find_by_text.

Graphs

  • Changed the signature of method Graph.create_edge_definition, and edge definitions in general (see here for details):

    # old
{
    'name': 'teach',
    'from_collections': ['teachers'],
    'to_collections': ['lectures']
}

# new
{
    'edge_collection': 'teach',
    'from_vertex_collections': ['teachers'],
    'to_vertex_collections': ['lectures']
}

  • Removed method Graph.orphan_collections. Use Graph.edge_definitions instead.

Cursors

  • Removed arango.cursor.ExportCursor. All cursors are now instances of arango.cursor.Cursor.

Pregel

  • Refactored Pregel API. See here for new usage examples.

HTTP Client

  • Simplified the way custom HTTP clients are defined. See here for details.

Error Handling

  • Removed exception arango.exceptions.CollectionBadStatusError.
  • Removed exception arango.exceptions.ServerSleepError.
  • Removed exception arango.exceptions.UserAccessError.
  • Removed exception arango.exceptions.UserGrantAccessError.
  • Removed exception arango.exceptions.UserRevokeAccessError.
  • Removed exception arango.exceptions.ClusterTestError.
  • Removed exception arango.exceptions.GraphGetError.
  • Removed exception arango.exceptions.OrphanCollectionListError.
  • Renamed exception arango.exceptions.TransactionError to arango.exceptions.TransactionExecuteError.
  • All ignore_missing parameters now default to False.

Logging

  • Removed python-arango's internal logger (redundant). You can instead increase the verbosity of requests logger, or inject your own logger using a custom HTTP client. See here for examples.
Assets 2
Loading