# `libcomps` - Libcomps objects

## libcomps.Comps

class libcomps.Comps

  Comps class is representating comps.xml file represented in structure form.

  Note

  members:

    blacklist, langpacks, whiteout

  are Fedora objects only

  arch_filter(arch_list) → libcomps.Comps

    Filter Comps object content by _arch attribute matchingpassed archictures

    Parameters:

      arch_list (list of strings or libcomps.StrSeq) – list of architectures

    Returns:

      new `libcomps.Comps` instace

  categories_match()

    validate inner structure of Comps object.Raise appropriate exception on first occured error

    Raises:

      ValueError – with appropriate error message

  clear()

    Clear Comps

  environments_match()

    validate inner structure of Comps object.Raise appropriate exception on first occured error

    Raises:

      ValueError – with appropriate error message

  fromxml_f(fname[, def_options]) → int

    Load COMPS from xml file

    Parameters:

      - fname (str) – filename to be readed

      - def_options (dict) – dictionary containing options used forspecify values of missing objects attributes in xml_str string

    Returns:

      1 if some non-fatal error occured during parsing

      0 if parsing ended without any error

    Raises:

      - libcomps.ParserError – if some fatal erroroccured during parsing

      - IOError – if specified filename cannot be opened for reading

  fromxml_str(xml_str[, def_options]) → int

    Load COMPS from xml string

    Parameters:

      - xml_str (str) – string containing comps xml representation

      - def_options (dict) – dictionary containing options used forspecify values of missing objects attributes in xml_str string

    Returns:

      1 if some non-fatal error occured during parsing

      0 if parsing ended without any error

    Raises:

      libcomps.ParserError – if some fatal error occured during parsing

  get_last_errors()

    return list of messages from log of last parse action, contains errors only

  get_last_log()

    return list of messages from log of last parse action.

  groups_match()

    validate inner structure of Comps object.Raise appropriate exception on first occured error

    Raises:

      ValueError – with appropriate error message

  toxml_f(fname[, xml_options[, def_options]]) → int

    alias for `Comps.xml_f()`

  toxml_str([xml_options[, def_options]]) → str

    alias for `Comps.xml_str()`

  validate()

    validate inner structure of Comps object.Raise appropriate exception on first occured error

    Raises:

      ValueError – with appropriate error message

  validate_nf()

    validate inner structure of Comps class.Returns list of error strings

    Return type:

      list of strings

  xml_f(fname[, xml_options[, def_options]]) → list

    Generate xml output of Comps class to file

    Parameters:

      - fname (str) – filename

      - xml_options (dict) – dict of options used for specify xml output

      - def_options (dict) – dict of options used for specify default values of missing attributes of objects

    Returns:

      list of errors encountered during xml generating

    Return type:

      list of strings

    Raises:

      XMLGenError – if generating xml encounter some fatal error

  xml_str([xml_options[, def_options]]) → str

    Generate xml output of Comps object a return it as string

    Parameters:

      - xml_options (dict) – dict of options used for specify xml output

      - def_options (dict) – dict of options used for specify default values of missing attributes of objects

    Returns:

      string containing xml output

  blacklist

    `libcomps.MDict` of blacklist

  categories

    `libcomps.CategoryList` of categories

  environments

    `libcomps.EnvList` of environments

  groups

    `libcomps.GroupList` of groups

  langpacks

    `libcomps.StrDict` of langpacks

  whiteout

    `libcomps.MDict` of whiteout

## libcomps.GroupList

class libcomps.GroupList

  Comps Group list

  is class mostly similar to normal python list with few diferences:

  - accepting only specified type of object. `GroupList` devours only `Group` instance.

  - accepting string argument in getter/setter items methods as identificator of objects by id.

  - run validation procedure on absorbed object so you can’t append/insert/set invalid `Group` object

      g1 = libcomps.Group()
      g1.id = "g1"
      comps.categories.append(g1)

      g2 = libcomps.Group()
      g2.id = "g2"
      comps.categories.append(g2)

      g = comps.groups["g2"]
      comps.categories["g1"] = libcomps.Group()

  append()

    Append item to new of the list

  clear()

    Clear the list

  insert(pos, item) → None

    Insert item into list at position pos

    Parameters:

      pos – intposition

    Returns:

      None

  remove(item) → None

    Remove first occurence of item from list

    Raises:

      - TypeError – If type of item is not type acceptable for list

      - ValueError – If item is not in the list

