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:

Kerning group names must begin with the appropriate prefix.
Only kerning groups are allowed to use the kerning group prefixes in their names.
Kerning groups are not required to appear in the kerning pairs.
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 the current object into a new object of the same type.
`BaseGroups.font`	Get or set the groups' parent font object.
`BaseGroups.__contains__`	Check if the given key exists in the groups.
`BaseGroups.__delitem__`	Remove the given group from the current groups instance.
`BaseGroups.__getitem__`	Get the contents of the given group.
`BaseGroups.__iter__`	Return an iterator over the keys in the current groups instance.
`BaseGroups.__len__`	Return the number of groups in the current groups instance.
`BaseGroups.__setitem__`	Set the glyph names for a given group in the current groups instance.
`BaseGroups.clear`	Remove all groups from the current groups instance.
`BaseGroups.get`	Get the contents for the given group in the current groups instance.
`BaseGroups.items`	Return the items in the current groups instance.
`BaseGroups.keys`	Return the group names (keys) in the current groups instance.
`BaseGroups.pop`	Remove the specified group and return its associated contents.
`BaseGroups.update`	Update the current groups instance with key-value pairs from another.
`BaseGroups.values`	Return the values in the current groups instance.
`BaseGroups.findGlyph`	Retrieve the groups associated with the given glyph.
`BaseGroups.naked`	Return the environment's native object wrapped by the current object.
`BaseGroups.changed`	Tell the environment that something has changed in the object.

Reference¶

class fontParts.base.BaseGroups(*args: Any, **kwargs: Any)[source]¶

Represent the basis for a groups object.

This object behaves like a Python dict object. Most of the dictionary functionality comes from BaseDict. Consult that object’s documentation for the required environment implementation details.

Variables:

keyNormalizer – A function to normalize the key of the dictionary. Defaults to normalizers.normalizeGroupKey
valueNormalizer – A function to normalize the value of the dictionary. Defaults to normalizers.normalizeGroupValue

This object is normally created as part of a BaseFont. An orphan BaseGroups object instance can be created like this:

>>> groups = RGroups()

Copy¶

BaseGroups.copy() → BaseObjectType¶

Copy the current object into a new object of the same type.

The returned object will not have a parent object.

Returns:: A new BaseObject subclass instance with the same attributes.

Parents¶

font The groups’ parent BaseFont.

Dictionary¶

BaseGroups.__contains__(groupName: str) → bool[source]¶

Check if the given key exists in the groups.

Parameters:: groupName – The group name to check for existence as a str.
Returns:: True if the groupName exists in the groups, False otherwise.

Example:

>>> "myGroup" in font.groups
True

BaseGroups.__delitem__(groupName: str) → None[source]¶

Remove the given group from the current groups instance.

Parameters:: groupName – The name of the group to remove as a str.

Example:

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

BaseGroups.__getitem__(groupName: str) → tuple[str, ...][source]¶

Get the contents of the given group.

Parameters:: groupName – The group name to retrieve the value for as a str.
Returns:: A tuple of str glyph names.
Raises:: KeyError – If the specified groupName does not exist.

Example:

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

Note

Any changes to the returned lib contents will not be reflected in it’s BaseGroups instance. To make changes to this content, do the following:

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

BaseGroups.__iter__() → Iterator[str][source]¶

Return an iterator over the keys in the current groups instance.

The iteration order is not fixed.

Returns:: An Iterator over the str keys.

Example:

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

BaseGroups.__len__() → int[source]¶

Return the number of groups in the current groups instance.

Returns:: An int representing the number of groups in the current groups instance.

Example:

>>> len(font.groups)
5

BaseGroups.__setitem__(groupName: str, glyphNames: list[str] | tuple[str, ...]) → None[source]¶

Set the glyph names for a given group in the current groups instance.

Parameters:

groupName – The group name to set as a str.
glyphNames – The glyph names to set for the given group as a list or tuple of str items.

Example:

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

BaseGroups.clear() → None[source]¶

Remove all groups from the current groups instance.

This will reset the BaseGroups instance to an empty dictionary.

Example:

>>> font.groups.clear()

BaseGroups.get(groupName: str, default: list[str] | tuple[str, ...] | None = None) → tuple[str, ...] | None[source]¶

Get the contents for the given group in the current groups instance.

If the given groupName is not found, The specified default will be returned.

Parameters:

groupName – The group name to look up as a str.
default – The optional default value to return if the groupName is not found`. The value must be either a class`list` or tuple of str glyph names, or None. Defaults to None.

Returns:

The contents of the given group as a tuple of str items, or the default value if the group is not found.

Example:

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

..note:

Any changes to the returned lib contents will not be reflected in
it's :class:`BaseGroups` instance. To make changes to this content,
do the following::

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

BaseGroups.items() → BaseItems[str, ValueType][source]¶

Return the items in the current groups instance.

Each item is represented as a tuple of key-value pairs, where:

key is a str representing a group name.
value is a tuple of str glyph names.

Returns:: A type-view of the groups’ (key, value) pairs.

Example:

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

BaseGroups.keys() → BaseKeys[source]¶

Return the group names (keys) in the current groups instance.

Returns:: A type-view of str items representing the groups’ keys.

Example:

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

BaseGroups.pop(groupName: str, default: list[str] | tuple[str, ...] | None = None) → tuple[str, ...] | None[source]¶

Remove the specified group and return its associated contents.

If the groupName does not exist, the default value is returned.

Parameters:

groupName – The group to remove as a str.
default – The optional default value to return if the groupName is not found`. The value must be either a class`list` or tuple of str glyph names, or None. Defaults to None.

Returns:

The contents of the given group as a tuple of str items, or the default value if the group is not found.

Example:

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

BaseGroups.update(otherGroups: MutableMapping[str, list[str] | tuple[str, ...]]) → None[source]¶

Update the current groups instance with key-value pairs from another.

For each group in otherGroups:

If the group exists in the current groups instance, its value is replaced with the value from otherGroups.
If the key does not exist in the current groups instance, it is added.

Keys that exist in the current groups instance but are not in otherLib remain unchanged.

Parameters:: otherLib – A MutableMapping of str group names mapped to a tuple of str glyph names to update the current groups instance with.

Example:

>>> font.groups.update(newGroups)

BaseGroups.values() → BaseValues[source]¶

Return the values in the current groups instance.

Returns:: A type-view of the groups’ values as tuple items of str glyph names.

Example:

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

Queries¶

BaseGroups.findGlyph(glyphName: str) → list[str][source]¶

Retrieve the groups associated with the given glyph.

Parameters:: glyphName – The name of the glyph to search for as a str.
Returns:: A list of str items.

Example:

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

Environment¶

BaseGroups.naked() → Any¶

Return the environment’s native object wrapped by the current object.

Raises:: NotImplementedError – If the method has not been overridden by a subclass.

Example:

>>> loweLevelObj = obj.naked()

BaseGroups.changed(*args: Any, **kwargs: Any) → None¶

Tell the environment that something has changed in the object.

The behavior of this method will vary from environment to environment.

Parameters:

*args – Any positional arguments.
**kwargs – Any keyword arguments.

Example:

>>> obj.changed()

Info

Kerning