Merge pull request #18 from daira/doc-and-tests

Doc and test improvements

.flake8

@@ -1,4 +1,14 @@
 [flake8]
 exclude = .git, __pycache__
-ignore = E302
+
+# Justifications for each ignored error or warning:
+# * E302: always requiring two blank lines rather than one between top-level items is too annoying and nitpicky.
+# * E402: we want imports for tests to go between the main code and the tests.
+# * W503, W504: these give false positives for the style of avoiding \ at the end of each line by using parens.
+#
+# References:
+# - https://flake8.pycqa.org/en/latest/user/error-codes.html
+# - https://pycodestyle.pycqa.org/en/latest/intro.html#error-codes
+ignore = E302, E402, W503, W504
+
 max-line-length = 120

.github/workflows/flake8.yml

@@ -10,6 +10,7 @@ jobs:
       - uses: actions/checkout@v2
 
       - name: Install gnome-keyring
+        # https://github.com/python-poetry/poetry/issues/2692
         run: sudo apt-get install gnome-keyring
 
       - name: Install poetry

.github/workflows/tests.yml

@@ -0,0 +1,24 @@
+name: tests
+
+on: pull_request
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Install gnome-keyring
+        # https://github.com/python-poetry/poetry/issues/2692
+        run: sudo apt-get install gnome-keyring
+
+      - name: Install poetry
+        run: pip install --user poetry
+
+      - name: Install dependencies
+        run: poetry install --no-root
+
+      - name: Run tests
+        # -p '[a-z]*.py' avoids running tests from __init__.py files twice.
+        run: poetry run python -m unittest discover -s simtfl -t . -p '[a-z]*.py' --verbose --buffer

.gitignore

@@ -1,6 +1,9 @@
 *.swp
 *.save
 
+# API docs
+apidoc/
+
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]

README.md

@@ -23,30 +23,26 @@ Note the caveats: *experimental*, *simulator*, *research*, *potential*.
 
        poetry run demo
 
-## Programming patterns
+## Documentation
 
-The code makes use of the [simpy](https://simpy.readthedocs.io/en/latest/)
-discrete event simulation library. This means that functions representing
-processes are implemented as generators, so that the library can simulate
-timeouts and asynchronous communication (typically faster than real time).
+Design documentation is under the `doc/` directory:
 
-We use the convention of putting "(process)" in the doc comment of these
-functions. They either must use the `yield` construct, *or* return the
-result of calling another "(process)" function (not both).
+* [Programming patterns for use of simpy](doc/patterns.md).
 
-Objects that implement processes typically hold the `simpy.Environment` in
-an instance variable `self.env`.
+You can also generate API documentation by running `./gendoc.sh`. This assumes
+that you have run `poetry install` as shown above. The starting point for the
+generated documentation is <apidoc/simtfl.html>.
 
-To wait for another process `f()` before continuing, use `yield from f()`.
-(If it is the last thing to do in a function with no other `yield`
-statements, `return f()` can be used as an optimization.)
+## Contributing
 
-A "(process)" function that does nothing should `return skip()`, using
-`simtfl.util.skip`.
+Please use `./check.sh` before submitting a PR. This currently runs `flake8`
+and the unit tests locally.
 
-## Contributing
+You can use `./check.sh -k <substring>` to run `flake8` and then only tests
+with names matching the given substring. This will not suppress output to
+stdout or stderr (but `./check.sh -bk <substring>` will).
 
-Please check `poetry run flake8` before submitting a PR.
+To see other options for running unit tests, use `poetry run python -m unittest -h`.
 
 ## License
 

check.sh

@@ -0,0 +1,12 @@
+#!/bin/sh
+
+set -eu
+cd -P -- "$(dirname -- "$(command -v -- "$0")")"
+
+echo Running flake8...
+poetry run flake8
+
+echo
+echo Running unit tests...
+args="${*:---buffer}"
+poetry run python -m unittest discover -s simtfl -t . -p '[a-z]*.py' --verbose ${args}

doc/patterns.md

@@ -0,0 +1,20 @@
+# Programming patterns
+
+The code makes use of the [simpy](https://simpy.readthedocs.io/en/latest/)
+discrete event simulation library. This means that functions representing
+processes are implemented as generators, so that the library can simulate
+timeouts and asynchronous communication (typically faster than real time).
+
+We use the convention of putting "(process)" in the doc comment of these
+functions. They either must use the `yield` construct, *or* return the
+result of calling another "(process)" function (not both).
+
+Objects that implement processes typically hold the `simpy.Environment` in
+an instance variable `self.env`.
+
+To wait for another process `f()` before continuing, use `yield from f()`.
+(If it is the last thing to do in a function with no other `yield`
+statements, `return f()` can be used as an optimization.)
+
+A "(process)" function that does nothing should `return skip()`, using
+`simtfl.util.skip`.

gendoc.sh

@@ -0,0 +1,5 @@
+#!/bin/sh
+
+set -eu
+
+poetry run pdoc simtfl -o apidoc --no-include-undocumented -d markdown

pyproject.toml

@@ -12,6 +12,7 @@ simpy = "^4"
 
 [tool.poetry.dev-dependencies]
 flake8 = "^6"
+pdoc = "^14"
 
 [tool.poetry.scripts]
 demo = "simtfl.demo:run"

simtfl/__init__.py

@@ -0,0 +1,7 @@
+"""
+This is an experimental simulator for research into a potential
+[Trailing Finality Layer](https://electric-coin-company.github.io/tfl-book/)
+for Zcash.
+
+See the [README](../README.md) for more information.
+"""

simtfl/demo.py

@@ -58,14 +58,9 @@ def run():
     """
     Runs the demo.
     """
-    env = Environment()
-    network = Network(env, delay=4)
+    network = Network(Environment(), delay=4)
     for i in range(10):
-        network.add_node(PongNode(i, env, network))
+        network.add_node(PongNode())
 
-    network.add_node(PingNode(10, env, network))
-
-    for i in range(network.num_nodes()):
-        env.process(network.start_node(i))
-
-    env.run()
+    network.add_node(PingNode())
+    network.run_all()

simtfl/message.py

@@ -1,12 +1,15 @@
+"""
+Base classes for messages.
+"""
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True)
 class PayloadMessage:
     """
     A message with an arbitrary payload.
     """
-    def __init__(self, payload):
-        """
-        Constructs a `PayloadMessage` with the given payload.
-        """
-        self.payload = payload
-
-    def __str__(self):
-        return f"{self.__class__.__name__}({self.payload})"
+    payload: Any
+    """The payload."""