## libcomps.CategoryList

class libcomps.CategoryList

  Comps Category list

  is class mostly similar to normal python list with few diferences:

  - accepting only specified type of object. `CategoryList` devours only `Category` instance.

  - accepting string argument in getter/setter items methods as identificator of objects by id.

  - run validation procedure on absorbed object so you can’t append/insert/set invalid `Category` object

      c1 = libcomps.Category()
      c1.id = "c1"
      comps.categories.append(c1)

      c2 = libcomps.Category()
      c2.id = "c2"
      comps.categories.append(c2)

      c = comps.groups["c2"]
      comps.categories["c1"] = libcomps.Category()

  append()

    Append item to new of the list

  clear()

    Clear the list

  insert(pos, item) → None

    Insert item into list at position pos

    Parameters:

      pos – intposition

    Returns:

      None

  remove(item) → None

    Remove first occurence of item from list

    Raises:

      - TypeError – If type of item is not type acceptable for list

      - ValueError – If item is not in the list

## libcomps.EnvList

class libcomps.EnvList

  Comps Env list

  is class mostly similar to normal python list with few diferences:

  - accepting only specified type of object. `EnvList` devours only `Environment` instance.

  - accepting string argument in getter/setter items methods as identificator of objects by id.

  - run validation procedure on absorbed object so you can’t append/insert/set invalid `Environment` object

      e1 = libcomps.Environment()
      e1.id = "e1"
      comps.environments.append(e1)

      e2 = libcomps.Environment()
      e2.id = "e2"
      comps.environments.append(e2)

      e = comps.groups["e2"]
      comps.categories["e1"] = libcomps.Environment()

  append()

    Append item to new of the list

  clear()

    Clear the list

  insert(pos, item) → None

    Insert item into list at position pos

    Parameters:

      pos – intposition

    Returns:

      None

  remove(item) → None

    Remove first occurence of item from list

    Raises:

      - TypeError – If type of item is not type acceptable for list

      - ValueError – If item is not in the list

## libcomps.Group

class libcomps.Group

  Comps Group

  packages_match()

    Return list of packages matching selected criteria

    Returns:

      List of packages

  validate()

    Validate inner group structure. Raise exception on firstoccured error.

    Returns:

      None if validation successful

    Raises:

      ValueError – on first occured error

  biarchonly

    Group uservisible attribute

  default

    Group default attribute

  desc

    descrition of group

  desc_by_lang

    dictionary of locale group descriptions

  display_order

    Group display order attribute

  id

    group string identificator

  lang_only

    group langonly attribute

  name

    name of group

  name_by_lang

    dictionary of locale group names

  packages

    `libcomps.PackageList` of `libcomps.Package`

  uservisible

    Group uservisible attribute

## libcomps.PackageList

class libcomps.PackageList

  Comps Group Package list

  is class mostly similar to normal python list with few diferences:

  - accepting only specified type of object. `PackageList` devours only `Package` instance.

  - accepting string argument in getter/setter items methods as identificator of package name.

  - run validation procedure on absorbed object so you can’t append/insert/set invalid `Package` object

## libcomps.Package

class libcomps.Package

  Comps Group Package

  validate()

    Validate inner package structure. Raise exception on firstoccured error.

    Returns:

      None if validation successful

    Raises:

      ValueError – on first occured error

  basearchonly

    Package basearchonly attribute

  name

    Package name

  requires

    Package requires

  type

    package type which could be one of following:

    - `libcomps.PACKAGE_TYPE_DEFAULT`

    - `libcomps.PACKAGE_TYPE_OPTIONAL`

    - `libcomps.PACKAGE_TYPE_CONDITIONAL`

    - `libcomps.PACKAGE_TYPE_MANDATORY`

    - `libcomps.PACKAGE_TYPE_UNKNOWN`

