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)
	`lookup_query_full` (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.

Added 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.

Added 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.

Added 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.

Added 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.

Added in version 0.1.0.

get_enable_node_cache()¶

Return type:: bool

Get Xmlb.Silo :enable-node-cache.

Added in version 0.2.0.

get_guid()¶

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

Gets the GUID used to identify this silo.

Added 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.

Added 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).

Added 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.

Added in version 0.1.0.

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

Added 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.

Added 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.

Added 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.

Added 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.

Added in version 0.3.0.

lookup_query_full(xpath)¶

Parameters:: xpath (str) – an XPath query string
Raises:: GLib.Error
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.

Added in version 0.3.27.

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.

Added 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.

Added 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.

Added 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.

Added 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.

Added 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.

Added 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.

Added 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.

Added 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.

Added 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.

Added 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.

Added 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.

Added 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.

Added 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