Xmlb.Silo¶

Subclasses:: None

Methods¶

Inherited:: GObject.Object (37)
Structs:: GObject.ObjectClass (5)

class	`new` ()
class	`new_from_xml` (xml)
	`export` (flags)
	`export_file` (file, flags, cancellable)
	`get_bytes` ()
	`get_enable_node_cache` ()
	`get_guid` ()
	`get_profile_string` ()
	`get_root` ()
	`get_size` ()
	`invalidate` ()
	`is_valid` ()
	`load_from_bytes` (blob, flags)
	`load_from_file` (file, flags, cancellable)
	`lookup_query` (xpath)
	`query` (xpath, limit)
	`query_build_index` (xpath, attr)
	`query_first` (xpath)
	`query_first_full` (query)
	`query_first_with_context` (query, context)
	`query_full` (query)
	`query_with_context` (query, context)
	`save_to_file` (file, cancellable)
	`set_enable_node_cache` (enable_node_cache)
	`set_profile_flags` (profile_flags)
	`to_string` ()
	`watch_file` (file, cancellable)

Virtual Methods¶

Inherited:: GObject.Object (7)

Properties¶

Name	Type	Flags
`enable-node-cache`	`bool`	r/w/en
`guid`	`str`	r/w/c/en
`valid`	`bool`	r/en

Signals¶

Inherited:: GObject.Object (1)

Fields¶

Inherited:: GObject.Object (1)

Name	Type	Access	Description
parent_instance	`GObject.Object`	r

Class Details¶

class Xmlb.Silo(**kwargs)¶

Bases:: GObject.Object
Abstract:: No
Structure:: Xmlb.SiloClass

classmethod new()¶

Returns:: a new Xmlb.Silo
Return type:: Xmlb.Silo

Creates a new silo.

New in version 0.1.0.

classmethod new_from_xml(xml)¶

Parameters:: xml (str) – XML string
Raises:: GLib.Error
Returns:: a new Xmlb.Silo, or None
Return type:: Xmlb.Silo

Creates a new silo from an XML string.

New in version 0.1.0.

export(flags)¶

Parameters:: flags (Xmlb.NodeExportFlags) – some Xmlb.NodeExportFlags, e.g. Xmlb.NodeExportFlags.NONE
Raises:: GLib.Error
Returns:: XML data, or None for an error
Return type:: str

Exports the silo back to XML.

New in version 0.1.0.

export_file(file, flags, cancellable)¶

Parameters:

file (Gio.File) – a Gio.File
flags (Xmlb.NodeExportFlags) – some Xmlb.NodeExportFlags, e.g. Xmlb.NodeExportFlags.NONE
cancellable (Gio.Cancellable or None) – a Gio.Cancellable, or None

Raises:

GLib.Error

Returns:

True on success

Return type:

bool

Exports the silo back to an XML file.

New in version 0.1.2.

get_bytes()¶

Returns:: A GLib.Bytes, or None if never set
Return type:: GLib.Bytes

Gets the backing object that created the blob.

You should never *ever* modify this data.

New in version 0.1.0.

get_enable_node_cache()¶

Return type:: bool

Get Xmlb.Silo :enable-node-cache.

New in version 0.2.0.

get_guid()¶

Returns:: a string, otherwise None
Return type:: str

Gets the GUID used to identify this silo.

New in version 0.1.0.

get_profile_string()¶

Returns:: text profiling data
Return type:: str

Returns the profiling data. This will only return profiling text if Xmlb.Silo.set_profile_flags() was used with Xmlb.SiloProfileFlags.APPEND.

New in version 0.1.1.

get_root()¶

Returns:: A Xmlb.Node, or None for an error
Return type:: Xmlb.Node

Gets the root node for the silo. (MIGHT BE MORE).

New in version 0.1.0.

get_size()¶

Returns:: a integer, or 0 is an empty blob
Return type:: int

Gets the number of nodes in the silo.

New in version 0.1.0.

invalidate()¶: Invalidates a silo. Future calls Xmlb.Silo.is_valid() will return False.