## libcomps.Category

class libcomps.Category

  Comps Category

  validate()

    validate inner category structure

  desc

    description of category

  desc_by_lang

    dictionary of locale category description

  display_order

    category display order attribute

  group_ids

    `libcomps.IdList` of `libcomps.GroupId`

  id

    category string identificator

  name

    name of category

  name_by_lang

    dictionary of locale category names

## libcomps.Environment

class libcomps.Environment

  Comps Environment

  validate()

    Validate inner environment structure. Raise exception on firstoccured error.

    Returns:

      None if validation successful

    Raises:

      ValueError – on first occured error

  desc

    description of environment

  desc_by_lang

    dictionary of locale environment descriptions

  display_order

    environment display order attribute

  group_ids

    `libcomps.IdList` of `libcomps.GroupId` representing environments group list

  id

    environment string identificator

  name

    name of environment

  name_by_lang

    dictionary of locale environment names

  option_ids

    `libcomps.IdList` of `libcomps.GroupId` representing environments option list

## libcomps.IdList

class libcomps.IdList

  Comps GIDs list

  is class mostly similar to normal python list with few diferences:

  - `IdList` accepting only unicode/string/`libcomps.GroupId` (string/unicode object are implicitly converted to `libcomps.GroupId`)

  - run validation procedure on absorbed object so you can’t append/insert/set invalid `GroupId` object

## libcomps.GroupId

class libcomps.GroupId

  Comps GroupId

  validate()

    validate inner Group ID structure

  default

    Group ID default

  name

    Group ID name

## libcomps.StrDict

class libcomps.StrDict

  Comps Str Dict

  clear()

    clear the dict

  copy()

    return shallow copy of dict

  get(key) → object

    Return object associated with key

    Parameters:

      key (str/unicode) – object key

    Returns:

      object if there’s object associated with key

      None otherwise

  has_key(key) → bool

    Tests if there’s key in object

    Parameters:

      key (str/unicode) – object key

    Returns:

      True if there’s object associated with key

      False otherwise

  items()

    return iterator returning (key, value) tuple

  keys()

    return iterator returning item’s key

  update(dict) → None

    Update dictionary with (key,value) pair from another dictionary.Existing pairs are overwritten

    Parameters:

      dict – `libcomps.Dict` instance or subclass instance

    Returns:

      None

  values()

    return iterator returning item’s value

is very lightweight version of python dict

> - libcomps.StrDict can have only string/unicode keys and accepts only string/unicode object

## libcomps.MDict

class libcomps.MDict

  Comps Dict

  clear()

    clear the dict

  copy()

    return shallow copy of dict

  get(key) → list of strings

    Return object associated with key

    Parameters:

      key (str/unicode) – object key

    Returns:

      object if there’s object associated with key

      None otherwise

  has_key(key) → bool

    Tests if there’s key in object

    Parameters:

      key (str/unicode) – object key

    Returns:

      True if there’s object associated with key

      False otherwise

  items()

    return iterator returning (key, value) tuple

  keys()

    return iterator returning item’s key

  update(dict) → None

    Update dictionary with (key,value) pair from another dictionary.Existing pairs are overwritten

    Parameters:

      dict – `libcomps.Dict` instance or subclass instance

    Returns:

      None

  values()

    return iterator returning item’s value

is class similar to python dict, except of these properties:

> - libcomps.MDict can have only string/unicode keys and accepts only list of string or libcomps.StrSeq which is also object returned from dict.__get__()

> - output of StrDict.keys() is in alphabetical order ()

## libcomps.StrSeq

class libcomps.StrSeq

  Comps Str list

  append()

    Append item to new of the list

  clear()

    Clear the list

  insert(pos, item) → None

    Insert item into list at position pos

    Parameters:

      pos – intposition

    Returns:

      None

  remove(item) → None

    Remove first occurence of item from list

    Raises:

      - TypeError – If type of item is not type acceptable for list

      - ValueError – If item is not in the list

is class similar to list, but accepts only string/unicode objects.