# Groups

## Description

Groups are collections of glyphs. Groups are used for many things, from OpenType features, kerning, or just keeping track of a collection of related glyphs. The name of the group must be at least one character, with no limit to the maximum length for the name, nor any limit on the characters used in a name. With the exception of the kerning groups defined below, glyphs may be in more than one group and they may appear within the same group more than once. Glyphs in the groups are not required to be in the font.

Groups behave like a Python dictionary. Anything you can do with a dictionary in Python, you can do with Groups.

    font = CurrentFont()
    for name, members in font.groups.items():
        print(name)
        print(members)

It is important to understand that any changes to the returned group contents will not be reflected in the groups object. This means that the following will not update the font’s groups:

    group = list(font.groups["myGroup"])
    group.remove("A")

If one wants to make a change to the group contents, one should do the following instead:

    group = list(font.groups["myGroup"])
    group.remove("A")
    font.groups["myGroup"] = group

### Kerning Groups

Groups may be used as members of kerning pairs in `BaseKerning`. These groups are divided into two types: groups that appear on the first side of a kerning pair and groups that appear on the second side of a kerning pair.

Kerning groups must begin with standard prefixes. The prefix for groups intended for use in the first side of a kerning pair is `public.kern1.`. The prefix for groups intended for use in the second side of a kerning pair is `public.kern2.`. One or more characters must follow the prefix.

Kerning groups must strictly adhere to the following rules:

1. Kerning group names must begin with the appropriate prefix.

2. Only kerning groups are allowed to use the kerning group prefixes in their names.

3. Kerning groups are not required to appear in the kerning pairs.

4. Glyphs must not appear in more than one kerning group per side.

These rules come from the Unified Font Object, more information on implementation details for application developers can be found there.

## Overview

`BaseGroups.copy` | Copy this object into a new object of the same type.
`BaseGroups.font` | The Groups' parent `BaseFont`.
`BaseGroups.__contains__` | Tests to see if a group name is in the Groups. groupName will be a String. This returns a `bool` indicating if the groupName is in the Groups. ::.
`BaseGroups.__delitem__` | Removes groupName from the Groups. groupName is a String.::.
`BaseGroups.__getitem__` | Returns the contents of the named group. groupName is a String. The returned value will be a Immutable List of the group contents.::.
`BaseGroups.__iter__` | Iterates through the Groups, giving the key for each iteration. The order that the Groups will iterate though is not fixed nor is it ordered.::.
`BaseGroups.__len__` | Returns the number of groups in Groups as an `int`..
`BaseGroups.__setitem__` | Sets the groupName to the list of glyphNames.
`BaseGroups.clear` | Removes all group information from Groups, resetting the Groups to an empty dictionary. ::.
`BaseGroups.get` | Returns the contents of the named group. groupName is a String, and the returned values will either be Immutable List of group contents or `None` if no group was found. ::.
`BaseGroups.items` | Returns a list of `tuple` of each group name and group members.
`BaseGroups.keys` | Returns a `list` of all the group names in Groups. This list will be unordered.::.
`BaseGroups.pop` | Removes the groupName from the Groups and returns the list of group members.
`BaseGroups.update` | Updates the Groups based on otherGroups.
`BaseGroups.values` | Returns a `list` of each named group's members.
`BaseGroups.findGlyph` | Returns a `list` of the group or groups associated with glyphName. glyphName will be an String. If no group is found to contain glyphName an empty `list` will be returned. ::.
`BaseGroups.naked` | Return the environment's native object that has been wrapped by this object.
`BaseGroups.changed` | Tell the environment that something has changed in the object.

## Reference

class fontParts.base.BaseGroups(*args, **kwargs)

  A Groups object. This object normally created as part of a `BaseFont`. An orphan Groups object can be created like this:

      >>> groups = RGroups()

  This object behaves like a Python dictionary. Most of the dictionary functionality comes from `BaseDict`, look at that object for the required environment implementation details.

  Groups uses `normalizers.normalizeGroupKey` to normalize the key of the `dict`, and `normalizers.normalizeGroupValue` to normalize the value of the `dict`.

### Copy

BaseGroups.copy()

  Copy this object into a new object of the same type. The returned object will not have a parent object.

