From ab5f3a47a45d6a78cff90846ea9564add85a6a58 Mon Sep 17 00:00:00 2001 From: Sven Slootweg Date: Fri, 27 Sep 2013 09:26:30 +0200 Subject: [PATCH] Documentation for database abstraction layer --- doc/db.html | 164 +++++++++++++++++++++++++++++++++++++++++++ doc/db.zpy | 199 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 363 insertions(+) create mode 100644 doc/db.html create mode 100644 doc/db.zpy diff --git a/doc/db.html b/doc/db.html new file mode 100644 index 0000000..3cf2c4e --- /dev/null +++ b/doc/db.html @@ -0,0 +1,164 @@ + + + + + + +

Database abstraction layer

Nexus uses a custom abstraction layer for SQLite database operations. It has a NoSQL-like API, meaning that objects work like dicts or lists where possible and appropriate.
The abstraction layer can be used by importing nexus.core.db.
Important: All tables that this abstraction layer is used for, must have a ROWID alias named id.

Table of contents

  • Database([filename]) Creates a new Database connection representing an SQLite database with the given...
  • Database.setup() Attempts to set up the tables needed for Nexus in the database. If the tables...
  • Database.query(query[, params=params]) Runs a custom query against the database, and returns an sqlite3.cursor object,...
  • Database[table_name] Retrieves a DatabaseTable object representing the table in the database with the... (also: Database.get_database_table(table_name))
  • Database.get_memory_table(table_name) Retrieves a MemoryTable object representing the specified table. A MemoryTable,...
  • DatabaseTable[row_id] Retrieves a Row object representing the row in the table with the specified... (also: MemoryTable[row_id])
  • DatabaseTable[row_id] = row Inserts a new row into the database. This can not be used to edit an... (also: MemoryTable[row_id] = row)
  • DatabaseTable.append(row) Inserts a new row into the table, and lets SQLite assign it an identifier. This... (also: MemoryTable.append(row))
  • Row() Creates a new Row object. You'll only need to use this if you want to insert a...
  • Row[column_name] Returns the value of the specified column in the row.
  • Row[column_name] = value Sets (or changes) the data for the given column in the row.
  • Row.commit() Process all changes you have made to the column data for the row. This will run...
  • Row.rollback() Cancels all the changes you have made to the column data for the row, and...
Database([filename])
Creates a new Database connection representing an SQLite database with the given filename. If it does not exist, it is created.
filename
Optional. Filename of the SQLite database.
Database.setup()
Attempts to set up the tables needed for Nexus in the database. If the tables already exist, nothing happens.
Database.query(query[, params=params])
Runs a custom query against the database, and returns an sqlite3.cursor object, that you can use to retrieve the results from (using .fetchone(), .fetchmany(size), or .fetchall()). The cursor will return Row objects, like other functions in the abstraction layer do.
You'll only need this if you need to run queries that aren't covered by any of the other functions; the functions specified in the abstraction layer are prefered for performance reasons.
Database[table_name]
Database.get_database_table(table_name)
Retrieves a DatabaseTable object representing the table in the database with the specified table name. Table objects are reused where appropriate, to minimize resource usage and state issues.
While a DatabaseTable does not immediately load all data from the table like a MemoryTable does, it does retain an internal cache of retrieved rows. You will want to .purge() this cache regularly if you use the table a lot.
Important: The existence of a table is not checked. You need to make sure that the table exists by yourself, if you cannot rely on this!
table_name
The name of the table you wish to work with.
Example: Accessing a database table
Code:
db = Database("test.db")
+table = db["sample_table"]
Example: Accessing a database table through the explicit function
Code:
db = Database("test.db")
+table = db.get_database_table("sample_table")
Database.get_memory_table(table_name)
Retrieves a MemoryTable object representing the specified table. A MemoryTable, upon creation, will immediately load all data from the database table it represents, and keep it in memory. It is reused where possible, just like a DatabaseTable.
A MemoryTable is intended to be used for cases where frequent lookup of data in small tables is necessary, eliminating the SQLite lookup overhead.
Important: The existence of a table is not checked. You need to make sure that the table exists by yourself, if you cannot rely on this!
Important: If your database table is modified by another application or instance, the data in your MemoryTable will be out of sync. In this case, use a regular MemoryTable or .refresh() the data frequently.
table_name
The name of the table you wish to work with.
Example: Accessing a database table and keeping it in memory
Code:
db = Database("test.db")
+table = db.get_memory_table("sample_table")
DatabaseTable[row_id]
MemoryTable[row_id]
Retrieves a Row object representing the row in the table with the specified identifier (in the id field). Data is retrieved immediately.
row_id
The identifier of the row to retrieve.

