API Documentation

bauble

The top level module for Bauble.

bauble.version = '1.0.55'

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::Uncategorized

session = 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'>
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.
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

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())

  1. 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 –
bauble.utils.setup_date_button(view, entry, button, date_func=None)

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 generic objects as well.

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

bauble.view

class bauble.view.SearchView.ViewMeta

bauble.plugins.plants

bauble.plugins.garden

bauble.plugins.abcd

bauble.plugins.imex

bauble.plugins.report

bauble.plugins.report.xsl

bauble.plugins.report.mako

bauble.plugins.tag