Modulemd.ModuleIndex: Modulemd Reference Manual

Modulemd.ModuleIndex

Modulemd.ModuleIndex — The primary interface to dealing with repodata in the module metadata format.

Stability Level

Stable, unless otherwise indicated

Functions

gint	(*ModulemdReadHandler) ()
gint	(*ModulemdWriteHandler) ()
ModulemdModuleIndex *	modulemd_module_index_new ()
gboolean	modulemd_module_index_update_from_file ()
gboolean	modulemd_module_index_update_from_string ()
gboolean	modulemd_module_index_update_from_stream ()
gboolean	modulemd_module_index_update_from_custom ()
gboolean	modulemd_module_index_update_from_defaults_directory ()
gchar *	modulemd_module_index_dump_to_string ()
gboolean	modulemd_module_index_dump_to_stream ()
gboolean	modulemd_module_index_dump_to_custom ()
GStrv	modulemd_module_index_get_module_names_as_strv ()
ModulemdModule *	modulemd_module_index_get_module ()
GPtrArray *	modulemd_module_index_search_streams ()
GPtrArray *	modulemd_module_index_search_streams_by_nsvca_glob ()
GPtrArray *	modulemd_module_index_search_rpms ()
gboolean	modulemd_module_index_remove_module ()
gboolean	modulemd_module_index_add_module_stream ()
gboolean	modulemd_module_index_add_defaults ()
gboolean	modulemd_module_index_add_obsoletes ()
GHashTable *	modulemd_module_index_get_default_streams_as_hash_table ()
gboolean	modulemd_module_index_add_translation ()
ModulemdDefaultsVersionEnum	modulemd_module_index_get_defaults_mdversion ()
ModulemdModuleStreamVersionEnum	modulemd_module_index_get_stream_mdversion ()
gboolean	modulemd_module_index_upgrade_streams ()
gboolean	modulemd_module_index_upgrade_defaults ()
void	modulemd_module_index_clear_xmds ()

Types and Values

#define	MODULEMD_TYPE_MODULE_INDEX
	ModulemdModuleIndex

Object Hierarchy

    GObject
    ╰── ModulemdModuleIndex

Description

This object provides an interface to the complete metadata read from a repository or manually added to this object.

NOTE: When adding or updating this object from YAML, all objects imported will be automatically upgraded to match the highest version of that object that is seen. This means that if the repository has a mix of ModulemdModuleStreamV1 and ModulemdModuleStreamV2 objects, the index will contain only ModulemdModuleStreamV2. You can check the versions the index upgraded to with the modulemd_module_index_get_stream_mdversion() and modulemd_module_index_get_defaults_mdversion(). If your application would prefer to always work with a particular stream or defaults version (such as to avoid extra branching logic), the modulemd_module_index_upgrade_streams() and modulemd_module_index_upgrade_defaults() functions can be used to force the contents of the index to upgrade to those versions.

Interacting with ModulemdModuleIndex is relatively simple. A common Python example for working with Fedora repodata might be (assuming the metadata has already been read into strings):

fedora_repo_index = Modulemd.ModuleIndex.new()
fedora_repo_index.update_from_string(fedora_modulemd, True)

# Get the list of all module names in the index
module_names = fedora_repo_index.get_module_names()

# Retrieve information about a particular module from the index
module = fedora_repo_index.get_module('module_name')

See the ModulemdModule documentation for details on retrieving information about specific modules, including how to get ModulemdDefaults information and retrieve individual ModulemdModuleStream objects.

See the ModulemdModuleIndexMerger documentation for details on merging ModulemdModuleIndex objects from separate repositories together.

Functions

ModulemdReadHandler ()

gint
(*ModulemdReadHandler) (void *data,
                        unsigned char *buffer,
                        size_t size,
                        size_t *size_read);

The prototype of a read handler.

The read handler is called when the parser needs to read more bytes from the source. The handler should write not more than size bytes to the buffer . The number of written bytes should be set to the size_read variable.

