Utilities

Hooks and Layout are the core for any customization. If you customize a Mask, chances are you would like to use that customization, any time you open that table, or you may need several different customization (eg. employees, manager may share some fields and differ on other fields).

The following utilities give you the possibility to register Hooks and Layout to make them available to any sqlwidget to which no Hook/Layout is passed.

Each time you register a hook/layout/class you can specify a nickname (eg.: customer/provider)

Hooks

sqlkit.db.utils.register_hook(table, hook, nick='default')

Register a hook for table. Each time a sqlwidget is instantiated for the table a hook is searched for here to initialize the sqlwidget

Parameters:

• table – a table for which we want to register the hook
• hook – the hook to be registered (a class or an instance)

sqlkit.db.utils.unregister_hook(table, nick='default')

unregister a hook

Parameters:

• table – the table or table_name for which you unregister the hook
• nick – the possible nick (default: ‘default’)

sqlkit.db.utils.get_hook(table, instance=False, nick='default')

Return a hook tor table or None

Parameters:

• table – the table for which we want the hook
• instance – a boolean: True is we want an instance False if we want the class

Layout

sqlkit.db.utils.register_layout(table, layout, nick='default', persistent=False)

Register a layout for table with a nick (default nick is ‘default’) Each time a sqlwidget is instantiated for the table a layout is searched for here

Parameters:

• table – the table to register the layout for. May be a sqlakchemy.Table or a string
• layout – the layut to be registered
• nick – the name of a nick to use for this layout (used for SqlMask(... nick=nick)
• persistent – register in the _sqlkit tables (not yet implemented)

sqlkit.db.utils.unregister_layout(table, nick='default')

unregister a layout

Parameters:

• table – the table or table_name for which you unregister the layout
• nick – the possible nick (default: ‘default’)

sqlkit.db.utils.get_layout(table, nick='default')

Return a layout for table for nick ‘nick’

Parameters:

• table – the table to register the layout for. May be a sqlakchemy.Table or a string
• nick – the nick used for this layout

Classes

Classes can be registered as well. If you register a class, all the times you pass a table to a sqlwidget, the class will be used, so that ll relations will be available as well. This is particularly usefull in case you use RecordInMask that can open a table that may use a layout with m2m/m2o nested table that would result as unknown if the table was reflected from the db.

sqlkit.db.utils.register_class(class_, table=None, nick='default')

Register a layout for table with a nick (default nick is ‘default’) Each time a sqlwidget is instantiated for the table a layout is searched for here

Parameters:

• table – the table to register the layout for. May be a sqlakchemy.Table or a string. class_.__table__ is used as default
• layout – the layout to be registered
• nick – the nick

sqlkit.db.utils.get_class(table, nick='default')

Return a layout for table for nick ‘nick’

Parameters:

• table – the table to register the layout for. May be a sqlakchemy.Table or a string
• nick – the nick used for this layout

Database

sqlkit.db.utils.get_differences(obj)

show differences between old and new version of an object this is a generator, you should use as in:

for field_name, old_value, new_value in get_differences(obj):
    print 'field   %s changed from %s, to %s' % (field_name, old_value, new_value)

Parameter:obj – the object to look for changes

this function uses sqlalchemy.orm.attributes.get_history but differs in 2 ways:

• it only yield changed values
• it returns the simple value (not a list) if the property is not a RelationProperty with direction MANYTOMANY or ONETOMANY (i.e.a collection)

Descr

This module provide a bare simple Class to help creating __str__ and __repr__ for tables, using _sqlkit_table.format field

tables

tables dictionary is a place where sqlkit looks for search_field and format for tables (see: ref:sqlkit_model).

You can set values directly using TableDescr class or implicitely via database editing (sqledit -c url)

Table Description

class sqlkit.db.utils.TableDescr(table, format=None, pk=None, metadata=None, register=True)

Handler for table search/format fields. This is an important component of Completion as it determines:

1. what is searched for (search attribute)
2. how it will be represented (format attribute)

TableDescr is automatically built from within get_description(). In __init__ it queries the database’ sqlkit_table to see if any site-wide configuration is available.

In turn get_description() is called within completion classes and sqlkit.fields.ForeignKeyField.lookup_value()

format

The format string used to represent the record.

When no format string is passed to the constructor, the first string field of the table is used. That clearly may be totally wrong in some cases, that’s why you can change it.

May be eather a normal python format string (eg.: “%(title)s - %(year)s”) in which case each prenthesized token must be a field_name or a simple string that again must be a field_name (e.g.: last_name) The representation of a director as in our demo could be: %(first_name)s %(last_name)s

Format string passed to TableDescr take precedence over format string present in the database.

attrs

List of attributes required by the format string. Always includes pkey.

search

this is the field that will be searched for in a foreign key. When using completion in a ForeignKey the database is queried using this field as a filter. E.g.: if in a SqlMask for a Movie you enter fe and then complete (Control-Enter) a query is build on the fly and sent to the database that selects the director’s table with an additional "SELECT DISTINCT %(attrs) FROM director WHERE %s = 'fe'" % (attrs, search_field).

It has the same default as format above.

__init__(table, format=None, pk=None, metadata=None, register=True)

Handler for table search/format fields

Parameters:

• table – the table_name or the sqlalchemy Table
• format – a possible format string, used to represent the record. See format above.
• pk – suggests which pk are to be used
• metadata – necessary to pick primary key or when autoloading is required unless a Table object is given
• register – (boolean) if True (default) this Table Description will be registered as default