Sgf_game objects

SGF data is represented using Sgf_game objects. Each object represents the data for a single SGF file (corresponding to a GameTree in the SGF spec). This is typically used to represent a single game, possibly with variations (but it could be something else, such as a problem set).

Creating Sgf_games

An Sgf_game can either be created from scratch or loaded from a string.

To create one from scratch, instantiate an Sgf_game object directly:

class sgfmill.sgf.Sgf_game(size[, encoding="UTF-8"])

size is an integer from 1 to 26, indicating the board size.

The optional encoding parameter specifies the raw property encoding to use for the game.

When a game is created this way, the following root properties are initially set: FF[4], GM[1], SZ[size], and CA[encoding].

To create a game from existing SGF data, use the Sgf_game.from_bytes() or Sgf_game.from_string() classmethod:

classmethod Sgf_game.from_bytes(bb[, override_encoding=None])

Return type:Sgf_game

Creates an Sgf_game from the SGF data in bb, which must be a bytes-like object.

Raises ValueError if it can’t parse the data, or if the SZ or CA properties are unacceptable. No error is reported for other malformed property values. See also Parser behaviour.

Assumes the data is in the encoding described by the CA property in the root node (defaulting to "ISO-8859-1"), and uses that as the raw property encoding.

But if override_encoding is present, assumes the data is in that encoding (no matter what the CA property says), and sets the CA property and raw property encoding to match.

The board size is taken from the SZ propery in the root node (defaulting to 19). Board sizes greater than 26 are rejected.

Example:

g = sgf.Sgf_game.from_bytes(
    b"(;FF[4]GM[1]SZ[9]CA[UTF-8];B[ee];W[ge])",
    override_encoding="iso8859-1")

classmethod Sgf_game.from_string(s)

Return type:Sgf_game

Creates an Sgf_game from the SGF data in s, which must be a string.

Raises ValueError if it can’t parse the data, or if the SZ or CA properties are unacceptable. No error is reported for other malformed property values. See also Parser behaviour.

The game’s raw property encoding and CA property will be "UTF-8" (replacing any CA property present in the string).

The board size is taken from the SZ propery in the root node (defaulting to 19). Board sizes greater than 26 are rejected.

Example:

g = sgf.Sgf_game.from_string(
    "(;FF[4]GM[1]SZ[9]CA[UTF-8];B[ee];W[ge])")

Serialising Sgf_games

To retrieve the SGF data as bytes, use the serialise() method:

Sgf_game.serialise([wrap])

Return type:bytes

Produces the SGF representation of the data in the Sgf_game.

Returns a bytes object, in the encoding specified by the CA root property (defaulting to "ISO-8859-1").

See Changing the CA property for details of the behaviour if the CA property is changed from its initial value.

serialise() makes some effort to keep the output line length to no more than 79 bytes. Pass None in the wrap parameter to disable this behaviour, or pass an integer to specify a different limit.

Accessing the game’s nodes

The complete game tree is represented using Tree_node objects, which are used to access the SGF properties. An Sgf_game always has at least one node, the root node.

Sgf_game.get_root()

Return type:Tree_node

Returns the root node of the game tree.

The complete game tree can be accessed through the root node, but the following convenience methods are also provided. They return the same Tree_node objects that would be reached via the root node.

Some of the convenience methods are for accessing the leftmost variation of the game tree. This is the variation which appears first in the SGF GameTree, often shown in graphical editors as the topmost horizontal line of nodes. In a game tree without variations, the leftmost variation is just the whole game.

Sgf_game.get_last_node()

Return type:Tree_node

Returns the last (leaf) node in the leftmost variation.

Sgf_game.get_main_sequence()

Return type:list of Tree_node objects

Returns the complete leftmost variation. The first element is the root node, and the last is a leaf.

Sgf_game.get_main_sequence_below(node)

Return type:list of Tree_node objects

Returns the leftmost variation beneath the Tree_node node. The first element is the first child of node, and the last is a leaf.

Note that this isn’t necessarily part of the leftmost variation of the game as a whole.

Sgf_game.get_main_sequence_above(node)

Return type:list of Tree_node objects

Returns the partial variation leading to the Tree_node node. The first element is the root node, and the last is the parent of node.

Sgf_game.extend_main_sequence()

Return type:Tree_node

Creates a new Tree_node, adds it to the leftmost variation, and returns it.

This is equivalent to get_last_node().new_child()

Root node properties

The root node contains global properties for the game tree, and typically also contains game-info properties. It sometimes also contains setup properties (for example, if the game does not begin with an empty board).

Changing the FF and GM properties is permitted, but Sgfmill will carry on using the FF[4] and GM[1] (Go) rules.

Changing SZ is not permitted (but if the size is 19 you may remove the property).

Changing CA is permitted (this controls the encoding used by serialise()).

The following methods provide convenient access to some of the root node’s SGF properties. The main difference between using these methods and using get() on the root node is that these methods return the appropriate default value if the property is not present.

Sgf_game.get_size()

Return type:integer

Returns the board size (19 if the SZ root property isn’t present).

Sgf_game.get_charset()

Return type:string

Returns the effective value of the CA root property (ISO-8859-1 if the CA root property isn’t present).

The returned value is a codec name in normalised form, which may not be identical to the string returned by get_root().get("CA"). Raises ValueError if the property value doesn’t identify a Python codec.

This gives the encoding that would be used by serialise(). It is not necessarily the same as the raw property encoding (use get_encoding() on the root node to retrieve that).

Sgf_game.get_komi()

Return type:float

Returns the komi (0.0 if the KM root property isn’t present).

Raises ValueError if the KM root property is present but malformed.

Sgf_game.get_handicap()

Return type:integer or None

Returns the number of handicap stones.

Returns None if the HA root property isn’t present, or if it has value zero (which isn’t strictly permitted).

Raises ValueError if the HA property is otherwise malformed.

Sgf_game.get_player_name(colour)

Return type:string or None

Returns the name of the specified player, or None if the required PB or PW root property isn’t present.

Sgf_game.get_winner()

Return type:colour

Returns the colour of the winning player.

Returns None if the RE root property isn’t present, or if neither player won.

Sgf_game.set_date([date])

Sets the DT root property, to a single date.

If date is specified, it should be a datetime.date. Otherwise the current date is used.

(SGF allows DT to be rather more complicated than a single date, so there’s no corresponding get_date() method.)