Fix read the docs & improve use of enum types

.github/workflows/docker.yml

@@ -8,7 +8,7 @@ on:
 env:
   IMAGE_NAME: python-snap7
 jobs:
-  push:
+  build-and-push-container-image:
     runs-on: ubuntu-latest
     permissions:
       packages: write

.readthedocs.yaml

@@ -0,0 +1,15 @@
+# Read the Docs configuration file for Sphinx projects
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+
+sphinx:
+  configuration: docs/conf.py
+
+python:
+  install:
+    - requirements: docs/requirements-dev.txt

Makefile

@@ -12,30 +12,52 @@ venv/installed: venv/
 	venv/bin/pip install -e .
 	touch venv/installed
 
-setup: venv/installed
-
 venv/bin/pytest: venv/
 	venv/bin/pip install -e ".[test]"
 
 venv/bin/sphinx-build:  venv/
 	venv/bin/pip install -e ".[doc]"
 
+venv/bin/tox: venv/
+	venv/bin/pip install tox
+
+requirements-dev.txt: venv/bin/tox pyproject.toml
+	venv/bin/tox -e requirements-dev
+
+.PHONY: setup
+setup: venv/installed
+
+.PHONY: doc
 doc: venv/bin/sphinx-build
 	cd doc && make html
 
+.PHONY: check
 check: venv/bin/pytest
 	venv/bin/ruff check snap7 tests example
 	 venv/bin/ruff format --diff snap7 tests example
 
-format: venv/bin/pytest
-	venv/bin/ruff format snap7 tests example
+.PHONY: ruff
+ruff: venv/bin/tox
+	venv/bin/tox -e ruff
+
+.PHONY: format
+format: ruff
 
+.PHONY: mypy
 mypy: venv/bin/pytest
-	venv/bin/mypy snap7 tests
+	venv/bin/mypy snap7 tests example
 
+.PHONY: test
 test: venv/bin/pytest
-	venv/bin/pytest tests/test_server.py tests/test_client.py tests/test_util.py tests/test_mainloop.py
-	sudo venv/bin/pytest tests/test_partner.py  # run this as last to prevent pytest cache dir creates as root
+	venv/bin/pytest
 
+.PHONY: clean
 clean:
 	rm -rf venv python_snap7.egg-info .pytest_cache .tox dist .eggs
+
+.PHONY: tox
+tox: venv/
+	venv/bin/tox
+
+.PHONY: requirements
+requirements: requirements-dev.txt

example/boolean.py

@@ -26,21 +26,21 @@
 # In this example boolean in DB 31 at byte 120 and bit 5 is changed. = 120.5
 
 reading = plc.db_read(31, 120, 1)  # read 1 byte from db 31 staring from byte 120
-snap7.util.setters.set_bool(reading, 0, 5)  # set a value of fifth bit
+snap7.util.setters.set_bool(reading, 0, 5, True)  # set a value of fifth bit
 plc.db_write(reading, 31, 120, 1)  # write back the bytearray and now the boolean value is changed in the PLC.
 
 # NOTE you could also use the read_area and write_area functions.
 # then you can specify an area to read from:
 # https://github.com/gijzelaerr/python-snap7/blob/master/snap7/types.py
 
-from snap7.types import areas  # noqa: E402
+from snap7.types import Area  # noqa: E402
 
 
 # play with these functions.
-plc.read_area(area=areas["MK"], dbnumber=0, start=20, size=2)
+plc.read_area(area=Area.MK, dbnumber=0, start=20, size=2)
 
 data = bytearray()
 snap7.util.setters.set_int(data, 0, 127)
-plc.write_area(area=areas["MK"], dbnumber=0, start=20, data=data)
+plc.write_area(area=Area.MK, dbnumber=0, start=20, data=data)
 # read the client source code!
 # and official snap7 documentation

example/read_multi.py

