Metadata-Version: 2.5
Name: pysgf
Version: 1.0.0
Summary: Simple parser for Go game records (SGF, NGF, GIB)
Author: Sander Land
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: chardet>=5.2.0
Description-Content-Type: text/markdown

# PySGF
[![CI](https://github.com/sanderland/pysgf/actions/workflows/ci.yml/badge.svg)](https://github.com/sanderland/pysgf/actions/workflows/ci.yml)
[![PyPI version](https://badge.fury.io/py/pysgf.svg)](https://pypi.org/project/pysgf/)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)


PySGF is a lightweight but powerful parser for Go game records,
supporting the SGF format as well as NGF and GIB.

## Quickstart

```python
from pysgf import GoGame

# parse either a string ..
root = GoGame.parse(input_sgf)
# or pass a file name. It will try to detect the encoding specified in the record file.
# files ending in .ngf or .gib are parsed as those formats instead.
root = GoGame.parse_file(input_file_name)
# all properties are stored as lists, but you can ask for the first
root.get_list_property("AB")
root.get_property("KM")
move = root.move  # returns a Move object with options for SGF, GTP or 0- based coordinates
children = root.children  # returns all child nodes
```

`parse`/`parse_sgf`/`parse_file` return the root node. To keep the game object itself,
use `GoGame.from_string(contents, ext="sgf")` or `GoGame.from_file(filename)` and
access `game.root`.

## Extending

`GoGame` and `GoNode` are the concrete classes for everyday use. Projects that need to
attach their own state or behaviour to nodes can subclass the generic base classes,
which keeps `parent`, `children` and `play()` typed as the subclass:

```python
from pysgf import BaseGoGame, BaseGoNode


class MyNode(BaseGoNode["MyNode"]):
    def __init__(self, parent=None, properties=None, move=None):
        super().__init__(parent=parent, properties=properties, move=move)
        self.my_analysis = None


class MyGame(BaseGoGame[MyNode]):
    NODE_TYPE = MyNode


root = MyGame.parse(input_sgf)  # -> MyNode
```

## Requirements

Python 3.11 or newer.

## Documentation

Building the documentation needs the `docs` dependency group. Install it first —
building against a system-wide Sphinx (e.g. Debian/Ubuntu's `python3-sphinx`) will
fail with `no theme named 'sphinx_rtd_theme' found`, since the packaged theme is
usually missing or too old:

```bash
uv sync --group docs
uv run make -C docs html
```

Without uv:

```bash
pip install -e . "sphinx>=9,<10" "sphinx-rtd-theme>=3.1,<4"
make -C docs html
```

Note the `-e .` — `autodoc` imports `pysgf` to document it, so the package has to be
installed in the same environment as Sphinx. The generated HTML lands in `docs/build/html`.