New in version 0.1.1.

is_valid()¶

Returns:: True if valid
Return type:: bool

Checks is the silo is valid. The usual reason the silo is invalidated is when the backing mmapped file has changed, or one of the imported files have been modified.

New in version 0.1.0.

load_from_bytes(blob, flags)¶

Parameters:

blob (GLib.Bytes) – a GLib.Bytes
flags (Xmlb.SiloLoadFlags) – Xmlb.SiloLoadFlags, e.g. Xmlb.SiloLoadFlags.NONE

Raises:

GLib.Error

Returns:

True for success, otherwise error is set.

Return type:

bool

Loads a silo from memory location.

New in version 0.1.0.

load_from_file(file, flags, cancellable)¶

Parameters:

file (Gio.File) – a Gio.File
flags (Xmlb.SiloLoadFlags) – Xmlb.SiloLoadFlags, e.g. Xmlb.SiloLoadFlags.NONE
cancellable (Gio.Cancellable or None) – a Gio.Cancellable, or None

Raises:

GLib.Error

Returns:

True for success, otherwise error is set.

Return type:

bool

Loads a silo from file.

New in version 0.1.0.

lookup_query(xpath)¶

Parameters:: xpath (str) – an XPath query string
Returns:: an Xmlb.Query representing xpath
Return type:: Xmlb.Query

Create an Xmlb.Query from the given xpath XPath string, or return it from the query cache in the Xmlb.Silo.

xpath must be valid: it is a programmer error if creating the query fails (i.e. if Xmlb.Query.new() returns an error).

This function is thread-safe.

New in version 0.3.0.

query(xpath, limit)¶

Parameters:

xpath (str) – an XPath, e.g. /components/component[@type=desktop]/id[abe.desktop]
limit (int) – maximum number of results to return, or 0 for “all”

Raises:

GLib.Error

Returns:

results, or None if unfound

Return type:

[Xmlb.Node]

Searches the silo using an XPath query, returning up to limit results.

It is safe to call this function from a different thread to the one that created the Xmlb.Silo.

Please note: Only a subset of XPath is supported.

New in version 0.1.0.

query_build_index(xpath, attr)¶

Parameters:

xpath (str) – An XPath, e.g. /components/component[@type=desktop]/id[abe.desktop]
attr (str or None) – Attribute name, e.g. type, or None

Raises:

GLib.Error

Returns:

True for success

Return type:

bool

Adds the attr() or text() results of a query to the index.

New in version 0.1.4.

query_first(xpath)¶

Parameters:: xpath (str) – An XPath, e.g. /components/component[@type=desktop]/id[abe.desktop]
Raises:: GLib.Error
Returns:: a Xmlb.Node, or None if unfound
Return type:: Xmlb.Node

Searches the silo using an XPath query, returning up to one result.

It is safe to call this function from a different thread to the one that created the Xmlb.Silo.

Please note: Only a tiny subset of XPath 1.0 is supported.

New in version 0.1.0.

query_first_full(query)¶

Parameters:: query (Xmlb.Query) – an Xmlb.Query
Raises:: GLib.Error
Returns:: a Xmlb.Node, or None if unfound
Return type:: Xmlb.Node

Searches the silo using an XPath query, returning up to one result.

It is safe to call this function from a different thread to the one that created the Xmlb.Silo.

Please note: Only a tiny subset of XPath 1.0 is supported.

New in version 0.1.13.

query_first_with_context(query, context)¶

Parameters:

query (Xmlb.Query) – an Xmlb.Query
context (Xmlb.QueryContext or None) – context including values bound to opcodes of type Xmlb.OpcodeKind.BOUND_INTEGER or Xmlb.OpcodeKind.BOUND_TEXT, or None if the query doesn’t need any context

Raises:

GLib.Error

Returns:

a Xmlb.Node, or None if unfound

Return type:

Xmlb.Node

Searches the silo using an XPath query, returning up to one result.

It is safe to call this function from a different thread to the one that created the Xmlb.Silo.