This handler is identical to a yaml_read_handler_t in yaml.h header of libyaml but is included here to avoid depending on yaml.h in modulemd headers.

Parameters

data	A private pointer to the data being read.	[inout]
buffer	The buffer to write the data from the source.	[out]
size	The size of the buffer.	[in]
size_read	The actual number of bytes read from the source.	[out]

Returns

On success, the handler must return 1. If the handler failed, the returned value must be 0. On EOF, the handler must set the size_read to 0 and return 1.

Since: 2.3

ModulemdWriteHandler ()

gint
(*ModulemdWriteHandler) (void *data,
                         unsigned char *buffer,
                         size_t size);

The prototype of a write handler.

The write handler is called when the emitter needs to flush the accumulated characters to the output. The handler should write size bytes of the buffer to the output.

This handler is identical to a yaml_write_handler_t in yaml.h header of libyaml but is included here to avoid depending on yaml.h in modulemd headers.

Parameters

data	A private pointer that includes the data source.	[inout]
buffer	The buffer with bytes to be written.	[out]
size	The size of the buffer.	[in]

Returns

On success, the handler must return 1. If the handler failed, the returned value must be 0.

Since: 2.3

modulemd_module_index_new ()

ModulemdModuleIndex *
modulemd_module_index_new (void);

Returns

A newly-allocated ModulemdModuleIndex object.

[transfer full]

Since: 2.0

modulemd_module_index_update_from_file ()

gboolean
modulemd_module_index_update_from_file
                               (ModulemdModuleIndex *self,
                                const gchar *yaml_file,
                                gboolean strict,
                                GPtrArray **failures,
                                GError **error);

Parameters

