Package gavo :: Package base :: Module meta

Module meta

Code dealing with meta information.

In DaCHS, tree-structured metadata can be attached to tables, services, resources as a whole, and some other structures. This module provides a python mixin to keep and manipulate such metadata.

We deal with VO-style RMI metadata but also allow custom metadata. Custom metadata keys should usually start with _.

See develNotes for some discussion of why this is so messy and an explanation of why in particular addMeta and helpers are a minefield of selections.

The rough plan to do this looks like this:

Metadata is kept in containers that mix in MetaMixin. Meta information is accessed through keys of the form <atom>{.<atom>} The first atom is the primary key. An atom consists exclusively of ascii letters and the underscore.

There's a meta mixin having the methods addMeta and getMeta that care about finding metadata including handover. For compound metadata, they will split the key and hand over to the parent if the don't have a meta item for the main key.

Classes
	MetaError A base class for metadata-related errors.
	MetaSyntaxError is raised when a meta key is invalid.
	NoMetaKey is raised when a meta key does not exist (and raiseOnFail is True).
	MetaCardError is raised when a meta value somehow has the wrong cardinality (e.g., on attempting to stringify a sequence meta).
	MetaValueError is raised when a meta value is inapproriate for the key given.
	MetaParser A structure parser that kicks in when meta information is parsed from XML.
	MetaAttribute An attribute magically inserting meta values to Structures mixing in MetaMixin.
	MetaMixin is a mixin for entities carrying meta information.
	ComputedMetaMixin A MetaMixin for classes that want to implement defaults for unresolvable meta items.
	MetaItem is a collection of homogenous MetaValues.
	MetaValue is a piece of meta information about a resource.
	IncludesChildren a formatted result that already includes all meta children.
	MetaURL A meta value containing a link and optionally a title
	RelatedResourceMeta A meta value containing an ivo-id and a name of a related resource.
	NewsMeta A meta value representing a "news" items.
	NoteMeta A meta value representing a "note" item.
	InfoItem A meta value for info items in VOTables.
	LogoMeta A MetaValue corresponding to a small image.
	BibcodeMeta A MetaValue that may contain bibcodes, which are rendered as links into ADS.
	VotLinkMeta A MetaValue serialized into VOTable links (or, ideally, analoguous constructs).
	ExampleMeta A MetaValue to keep VOSI examples in.
	MetaBuilder A base class for meta builders.
	TextBuilder is a MetaBuilder that recovers a tuple sequence of the meta items in text representation.
	ModelBasedBuilder is a meta builder that can create stan-like structures from meta information

Functions

metaRstToHtml(inputString)

source code

getPrimary(metaKey)

source code

parseKey(metaKey)

source code

parseMetaStream(metaContainer, metaStream, clearItems=False)
parser meta key/value pairs from metaStream and adds them to metaContainer.

source code

printMetaTree(metaContainer, curKey='') source code

ensureMetaValue(val, moreAttrs={})
makes a MetaValue out of val and a dict moreAttrs unless val already is a MetaValue. source code

ensureMetaItem(thing, moreAttrs={})
ensures that thing is a MetaItem. source code

doMetaOverride(container, metaKey, metaValue, extraArgs={})
creates the representation of metaKey/metaValue in container. source code

getMetaText(ob, key, default=None, **kwargs)
returns the meta item key form ob in text form if present, default otherwise.

source code

stanFactory(tag, **kwargs)
returns a factory for ModelBasedBuilder built from a stan-like "tag".

source code

Variables
	DEPRECATED_ATOMS = `{'_associatedDatalinkSvc': '_associatedData...`
	configMeta = `<gavo.base.meta.MetaMixin object>`
	META_CLASSES_FOR_KEYS = `{'_example': <class 'gavo.base.meta.Ex...`
	__package__ = `'gavo.base'`

Function Details

parseMetaStream(metaContainer, metaStream, clearItems=False)

source code

parser meta key/value pairs from metaStream and adds them to metaContainer.

If clearItems is true, for each key found in the metaStream there's first a delMeta for that key executed. This is for re-parsing meta streams.

The stream format is:

continuation lines with backslashes, where any sequence of backslash, (cr?) lf (blank or tab)* is replaced by nothing.
comments are lines like (ws*)# anything
empty lines are no-ops
all other lines are (ws*)<key>(ws*):(ws*)value(ws*)
if a key starts with !, any meta info for the key is cleared before setting

ensureMetaItem(thing, moreAttrs=`{}`)

source code

ensures that thing is a MetaItem.

If it is not, thing is turned into a sequence of MetaValues, which is then packed into a MetaItem.

Essentially, if thing is not a MetaValue, it is made into one with moreAttrs. If thing is a list, this recipe is used for all its items.

doMetaOverride(container, metaKey, metaValue, extraArgs=`{}`)

source code

creates the representation of metaKey/metaValue in container.

If metaKey does not need any special action, this returns None.

This gets called from one central point in MetaMixin.addMeta, and essentially all magic involved should be concentrated here.

getMetaText(ob, key, default=None, **kwargs)

source code

returns the meta item key form ob in text form if present, default otherwise.

You can pass getMeta keyword arguments (except default).

Additionally, there's acceptSequence; if set to true, this will return the first item of a sequence-valued meta item rather than raising an error.

ob will be used as a macro package if it has an expand method; to use something else as the macro package, pass a macroPackage keyword argument.

stanFactory(tag, **kwargs)

source code

returns a factory for ModelBasedBuilder built from a stan-like "tag".

Do *not* pass in instanciated tags -- they will just keep accumulating children on every model run.

Variables Details

DEPRECATED_ATOMS

Value:

{'_associatedDatalinkSvc': '_associatedDatalinkService'}

META_CLASSES_FOR_KEYS

Value:

{'_example': <class 'gavo.base.meta.ExampleMeta'>,
 '_news': <class 'gavo.base.meta.NewsMeta'>,
 '_related': <class 'gavo.base.meta.MetaURL'>,
 'cites': <class 'gavo.base.meta.RelatedResourceMeta'>,
 'continues': <class 'gavo.base.meta.RelatedResourceMeta'>,
 'creator.logo': <class 'gavo.base.meta.LogoMeta'>,
 'derivedFrom': <class 'gavo.base.meta.RelatedResourceMeta'>,
 'hasPart': <class 'gavo.base.meta.RelatedResourceMeta'>,
...

Module meta

parseMetaStream(metaContainer, metaStream, clearItems=False)

ensureMetaItem(thing, moreAttrs={})

doMetaOverride(container, metaKey, metaValue, extraArgs={})

getMetaText(ob, key, default=None, **kwargs)

stanFactory(tag, **kwargs)

DEPRECATED_ATOMS

META_CLASSES_FOR_KEYS

ensureMetaItem(thing, moreAttrs=`{}`)

doMetaOverride(container, metaKey, metaValue, extraArgs=`{}`)