gavo.base.macros module

A macro mechanism primarily for string replacement in resource descriptors.

class gavo.base.macros.ExpansionDelegator

Bases: object

A mixin to make a class expand macros by delegating everything to its parent.

This is intended for base.Structures that have a parent attribute; by mixing this in, they use their parents to expand macros for them.

expand(aString)

class gavo.base.macros.MacDef(parent, **kwargs)

Bases: Structure

A macro definition within an RD.

The macro defined is available on the parent; macros are expanded within the parent (behaviour is undefined if you try a recursive expansion).

attrSeq = [<gavo.base.structure.DataContent object>, <gavo.base.parsecontext.IdAttribute object>, <gavo.base.attrdef.UnicodeAttribute object>]

completedCallbacks = []

managedAttrs = {'content_': <gavo.base.structure.DataContent object>, 'id': <gavo.base.parsecontext.IdAttribute object>, 'name': <gavo.base.attrdef.UnicodeAttribute object>}

name_ = 'macDef'

onElementComplete()

validate()

gavo.base.macros.MacDefAttribute(**kwargs)

exception gavo.base.macros.MacroError(message, macroName, hint=None, pos=None)

Bases: StructureError

is raised when something bad happens during macro expansion.

It is constructed with an error message, a macro name, and optionally a hint and a position.

class gavo.base.macros.MacroExpander(package)

Bases: object

is a generic “macro” expander for scripts of all kinds.

It is loosely inspired by TeX, but of course much simpler. See the syntax below.

The macros themselves come from a MacroPackage object. There are a few of these around, implementing different functionality depending on the script context (i.e., whether it belongs to an RD, a DD, or a Table.

All macros are just functions receiving and returning strings. The arguments are written as {arg1}{arg2}, where you can escape curly braces with a backslash. There must be no whitespace between a macro and its first argument.

If you need to glue together a macro expansion and text following, use the glue sequence +

The main entry point to the class is the expand function below, taking a string possibly containing macro calls and returning a string.

The construction of such a macro expander is relatively expensive, so it pays to cache them. MacroPackage below has a getExpander method that does the caching for you.

expand(aString)

class gavo.base.macros.MacroPackage

Bases: StructCallbacks

is a function dispatcher for MacroExpander.

Basically, you inherit from this class and define macro_xxx functions. MacroExpander can then call xxx, possibly with arguments.

execMacro(macName, args)

expand(stuff)

getExpander()

listMacros()

macro_quote(arg)

returns the argument in quotes (with internal quotes backslash-escaped if necessary).

macro_reSub(pattern, replacement, string)

returns the string with the python RE pattern replaced with replacement.

This is directly handed through to python re.sub, so you can (but probably shouldn’t) play all the RE tricks you can in python (e.g., back references).

If you find yourself having to use reSub, you should regard that as an alarm sign that you’re probably doing it wrong.

Oh: closing curly braces can be included in the argument by backslash-escaping them.

macro_sql_standardPubDID(fromCol='accref')

returns a SQL expression returning a DaCHS standard pubDID generated from the accref (or something overridden) column.

This is convenient in obscore or ssa views when the underlying table just has accrefs. If your code actually uses the pubDID to search in the table (and it probably shouldn’t), better use an actual column and index it.

macro_sqlquote(arg)

returns the argument as a quoted string, unless it is ‘NULL’ or None, in which case just NULL is returned.

class gavo.base.macros.StandardMacroMixin

Bases: MacroPackage

is a mixin providing some macros for scripting’s MacroExpander.

The class mixing in needs to provide its resource descriptor in the rd attribute.

macro_RSTservicelink(serviceId, title=None)

a link to an internal service; id is <rdId>/<serviceId>/<renderer>, title, if given, is the anchor text.

The result is a link in the short form for restructured test.

macro_RSTtable(tableName)

adds an reStructured test link to a tableName pointing to its table info.

macro_decapitalize(aString)

returns aString with the first character lowercased.

macro_getConfig(section, name=None)

the current value of configuration item {section}{name}.

You can also only give one argument to access settings from the general section.

macro_internallink(relPath)

an absolute URL from a path relative to the DC root.

macro_lower(aString)

returns aString lowercased.

There’s no guarantees for characters outside ASCII.

macro_magicEmpty(val)

returns __EMPTY__ if val is empty.

This is necessary when feeding possibly empty params from mixin parameters (don’t worry if you don’t understand this).

macro_metaSeq(metaKey, default='', joiner=', ')

returns all values of metaKey on the current macro expander joined by joiner.

This will be an empty string if there is no corresponding metadata (or default, if passed).

macro_metaString(metaKey, default=None)

the value of metaKey on the macro expander.

This will raise an error when the meta Key is not available unless you give a default. It will also raise an error if metaKey is not atomic (i.e., single-valued). Use metaSeq for meta items that may have multiple values.

Because it’s sometimes useful, if the expander itself doesn’t have metadat, this goes up in the RD tree until it finds something that has metadata.

macro_rdId()

the identifier of the current resource descriptor.

macro_rdIdDotted()

the identifier for the current resource descriptor with slashes replaced with dots (so they work as the “host part” in URIs.

macro_resdir()

the input-relative resource directory of the current resource descriptor.

This never has a trailing slash.

macro_schema()

the schema of the current resource descriptor.

macro_test(*args)

always “test macro expansion”.

macro_today()

today’s date in ISO representation.

macro_upper(aString)

returns aString uppercased.

There’s no guarantees for characters outside ASCII.

macro_urlquote(string)

wraps urllib.quote.