@@ -8,29 +8,29 @@
 
 import snap7.util.getters
 from snap7.common import check_error
-from snap7.types import S7DataItem, S7AreaDB, S7WLByte
+from snap7.types import S7DataItem, Area, WordLen
 
 client = snap7.client.Client()
 client.connect("10.100.5.2", 0, 2)
 
 data_items = (S7DataItem * 3)()
 
-data_items[0].Area = ctypes.c_int32(S7AreaDB)
-data_items[0].WordLen = ctypes.c_int32(S7WLByte)
+data_items[0].Area = ctypes.c_int32(Area.DB.value)
+data_items[0].WordLen = ctypes.c_int32(WordLen.Byte.value)
 data_items[0].Result = ctypes.c_int32(0)
 data_items[0].DBNumber = ctypes.c_int32(200)
 data_items[0].Start = ctypes.c_int32(16)
 data_items[0].Amount = ctypes.c_int32(4)  # reading a REAL, 4 bytes
 
-data_items[1].Area = ctypes.c_int32(S7AreaDB)
-data_items[1].WordLen = ctypes.c_int32(S7WLByte)
+data_items[1].Area = ctypes.c_int32(Area.DB.value)
+data_items[1].WordLen = ctypes.c_int32(WordLen.Byte.value)
 data_items[1].Result = ctypes.c_int32(0)
 data_items[1].DBNumber = ctypes.c_int32(200)
 data_items[1].Start = ctypes.c_int32(12)
 data_items[1].Amount = ctypes.c_int32(4)  # reading a REAL, 4 bytes
 
-data_items[2].Area = ctypes.c_int32(S7AreaDB)
-data_items[2].WordLen = ctypes.c_int32(S7WLByte)
+data_items[2].Area = ctypes.c_int32(Area.DB.value)
+data_items[2].WordLen = ctypes.c_int32(WordLen.Byte.value)
 data_items[2].Result = ctypes.c_int32(0)
 data_items[2].DBNumber = ctypes.c_int32(200)
 data_items[2].Start = ctypes.c_int32(2)

example/write_multi.py

@@ -1,6 +1,6 @@
 import ctypes
 import snap7
-from snap7.types import Areas, S7DataItem, S7WLWord, S7WLReal, S7WLTimer
+from snap7.types import Area, S7DataItem, WordLen
 from snap7.util import set_int, set_real, get_int, get_real, get_s5time
 
 