### Parents

- `font` The groups’ parent `BaseFont`.

### Dictionary

BaseGroups.__contains__(groupName)

  Tests to see if a group name is in the Groups. groupName will be a String. This returns a `bool` indicating if the groupName is in the Groups.

      >>> "myGroup" in font.groups
      True

BaseGroups.__delitem__(groupName)

  Removes groupName from the Groups. groupName is a String.:

      >>> del font.groups["myGroup"]

BaseGroups.__getitem__(groupName)

  Returns the contents of the named group. groupName is a String. The returned value will be a Immutable List of the group contents.:

      >>> font.groups["myGroup"]
      ("A", "B", "C")

  It is important to understand that any changes to the returned group contents will not be reflected in the Groups object. If one wants to make a change to the group contents, one should do the following:

      >>> group = font.groups["myGroup"]
      >>> group.remove("A")
      >>> font.groups["myGroup"] = group

BaseGroups.__iter__()

  Iterates through the Groups, giving the key for each iteration. The order that the Groups will iterate though is not fixed nor is it ordered.:

      >>> for groupName in font.groups:
      >>>     print groupName
      "myGroup"
      "myGroup3"
      "myGroup2"

BaseGroups.__len__()

  Returns the number of groups in Groups as an `int`.:

      >>> len(font.groups)
      5

BaseGroups.__setitem__(groupName, glyphNames)

  Sets the groupName to the list of glyphNames. groupName is the group name as a String and glyphNames is a `list` of glyph names as String.

      >>> font.groups["myGroup"] = ["A", "B", "C"]

BaseGroups.clear()

  Removes all group information from Groups, resetting the Groups to an empty dictionary.

      >>> font.groups.clear()

BaseGroups.get(groupName, default=None)

  Returns the contents of the named group. groupName is a String, and the returned values will either be Immutable List of group contents or `None` if no group was found.

      >>> font.groups["myGroup"]
      ("A", "B", "C")

  It is important to understand that any changes to the returned group contents will not be reflected in the Groups object. If one wants to make a change to the group contents, one should do the following:

      >>> group = font.groups["myGroup"]
      >>> group.remove("A")
      >>> font.groups["myGroup"] = group

BaseGroups.items()

  Returns a list of `tuple` of each group name and group members. Group names are String and group members are a Immutable List of String. The initial list will be unordered.

      >>> font.groups.items()
      [("myGroup", ("A", "B", "C"), ("myGroup2", ("D", "E", "F"))]

BaseGroups.keys()

  Returns a `list` of all the group names in Groups. This list will be unordered.:

      >>> font.groups.keys()
      ["myGroup4", "myGroup1", "myGroup5"]

BaseGroups.pop(groupName, default=None)

  Removes the groupName from the Groups and returns the list of group members. If no group is found, default is returned. groupName is a String. This must return either default or a Immutable List of glyph names as String.

      >>> font.groups.pop("myGroup")
      ("A", "B", "C")

BaseGroups.update(otherGroups)

  Updates the Groups based on otherGroups. otherGroups* is a `dict` of groups information. If a group from otherGroups is in Groups, the group members will be replaced by the group members from otherGroups. If a group from otherGroups is not in the Groups, it is added to the Groups. If Groups contain a group name that is not in otherGroups*, it is not changed.

      >>> font.groups.update(newGroups)

BaseGroups.values()

  Returns a `list` of each named group’s members. This will be a list of lists, the group members will be a Immutable List of String. The initial list will be unordered.

      >>> font.groups.items()
      [("A", "B", "C"), ("D", "E", "F")]

### Queries

BaseGroups.findGlyph(glyphName)

  Returns a `list` of the group or groups associated with glyphName. glyphName will be an String. If no group is found to contain glyphName an empty `list` will be returned.

      >>> font.groups.findGlyph("A")
      ["A_accented"]

### Environment

BaseGroups.naked()

  Return the environment’s native object that has been wrapped by this object.

      >>> loweLevelObj = obj.naked()

BaseGroups.changed(*args, **kwargs)

  Tell the environment that something has changed in the object. The behavior of this method will vary from environment to environment.

      >>> obj.changed()

Previous

Info

Next

Kerning