Please note: Only a tiny subset of XPath 1.0 is supported.

New in version 0.3.0.

query_full(query)¶

Parameters:: query (Xmlb.Query) – an Xmlb.Query
Raises:: GLib.Error
Returns:: results, or None if unfound
Return type:: [Xmlb.Node]

Searches the silo using an XPath query.

It is safe to call this function from a different thread to the one that created the Xmlb.Silo.

Please note: Only a subset of XPath is supported.

New in version 0.1.13.

query_with_context(query, context)¶

Parameters:

query (Xmlb.Query) – an Xmlb.Query
context (Xmlb.QueryContext or None) – context including values bound to opcodes of type Xmlb.OpcodeKind.BOUND_INTEGER or Xmlb.OpcodeKind.BOUND_TEXT, or None if the query doesn’t need any context

Raises:

GLib.Error

Returns:

results, or None if unfound

Return type:

[Xmlb.Node]

Searches the silo using an XPath query.

It is safe to call this function from a different thread to the one that created the Xmlb.Silo.

Please note: Only a subset of XPath is supported.

New in version 0.3.0.

save_to_file(file, cancellable)¶

Parameters:

file (Gio.File) – a Gio.File
cancellable (Gio.Cancellable or None) – a Gio.Cancellable, or None

Raises:

GLib.Error

Returns:

True for success, otherwise error is set.

Return type:

bool

Saves a silo to a file.

New in version 0.1.0.

set_enable_node_cache(enable_node_cache)¶

Parameters:: enable_node_cache (bool) – True to enable the node cache, False otherwise

Set Xmlb.Silo :enable-node-cache.

This is not thread-safe, and can only be called before the Xmlb.Silo is passed between threads.

New in version 0.2.0.

set_profile_flags(profile_flags)¶

Parameters:: profile_flags (Xmlb.SiloProfileFlags) – some Xmlb.SiloProfileFlags, e.g. Xmlb.SiloProfileFlags.DEBUG

Enables or disables the collection of profiling data.

New in version 0.1.1.

to_string()¶

Raises:: GLib.Error
Returns:: A string, or None for an error
Return type:: str

Converts the silo to an internal string representation. This is only really useful for debugging Xmlb.Silo itself.

New in version 0.1.0.

watch_file(file, cancellable)¶

Parameters:

file (Gio.File) – a Gio.File
cancellable (Gio.Cancellable or None) – a Gio.Cancellable, or None

Raises:

GLib.Error

Returns:

True for success, otherwise error is set.

Return type:

bool

Adds a file monitor to the silo. If the file or directory for file changes then the silo will be invalidated.

The monitor will internally use the GLib.MainContext which was the thread default when the Xmlb.Silo was created, so that GLib.MainContext must be iterated for monitoring to work.

New in version 0.1.0.

Property Details¶

Xmlb.Silo.props.enable_node_cache¶

Name:: enable-node-cache
Type:: bool
Default Value:: True
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Whether to cache all Xmlb.Node instances ever constructed in a single cache in the Xmlb.Silo, so that the same Xmlb.Node instance is always returned in query results for a given XPath. This is a form of memoisation, and allows Xmlb.Node.get_data() and Xmlb.Node.set_data() to be used.

This is enabled by default to preserve compatibility with older versions of libxmlb, but most clients will want to disable it. It adds a large memory overhead (no Xmlb.Node is ever finalised) but achieves moderately low hit rates for typical XML parsing workloads where most nodes are accessed only once or twice as they are processed and then processing moves on to other nodes.

This property can only be changed before the Xmlb.Silo is passed between threads. Changing it is not thread-safe.

New in version 0.2.0.

Xmlb.Silo.props.guid¶

Name:: guid
Type:: str
Default Value:: None
Flags:: READABLE, WRITABLE, CONSTRUCT, EXPLICIT_NOTIFY

Xmlb.Silo.props.valid¶

Name:: valid
Type:: bool
Default Value:: True
Flags:: READABLE, EXPLICIT_NOTIFY