Create initial games catalog from contrib/games

[edwardchalstrey1]

This feature request is for...

PyGambit

Requested enahancement or feature

This issue is meant to scope an initial PR of the games library/catalog idea discussed in #623 but not yet to move all tests & documentation/tutorials etc over to loading from the catalog.

To do:

• Create a new folder called /catalog and move the EFG/NFG files from contrib/games there
• Create a new catalog.py which contains the catalog of games.
• Decide whether to structure catalog and contained games as a class with functions, class with subclasses, or dataclasses. You should be able to get a game like g = pygambit.catalog.PrisonersDilemma()
• Should be a way to retrieve/list all games
• Each game needs a name that makes sense according to a consistent naming convention that can easily remain stable
  • Derive class name slugs from the filename for now
  • Restore getting game_type from game_file
  • Restore loading attributes from games - no metadata fields should be added that can already be part of a game object anyway
    • But we still want ability to add metadata e.g. is_perfect_recall
  • Get the description field from the gambit game "comment"
    • it should let you do arbitrary text
    • Citation should be included in comment
  • Decide a way to auto-generated from contrib files
  • Write a script that builds a "database" from contrib/games by updating catalog.py
    • Make it so this script ignores files that already have a class in the catalog, just adding anything not already added
    • Ensure comments are retained
    • Document the script, including for now pip install ruamel.yaml
    • Ted and Rahul can then go in and update the "database" for the slug/class, title & comment/description
• Think about whether catalog.py should be refactored to be a proper database, whether a yml/json file or sqlite etc
  • I think a json/yml file would be harder to maintain and look at diffs in PRs, db is overkill
  • Add catalog.yml which is generated by the database building script
  • Make it so we can add whatever custom metadata we want to each class - It could be that we update the Game class to have an attribute which is a dataclass for the catalog metadata
    • Another option could be a "catalog metadata" dataclass that is added to Game objects directly
    • Add catalog metadata to classes
    • Ignore any that have valid_game: false
    • You should be able to filter on all metadata fields, whether they come from the game object or the catalog metadata
• Each game has to have the following attributes:
  • title
  • description
  • citation
  • no. of players
    • should be able to filter on this
  • extensive or normal form
    • should be able to filter on this
• For the initial games (from contrib/games) the functions will simply call read_efg("game.efg") or read_nfg("game.nfg") and return the game object
  • Add a class for all the efg and nfg games
  • Also look at the other game filetypes e.g. .agg
• Include an "Adding a game to the catalog" docs page
• Update tutorials
• Add tests
• Make it so the notebook tests don't fail with an ImportError when doing from pygambit import catalog - at the moment, I don't include catalog module in the main __init__.py because of the circular imports I created to allow the functionality of the catalog filtering games() by the number of players in advance of game instantiation.
  • An alternative to avoid this conundrum would be to make the number of players, titles and type (efg/nfg) mandatorily defined in the catalog entry (at the moment, a subclass of CatalogGame. Then could either enforce or throw warning if these don't match the game. Perhaps via tests.
• Ensure catalog functions are properly documented in API reference
  • Make it so that all classes that are generated from catalog.yml have a docstring, which gets populated by game.comment or description field (not metadata) in the catalog entry
• Some of the game functions (or classes) you can pass in parameters to get variants of games
• New games can be added to the catalog as functions that create the game from the python code directly rather than loading from efg/nfg e.g. those currently in tests/games.py