You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
165 lines
14 KiB
HTML
165 lines
14 KiB
HTML
<!doctype html>
|
|
<html>
|
|
<head>
|
|
<style>
|
|
body {
|
|
background-color: #F5F5F5;
|
|
font-family: sans-serif;
|
|
margin-right: 40px;
|
|
}
|
|
|
|
h2, h3, h4, h5, h6, h7
|
|
{
|
|
margin-top: 16px;
|
|
margin-bottom: 4px;
|
|
}
|
|
|
|
.children { padding-left: 40px; }
|
|
|
|
.definition
|
|
{
|
|
font-weight: bold;
|
|
margin-bottom: 32px;
|
|
}
|
|
|
|
.example
|
|
{
|
|
padding: 5px 6px;
|
|
font-weight: bold;
|
|
font-size: 15px;
|
|
background-color: #E6E6E6;
|
|
margin-top: 11px;
|
|
}
|
|
|
|
.example > .children
|
|
{
|
|
padding-top: 11px;
|
|
padding-left: 10px;
|
|
}
|
|
|
|
.example > .children > h7
|
|
{
|
|
font-size: 13px;
|
|
}
|
|
|
|
h7
|
|
{
|
|
font-size: 14px;
|
|
font-weight: bold;
|
|
margin-bottom: 2px;
|
|
}
|
|
|
|
pre
|
|
{
|
|
margin-top: 0px;
|
|
padding: 6px 7px;
|
|
background-color: #D9D9D9;
|
|
font-weight: normal;
|
|
font-size: 13px;
|
|
}
|
|
|
|
dl
|
|
{
|
|
margin: 5px 0px;
|
|
}
|
|
|
|
dt
|
|
{
|
|
font-weight: bold;
|
|
}
|
|
|
|
dd
|
|
{
|
|
font-size: 14px;
|
|
font-weight: normal;
|
|
margin-left: 8px;
|
|
}
|
|
|
|
dd > .children
|
|
{
|
|
font-size: 95%;
|
|
}
|
|
|
|
dd > .children > dl > dd
|
|
{
|
|
margin-left: 13px;
|
|
}
|
|
|
|
.exclamation
|
|
{
|
|
padding: 7px 8px;
|
|
margin: 11px 0px;
|
|
background-color: #FFE9AA;
|
|
border: 1px solid yellow;
|
|
font-size: 15px;
|
|
font-weight: normal;
|
|
}
|
|
|
|
.text
|
|
{
|
|
font-size: 15px;
|
|
font-weight: normal;
|
|
margin-bottom: 14px;
|
|
margin-top: 10px;
|
|
}
|
|
|
|
.toc
|
|
{
|
|
border: 1px solid gray;
|
|
background-color: #E6E6E6;
|
|
padding: 8px 9px;
|
|
font-size: 15px;
|
|
margin-bottom: 12px;
|
|
}
|
|
|
|
.toc h2
|
|
{
|
|
margin: 0px 0px 3px 0px;
|
|
font-size: 19px;
|
|
}
|
|
|
|
.toc ul
|
|
{
|
|
margin-top: 0px;
|
|
margin-bottom: 0px;
|
|
padding-left: 25px;
|
|
}
|
|
|
|
.toc li
|
|
{
|
|
margin-bottom: 2px;
|
|
}
|
|
|
|
.toc .alternatives
|
|
{
|
|
font-size: 12px;
|
|
}
|
|
|
|
.toc a
|
|
{
|
|
color: #292722;
|
|
}
|
|
|
|
.toc a:hover
|
|
{
|
|
color: black;
|
|
}
|
|
|
|
.fixed
|
|
{
|
|
font-family: monospace;
|
|
background-color: white;
|
|
padding: 1px 4px;
|
|
border: 1px solid silver;
|
|
border-radius: 4px;
|
|
}
|
|
</style>
|
|
</head>
|
|
<body>
|
|
<div class="children"><h1>Database abstraction layer</h1><div class="text">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.</div><div class="text">The abstraction layer can be used by importing <span class="fixed">nexus.core.db</span>.</div><div class="exclamation"><strong>Important:</strong> All tables that this abstraction layer is used for, <em>must</em> have a <span class="fixed">ROWID</span> alias named <span class="fixed">id</span>. <div class="children"></div></div><div class="toc"><h2>Table of contents</h2><ul><li><a href="#Databasefilename">Database([filename])</a> Creates a new Database connection representing an SQLite database with the given... </li><li><a href="#Database_setup">Database.setup()</a> Attempts to set up the tables needed for Nexus in the database. If the tables... </li><li><a href="#Database_queryqueryparamsparams">Database.query(query[, params=params])</a> Runs a custom query against the database, and returns an sqlite3.cursor object,... </li><li><a href="#Databasetable_name">Database[table_name]</a> Retrieves a DatabaseTable object representing the table in the database with the... <span class="alternatives">(also: Database.get_database_table(table_name))</span></li><li><a href="#Database_get_memory_tabletable_name">Database.get_memory_table(table_name)</a> Retrieves a MemoryTable object representing the specified table. A MemoryTable,... </li><li><a href="#DatabaseTablerow_id">DatabaseTable[row_id]</a> Retrieves a Row object representing the row in the table with the specified... <span class="alternatives">(also: MemoryTable[row_id])</span></li><li><a href="#DatabaseTablerow_idrow">DatabaseTable[row_id] = row</a> Inserts a new row into the database. This can <em>not</em> be used to edit an... <span class="alternatives">(also: MemoryTable[row_id] = row)</span></li><li><a href="#DatabaseTable_appendrow">DatabaseTable.append(row)</a> Inserts a new row into the table, and lets SQLite assign it an identifier. This... <span class="alternatives">(also: MemoryTable.append(row))</span></li><li><a href="#DatabaseTable_purge">DatabaseTable.purge()</a> Purges the internal row cache of a DatabaseTable. </li><li><a href="#MemoryTable_refresh">MemoryTable.refresh()</a> Replaces the current copy of the table in memory, with a newly retrieved copy.... </li><li><a href="#Row">Row()</a> Creates a new Row object. You'll only need to use this if you want to insert a... </li><li><a href="#Rowcolumn_name">Row[column_name]</a> Returns the value of the specified column in the row. </li><li><a href="#Rowcolumn_namevalue">Row[column_name] = value</a> Sets (or changes) the data for the given column in the row. </li><li><a href="#Row_commit">Row.commit()</a> Process all changes you have made to the column data for the row. This will run... </li><li><a href="#Row_rollback">Row.rollback()</a> Cancels all the changes you have made to the column data for the row, and... </li></ul></div><div class="definition"><a name="Databasefilename">Database([<em>filename</em>]) <div class="children"><div class="text">Creates a new Database connection representing an SQLite database with the given filename. If it does not exist, it is created.</div><dl><dt>filename</dt><dd><em>Optional.</em> Filename of the SQLite database.<div class="children"></div></dd></dl></div></a></div><div class="definition"><a name="Database_setup">Database.setup() <div class="children"><div class="text">Attempts to set up the tables needed for Nexus in the database. If the tables already exist, nothing happens.</div></div></a></div><div class="definition"><a name="Database_queryqueryparamsparams">Database.query(<em>query</em>[, params=<em>params</em>]) <div class="children"><div class="text">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(<em>size</em>), or .fetchall()). The cursor will return Row objects, like other functions in the abstraction layer do.</div><div class="text">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.</div></div></a></div><div class="definition"><a name="Databasetable_name">Database[<em>table_name</em>]<br>Database.get_database_table(<em>table_name</em>) <div class="children"><div class="text">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.</div><div class="text">While a DatabaseTable does not immediately load all data from the table like a MemoryTable does, it <em>does</em> retain an internal cache of retrieved rows. You will want to .purge() this cache regularly if you use the table a lot.</div><div class="exclamation"><strong>Important:</strong> 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! <div class="children"></div></div><dl><dt>table_name</dt><dd>The name of the table you wish to work with.<div class="children"></div></dd></dl><div class="example">Example: Accessing a database table <div class="children"><h7>Code:</h7><pre class="code">db = Database("test.db")
|
|
table = db["sample_table"]</pre></div></div><div class="example">Example: Accessing a database table through the explicit function <div class="children"><h7>Code:</h7><pre class="code">db = Database("test.db")
|
|
table = db.get_database_table("sample_table")</pre></div></div></div></a></div><div class="definition"><a name="Database_get_memory_tabletable_name">Database.get_memory_table(<em>table_name</em>) <div class="children"><div class="text">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.</div><div class="text">A MemoryTable is intended to be used for cases where frequent lookup of data in small tables is necessary, eliminating the SQLite lookup overhead.</div><div class="exclamation"><strong>Important:</strong> 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! <div class="children"></div></div><div class="exclamation"><strong>Important:</strong> 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. <div class="children"></div></div><dl><dt>table_name</dt><dd>The name of the table you wish to work with.<div class="children"></div></dd></dl><div class="example">Example: Accessing a database table and keeping it in memory <div class="children"><h7>Code:</h7><pre class="code">db = Database("test.db")
|
|
table = db.get_memory_table("sample_table")</pre></div></div></div></a></div><div class="definition"><a name="DatabaseTablerow_id">DatabaseTable[<em>row_id</em>]<br>MemoryTable[<em>row_id</em>] <div class="children"><div class="text">Retrieves a Row object representing the row in the table with the specified identifier (in the <span class="fixed">id</span> field). Data is retrieved immediately.</div><dl><dt>row_id</dt><dd>The identifier of the row to retrieve.<div class="children"></div></dd></dl><h3>Exceptions</h3><dl><dt>KeyError</dt><dd>Raised when a row with the given identifier does not exist in the table.<div class="children"></div></dd></dl></div></a></div><div class="definition"><a name="DatabaseTablerow_idrow">DatabaseTable[<em>row_id</em>] = <em>row</em><br>MemoryTable[<em>row_id</em>] = <em>row</em> <div class="children"><div class="text">Inserts a new row into the database. This can <em>not</em> be used to edit an existing row; to do so, edit the Row object for that row directly.</div><div class="text">If you do not want to explicitly specify a row identifier, use the .append() method instead.</div><dl><dt>row_id</dt><dd>The identifier to give the row in the database.<div class="children"></div></dd></dl><dl><dt>row</dt><dd>A Row object representing the new row to insert.<div class="children"></div></dd></dl><h3>Exceptions</h3><dl><dt>TypeError</dt><dd>Raised when a row with the given identifier already exists.<div class="children"></div></dd></dl></div></a></div><div class="definition"><a name="DatabaseTable_appendrow">DatabaseTable.append(<em>row</em>)<br>MemoryTable.append(<em>row</em>) <div class="children"><div class="text">Inserts a new row into the table, and lets SQLite assign it an identifier. This is the method you'll usually want to use.</div><dl><dt>row</dt><dd>A Row object representing the new row to insert.<div class="children"></div></dd></dl></div></a></div><div class="definition"><a name="DatabaseTable_purge">DatabaseTable.purge() <div class="children"><div class="text">Purges the internal row cache of a DatabaseTable.</div><div class="exclamation"><strong>Important:</strong> You cannot use this method for a MemoryTable! Use .refresh() instead. <div class="children"></div></div></div></a></div><div class="definition"><a name="MemoryTable_refresh">MemoryTable.refresh() <div class="children"><div class="text">Replaces the current copy of the table in memory, with a newly retrieved copy. You'll need to call this regularly when you have multiple applications modifying the same table, to prevent going out of sync. If synchronized data is absolutely essential at all times, use a DatabaseTable instead.</div><div class="exclamation"><strong>Important:</strong> You cannot use this method for a DatabaseTable! Use .purge() instead. <div class="children"></div></div></div></a></div><div class="definition"><a name="Row">Row() <div class="children"><div class="text">Creates a new Row object. You'll only need to use this if you want to insert a new row into a table.</div><div class="text">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.</div></div></a></div><div class="definition"><a name="Rowcolumn_name">Row[<em>column_name</em>] <div class="children"><div class="text">Returns the value of the specified column in the row.</div><dl><dt>column_name</dt><dd>The column whose value you wish to retrieve.<div class="children"></div></dd></dl><h3>Exceptions</h3><dl><dt>KeyError</dt><dd>Returned when there is no such column in the table that the row belongs to.<div class="children"></div></dd></dl></div></a></div><div class="definition"><a name="Rowcolumn_namevalue">Row[<em>column_name</em>] = <em>value</em> <div class="children"><div class="text">Sets (or changes) the data for the given column in the row.</div><div class="exclamation"><strong>Important:</strong> The change is not immediately reflected in the database (or memory table). To apply your changes, you need to .commit(). <div class="children"></div></div><div class="exclamation"><strong>Important:</strong> This does not check whether such a column exists! If you specify an invalid column name, the data will simply never be inserted. <div class="children"></div></div><dl><dt>column_name</dt><dd>The column whose value you wish to set or change.<div class="children"></div></dd></dl><dl><dt>value</dt><dd>The value to set the column to.<div class="children"></div></dd></dl></div></a></div><div class="definition"><a name="Row_commit">Row.commit() <div class="children"><div class="text">Process all changes you have made to the column data for the row. This will run one or more SQL queries.</div><div class="text">You don't need to do this when inserting a new row; the insertion methods for the table will do this for you automatically.</div></div></a></div><div class="definition"><a name="Row_rollback">Row.rollback() <div class="children"><div class="text">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.</div><div class="text">Note that this will only work with uncommitted changes; after you commit a change, it is final and not reversible.</div></div></a></div></div>
|
|
</body>
|
|
</html>
|