self	This ModulemdModuleIndex object.
yaml_file	A name of a YAML file containing the module metadata and other related information such as default streams.	[in]
strict	Whether the parser should return failure if it encounters an unknown mapping key or if it should ignore it.	[in]
failures	On output, an array containing any subdocuments (pointers to ModulemdSubdocumentInfo) from the YAML file that failed to parse. On input, it must be a non-`NULL` pointer. If that pointer points to `NULL`, this call will allocate a new array (regardless of any failures) with an element destructor set to `g_object_unref()`. Otherwise, the pointed array is reused without emptying before adding the failed subdocuments. The caller is responsible for freeing the array.	[out][element-type ModulemdSubdocumentInfo][transfer container]
error	A GError containing additional information if this function fails in a way that prevents program continuation. On input, it must be `NULL` (if you don't care) or a pointer to `NULL` (if you want to know the error). On output, it will become allocated only if an error occured.	[out]

Returns

TRUE if the update was successful. Returns FALSE and sets failures appropriately if any of the YAML subdocuments were invalid or sets error if there was a fatal parse error.

Since: 2.0

modulemd_module_index_update_from_string ()

gboolean
modulemd_module_index_update_from_string
                               (ModulemdModuleIndex *self,
                                const gchar *yaml_string,
                                gboolean strict,
                                GPtrArray **failures,
                                GError **error);

Parameters

self	This ModulemdModuleIndex object.
yaml_string	A YAML string containing the module metadata and other related information such as default streams.	[in]
strict	Whether the parser should return failure if it encounters an unknown mapping key or if it should ignore it.	[in]
failures	On output, an array containing any subdocuments (pointers to ModulemdSubdocumentInfo) from the YAML file that failed to parse. On input, it must be a non-`NULL` pointer. If that pointer points to `NULL`, this call will allocate a new array (regardless of any failures) with an element destructor set to `g_object_unref()`. Otherwise, the pointed array is reused without emptying before adding the failed subdocuments. The caller is responsible for freeing the array.	[out][element-type ModulemdSubdocumentInfo][transfer container]
error	A GError containing additional information if this function fails in a way that prevents program continuation. On input, it must be `NULL` (if you don't care) or a pointer to `NULL` (if you want to know the error). On output, it will become allocated only if an error occured.	[out]

Returns

TRUE if the update was successful. Returns FALSE and sets failures appropriately if any of the YAML subdocuments were invalid or sets error if there was a fatal parse error.

Since: 2.0

modulemd_module_index_update_from_stream ()

gboolean
modulemd_module_index_update_from_stream
                               (ModulemdModuleIndex *self,
                                FILE *yaml_stream,
                                gboolean strict,
                                GPtrArray **failures,
                                GError **error);

[skip]

Parameters

self	This ModulemdModuleIndex object.
yaml_stream	A YAML stream containing the module metadata and other related information such as default streams.	[in]
strict	Whether the parser should return failure if it encounters an unknown mapping key or if it should ignore it.	[in]
failures	On output, an array containing any subdocuments (pointers to ModulemdSubdocumentInfo) from the YAML file that failed to parse. On input, it must be a non-`NULL` pointer. If that pointer points to `NULL`, this call will allocate a new array (regardless of any failures) with an element destructor set to `g_object_unref()`. Otherwise, the pointed array is reused without emptying before adding the failed subdocuments. The caller is responsible for freeing the array.	[out][element-type ModulemdSubdocumentInfo][transfer container]
error	A GError containing additional information if this function fails in a way that prevents program continuation. On input, it must be `NULL` (if you don't care) or a pointer to `NULL` (if you want to know the error). On output, it will become allocated only if an error occured.	[out]

Returns

TRUE if the update was successful. Returns FALSE and sets failures appropriately if any of the YAML subdocuments were invalid or sets error if there was a fatal parse error.

Since: 2.0

modulemd_module_index_update_from_custom ()

gboolean
modulemd_module_index_update_from_custom
                               (ModulemdModuleIndex *self,
                                ModulemdReadHandler custom_read_fn,
                                void *custom_pvt_data,
                                gboolean strict,
                                GPtrArray **failures,
                                GError **error);

[skip]

Parameters

self	This ModulemdModuleIndex object.
custom_read_fn	A ModulemdReadHandler.	[in]
custom_pvt_data	The private data needed by the ModulemdReadHandler.	[inout]
strict	Whether the parser should return failure if it encounters an unknown mapping key or if it should ignore it.	[in]
failures	On output, an array containing any subdocuments (pointers to ModulemdSubdocumentInfo) from the YAML file that failed to parse. On input, it must be a non-`NULL` pointer. If that pointer points to `NULL`, this call will allocate a new array (regardless of any failures) with an element destructor set to `g_object_unref()`. Otherwise, the pointed array is reused without emptying before adding the failed subdocuments. The caller is responsible for freeing the array.	[out][element-type ModulemdSubdocumentInfo][transfer container]
error	A GError containing additional information if this function fails in a way that prevents program continuation. On input, it must be `NULL` (if you don't care) or a pointer to `NULL` (if you want to know the error). On output, it will become allocated only if an error occured.	[out]

Returns

TRUE if the update was successful. Returns FALSE and sets failures appropriately if any of the YAML subdocuments were invalid or sets error if there was a fatal parse error.

Since: 2.3

modulemd_module_index_update_from_defaults_directory ()

gboolean
modulemd_module_index_update_from_defaults_directory
                               (ModulemdModuleIndex *self,
                                const gchar *path,
                                gboolean strict,
                                const gchar *overrides_path,
                                GError **error);

This function will open the directory at path and iterate through it, adding any files with the suffix ".yaml" to self . If overrides_path is non-NULL, it will also open any files with the suffix ".yaml" in that location and import them, overriding any conflicts with the existing defaults.

Note: If you need detailed information about what failed and why, it is better to implement the directory traversal yourself and use the modulemd_module_index_update_from_file() function, as it will return the failures information.

Parameters

self	This ModulemdModuleIndex object.
path	The path to a directory containing defaults documents.	[in]
strict	Whether the parser should return failure if it encounters an unknown mapping key or a conflict in module default streams.	[in]
overrides_path	If non-`NULL`, the path to a directory containing defaults documents that should override those in `path` .	[in][nullable]
error	A GError indicating why this function failed. On input, it must be `NULL` (if you don't care) or a pointer to `NULL` (if you want to know the error). On output, it will become allocated only if an error occured.	[out]

Returns

TRUE if all ".yaml" files in the directory were imported successfully (this includes if no ".yaml" files were present). FALSE if one or more files could not be read successfully and sets error appropriately.

Since: 2.8

modulemd_module_index_dump_to_string ()

gchar *
modulemd_module_index_dump_to_string (ModulemdModuleIndex *self,
                                      GError **error);

Parameters

self	This ModulemdModuleIndex object.
error	A GError containing the reason the function failed, NULL if the function succeeded.	[out]

Returns

A YAML representation of the index as a string. In the event of an error, sets error appropriately and returns NULL.

[transfer full]

Since: 2.0

modulemd_module_index_dump_to_stream ()

gboolean
modulemd_module_index_dump_to_stream (ModulemdModuleIndex *self,
                                      FILE *yaml_stream,
                                      GError **error);

[skip]

Parameters

self	This ModulemdModuleIndex object.
yaml_stream	A stream to write the module metadata and other related information to.	[in]
error	A GError containing the reason the function failed, NULL if the function succeeded.	[out]

Returns

TRUE if written successfully, FALSE and sets error appropriately in the event of an error.

Since: 2.0

modulemd_module_index_dump_to_custom ()

gboolean
modulemd_module_index_dump_to_custom (ModulemdModuleIndex *self,
                                      ModulemdWriteHandler custom_write_fn,
                                      void *custom_pvt_data,
                                      GError **error);

[skip]

Parameters

self	This ModulemdModuleIndex object.
custom_write_fn	A ModulemdWriteHandler.	[in]
custom_pvt_data	The private data needed by the ModulemdWriteHandler.	[inout]
error	A GError containing the reason the function failed, NULL if the function succeeded.	[out]

Returns

TRUE if written successfully, FALSE and sets error appropriately in the event of an error.

Since: 2.3

modulemd_module_index_get_module_names_as_strv ()

GStrv
modulemd_module_index_get_module_names_as_strv
                               (ModulemdModuleIndex *self);

[rename-to modulemd_module_index_get_module_names]

Parameters

self

This ModulemdModuleIndex object.

Returns

An ordered list of string keys in this index.

[transfer full]

Since: 2.0

modulemd_module_index_get_module ()

ModulemdModule *
modulemd_module_index_get_module (ModulemdModuleIndex *self,
                                  const gchar *module_name);

Parameters

self	This ModulemdModuleIndex object.
module_name	The module name to look up in the index.

Returns

The ModulemdModule object matching the provided module name or NULL if the key was not present in the index.

[transfer none]

Since: 2.0

modulemd_module_index_search_streams ()

GPtrArray *
modulemd_module_index_search_streams (ModulemdModuleIndex *self,
                                      const gchar *module_name,
                                      const gchar *stream_name,
                                      const gchar *version,
                                      const gchar *context,
                                      const gchar *arch);

All arguments to this method will be compared using fnmatch(3).

Parameters

self	This ModulemdModuleIndex object.
module_name	The name of the module to retrieve. If NULL, will search all modules in the index.	[nullable]
stream_name	The name of the stream to retrieve. If NULL, will search all streams in a module.	[nullable]
version	The version of the stream to retrieve. If NULL, will search all versions.	[nullable]
context	The context of the stream to retrieve. If NULL, will search all contexts.	[nullable]
arch	The processor architecture of the stream to retrieve. If NULL, the architecture is not included in the search.	[nullable]

Returns

The list of stream objects matching all of the requested parameters. This function cannot fail, but it may return a zero-length list if no matches were found. The returned streams will be in a predictable order, sorted first by module name, then stream name, then by version (highest first), then by context and finally by architecture.

[transfer container][element-type ModulemdModuleStream]

Since: 2.9

modulemd_module_index_search_streams_by_nsvca_glob ()

GPtrArray *
modulemd_module_index_search_streams_by_nsvca_glob
                               (ModulemdModuleIndex *self,
                                const gchar *nsvca_pattern);

Parameters

self	This ModulemdModuleIndex object.
nsvca_pattern	A glob pattern to match against the NSVCA strings of the ModulemdModuleStream objects in this module. If NULL, this will match all NSVCAs.	[nullable]

Returns

[transfer container][element-type ModulemdModuleStream]

Since: 2.9

modulemd_module_index_search_rpms ()

GPtrArray *
modulemd_module_index_search_rpms (ModulemdModuleIndex *self,
                                   const gchar *nevra_pattern);

All arguments to this method will be compared using fnmatch(3).

Parameters

self	This ModulemdModuleIndex object.
nevra_pattern	A glob pattern to match against the NEVRA strings of the rpm artifacts in the ModulemdModuleStream objects in this module.	[not nullable]

Returns

The list of stream objects containing an RPM that matches the nevra_pattern . This function cannot fail, but it may return a zero-length list if no matches were found. The returned streams will be in a predictable order, sorted first by module name, then stream name, then by version (highest first), then by context and finally by architecture.

[transfer container][element-type ModulemdModuleStream]

Since: 2.9

modulemd_module_index_remove_module ()

gboolean
modulemd_module_index_remove_module (ModulemdModuleIndex *self,
                                     const gchar *module_name);

Remove a module, including all of its streams, its defaults and its translations from a ModulemdModuleIndex.

Parameters

self	This ModulemdModuleIndex object.
module_name	The name of the module to remove from the index.

Returns

TRUE if the module name was present in the index. FALSE if it was not.

Since: 2.2

modulemd_module_index_add_module_stream ()

gboolean
modulemd_module_index_add_module_stream
                               (ModulemdModuleIndex *self,
                                ModulemdModuleStream *stream,
                                GError **error);

Add a ModulemdModuleStream to the ModulemdModuleIndex. While being added, the ModulemdModuleStream will be upgraded to MD_MODULESTREAM_VERSION_LATEST to ensure that merges done with ModulemdModuleIndexMerger will always occur between streams of the same version. If this upgrade cannot be performed, the function will return error set appropriately.

Parameters

self	This ModulemdModuleIndex object.
stream	The ModulemdModuleStream to add to the index. The stream added must have a module name and stream name set on it or it will be rejected.
error	A GError containing the reason the ModulemdModuleStream object could not be added or NULL if the function succeeded.	[out]

Returns

TRUE if the ModulemdModuleStream was added successfully. If the stream already existed in the index, it will be replaced by the new one. On failure, returns FALSE and sets error appropriately.

Since: 2.0

modulemd_module_index_add_defaults ()

gboolean
modulemd_module_index_add_defaults (ModulemdModuleIndex *self,
                                    ModulemdDefaults *defaults,
                                    GError **error);

Parameters

self	This ModulemdModuleIndex object.
defaults	The ModulemdDefaults object to add to the index.
error	A GError containing the reason the ModulemdDefaults object could not be added or NULL if the function succeeded.	[out]

Returns

TRUE if the ModulemdDefaults was added successfully. If the defaults already existed in the index, it will be replaced by the new one. On failure, returns FALSE and sets error appropriately.

Since: 2.0

modulemd_module_index_add_obsoletes ()

gboolean
modulemd_module_index_add_obsoletes (ModulemdModuleIndex *self,
                                     ModulemdObsoletes *obsoletes,
                                     GError **error);

Parameters

self	This ModulemdModuleIndex object.
obsoletes	The ModulemdObsoletes object to add to the index.	[in]
error	A GError containing the reason the ModulemdObsoletes object could not be added or NULL if the function succeeded.	[out]

Returns

TRUE if the ModulemdObsoletes was added successfully. If the obsoletes already existed in the index, it will be replaced by the new one. On failure, returns FALSE and sets error appropriately.

Since: 2.10

modulemd_module_index_get_default_streams_as_hash_table ()

GHashTable *
modulemd_module_index_get_default_streams_as_hash_table
                               (ModulemdModuleIndex *self,
                                const gchar *intent);

Get a dictionary of all modules in the index that have a default stream.

This function cannot fail, but may return an empty (non-NULL) GHashTable.

[rename-to modulemd_module_index_get_default_streams]

Parameters

self	This ModulemdModuleIndex object.	[in]
intent	The name of the system intent whose default stream will be retrieved. If left NULL or the specified intent has no separate default, it will return the generic default stream for this module. System intents are deprecated and this argument will be ignored in the future.	[in][nullable]

Returns

A GHashTable with the module name as the key and the default stream as the value for all modules with a default stream in the index. Modules without a default stream will not appear in this table.

[transfer container][element-type utf8 utf8]

Since: 2.5

modulemd_module_index_add_translation ()

gboolean
modulemd_module_index_add_translation (ModulemdModuleIndex *self,
                                       ModulemdTranslation *translation,
                                       GError **error);

Parameters

self	This ModulemdModuleIndex object.
translation	The ModulemdTranslation object to add to the index.
error	A GError containing the reason the ModulemdTranslation object could not be added or NULL if the function succeeded.	[out]

Returns

TRUE if the ModulemdTranslation was added successfully. If the translation already existed in the index, it will be replaced by the new one. On failure, returns FALSE and sets error appropriately.

Since: 2.0

modulemd_module_index_get_defaults_mdversion ()

ModulemdDefaultsVersionEnum
modulemd_module_index_get_defaults_mdversion
                               (ModulemdModuleIndex *self);

Parameters

self

This ModulemdModuleIndex object.

Returns

The metadata version of ModulemdDefaults in use for this index.

Since: 2.0

modulemd_module_index_get_stream_mdversion ()

ModulemdModuleStreamVersionEnum
modulemd_module_index_get_stream_mdversion
                               (ModulemdModuleIndex *self);

Parameters

self

This ModulemdModuleIndex object.

Returns

The metadata version of ModulemdModuleStream in use for this index.

Since: 2.0

modulemd_module_index_upgrade_streams ()

gboolean
modulemd_module_index_upgrade_streams (ModulemdModuleIndex *self,
                                       ModulemdModuleStreamVersionEnum mdversion,
                                       GError **error);

Upgrades all ModulemdModuleStream objects in this index to mdversion if they are not already at that version.

Parameters

self	This ModulemdModuleIndex object.
mdversion	The ModulemdModuleStream metadata version to upgrade to.
error	A GError that contains information on why the index could not be upgraded in the event of an error.	[out]

Since: 2.0

modulemd_module_index_upgrade_defaults ()

gboolean
modulemd_module_index_upgrade_defaults
                               (ModulemdModuleIndex *self,
                                ModulemdDefaultsVersionEnum mdversion,
                                GError **error);

Upgrades all ModulemdDefaults objects in this index to mdversion if they are not already at that version. An attempt to downgrade or an attempt to upgrade beyond the latest supported version will report an error. In the case of a failure to upgrade a particular ModulemdDefaults object of the index, an error will be reported and the index will be left in an undefined state.

Parameters

self	This ModulemdModuleIndex object.
mdversion	The ModulemdDefaults metadata version to upgrade to.
error	A GError that contains information on why the index could not be upgraded in the event of an error.	[out][optional]

Since: 2.0

modulemd_module_index_clear_xmds ()

void
modulemd_module_index_clear_xmds (ModulemdModuleIndex *self);

Iterates through all ModulemdModuleStream entries in this ModulemdModuleIndex and removes any XMD sections that are present. This is generally done to trim down the metadata to only the portions that are useful to the package manager.

Parameters

self

This ModulemdModuleIndex object.

Since: 2.14

Types and Values

MODULEMD_TYPE_MODULE_INDEX

#define MODULEMD_TYPE_MODULE_INDEX (modulemd_module_index_get_type ())

ModulemdModuleIndex

typedef struct _ModulemdModuleIndex ModulemdModuleIndex;