Exceptions

KeyError
Raised when a row with the given identifier does not exist in the table.
DatabaseTable[row_id] = row
MemoryTable[row_id] = row
Inserts a new row into the database. This can not be used to edit an existing row; to do so, edit the Row object for that row directly.
If you do not want to explicitly specify a row identifier, use the .append() method instead.
row_id
The identifier to give the row in the database.
row
A Row object representing the new row to insert.

Exceptions

TypeError
Raised when a row with the given identifier already exists.
DatabaseTable.append(row)
MemoryTable.append(row)
Inserts a new row into the table, and lets SQLite assign it an identifier. This is the method you'll usually want to use.
row
A Row object representing the new row to insert.
Row()
Creates a new Row object. You'll only need to use this if you want to insert a new row into a table.
You do not need to immediately specify a table name or row data. Instead, you can just set column values on the Row object after creating it, and tell it what table to be inserted to by using any of the insertion methods on a DatabaseTable or MemoryTable.
Row[column_name]
Returns the value of the specified column in the row.
column_name
The column whose value you wish to retrieve.

Exceptions

KeyError
Returned when there is no such column in the table that the row belongs to.
Row[column_name] = value
Sets (or changes) the data for the given column in the row.
Important: The change is not immediately reflected in the database (or memory table). To apply your changes, you need to .commit().
Important: This does not check whether such a column exists! If you specify an invalid column name, the data will simply never be inserted.
column_name
The column whose value you wish to set or change.
value
The value to set the column to.
Row.commit()
Process all changes you have made to the column data for the row. This will run one or more SQL queries.
You don't need to do this when inserting a new row; the insertion methods for the table will do this for you automatically.
Row.rollback()
Cancels all the changes you have made to the column data for the row, and returns it to the original state. The "original state" will be state the row was in when you last retrieved or committed it.
Note that this will only work with uncommitted changes; after you commit a change, it is final and not reversible.
+ + diff --git a/doc/db.zpy b/doc/db.zpy new file mode 100644 index 0000000..7a378d9 --- /dev/null +++ b/doc/db.zpy @@ -0,0 +1,199 @@ +# Database abstraction layer + +Nexus uses a custom abstraction layer for SQLite database operations. It +has a NoSQL-like API, meaning that objects work like dicts or lists +where possible and appropriate. + +The abstraction layer can be used by importing `nexus.core.db`. + +! All tables that this abstraction layer is used for, **must** have a + `ROWID` alias named `id`. + +{TOC} + +^ Database([**filename**]) + + Creates a new Database connection representing an SQLite + database with the given filename. If it does not exist, it is + created. + + filename:: + **Optional.** Filename of the SQLite database. + +^ Database.setup() + + Attempts to set up the tables needed for Nexus in the database. + If the tables already exist, nothing happens. + +^ Database.query(**query**[, params=**params**]) + + Runs a custom query against the database, and returns an + sqlite3.cursor object, that you can use to retrieve the results + from (using .fetchone(), .fetchmany(**size**), or .fetchall()). + The cursor will return Row objects, like other functions in the + abstraction layer do. + + You'll only need this if you need to run queries that aren't + covered by any of the other functions; the functions specified + in the abstraction layer are prefered for performance reasons. + +^ Database[**table_name**] + Database.get_database_table(**table_name**) + + Retrieves a DatabaseTable object representing the table in the + database with the specified table name. Table objects are reused + where appropriate, to minimize resource usage and state issues. + + While a DatabaseTable does not immediately load all data from + the table like a MemoryTable does, it **does** retain an + internal cache of retrieved rows. You will want to .purge() this + cache regularly if you use the table a lot. + + ! The existence of a table is not checked. You need to make sure + that the table exists by yourself, if you cannot rely on this! + + table_name:: + The name of the table you wish to work with. + + @ Accessing a database table + + $ db = Database("test.db") + table = db["sample_table"] + + @ Accessing a database table through the explicit function + + $ db = Database("test.db") + table = db.get_database_table("sample_table") + +^ Database.get_memory_table(**table_name**) + + Retrieves a MemoryTable object representing the specified table. + A MemoryTable, upon creation, will immediately load all data + from the database table it represents, and keep it in memory. It + is reused where possible, just like a DatabaseTable. + + A MemoryTable is intended to be used for cases where frequent + lookup of data in small tables is necessary, eliminating the + SQLite lookup overhead. + + ! The existence of a table is not checked. You need to make sure + that the table exists by yourself, if you cannot rely on this! + + ! If your database table is modified by another application or + instance, the data in your MemoryTable will be out of sync. + In this case, use a regular MemoryTable or .refresh() the data + frequently. + + table_name:: + The name of the table you wish to work with. + + @ Accessing a database table and keeping it in memory + + $ db = Database("test.db") + table = db.get_memory_table("sample_table") + +^ DatabaseTable[**row_id**] + MemoryTable[**row_id**] + + Retrieves a Row object representing the row in the table with + the specified identifier (in the `id` field). Data is retrieved + immediately. + + row_id:: + The identifier of the row to retrieve. + + ### Exceptions + + KeyError:: + Raised when a row with the given identifier does not + exist in the table. + +^ DatabaseTable[**row_id**] = **row** + MemoryTable[**row_id**] = **row** + + Inserts a new row into the database. This can **not** be used to + edit an existing row; to do so, edit the Row object for that row + directly. + + If you do not want to explicitly specify a row identifier, use + the .append() method instead. + + row_id:: + The identifier to give the row in the database. + + row:: + A Row object representing the new row to insert. + + ### Exceptions + + TypeError:: + Raised when a row with the given identifier already + exists. + +^ DatabaseTable.append(**row**) + MemoryTable.append(**row**) + + Inserts a new row into the table, and lets SQLite assign it an + identifier. This is the method you'll usually want to use. + + row:: + A Row object representing the new row to insert. + +^ Row() + + Creates a new Row object. You'll only need to use this if you + want to insert a new row into a table. + + You do not need to immediately specify a table name or row data. + Instead, you can just set column values on the Row object after + creating it, and tell it what table to be inserted to by using + any of the insertion methods on a DatabaseTable or MemoryTable. + +^ Row[**column_name**] + + Returns the value of the specified column in the row. + + column_name:: + The column whose value you wish to retrieve. + + ### Exceptions + + KeyError:: + Returned when there is no such column in the table that + the row belongs to. + +^ Row[**column_name**] = **value** + + Sets (or changes) the data for the given column in the row. + + ! The change is not immediately reflected in the database (or + memory table). To apply your changes, you need to .commit(). + + ! This does not check whether such a column exists! If you + specify an invalid column name, the data will simply never be + inserted. + + column_name:: + The column whose value you wish to set or change. + + value:: + The value to set the column to. + +^ Row.commit() + + Process all changes you have made to the column data for the + row. This will run one or more SQL queries. + + You don't need to do this when inserting a new row; the + insertion methods for the table will do this for you + automatically. + +^ Row.rollback() + + Cancels all the changes you have made to the column data for the + row, and returns it to the original state. The "original state" + will be state the row was in when you last retrieved or + committed it. + + Note that this will only work with uncommitted changes; after + you commit a change, it is final and not reversible.