Coding

Installing Source Code

• Install Python as explained in Installing.

• Download the source code from github, or make a fork and git clone that.

• Inside the directory, do the following:

  • Make "editable installation" of the package. An editable installation runs from the source code, so changes you make to the source are used when you run or test the code, without the need to reinstall the package:

    pip install -e .'[dev]'
    

  where the single quotes around [dev] are required in zsh, but not in bash. '[dev]' installs development-related packages such as pytest (see the file pyproject.toml for the full list).

  • Activate the pre-commit hooks:

    pre-commit install
    

  • Run unit tests to test your installation:

    pytest
    

• You may run an example loom server with:

  run_example_loom <num_shafts> mock
  

Please only specify the mock port; connecting the example loom server to a real loom will not work.

These run commands accept various command-line options, which you can see by running with -h or --help. Two of note for debugging are:

* `--reset-db` Reset the pattern database. Try this if you think the database is corrupted.

* `--verbose` Print more diagnostic information.

Note that the example loom server uses the same pattern database as seguin_loom_server and toika_loom_server.

Also note that real loom servers can also run in mock mode. For example:

    run_toika_loom 32 mock

    run_seguin_loom 16 mock

• In mock mode the web page shows a few extra controls for debugging.

• Warning: the web server's automatic reload feature, which reloads Python code whenever you save changes, does not work with this software. Instead you have to kill the web server by typing control-C several times, until you get a terminal prompt, then run the server again. This may be a bug in uvicorn; see this discussion for more information.

Writing a Loom Server

• Install the base_loom_server package either using pip, or from source (as described above). Source makes it easier to look through the code.

• Write a subclass of BaseMockLoom that emulates your loom. Two examples are ExampleMockLoom in this package and MockLoom in toika_loom_server.

For simplicity and future compatibility, try to avoid overriding the constructor. Instead, perform loom-specific initialization by overriding the __post_init__ method (which is normally a no-op in BaseMockLoom, so you need not call super().__post_init__).

• Write a subclass of BaseLoomServer that talks to the loom. Two examples are ExampleLoomServer in this package and LoomServer in toika_loom_server.

For simplicity and future compatibility, try to avoid overriding the constructor. Instead, perform loom-specific initialization by overriding the __post_init__ method (which is a no-op in BaseLoomServer, so you need not call super().__post_init__).

• Write a main.py like the one in base_loom_server, to run your loom server.

• Copy tests/test_mock_loom.py and modify it to suit your mock loom.

• The unit tests for your loom server should be able to use testutils.BaseTestLoomServer, as tests/test_loom_server.py does.

• Write a pyproject.toml like the one for toika_loom_server.