@@ -31,11 +31,11 @@ def set_data_item(area, word_len, db_number: int, start: int, amount: int, data:
 real = bytearray(4)
 set_real(real, 0, 42.5)
 
-counters = 0x2999.to_bytes(2, "big") + 0x1111.to_bytes(2, "big")
+counters = bytearray(0x2999.to_bytes(2, "big") + 0x1111.to_bytes(2, "big"))
 
-item1 = set_data_item(area=Areas.DB, word_len=S7WLWord, db_number=1, start=0, amount=4, data=ints)
-item2 = set_data_item(area=Areas.DB, word_len=S7WLReal, db_number=1, start=8, amount=1, data=real)
-item3 = set_data_item(area=Areas.TM, word_len=S7WLTimer, db_number=0, start=2, amount=2, data=counters)
+item1 = set_data_item(area=Area.DB, word_len=WordLen.Word.value, db_number=1, start=0, amount=4, data=ints)
+item2 = set_data_item(area=Area.DB, word_len=WordLen.Real.value, db_number=1, start=8, amount=1, data=real)
+item3 = set_data_item(area=Area.TM, word_len=WordLen.Timer.value, db_number=0, start=2, amount=2, data=counters)
 
 items.append(item1)
 items.append(item2)

pyproject.toml

@@ -32,7 +32,7 @@ Homepage = "https://github.com/gijzelaerr/python-snap7"
 Documentation = "https://python-snap7.readthedocs.io/en/latest/"
 
 [project.optional-dependencies]
-test = ["pytest", "mypy", "types-setuptools", "ruff"]
+test = ["pytest", "mypy", "types-setuptools", "ruff", "tox"]
 cli = ["rich", "click" ]
 doc = ["sphinx", "sphinx_rtd_theme"]
 

requirements-dev.txt

@@ -0,0 +1,125 @@
+#
+# This file is autogenerated by pip-compile with Python 3.9
+# by the following command:
+#
+#    'tox -e requirements-dev'
+#
+
+alabaster==0.7.16
+    # via sphinx
+babel==2.15.0
+    # via sphinx
+cachetools==5.3.3
+    # via tox
+certifi==2024.2.2
+    # via requests
+chardet==5.2.0
+    # via tox
+charset-normalizer==3.3.2
+    # via requests
+click==8.1.7
+    # via python-snap7 (pyproject.toml)
+colorama==0.4.6
+    # via tox
+distlib==0.3.8
+    # via virtualenv
+docutils==0.20.1
+    # via
+    #   sphinx
+    #   sphinx-rtd-theme
+exceptiongroup==1.2.1
+    # via pytest
+filelock==3.14.0
+    # via
+    #   tox
+    #   virtualenv
+idna==3.7
+    # via requests
+imagesize==1.4.1
+    # via sphinx
+importlib-metadata==7.1.0
+    # via sphinx
+iniconfig==2.0.0
+    # via pytest
+jinja2==3.1.4
+    # via sphinx
+markdown-it-py==3.0.0
+    # via rich
+markupsafe==2.1.5
+    # via jinja2
+mdurl==0.1.2
+    # via markdown-it-py
+mypy==1.10.0
+    # via python-snap7 (pyproject.toml)
+mypy-extensions==1.0.0
+    # via mypy
+packaging==24.0
+    # via
+    #   pyproject-api
+    #   pytest
+    #   sphinx
+    #   tox
+platformdirs==4.2.1
+    # via
+    #   tox
+    #   virtualenv
+pluggy==1.5.0
+    # via
+    #   pytest
+    #   tox
+pygments==2.18.0
+    # via
+    #   rich
+    #   sphinx
+pyproject-api==1.6.1
+    # via tox
+pytest==8.2.0
+    # via python-snap7 (pyproject.toml)
+requests==2.31.0
+    # via sphinx
+rich==13.7.1
+    # via python-snap7 (pyproject.toml)
+ruff==0.4.4
+    # via python-snap7 (pyproject.toml)
+snowballstemmer==2.2.0
+    # via sphinx
+sphinx==7.3.7
+    # via
+    #   python-snap7 (pyproject.toml)
+    #   sphinx-rtd-theme
+    #   sphinxcontrib-jquery
+sphinx-rtd-theme==2.0.0
+    # via python-snap7 (pyproject.toml)
+sphinxcontrib-applehelp==1.0.8
+    # via sphinx
+sphinxcontrib-devhelp==1.0.6
+    # via sphinx
+sphinxcontrib-htmlhelp==2.0.5
+    # via sphinx
+sphinxcontrib-jquery==4.1
+    # via sphinx-rtd-theme
+sphinxcontrib-jsmath==1.0.1
+    # via sphinx
+sphinxcontrib-qthelp==1.0.7
+    # via sphinx
+sphinxcontrib-serializinghtml==1.1.10
+    # via sphinx
+tomli==2.0.1
+    # via
+    #   mypy
+    #   pyproject-api
+    #   pytest
+    #   sphinx
+    #   tox
+tox==4.15.0
+    # via python-snap7 (pyproject.toml)
+types-setuptools==69.5.0.20240423
+    # via python-snap7 (pyproject.toml)
+typing-extensions==4.11.0
+    # via mypy
+urllib3==2.2.1
+    # via requests
+virtualenv==20.26.1
+    # via tox
+zipp==3.18.1
+    # via importlib-metadata