FEATURE: basic notation standard

.flake8

@@ -0,0 +1,15 @@
+[flake8]
+exclude =
+    .git
+    .github
+    .venv
+    __pycache__
+    .eggs
+    *.egg
+    *.egg-info
+    build
+    dist
+    venv
+ignore = D200, D204, D205, D400, D401
+max-line-length = 100
+max-complexity = 10

.readthedocs.yaml

@@ -7,7 +7,7 @@ build:
 
 sphinx:
   configuration: docs/source/conf.py
-  
+
 formats:
   - pdf
 

docs/source/conf.py

@@ -30,11 +30,12 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    'autoapi.extension'
+    'autoapi.extension',
+    'sphinx.ext.autosectionlabel',
 ]
 
 autoapi_dirs = ['../../notation']
-
+autosectionlabel_prefix_document = True
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 

docs/source/index.rst

@@ -1,4 +1,4 @@
-.. Whist-Core documentation master file, created by
+.. Notations documentation master file, created by
    sphinx-quickstart on Mon May 10 14:28:49 2021.
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
@@ -12,6 +12,9 @@ Welcome to Notation's documentation!
 
    autoapi/notation/index.rst
 
+
+:ref:`standard:Card Game Notation Standard`
+
 Indices and tables
 ==================
 

docs/source/standard.rst

@@ -0,0 +1,55 @@
+Card Game Notation Standard
+===========================
+This standard uses TOML_ as notation language.
+
+Header
+-------
+All meta data is defined in the Header.
+This contains information about teams and players.
+Furthermore, the location and datetime is stated.
+
+.. code-block:: toml
+
+    [header]
+    # Timestamp of the starting time in RFC 3339
+    timestamp = 2022-08-06T11:22:00
+    # Location of the game or the server url
+    location = "Hamburg"
+    # Unsigned Integer
+    number_of_teams = 2
+    [[players]]
+    # Unsigned Integer: ID of team starting with 0
+    team = 0
+    name = "John"
+    [[players]]
+    team = 1
+    Name = "Lucy"
+
+Stack
+-----
+The data contains one mandatory field ``stack`` that is a list of strings representing a card.
+Furthermore it has an optional field ``hands`` that is a table of the players' cards in hand.
+One card can be represented with
+
+.. code-block:: toml
+
+    suit = "[♦♣♥♠]"
+    rank = "[2-10JQKA]"
+
+.. code-block:: toml
+
+
+    [[stack]]
+    suit="heart"
+    rank="A"
+    [[stack]]
+    suit="heart"
+    rank="K"
+
+    [[hands.player_1]]
+    [[hands.player_1.card]]
+    suit="heart"
+    rank="2"
+
+
+.. _TOML: https://toml.io/en/

notation/card.py

@@ -0,0 +1,70 @@
+"""Python implementation of a general card and specific versions."""
+import tomlkit
+
+FRENCH_SUITS = ('♦', '♣', '♥', '♠')
+
+FRENCH_RANKS = ('A', '2', '3', '4', '5', '6', '7', '8', '9', '10', 'J', 'Q', 'K')
+
+
+class Card:
+    """General representation of a card."""
+
+    def __init__(self, suit: str, rank: str) -> None:
+        """
+        Construct a card.
+
+        :param suit: The suit of the card.
+        :param rank: The rank of the card.
+        """
+        self._suit: str = self._valid_suit(suit)
+        self._rank: str = self._valid_rank(rank)
+
+    @staticmethod
+    def _valid_suit(suit: str) -> str:
+        if not isinstance(suit, str):
+            raise ValueError('Suit must be string.')
+        if not suit:
+            raise ValueError('Suit cannot be empty.')
+        return suit
+
+    @staticmethod
+    def _valid_rank(rank: str) -> str:
+        if not isinstance(rank, str):
+            raise ValueError('Rank must be string.')
+        if not rank:
+            raise ValueError('Rank must not be empty.')
+        return rank
+
+    @property
+    def suit(self) -> str:
+        """Returns the suit of a card as string."""
+        return self._suit
+
+    @property
+    def rank(self) -> str:
+        """Returns the rank of a card as string."""
+        return self._rank
+
+    def dumps(self) -> str:
+        """Return the card as TOML string."""
+        return tomlkit.dumps(self.dict())
+
+    def dict(self):
+        """Return the card as dictionary."""
+        return {'suit': self._suit, 'rank': self._rank}
+
+
+class FrenchCard(Card):
+    """Represents a French card."""
+
+    @staticmethod
+    def _valid_suit(suit: str) -> str:
+        if suit not in FRENCH_SUITS:
+            raise ValueError('Not a correct french suit.')
+        return suit
+
+    @staticmethod
+    def _valid_rank(rank: str) -> str:
+        if rank not in FRENCH_RANKS:
+            raise ValueError('Not a correct french rank.')
+        return rank

notation/header.py

@@ -0,0 +1,39 @@
+"""Header containing the meta data of a game."""
+from datetime import datetime
+from typing import Optional
+
+import tomlkit
+
+from notation.player import Player
+
+
+# pylint: disable=too-few-public-methods
+class Header:
+    """Class implementation of a meta data wrapper."""
+
+    def __init__(self, start_time: datetime, players: list[Player],
+                 number_teams: int, location: Optional[str] = None, ):
+        """Constructor.
+        :param start_time: The start time of the game as datetime object
+        :param players: The list of players.
+        :param number_teams: The number of teams.
+        :param location: Optional. Where the game to place.
+        """
+        self._start_time: datetime = start_time
+        self._location = location
+        if players is None or len(players) == 0:
+            raise ValueError('Player list cannot be empty')
+        if number_teams > len(players):
+            raise ValueError('Number teams cannot be greater than amount of players')
+        self._players = players
+        self._number_teams = number_teams
+
+    def dumps(self) -> str:
+        """Return a TOML string representation of the header."""
+        players = [tomlkit.dumps({'players': [player.dict()]}) for player in self._players]
+        header_dump = {'header': {'timestamp': self._start_time.isoformat(),
+                                  'number_of_teams': self._number_teams}}
+        if self._location:
+            header_dump['header']['location'] = self._location
+        player_string = '\n'.join(players)
+        return f'{tomlkit.dumps(header_dump)}\n{player_string}'

notation/player.py

@@ -0,0 +1,20 @@
+"""Wrapper for player data."""
+
+
+# pylint: disable=too-few-public-methods
+class Player:
+    """Class containing player data."""
+
+    def __init__(self, name: str, team: int, seat: int):
+        """Constructs
+        :param name: name of player
+        :param team: integer of the team ID
+        :param seat: The unique identifier of place at table for that player.
+        """
+        self._name = name
+        self._team = team
+        self._seat = seat
+
+    def dict(self) -> dict[str, str]:
+        """Return player data as dictionary."""
+        return {'name': self._name, 'team': self._team, 'seat': self._seat}

notation/stack.py

@@ -0,0 +1,24 @@
+"""Implementation of a stack of cards."""
+from typing import List
+
+import tomlkit
+
+from notation.card import Card
+
+
+# pylint: disable=too-few-public-methods
+class Stack:
+    """A list of cards."""
+
+    def __init__(self, cards: List[Card]):
+        """
+        Construct a stack of cards.
+
+        :param cards: A list of cards.
+        """
+        self._card_list: List[Card] = cards
+
+    def dumps(self) -> str:
+        """Return the stack as TOML string."""
+        card_dump = [card.dict() for card in self._card_list]
+        return tomlkit.dumps({'stack': card_dump})