base-loom-server 0.2__tar.gz → 0.3.0__tar.gz

{base_loom_server-0.2 → base_loom_server-0.3.0}/.gitignore

@@ -1,5 +1,6 @@
 __pycache__
 .coverage
 *.egg-info
-dist
+build/
+dist/
 version.py

{base_loom_server-0.2 → base_loom_server-0.3.0}/.pre-commit-config.yaml

@@ -1,13 +1,13 @@
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.6.0
+    rev: v5.0.0
     hooks:
       - id: check-yaml
         exclude: conda/meta.yaml
       - id: check-xml
 
   - repo: https://github.com/psf/black
-    rev: 24.8.0
+    rev: 25.1.0
     hooks:
       - id: black
 
@@ -17,12 +17,12 @@ repos:
       - id: flake8
 
   - repo: https://github.com/pycqa/isort
-    rev: 5.13.2
+    rev: 6.0.0
     hooks:
       - id: isort
         name: isort (python)
 
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.11.2
+    rev: v1.15.0
     hooks:
       - id: mypy

base_loom_server-0.3.0/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.2
+Name: base_loom_server
+Version: 0.3.0
+Summary: Base package for web servers that control dobby multi-shaft looms
+Author-email: Russell Owen <r3owen@gmail.com>
+Project-URL: Homepage, https://github.com/r-owen/base_loom_server
+Project-URL: Issues, https://github.com/r-owen/base_loom_server/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: aiosqlite>=0.20
+Requires-Dist: dtx_to_wif~=3.0
+Requires-Dist: fastapi[standard]~=0.115
+Requires-Dist: pyserial-asyncio~=0.6
+Provides-Extra: dev
+Requires-Dist: pre-commit~=4.0; extra == "dev"
+Requires-Dist: pytest~=8.3; extra == "dev"
+Requires-Dist: pytest-asyncio~=0.25; extra == "dev"
+
+# Base package for web servers that control dobby multi-shaft looms
+
+Such web servers are intended to allow you to control your loom from any phone, tablet or other device that has wifi and a web browser.
+
+Used by [seguin_loom_server](<https://pypi.org/project/seguin-loom-server/)>)
+and [toika_loom_server](https://pypi.org/project/toika-loom-server/).
+
+## Installing this Package
+
+You should only have to install this package if you want to examine or modify it.
+If you are installing a loom driver such as
+such as [seguin_loom_server](<https://pypi.org/project/seguin-loom-server/)>)
+or [toika_loom_server](https://pypi.org/project/toika-loom-server/),
+then you only need to install that package.
+Doing so will pull in all dependencies.
+
+Assuming you still want your own installation of base_loom_server:
+
+* Install [Python](https://www.python.org/downloads/) 3.11 or later on the computer.
+
+* If you are using python for other things, you may wish to make a virtual environment
+  dedicated to your loom server software. Look up "python virtual environment" on line.
+
+* Install this [base_loom_server](https://pypi.org/project/base-loom-server/) package on the computer with command:
+
+  * On Raspberry Pi: **sudo pip install base_loom_server**
+  * On most other computers: **pip install base_loom_server**
+
+  If you have a Raspberry Pi then you have three choices for installation:
+
+  * Use sudo for all pip install commands. This is simplest.
+  * Add "~/.local/bin" to your PATH. You can read about that on line.
+  * Prefix the run command with ".local/bin", e.g. **.local/bin/run_example_loom**.
+
+## Using this Package to Write a Loom Server
+
+* Write a subclass of `BaseMockLoom` that emulates your loom.
+  Two examples are `ExampleMockLoom` in this package and `MockLoom`
+  in [toika_loom_server](https://pypi.org/project/toika-loom-server/).
+
+* Write a subclass of `BaseLoomServer` that talks to the loom.
+  Two examples are `ExampleLoomServer` in this package and `LoomServer`
+  in [toika_loom_server](https://pypi.org/project/toika-loom-server/).
+
+* Write a `main.py` like the one in this package, 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](https://pypi.org/project/toika-loom-server/).
+
+## Remembering Patterns
+
+The web server keeps track of the most recent 25 patterns you have used in a database
+(including the most recent pick number and number of repeats, which are restored when you select a pattern).
+The patterns in the database are displayed in the pattern menu.
+If you shut down the server or there is a power failure, all this information should be retained.
+
+You can reset the database by starting the server with the **--reset-db** argument.
+You must reset the database if you upgrade this base_loom_server package and the new database format is incompatible
+(in which case the server will fail at startup).
+You may also want to reset the database if you are weaving a new project and don't want to see any of the saved patterns.
+
+## Developer Tips
+
+* Download the source code from [github](https://github.com/r-owen/base_loom_server.git),
+  or make a fork and git clone that.
+
+* Inside the directory, issue the following commands:
+
+    * **pip install -e .'[dev]'** (the single quotes are required in zsh, but not in bash)
+      to make an "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.
+      **'[dev]'** installs development-related packages such as pytest
+      (see the file `pyproject.toml` for the full list).
+
+    * **pre-commit install** to activate the pre-commit hooks.
+    
+    * **pytest** to test your installation.
+
+* You may run an example loom server with: **run_example_loom mock**.
+  Please only specify the **mock** serial port; connecting it to a real loom will not work
+  (`ExampleMockLoom` is loosely based on a Séguin loom, but is not compatible).
+
+  **run_example_loom mock** also accepts these command-line arguments:
+
+    * **--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](<https://pypi.org/project/seguin-loom-server/)>)
+  and [toika_loom_server](https://pypi.org/project/toika-loom-server/).
+
+* To run mypy run: ***MYPYPATH=src mypy .***. This avoids complaints about module name ambiguity.
+
+* 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](https://github.com/encode/uvicorn/discussions/2075) for more information.

base_loom_server-0.3.0/README.md

@@ -0,0 +1,104 @@
+# Base package for web servers that control dobby multi-shaft looms
+
+Such web servers are intended to allow you to control your loom from any phone, tablet or other device that has wifi and a web browser.
+
+Used by [seguin_loom_server](<https://pypi.org/project/seguin-loom-server/)>)
+and [toika_loom_server](https://pypi.org/project/toika-loom-server/).
+
+## Installing this Package
+
+You should only have to install this package if you want to examine or modify it.
+If you are installing a loom driver such as
+such as [seguin_loom_server](<https://pypi.org/project/seguin-loom-server/)>)
+or [toika_loom_server](https://pypi.org/project/toika-loom-server/),
+then you only need to install that package.
+Doing so will pull in all dependencies.
+
+Assuming you still want your own installation of base_loom_server:
+
+* Install [Python](https://www.python.org/downloads/) 3.11 or later on the computer.
+
+* If you are using python for other things, you may wish to make a virtual environment
+  dedicated to your loom server software. Look up "python virtual environment" on line.
+
+* Install this [base_loom_server](https://pypi.org/project/base-loom-server/) package on the computer with command:
+
+  * On Raspberry Pi: **sudo pip install base_loom_server**
+  * On most other computers: **pip install base_loom_server**
+
+  If you have a Raspberry Pi then you have three choices for installation:
+
+  * Use sudo for all pip install commands. This is simplest.
+  * Add "~/.local/bin" to your PATH. You can read about that on line.
+  * Prefix the run command with ".local/bin", e.g. **.local/bin/run_example_loom**.
+
+## Using this Package to Write a Loom Server
+
+* Write a subclass of `BaseMockLoom` that emulates your loom.
+  Two examples are `ExampleMockLoom` in this package and `MockLoom`
+  in [toika_loom_server](https://pypi.org/project/toika-loom-server/).
+
+* Write a subclass of `BaseLoomServer` that talks to the loom.
+  Two examples are `ExampleLoomServer` in this package and `LoomServer`
+  in [toika_loom_server](https://pypi.org/project/toika-loom-server/).
+
+* Write a `main.py` like the one in this package, 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](https://pypi.org/project/toika-loom-server/).
+
+## Remembering Patterns
+
+The web server keeps track of the most recent 25 patterns you have used in a database
+(including the most recent pick number and number of repeats, which are restored when you select a pattern).
+The patterns in the database are displayed in the pattern menu.
+If you shut down the server or there is a power failure, all this information should be retained.
+
+You can reset the database by starting the server with the **--reset-db** argument.
+You must reset the database if you upgrade this base_loom_server package and the new database format is incompatible
+(in which case the server will fail at startup).
+You may also want to reset the database if you are weaving a new project and don't want to see any of the saved patterns.
+
+## Developer Tips
+
+* Download the source code from [github](https://github.com/r-owen/base_loom_server.git),
+  or make a fork and git clone that.
+
+* Inside the directory, issue the following commands:
+
+    * **pip install -e .'[dev]'** (the single quotes are required in zsh, but not in bash)
+      to make an "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.
+      **'[dev]'** installs development-related packages such as pytest
+      (see the file `pyproject.toml` for the full list).
+
+    * **pre-commit install** to activate the pre-commit hooks.
+    
+    * **pytest** to test your installation.
+
+* You may run an example loom server with: **run_example_loom mock**.
+  Please only specify the **mock** serial port; connecting it to a real loom will not work
+  (`ExampleMockLoom` is loosely based on a Séguin loom, but is not compatible).
+
+  **run_example_loom mock** also accepts these command-line arguments:
+
+    * **--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](<https://pypi.org/project/seguin-loom-server/)>)
+  and [toika_loom_server](https://pypi.org/project/toika-loom-server/).
+
+* To run mypy run: ***MYPYPATH=src mypy .***. This avoids complaints about module name ambiguity.
+
+* 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](https://github.com/encode/uvicorn/discussions/2075) for more information.

{base_loom_server-0.2 → base_loom_server-0.3.0}/pyproject.toml

@@ -11,9 +11,10 @@ dynamic = ["version"]
 description = "Base package for web servers that control dobby multi-shaft looms"
 readme = "README.md"
 dependencies = [
-  "fastapi >= 0.115",
-  "dtx_to_wif >= 3.0",
-  "pyserial-asyncio >= 0.6",
+  "aiosqlite >= 0.20",
+  "dtx_to_wif ~= 3.0",
+  "fastapi[standard] ~= 0.115",
+  "pyserial-asyncio ~= 0.6",
 ]
 authors = [
   { name="Russell Owen", email="r3owen@gmail.com" },
@@ -27,22 +28,9 @@ requires-python = ">=3.11"
 
 [project.optional-dependencies]
 dev = [
-  "pre-commit >= 3.8",
-  "pytest >= 8.3",
-  "pytest-asyncio >= 0.24",
-]
-
-# Needed due to including package data below
-[tool.setuptools.packages.find]
-where = ["src"]
-
-[tool.setuptools.package-data]
-"base_loom_server" = [
-  "py.typed",
-  "display.css",
-  "display.html_template",
-  "display.js",
-  "favicon-32x32.png"
+  "pre-commit ~= 4.0",
+  "pytest ~= 8.3",
+  "pytest-asyncio ~= 0.25",
 ]
 
 [project.scripts]
@@ -65,3 +53,6 @@ write_to_template = """
 __all__ = ["__version__"]
 __version__ = "{version}"
 """
+
+[tool.mypy]
+explicit_package_bases = "True"

{base_loom_server-0.2 → base_loom_server-0.3.0}/src/base_loom_server/app_runner.py

@@ -19,6 +19,30 @@ LOCALE_FILES = PKG_FILES.joinpath("locales")
 
 
 class AppRunner:
+    """Run the loom server application.
+
+    This contains the web server's endpoints,
+    the lifespan context manager,
+    and a method to create the argument parser.
+
+    In order to use this you *must* create an instance on import
+    (i.e. at the module level), typically in `main.py'.
+    If you defer creation, the web server will not see the endpoints!
+    See ``main.py`` for an example.
+
+    Parameters
+    ----------
+    app : FastAPI
+        The application, generated with ``app = FastAPI()``
+    server_class : Type[BaseLoomServer]
+        Your loom server class (NOT an instance, but the class itself).
+    favicon : bytes
+        A 32x32 or so favicon. None if empty.
+    app_package_name : the name of the python package for your loom server,
+        e.g. "toika_loom_server". This is used by the `run` method,
+        as an argument to `uvicorn.run`.
+    """
+
     def __init__(
         self,
         app: FastAPI,
@@ -52,9 +76,11 @@ class AppRunner:
         async def get_wrapper():
             return await self.get()
 
-        @router.get("/favicon.ico", include_in_schema=False)
-        async def get_favicon():
-            return await self.get_favicon()
+        if self.favicon:
+
+            @router.get("/favicon.ico", include_in_schema=False)
+            async def get_favicon():
+                return await self.get_favicon()
 
         @router.websocket("/ws")
         async def websocket_endpoint_wrapper(websocket: WebSocket):
@@ -63,6 +89,10 @@ class AppRunner:
         app.include_router(router)
 
     def create_argument_parser(self) -> argparse.ArgumentParser:
+        """Create the argument parser.
+
+        Subclasses may override this to add more options.
+        """
         parser = argparse.ArgumentParser()
         parser.add_argument(
             "serial_port",
@@ -98,6 +128,13 @@ class AppRunner:
 
     @asynccontextmanager
     async def lifespan(self, app: FastAPI) -> AsyncGenerator[None, FastAPI]:
+        """Lifespan context manager for fastAPI.
+
+        Load the translation dict and create the sole instance of
+        the loom server class. That loom server instance persists
+        for the entire time the web server is running. This is because
+        the loom server speaks to one loom and serves at most one user.
+        """
         self.translation_dict = self.get_translation_dict()
 
         parser = self.create_argument_parser()
@@ -138,6 +175,7 @@ class AppRunner:
         return translation_dict
 
     async def get(self) -> HTMLResponse:
+        """Endpoint to get the main page."""
         display_html_template = PKG_FILES.joinpath("display.html_template").read_text()
 
         display_css = PKG_FILES.joinpath("display.css").read_text()
@@ -164,13 +202,16 @@ class AppRunner:
         return HTMLResponse(display_html)
 
     async def get_favicon(self) -> Response:
+        """Endpoint to get the favicon"""
         return Response(content=self.favicon, media_type="image/x-icon")
 
     async def websocket_endpoint(self, websocket: WebSocket) -> None:
+        """Websocket endpoint."""
         assert self.loom_server is not None
         await self.loom_server.run_client(websocket=websocket)
 
     def run(self, host="0.0.0.0", port=8000, log_level="info", reload=True) -> None:
+        """Parse command-line arguments and run the web server."""
         # Handle the help argument and also catch parsing errors right away
         arg_parser = self.create_argument_parser()
         arg_parser.parse_args()

{base_loom_server-0.2 → base_loom_server-0.3.0}/src/base_loom_server/base_loom_server.py

@@ -119,7 +119,7 @@ class BaseLoomServer:
         self.done_task: asyncio.Future = asyncio.Future()
         self.current_pattern: ReducedPattern | None = None
         self.jump_pick = client_replies.JumpPickNumber(
-            pick_number=None, repeat_number=None
+            pick_number=None, weaving_repeat_number=None
         )
         self.weave_forward = True
         self.loom_error_flag = False
@@ -309,7 +309,7 @@ class BaseLoomServer:
             If True then report JumpPickNumber, even if it has not changed.
         """
         null_jump_pick = client_replies.JumpPickNumber(
-            pick_number=None, repeat_number=None
+            pick_number=None, weaving_repeat_number=None
         )
         do_report = force_output or self.jump_pick != null_jump_pick
         self.jump_pick = null_jump_pick
@@ -338,10 +338,12 @@ class BaseLoomServer:
     def increment_pick_number(self) -> int:
         """Increment pick_number in the specified direction.
 
-        Increment repeat_number as well, if appropriate.
+        Increment weaving_repeat_number as well, if appropriate.
 
-        Return the new pick number. This will be 0 if repeat_number changed,
-        or if unweaving and repeat_number would be decremented to 0.
+        Return the new pick number. This will be 0 if
+        weaving_repeat_number changed,
+        or if unweaving and weaving_repeat_number
+        would be decremented to 0.
         """
         if self.current_pattern is None:
             return 0
@@ -405,7 +407,7 @@ class BaseLoomServer:
 
         self.jump_pick = client_replies.JumpPickNumber(
             pick_number=command.pick_number,
-            repeat_number=command.repeat_number,
+            weaving_repeat_number=command.weaving_repeat_number,
         )
         await self.report_jump_pick_number()
 
@@ -530,8 +532,10 @@ class BaseLoomServer:
             self.current_pattern.set_current_pick_number(new_pick_number)
         else:
             new_pick_number = self.increment_pick_number()
-        if self.jump_pick.repeat_number is not None:
-            self.current_pattern.repeat_number = self.jump_pick.repeat_number
+        if self.jump_pick.weaving_repeat_number is not None:
+            self.current_pattern.weaving_repeat_number = (
+                self.jump_pick.weaving_repeat_number
+            )
         pick = self.current_pattern.get_current_pick()
         await self.write_shafts_to_loom(pick)
         await self.clear_jump_pick()
@@ -624,11 +628,11 @@ class BaseLoomServer:
         await self.pattern_db.update_pick_number(
             pattern_name=self.current_pattern.name,
             pick_number=self.current_pattern.pick_number,
-            repeat_number=self.current_pattern.repeat_number,
+            weaving_repeat_number=self.current_pattern.weaving_repeat_number,
         )
         reply = client_replies.CurrentPickNumber(
             pick_number=self.current_pattern.pick_number,
-            repeat_number=self.current_pattern.repeat_number,
+            weaving_repeat_number=self.current_pattern.weaving_repeat_number,
         )
         await self.write_to_client(reply)
 

{base_loom_server-0.2 → base_loom_server-0.3.0}/src/base_loom_server/client_replies.py

@@ -1,5 +1,3 @@
-from __future__ import annotations
-
 import dataclasses
 import enum
 
@@ -45,7 +43,7 @@ class CurrentPickNumber:
 
     type: str = dataclasses.field(init=False, default="CurrentPickNumber")
     pick_number: int
-    repeat_number: int
+    weaving_repeat_number: int
 
 
 @dataclasses.dataclass
@@ -54,7 +52,7 @@ class JumpPickNumber:
 
     type: str = dataclasses.field(init=False, default="JumpPickNumber")
     pick_number: int | None
-    repeat_number: int | None
+    weaving_repeat_number: int | None
 
 
 @dataclasses.dataclass

{base_loom_server-0.2 → base_loom_server-0.3.0}/src/base_loom_server/display.html_template

@@ -50,7 +50,7 @@
         <label>{of}</label>
         <label id="total_picks">?</label>
         <label>{repeat}</label>
-        <label id="repeat_number"></label>
+        <label id="weaving_repeat_number"></label>
     </div>
 
     <form action="" id="jump_to_pick_form">

{base_loom_server-0.2 → base_loom_server-0.3.0}/src/base_loom_server/display.js

@@ -66,7 +66,7 @@ class ReducedPattern {
         this.threading = datadict.threading
         this.picks = []
         this.pick_number = datadict.pick_number
-        this.repeat_number = datadict.repeat_number
+        this.weaving_repeat_number = datadict.weaving_repeat_number
         datadict.picks.forEach((pickdata) => {
             this.picks.push(new Pick(pickdata))
         })
@@ -209,12 +209,12 @@ class LoomClient {
                 console.log("Ignoring CurrentPickNumber: no pattern loaded")
             }
             this.currentPattern.pick_number = datadict.pick_number
-            this.currentPattern.repeat_number = datadict.repeat_number
+            this.currentPattern.weaving_repeat_number = datadict.weaving_repeat_number
             this.displayCurrentPattern()
             this.displayPick()
         } else if (datadict.type == "JumpPickNumber") {
             this.jumpPickNumber = datadict.pick_number
-            this.jumpRepeatNumber = datadict.repeat_number
+            this.jumpRepeatNumber = datadict.weaving_repeat_number
             this.displayJumpPick()
         } else if (datadict.type == "LoomConnectionState") {
             this.loomConnectionState = datadict
@@ -505,7 +505,7 @@ class LoomClient {
     Display the current pick and repeat.
     */
     displayPick() {
-        var repeatNumberElt = document.getElementById("repeat_number")
+        var repeatNumberElt = document.getElementById("weaving_repeat_number")
         var pickNumberElt = document.getElementById("pick_number")
         var totalPicksElt = document.getElementById("total_picks")
         var pickNumber = ""
@@ -513,7 +513,7 @@ class LoomClient {
         var repeatNumber = ""
         if (this.currentPattern) {
             pickNumber = this.currentPattern.pick_number
-            repeatNumber = this.currentPattern.repeat_number
+            repeatNumber = this.currentPattern.weaving_repeat_number
             totalPicks = this.currentPattern.picks.length
         }
         pickNumberElt.textContent = pickNumber
@@ -644,7 +644,7 @@ class LoomClient {
         // Handle blanks by using the current default, if any
         var pickNumber = asNumberOrNull(jumpPickNumberElt.value)
         var repeatNumber = asNumberOrNull(jumpRepeatNumberElt.value)
-        var command = { "type": "jump_to_pick", "pick_number": pickNumber, "repeat_number": repeatNumber }
+        var command = { "type": "jump_to_pick", "pick_number": pickNumber, "weaving_repeat_number": repeatNumber }
         await this.sendCommand(command)
         event.preventDefault()
     }
@@ -659,7 +659,7 @@ class LoomClient {
         var jumpRepeatNumberElt = document.getElementById("jump_repeat_number")
         jumpPickNumberElt.value = ""
         jumpRepeatNumberElt.value = ""
-        var command = { "type": "jump_to_pick", "pick_number": null, "repeat_number": null }
+        var command = { "type": "jump_to_pick", "pick_number": null, "weaving_repeat_number": null }
         await this.sendCommand(command)
         event.preventDefault()
     }

{base_loom_server-0.2 → base_loom_server-0.3.0}/src/base_loom_server/example_loom_server.py

@@ -1,6 +1,4 @@
-from __future__ import annotations
-
-__all__ = ["BaseLoomServer"]
+__all__ = ["ExampleLoomServer"]
 
 import pathlib
 
@@ -10,10 +8,6 @@ from .example_mock_loom import ExampleMockLoom
 from .reduced_pattern import Pick
 
 
-class CommandError(Exception):
-    pass
-
-
 class ExampleLoomServer(BaseLoomServer):
     """Example loom server.
 

{base_loom_server-0.2 → base_loom_server-0.3.0}/src/base_loom_server/example_mock_loom.py

@@ -1,5 +1,3 @@
-from __future__ import annotations
-
 __all__ = ["BaseMockLoom"]
 
 from .base_mock_loom import BaseMockLoom