base-loom-server 0.1__tar.gz

base_loom_server-0.1/.gitignore

@@ -0,0 +1,5 @@
+__pycache__
+.coverage
+*.egg-info
+dist
+version.py

base_loom_server-0.1/.pre-commit-config.yaml

@@ -0,0 +1,28 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: check-yaml
+        exclude: conda/meta.yaml
+      - id: check-xml
+
+  - repo: https://github.com/psf/black
+    rev: 24.8.0
+    hooks:
+      - id: black
+
+  - repo: https://github.com/pycqa/flake8
+    rev: 7.1.1
+    hooks:
+      - id: flake8
+
+  - repo: https://github.com/pycqa/isort
+    rev: 5.13.2
+    hooks:
+      - id: isort
+        name: isort (python)
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.11.2
+    hooks:
+      - id: mypy

base_loom_server-0.1/LICENSE.txt

@@ -0,0 +1,7 @@
+Copyright 2024 Russell Owen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

base_loom_server-0.1/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.2
+Name: base_loom_server
+Version: 0.1
+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: fastapi>=0.115
+Requires-Dist: dtx_to_wif>=3.0
+Requires-Dist: pyserial-asyncio>=0.6
+Provides-Extra: dev
+Requires-Dist: pre-commit>=3.8; extra == "dev"
+Requires-Dist: pytest>=8.3; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.24; 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
+
+* Install [Python](https://www.python.org/downloads/) 3.11 or later on the computer.
+
+* Install this [base_loom_server](https://pypi.org/project/base-loom-server/) package on the computer with command: **pip install base_loom_server**
+
+## Using this Package
+
+* Subclass `BaseMockLoom`; see `ExampleMockLoom` for an example.
+* Subclass `BaseLoomServer`; see `ExampleLoomServer` for an example.
+* Write a `main.py` like the one in this package (which runs `ExampleLoomServer`).
+* The unit tests for `BaseMockLoom` 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/), unless you would rather use a different distribution system.
+
+## 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 download that.
+
+* Inside the directory, issue the following commands:
+
+    * **pip install -e .** (note the final period) 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.
+
+    * **pre-commit install** to activate the pre-commit hooks.
+
+* You may run a mock loom by starting the server with: **run_example_loom mock**.
+  The mock loom does not use a serial port.
+  **run_example_loom** 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.
+
+* 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.1/README.md

@@ -0,0 +1,58 @@
+# 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
+
+* Install [Python](https://www.python.org/downloads/) 3.11 or later on the computer.
+
+* Install this [base_loom_server](https://pypi.org/project/base-loom-server/) package on the computer with command: **pip install base_loom_server**
+
+## Using this Package
+
+* Subclass `BaseMockLoom`; see `ExampleMockLoom` for an example.
+* Subclass `BaseLoomServer`; see `ExampleLoomServer` for an example.
+* Write a `main.py` like the one in this package (which runs `ExampleLoomServer`).
+* The unit tests for `BaseMockLoom` 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/), unless you would rather use a different distribution system.
+
+## 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 download that.
+
+* Inside the directory, issue the following commands:
+
+    * **pip install -e .** (note the final period) 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.
+
+    * **pre-commit install** to activate the pre-commit hooks.
+
+* You may run a mock loom by starting the server with: **run_example_loom mock**.
+  The mock loom does not use a serial port.
+  **run_example_loom** 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.
+
+* 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.1/pyproject.toml

@@ -0,0 +1,67 @@
+[build-system]
+requires = [
+    "setuptools>=61.0",
+    "setuptools_scm[toml]>=8.0",
+]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "base_loom_server"
+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",
+]
+authors = [
+  { name="Russell Owen", email="r3owen@gmail.com" },
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+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"
+]
+
+[project.scripts]
+run_example_loom = "base_loom_server.main:run_example_loom"
+
+[project.urls]
+Homepage = "https://github.com/r-owen/base_loom_server"
+Issues = "https://github.com/r-owen/base_loom_server/issues"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+
+[tool.isort]
+profile = "black"
+
+[tool.setuptools_scm]
+write_to = "src/base_loom_server/version.py"
+write_to_template = """
+# Generated by setuptools_scm
+__all__ = ["__version__"]
+__version__ = "{version}"
+"""

base_loom_server-0.1/setup.cfg

@@ -0,0 +1,10 @@
+[flake8]
+extend-ignore = E133, E203, E226, E228, N802, N803, N806, N812, N813, N815, N816, W503
+max-line-length = 110
+max-doc-length = 79
+exclude = __init__.py
+
+[egg_info]
+tag_build = 
+tag_date = 0
+

base_loom_server-0.1/src/base_loom_server/app_runner.py

@@ -0,0 +1,184 @@
+import argparse
+import importlib.resources
+import json
+import locale
+import logging
+import pathlib
+from contextlib import asynccontextmanager
+from typing import AsyncGenerator, Type
+
+import uvicorn
+from fastapi import APIRouter, FastAPI, WebSocket
+from fastapi.responses import HTMLResponse, Response
+
+from .base_loom_server import DEFAULT_DATABASE_PATH, BaseLoomServer
+from .constants import LOG_NAME
+
+PKG_FILES = importlib.resources.files("base_loom_server")
+LOCALE_FILES = PKG_FILES.joinpath("locales")
+
+
+class AppRunner:
+    def __init__(
+        self,
+        app: FastAPI,
+        server_class: Type[BaseLoomServer],
+        favicon: bytes,
+        app_package_name: str,
+    ) -> None:
+        """Construct endpoints for FastAPI"""
+        self.log = logging.getLogger(LOG_NAME)
+
+        self.server_class = server_class
+        self.favicon = favicon
+        self.app_package_name = app_package_name
+        self.loom_server: BaseLoomServer | None = None
+        self.translation_dict: dict[str, str] = {}
+
+        # There must be a better way to do this,
+        # but everything I have tried fails,
+        # including using an APIRouter with add_api_route
+
+        @asynccontextmanager
+        async def lifespan_wrapper(*args):
+            async with self.lifespan(app):
+                yield
+
+        # The only rason we need a router is to set the lifespan
+        # but once we have it we may as well use it to add endpoints as well
+        router = APIRouter(lifespan=lifespan_wrapper)
+
+        @router.get("/")
+        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()
+
+        @router.websocket("/ws")
+        async def websocket_endpoint_wrapper(websocket: WebSocket):
+            return await self.websocket_endpoint(websocket)
+
+        app.include_router(router)
+
+    def create_argument_parser(self) -> argparse.ArgumentParser:
+        parser = argparse.ArgumentParser()
+        parser.add_argument(
+            "serial_port",
+            help="Serial port connected to the loom, "
+            "typically of the form /dev/tty... "
+            "Specify 'mock' to run a mock (simulated) loom",
+        )
+        parser.add_argument(
+            "-n",
+            "--name",
+            help="loom name",
+        )
+        parser.add_argument(
+            "-r",
+            "--reset-db",
+            action="store_true",
+            help="reset pattern database?",
+        )
+        parser.add_argument(
+            "-v",
+            "--verbose",
+            action="store_true",
+            help="print diagnostic information to stdout",
+        )
+        parser.add_argument(
+            "--db-path",
+            default=DEFAULT_DATABASE_PATH,
+            type=pathlib.Path,
+            help="Path for pattern database. "
+            "Settable so unit tests can avoid changing the real database.",
+        )
+        return parser
+
+    @asynccontextmanager
+    async def lifespan(self, app: FastAPI) -> AsyncGenerator[None, FastAPI]:
+        self.translation_dict = self.get_translation_dict()
+
+        parser = self.create_argument_parser()
+        args = parser.parse_args()
+
+        async with self.server_class(
+            **vars(args), translation_dict=self.translation_dict
+        ) as self.loom_server:
+            yield
+
+    def get_translation_dict(self) -> dict[str, str]:
+        """Get the translation dict for the current locale"""
+        # Read a dict of key: None and turn into a dict of key: key
+        default_dict = json.loads(LOCALE_FILES.joinpath("default.json").read_text())
+        translation_dict = {key: key for key in default_dict}
+
+        language_code = locale.getlocale(locale.LC_CTYPE)[0]
+        self.log.info(f"Locale: {language_code!r}")
+        if language_code is not None:
+            short_language_code = language_code.split("_")[0]
+            for lc in (short_language_code, language_code):
+                translation_name = lc + ".json"
+                translation_file = LOCALE_FILES.joinpath(translation_name)
+                if translation_file.is_file():
+                    self.log.info(f"Loading translation file {translation_name!r}")
+                    locale_dict = json.loads(translation_file.read_text())
+                    purged_locale_dict = {
+                        key: value
+                        for key, value in locale_dict.items()
+                        if value is not None
+                    }
+                    if purged_locale_dict != locale_dict:
+                        self.log.warning(
+                            f"Some entries in translation file {translation_name!r} "
+                            "have null entries"
+                        )
+                    translation_dict.update(purged_locale_dict)
+        return translation_dict
+
+    async def get(self) -> HTMLResponse:
+        display_html_template = PKG_FILES.joinpath("display.html_template").read_text()
+
+        display_css = PKG_FILES.joinpath("display.css").read_text()
+
+        display_js = PKG_FILES.joinpath("display.js").read_text()
+        js_translation_str = "const TranslationDict = " + json.dumps(
+            self.translation_dict, indent=4
+        )
+        display_js = display_js.replace(
+            "const TranslationDict = {}", js_translation_str
+        )
+
+        assert self.loom_server is not None
+        is_mock = self.loom_server.mock_loom is not None
+        display_debug_controls = "block" if is_mock else "none"
+
+        display_html = display_html_template.format(
+            display_css=display_css,
+            display_js=display_js,
+            display_debug_controls=display_debug_controls,
+            **self.translation_dict,
+        )
+
+        return HTMLResponse(display_html)
+
+    async def get_favicon(self) -> Response:
+        return Response(content=self.favicon, media_type="image/x-icon")
+
+    async def websocket_endpoint(self, websocket: WebSocket) -> None:
+        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:
+        # Handle the help argument and also catch parsing errors right away
+        arg_parser = self.create_argument_parser()
+        arg_parser.parse_args()
+
+        uvicorn.run(
+            self.app_package_name,
+            host=host,
+            port=port,
+            log_level=log_level,
+            reload=reload,
+        )