API Documentation¶
bauble
¶
The top level module for Bauble.
-
bauble.
version
= '1.0.52'¶ str(object=’‘) -> string
Return a nice string representation of the object. If the argument is a string, the return value is the same object.
-
bauble.
gui
= None¶ bauble.gui is the instance
bauble.ui.GUI
-
bauble.
command_handler
(cmd, arg)¶ Call a command handler.
Parameters: - cmd (str) – The name of the command to call
- arg (list) – The arg to pass to the command handler
-
bauble.
main
(uri=None)¶ Run the main Bauble application.
Parameters: uri (str) – the URI of the database to connect to. For more information about database URIs see http://www.sqlalchemy.org/docs/05/dbengine.html#create-engine-url-arguments
-
bauble.
main_is_frozen
()¶ Return True if we are running in a py2exe environment, else return False
-
bauble.
quit
()¶ Stop all tasks and quit Bauble.
-
bauble.
save_state
()¶ Save the gui state and preferences.
bauble.db
¶
-
bauble.db.
Session
= None¶ bauble.db.Session is created after the database has been opened with
bauble.db.open()
. bauble.db.Session should be used when you need to do ORM based activities on a bauble database. To create a new Session use::Uncategorizedsession = bauble.db.Session()When you are finished with the session be sure to close the session with
session.close()
. Failure to close sessions can lead to database deadlocks, particularly when using PostgreSQL based databases.
-
bauble.db.
engine
= None¶ A
sqlalchemy.engine.base.Engine
used as the default connection to the database.
-
bauble.db.
Base
= <class 'sqlalchemy.ext.declarative.api.Base'>¶ The most base type
-
bauble.db.
Base
¶ All tables/mappers in Bauble which use the SQLAlchemy declarative plugin for declaring tables and mappers should derive from this class.
An instance of
sqlalchemy.ext.declarative.Base
-
db.
metadata
= MetaData(bind=None)¶
-
bauble.db.
metadata
¶ The default metadata for all Bauble tables.
An instance of
sqlalchemy.schema.MetaData
-
class
bauble.db.
MapperBase
(classname, bases, dict_)¶ MapperBase adds the id, _created and _last_updated columns to all tables.
In general there is no reason to use this class directly other than to extend it to add more default columns to all the bauble tables.
-
class
bauble.db.
HistoryExtension
¶ Bases:
sqlalchemy.orm.deprecated_interfaces.MapperExtension
HistoryExtension is a
MapperExtension
that is added to all clases that inherit from bauble.db.Base so that all inserts, updates, and deletes made to the mapped objects are recorded in the history table.
-
class
bauble.db.
History
(**kwargs)¶ Bases:
sqlalchemy.ext.declarative.api.Base
The history table records ever changed made to every table that inherits from Base
Table name: history
Columns: - id:
sqlalchemy.types.Integer
A unique identifier.
- table_name:
sqlalchemy.types.String
The name of the table the change was made on.
- table_id:
sqlalchemy.types.Integer
The id in the table of the row that was changed.
- values:
sqlalchemy.types.String
The changed values.
- operation:
sqlalchemy.types.String
The type of change. This is usually one of insert, update or delete.
- user:
sqlalchemy.types.String
The name of the user who made the change.
- timestamp:
sqlalchemy.types.DateTime
When the change was made.
- id:
-
bauble.db.
open
(uri, verify=True, show_error_dialogs=False)¶ Open a database connection. This function sets bauble.db.engine to the opened engined.
Return bauble.db.engine if successful else returns None and bauble.db.engine remains unchanged.
Parameters: - uri (str) – The URI of the database to open.
- verify (bool) – Where the database we connect to should be verified as one created by Bauble. This flag is used mostly for testing.
- show_error_dialogs (bool) – A flag to indicate whether the error dialogs should be displayed. This is used mostly for testing.
-
bauble.db.
create
(import_defaults=True)¶ Create new Bauble database at the current connection
Parameters: import_defaults (bool) – A flag that is passed to each plugins install() method to indicate where it should import its default data. This is mainly used for testing. The default value is True
-
bauble.db.
verify_connection
(engine, show_error_dialogs=False)¶ Test whether a connection to an engine is a valid Bauble database. This method will raise an error for the first problem it finds with the database.
Parameters: - engine (
sqlalchemy.engine.Engine
) – the engine to test - show_error_dialogs (bool) – flag for whether or not to show message dialogs detailing the error, default=False
- engine (
bauble.connmgr
¶
bauble.editor
¶
bauble.i18n
¶
The i18n module defines the _() function for creating translatable strings.
_() is added to the Python builtins so there is no reason to import
this module more than once in an application. It is usually imported
in bauble
bauble.ui
¶
bauble.meta
¶
-
bauble.meta.
get_default
(name, default=None, session=None)¶ Get a BaubleMeta object with name. If the default value is not None then a BaubleMeta object is returned with name and the default value given.
If a session instance is passed (session != None) then we don’t commit the session.
-
class
bauble.meta.
BaubleMeta
(**kwargs)¶ Bases:
sqlalchemy.ext.declarative.api.Base
The BaubleMeta class is used to set and retrieve meta information based on key/name values from the bauble meta table.
Table name: bauble
Columns: - name:
The name of the data.
- value:
The value.
bauble.paths
¶
Access to standard paths used by Bauble.
-
bauble.paths.
main_dir
()¶ Returns the path of the bauble executable.
-
bauble.paths.
lib_dir
()¶ Returns the path of the bauble module.
-
bauble.paths.
locale_dir
()¶ Returns the root path of the locale files
-
bauble.paths.
user_dir
()¶ Returns the path to where Bauble settings should be saved.
bauble.pluginmgr
¶
Manage plugin registry, loading, initialization and installation. The plugin manager should be started in the following order:
1. load the plugins: search the plugin directory for plugins, populates the plugins dict (happens in load())
2. install the plugins if not in the registry, add properly installed plugins in to the registry (happens in load())
- initialize the plugins (happens in init())
-
bauble.pluginmgr.
register_command
(handler)¶ Register command handlers. If a command is a duplicate then it will overwrite the old command of the same name.
Parameters: handler – A class which extends pluginmgr.CommandHandler
-
bauble.pluginmgr.
load
(path=None)¶ Search the plugin path for modules that provide a plugin. If path is a directory then search the directory for plugins. If path is None then use the default plugins path, bauble.plugins.
This method populates the pluginmgr.plugins dict and imports the plugins but doesn’t do any plugin initialization.
Parameters: path (str) – the path where to look for the plugins
-
bauble.pluginmgr.
init
(force=False)¶ Initialize the plugin manager.
1. Check for and install any plugins in the plugins dict that aren’t in the registry. 2. Call each init() for each plugin the registry in order of dependency 3. Register the command handlers in the plugin’s commands[]
NOTE: This is called after after Bauble has created the GUI and established a connection to a database with db.open()
-
bauble.pluginmgr.
install
(plugins_to_install, import_defaults=True, force=False)¶ Parameters: - plugins_to_install – A list of plugins to install. If the string “all” is passed then install all plugins listed in the bauble.pluginmgr.plugins dict that aren’t already listed in the plugin registry.
- import_defaults (bool) – Flag passed to the plugin’s install() method to indicate whether it should import its default data.
- force (book) – Force, don’t ask questions.
-
class
bauble.pluginmgr.
Plugin
¶ - tools:
- a list of BaubleTool classes that this plugin provides, the tools’ category and label will be used in Bauble’s “Tool” menu
- depends:
- a list of names classes that inherit from BaublePlugin that this plugin depends on
- cmds:
- a map of commands this plugin handled with callbacks, e.g dict(‘cmd’, lambda x: handler)
- description:
- a short description of the plugin
-
classmethod
init
()¶ init() is run when Bauble is first started
-
classmethod
install
(import_defaults=True)¶ install() is run when a new plugin is installed, it is usually only run once for the lifetime of the plugin
-
class
bauble.pluginmgr.
Tool
¶
-
class
bauble.pluginmgr.
View
(*args, **kwargs)¶
-
class
bauble.pluginmgr.
CommandHandler
¶
bauble.prefs
¶
bauble.task
¶
The bauble.task module allows you to queue up long running tasks. The running tasks still block but allows the GUI to update.
-
bauble.task.
queue
(task)¶ Run a task.
task should be a generator with side effects. it does not matter what it yields, it is important that it does stop from time to time yielding whatever it wants to, and causing the side effect it has to cause.
-
bauble.task.
set_message
(msg)¶ A convenience function for setting a message on the statusbar. Returns the message id
-
bauble.task.
clear_messages
()¶ Clear all the messages from the statusbar that were set with
bauble.task.set_message()
bauble.types
¶
-
class
bauble.btypes.
Enum
(values, empty_to_none=False, strict=True, translations={}, **kwargs)¶ Bases:
sqlalchemy.sql.type_api.TypeDecorator
A database independent Enum type. The value is stored in the database as a Unicode string.
-
class
bauble.btypes.
Date
(*args, **kwargs)¶ Bases:
sqlalchemy.sql.type_api.TypeDecorator
A Date type that allows Date strings
-
class
bauble.btypes.
DateTime
(*args, **kwargs)¶ Bases:
sqlalchemy.sql.type_api.TypeDecorator
A DateTime type that allows strings
bauble.utils
¶
A common set of utility functions used throughout Bauble.
-
bauble.utils.
find_dependent_tables
(table, metadata=None)¶ Return an iterator with all tables that depend on table. The tables are returned in the order that they depend on each other. For example you know that table[0] does not depend on tables[1].
Parameters: - table – The tables who dependencies we want to find
- metadata – The
sqlalchemy.engine.MetaData
object that holds the tables to search through. If None then use bauble.db.metadata
-
bauble.utils.
tree_model_has
(tree, value)¶ Return True or False if value is in the tree.
-
bauble.utils.
search_tree_model
(parent, data, cmp=<function <lambda>>)¶ Return a iterable of gtk.TreeIter instances to all occurences of data in model
Parameters: - parent – a gtk.TreeModel or a gtk.TreeModelRow instance
- data – the data to look for
- cmp – the function to call on each row to check if it matches data, default is C{lambda row, data: row[0] == data}
-
bauble.utils.
clear_model
(obj_with_model)¶ Parameters: obj_with_model – a gtk Widget that has a gtk.TreeModel that can be retrieved with obj_with_mode.get_model Remove the model from the object, deletes all the items in the model, clear the model and then delete the model and set the model on the object to None
-
bauble.utils.
combo_set_active_text
(combo, value)¶ does the same thing as set_combo_from_value but this looks more like a GTK+ method
-
bauble.utils.
set_combo_from_value
(combo, value, cmp=<function <lambda>>)¶ Find value in combo model and set it as active, else raise ValueError cmp(row, value) is the a function to use for comparison
Note
if more than one value is found in the combo then the first one in the list is set
-
bauble.utils.
combo_get_value_iter
(combo, value, cmp=<function <lambda>>)¶ Returns a gtk.TreeIter that points to first matching value in the combo’s model.
Parameters: - combo – the combo where we should search
- value – the value to search for
- cmp – the method to use to compare rows in the combo model and value, the default is C{lambda row, value: row[0] == value}
Note
if more than one value is found in the combo then the first one in the list is returned
-
bauble.utils.
set_widget_value
(widget, value, markup=False, default=None, index=0)¶ Parameters: - widget – an instance of gtk.Widget
- value – the value to put in the widget
- markup – whether or not value is markup
- default – the default value to put in the widget if the value is None
- index – the row index to use for those widgets who use a model
Note
any values passed in for widgets that expect a string will call the values __str__ method
-
bauble.utils.
create_message_dialog
(msg, type=<enum GTK_MESSAGE_INFO of type GtkMessageType>, buttons=<enum GTK_BUTTONS_OK of type GtkButtonsType>, parent=None)¶ Create a message dialog.
Parameters: - msg – The markup to use for the message. The value should be escaped in case it contains any HTML entities.
- type – A GTK message type constant. The default is gtk.MESSAGE_INFO.
- buttons – A GTK buttons type constant. The default is gtk.BUTTONS_OK.
- parent – The parent window for the dialog
Returns a
gtk.MessageDialog
-
bauble.utils.
message_dialog
(msg, type=<enum GTK_MESSAGE_INFO of type GtkMessageType>, buttons=<enum GTK_BUTTONS_OK of type GtkButtonsType>, parent=None)¶ Create a message dialog with
bauble.utils.create_message_dialog()
and run and destroy it.Returns the dialog’s response.
-
bauble.utils.
create_yes_no_dialog
(msg, parent=None)¶ Create a dialog with yes/no buttons.
-
bauble.utils.
yes_no_dialog
(msg, parent=None, yes_delay=-1)¶ Create and run a yes/no dialog.
Return True if the dialog response equals gtk.RESPONSE_YES
Parameters: - msg – the message to display in the dialog
- parent – the dialog’s parent
- yes_delay – the number of seconds before the yes button should become sensitive
-
bauble.utils.
create_message_details_dialog
(msg, details, type=<enum GTK_MESSAGE_INFO of type GtkMessageType>, buttons=<enum GTK_BUTTONS_OK of type GtkButtonsType>, parent=None)¶ Create a message dialog with a details expander.
-
bauble.utils.
message_details_dialog
(msg, details, type=<enum GTK_MESSAGE_INFO of type GtkMessageType>, buttons=<enum GTK_BUTTONS_OK of type GtkButtonsType>, parent=None)¶ Create and run a message dialog with a details expander.
-
bauble.utils.
setup_text_combobox
(combo, values=None, cell_data_func=None)¶ Configure a gtk.ComboBox as a text combobox
NOTE: If you pass a cell_data_func that is a method of an object that holds a reference to combo then the object will not be properly garbage collected. To avoid this problem either don’t pass a method of object or make the method static
Parameters: - combo – gtk.ComboBox
- values – list vales or gtk.ListStore
- cell_date_func –
Associate a button with entry so that when the button is clicked a date is inserted into the entry.
Parameters: - view – a bauble.editor.GenericEditorView
- entry – the entry that the data goes into
- button – the button that enters the data in entry
- date_func – the function that returns a string represention of the date
-
bauble.utils.
to_unicode
(obj, encoding='utf-8')¶ Return obj converted to unicode. If obj is already a unicode object it will not try to decode it to converted it to <encoding> but will just return the original obj
-
bauble.utils.
utf8
(obj)¶ This function is an alias for to_unicode(obj, ‘utf-8’)
-
bauble.utils.
xml_safe
(obj, encoding='utf-8')¶ Return a string with character entities escaped safe for xml, if the str parameter is a string a string is returned, if str is a unicode object then a unicode object is returned
-
bauble.utils.
xml_safe_utf8
(obj)¶ This method is deprecated and just returns xml_safe(obj)
-
bauble.utils.
natsort_key
(obj)¶ a key getter for sort and sorted function
the sorting is done on return value of obj.__str__() so we can sort objects as well, i don’t know if this will cause problems with unicode
use like: sorted(some_list, key=utils.natsort_key)
-
bauble.utils.
delete_or_expunge
(obj)¶ If the object is in object_session(obj).new then expunge it from the session. If not then session.delete it.
-
bauble.utils.
reset_sequence
(column)¶ If column.sequence is not None or the column is an Integer and column.autoincrement is true then reset the sequence for the next available value for the column...if the column doesn’t have a sequence then do nothing and return
The SQL statements are executed directly from db.engine
This function only works for PostgreSQL database. It does nothing for other database engines.
-
bauble.utils.
make_label_clickable
(label, on_clicked, *args)¶ Parameters: - label – a gtk.Label that has a gtk.EventBox as its parent
- on_clicked – callback to be called when the label is clicked on_clicked(label, event, data)
-
bauble.utils.
enum_values_str
(col)¶ Parameters: col – a string if table.col where col is an enum type return a string with of the values on an enum type join by a comma
-
bauble.utils.
which
(filename, path=None)¶ Return first occurence of file on the path.
-
bauble.utils.
ilike
(col, val, engine=None)¶ Return a cross platform ilike function.
-
bauble.utils.
range_builder
(text)¶ Return a list of numbers from a string range of the form 1-3,4,5
-
bauble.utils.
topological_sort
(items, partial_order)¶ Perform topological sort.
Parameters: - items – a list of items to be sorted.
- partial_order – a list of pairs. If pair (a,b) is in it, it means that item a should appear before item b. Returns a list of the items in one of the possible orders, or None if partial_order contains a loop.
-
bauble.utils.
get_distinct_values
(column, session)¶ Return a list of all the distinct values in a table column
-
bauble.utils.
get_invalid_columns
(obj, ignore_columns=['id'])¶ Return column names on a mapped object that have values which aren’t valid for the model.
Invalid columns meet the following criteria: - nullable columns with null values - ...what else?
-
bauble.utils.
get_urls
(text)¶ Return tuples of http/https links and labels for the links. To label a link prefix it with [label text], e.g. [BBG]http://belizebotanic.org
-
class
bauble.utils.
GenericMessageBox
¶ Bases:
gtk.EventBox
Abstract class for showing a message box at the top of an editor.
-
class
bauble.utils.
MessageBox
(msg=None, details=None)¶ Bases:
bauble.utils.GenericMessageBox
A MessageBox that can display a message label at the top of an editor.
-
class
bauble.utils.
YesNoMessageBox
(msg=None, on_response=None)¶ Bases:
bauble.utils.GenericMessageBox
A message box that can present a Yes or No question to the user
-
bauble.utils.
add_message_box
(parent, type=1)¶ Parameters: - parent – the parent
gtk.Box
width to add the message box to - type – one of MESSAGE_BOX_INFO, MESSAGE_BOX_ERROR or MESSAGE_BOX_YESNO
- parent – the parent
bauble.search
¶
-
class
bauble.search.
SearchParser
¶ The parser for bauble.search.MapperSearch
-
parse_string
(text)¶ request pyparsing object to parse text
text can be either a query, or a domain expression, or a list of values. the self.statement pyparsing object parses the input text and return a pyparsing.ParseResults object that represents the input
-
-
class
bauble.search.
SearchStrategy
¶ Interface for adding search strategies to a view.
-
search
(text, session=None)¶ Parameters: - text – the search string
- session – the session to use for the search
Return an iterator that iterates over mapped classes retrieved from the search.
-
-
class
bauble.search.
MapperSearch
¶ Bases:
bauble.search.SearchStrategy
Mapper Search support three types of search expression: 1. value searches: search that are just list of values, e.g. value1, value2, value3, searches all domains and registered columns for values 2. expression searches: searched of the form domain=value, resolves the domain and searches specific columns from the mapping 3. query searchs: searches of the form domain where ident.ident = value, resolve the domain and identifiers and search for value
-
search
(text, session=None)¶ Returns a set() of database hits for the text search string.
If session=None then the session should be closed after the results have been processed or it is possible that some database backends could cause deadlocks.
-
-
class
bauble.search.
QueryBuilder
(parent=None)¶ Bases:
gtk.Dialog