API Docs: GitDB

class ogitm.gitdb.GitDB(location)

The raw database class.

This class constructs a database instance in the location described. This is automatically created under the covers by ogitm.Model, but it can also be created and used outside the confines of Object-Model mappings. Total freedom!

Any methods called on GitDB that can’t be found will be passed to the default Table instance, so this class could be used as a simple one-table document store without worrying about tables at all. This isn’t recommended, however.

Parameters:location (str) – The path of the database

drop(table_name, force=False)

Completely and irevocably destroy a table.

Parameters:

• table_name (str) – The name of the table to destroy
• force (bool) – If true, no errors will be raised if the table does not exist

Raises:

ValueError – if the table is reserved, or could not be deleted for other reasons

table(table_name)

Create a new table.

This creates a new table in the current database. You can also use the form gitdb['table name'], which delegates to this method. If a table exists, this method will return a new instance of Table pointing to the same table. (Note that two tables pointing to the same location will always return equal.)

Parameters:table_name (str) – The name this table will take Raises:ValueError – if the name is a reserved table name

class ogitm.gitdb.Table(name, location)

A class to represent an individual table in a database

This class should only really be created by a GitDB instance, although instantiating it manually won’t actually change the way this class operates.

Parameters:

• name (str) – The name of the table
• path (str) – The path of the table (Note that this is the path to this particular table’s location, not the root path of the database.)

begin_transaction()

Opens a new transaction.

Raises:ValueError – if a transaction is already open

See also

transaction()

a context manager that automatically handles most of the details of a transaction

commit() and rollback()

methods for closing the transaction created here

commit()

Commits all work performed during a transaction.

Raises:ValueError – if this method is called inside the transaction() context manager, or if there is no open transaction when this method is called

See also

transaction()

a context manager that automatically handles most of the details of a transaction

begin_transaction()

opens up a transaction

rollback()

rolls back instead of committing

find(where)

Finds the documents that match a given query.

For details on searching, see Searching In GitDB. Searches in the raw GitDB should be documents, rather than keyword arguments, but otherwise searches are the same.

This method returns (id, document) pairs. There are also the convenience methods find_ids() and find_items(), which just return the ids and documents respectively.

Parameters:where (dict) – Search definition Returns:list[(int, dict)] – A list of matching documents

find_ids(where)

Find the ids that match a given query.

This method is the same as find(), but returns the ids rather than (id, doc) pairs.

Parameters:where (dict) – Search definition (see find()) Returns:list[int] – A list of matching document ids

find_items(where)

Find the documents that match a given query.

This method is the same as find(), but returns the documents rather than (id, doc) pairs.

Parameters:where (dict) – Search definition (see find()) Returns:list[dict] – A list of matching documents

find_one(where)

Finds one document

This method functions the same as find(), but returns just one element, or None if no element found.

Parameters:where (dict) – Search definition (see find()) Returns:(int, document) or None

get(doc_id)

Gets a document given it’s document id.

This is the simplest but least useful way of getting information out of the database. It returns the document.

Parameters:doc_id (int) – The document ID to fetch Returns:dict – The document

insert(document)

Inserts a document into this database.

Documents are key-value python dicts. Nested documents are not currently tested, and will probably break everything. Documents also can’t be scalar objects, although again that is untested and behaviour is therefore undefined in that area as well. Those should probably be tested and defined more rigorously.

Oh, and also the only allowed keys and values are the standard primitives (str, int, bool, float, etc), not other objects or collections.

If a transaction is not open, this method will commit all changes into the database.

Parameters:document (dict) – A key-val single-level dictionary Returns:int – Document ID

revert_steps(steps, doc_id=None)

Reverts the whole database a number of steps.

Parameters:

• steps (int) – The number of steps to revert
• doc_id (int) – Not implemented yet

See also

revert_to_state()

Another way of reverting changes to the database

revert_to_state(state, doc_id=None)

Reverts the whole database to a previously stored state.

Parameters:

• state (oid) – The state to return to
• doc_id (int) – Not implemented yet

See also

revert_steps()

Another way of reverting changes to the database

save_state()

A method that allows saving the state of the database

rollback()

Rolls back all work performed during a transaction.

Raises:ValueError – if this method is called inside the transaction() context manager, or if there is no open transaction when this method is called.

See also

transaction()

a context manager that automatically handles most of the details of a transaction

begin_transaction()

opens up a transaction

commit()

commits instead of rolling back

save(msg='')

Commits all current unsaved changes

Normally, this will be automatically called by any methods that make changes, or by the transaction methods. This shouldn’t be called otherwise, unless in exceptional circumstances (in which case, file an issue because something’s probably gone wrong.)

Parameters:msg (str) – This will become git’s commit message

save_state()

Returns a marker that can be used later to revert to the same state.

Because the database is built on top of git, all states are saved, and can be checked out. This method returns a marker to the particular commit that refers to the current database. Note that if the database is reverted to a position before this marker, the database can still be “for-verted” back to the marker position.

Returns:A save state marker of arbitrary type

See also

revert_to_state()

Reverts to states saved by this method

transaction()

A context manager for transactions.

Sometimes it’s more convenient to use with-blocks for transactions. This is a context manager to allow that. When entering the context, it calls begin_transaction(). When leaving the context due to normal execution, it will commit all changes. When leaving the context due to an error or exception being raised, it will revert all changes, and pass the error on up.

See also

begin_transaction(), commit(), rollback()

Methods for manually managing a transaction

transaction_open

Returns whether there is currently a transaction open.

Read-only

update(d_id, document)

Updates the document at d_id with a new document

This method replaces the document at d_id with a new document, completely deleting the old document to replace it with the new version. This is not very efficient.

See the documentation for insert() for a discussion on what actually counts as a document.

Parameters:

• d_id (int) – A previously-saved document id
• document (dict) – The document to replace with

Returns:

int – Document ID

Raises:

ValueError – if the document id does not exist