slmp-connect-python 1.0.1__tar.gz → 1.1.1__tar.gz

{slmp_connect_python-1.0.1/slmp_connect_python.egg-info → slmp_connect_python-1.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: slmp-connect-python
-Version: 1.0.1
+Version: 1.1.1
 Summary: SLMP Connect Python: client library for MELSEC SLMP binary communication
 Author: fa-yoshinobu
 License-Expression: MIT
@@ -93,3 +93,9 @@ See that page for verified PLC models, transports, dates, limitations, and retai
 | License | [MIT](LICENSE) |
 | Registry | [PyPI](https://pypi.org/project/slmp-connect-python/) |
 | Package | `slmp-connect-python` |
+
+## Commercial support
+
+If you plan to embed this library in a paid or commercial product, please consider a separate support agreement or supporting the project as a sponsor.
+
+Contact: <https://fa-labo.com/contact.html>

{slmp_connect_python-1.0.1 → slmp_connect_python-1.1.1}/README.md

@@ -41,9 +41,9 @@ asyncio.run(main())
 | Page | Use it for |
 | --- | --- |
 | [Full documentation site](https://fa-yoshinobu.github.io/plc-comm-docs-site/) | Unified docs for all PLC communication libraries. |
-| [Getting started](docsrc/user/GETTING_STARTED.md) | Install the package, connect to your PLC, and run your first SLMP read/write. |
-| [Usage guide](docsrc/user/USAGE_GUIDE.md) | Use the high-level API and common SLMP workflows. |
-| [Supported registers](docsrc/user/SUPPORTED_REGISTERS.md) | Check supported device families, address syntax, and numbering rules. |
+| [Getting started](docsrc/user/GETTING_STARTED.md) | Install the package, connect to your PLC, and run your first SLMP read/write. |
+| [Usage guide](docsrc/user/USAGE_GUIDE.md) | Use the high-level API and common SLMP workflows. |
+| [Supported registers](docsrc/user/SUPPORTED_REGISTERS.md) | Check supported device families, address syntax, and numbering rules. |
 | [PLC profiles](docsrc/user/PROFILES.md) | Choose the canonical MELSEC profile and frame behavior. |
 | [Examples](samples/README.md) | Run maintained Python samples. |
 
@@ -59,3 +59,9 @@ See that page for verified PLC models, transports, dates, limitations, and retai
 | License | [MIT](LICENSE) |
 | Registry | [PyPI](https://pypi.org/project/slmp-connect-python/) |
 | Package | `slmp-connect-python` |
+
+## Commercial support
+
+If you plan to embed this library in a paid or commercial product, please consider a separate support agreement or supporting the project as a sponsor.
+
+Contact: <https://fa-labo.com/contact.html>

{slmp_connect_python-1.0.1 → slmp_connect_python-1.1.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "slmp-connect-python"
-version = "1.0.1"
+version = "1.1.1"
 description = "SLMP Connect Python: client library for MELSEC SLMP binary communication"
 readme = "README.md"
 requires-python = ">=3.10"

slmp_connect_python-1.1.1/slmp/error_codes.py

@@ -0,0 +1,45 @@
+"""SLMP end-code keys and categories."""
+
+from __future__ import annotations
+
+from typing import Literal
+
+SlmpEndCodeLanguage = Literal["en", "ja"]
+
+_REMOTE_PASSWORD_END_CODES = {
+    0xC200,
+    0xC201,
+    0xC202,
+    0xC203,
+    0xC204,
+    0xC205,
+    0xC810,
+    0xC811,
+    0xC812,
+    0xC813,
+    0xC814,
+    0xC815,
+    0xC816,
+}
+
+
+def get_end_code_name(end_code: int) -> str:
+    """Return the stable code-derived key for an SLMP end code."""
+    return f"slmp_end_code_{int(end_code) & 0xFFFF:04x}"
+
+
+def get_end_code_message(end_code: int, language: SlmpEndCodeLanguage = "en") -> str | None:
+    """Return a user-facing message for an SLMP end code.
+
+    Localized message text is not embedded in this package. Resolve
+    get_end_code_name(end_code) in an application-owned catalog when text is
+    required.
+    """
+    _ = end_code
+    _ = language
+    return None
+
+
+def is_remote_password_end_code(end_code: int) -> bool:
+    """Return True if the SLMP end code is related to remote password protection."""
+    return (int(end_code) & 0xFFFF) in _REMOTE_PASSWORD_END_CODES

{slmp_connect_python-1.0.1 → slmp_connect_python-1.1.1}/slmp/utils.py

@@ -29,7 +29,6 @@ if TYPE_CHECKING:
 _WORD_DTYPES = frozenset({"U", "S"})
 _DWORD_DTYPES = frozenset({"D", "L", "F"})
 _UNBATCHED_DEVICE_CODES = frozenset({"G", "HG"})
-_DEFAULT_DWORD_DEVICE_CODES = frozenset({"LTN", "LSTN", "LCN", "LZ"})
 _RANDOM_DWORD_SCALAR_DEVICE_CODES = frozenset({"LCN", "LZ"})
 _LONG_COUNTER_STATE_DEVICE_CODES = frozenset({"LCS", "LCC"})
 _LONG_TIMER_READ_FAMILIES: dict[str, tuple[str, str]] = {
@@ -196,7 +195,7 @@ async def read_typed(
         ``bool`` for ``BIT``, otherwise ``int`` or ``float``.
     """
     ref = _parse_device_for_client(client, device)
-    key = dtype.upper()
+    key = _require_dtype(dtype)
     long_read = _get_long_timer_read(ref)
     if long_read is not None:
         _validate_long_timer_entry(str(ref), ref, key)
@@ -235,7 +234,7 @@ async def write_typed(
         value: Application value to encode and write.
     """
     ref = _parse_device_for_client(client, device)
-    key = dtype.upper()
+    key = _require_dtype(dtype)
     long_read = _get_long_timer_read(ref)
     if long_read is not None:
         _validate_long_timer_entry(str(ref), ref, key)
@@ -268,7 +267,7 @@ def read_typed_sync(
 ) -> int | float | bool:
     """Synchronously read one logical value as a Python scalar."""
     ref = _parse_device_for_client(client, device)
-    key = dtype.upper()
+    key = _require_dtype(dtype)
     long_read = _get_long_timer_read(ref)
     if long_read is not None:
         _validate_long_timer_entry(str(ref), ref, key)
@@ -300,7 +299,7 @@ def write_typed_sync(
 ) -> None:
     """Synchronously write one logical value using the requested type."""
     ref = _parse_device_for_client(client, device)
-    key = dtype.upper()
+    key = _require_dtype(dtype)
     long_read = _get_long_timer_read(ref)
     if long_read is not None:
         _validate_long_timer_entry(str(ref), ref, key)
@@ -444,10 +443,11 @@ async def write_named(
         base, dtype, bit_idx = _parse_address(address)
         if dtype == "BIT_IN_WORD":
             _validate_bit_in_word_target(address, _parse_device_for_address_profile(base, address_profile))
-            await write_bit_in_word(client, base, bit_idx or 0, bool(value))
+            await write_bit_in_word(client, base, _require_bit_in_word_index(address, bit_idx), bool(value))
         else:
             device = _parse_device_for_address_profile(base, address_profile)
             resolved_dtype = _resolve_dtype_for_address(address, device, dtype, bit_idx)
+            _validate_device_dtype(address, device, resolved_dtype)
             _validate_long_timer_entry(address, device, resolved_dtype)
             await write_typed(client, base, resolved_dtype, value)
 
@@ -462,10 +462,11 @@ def write_named_sync(
         base, dtype, bit_idx = _parse_address(address)
         if dtype == "BIT_IN_WORD":
             _validate_bit_in_word_target(address, _parse_device_for_address_profile(base, address_profile))
-            write_bit_in_word_sync(client, base, bit_idx or 0, bool(value))
+            write_bit_in_word_sync(client, base, _require_bit_in_word_index(address, bit_idx), bool(value))
         else:
             device = _parse_device_for_address_profile(base, address_profile)
             resolved_dtype = _resolve_dtype_for_address(address, device, dtype, bit_idx)
+            _validate_device_dtype(address, device, resolved_dtype)
             _validate_long_timer_entry(address, device, resolved_dtype)
             write_typed_sync(client, base, resolved_dtype, value)
 
@@ -483,14 +484,33 @@ def _parse_address(address: str) -> tuple[str, str, int | None]:
     address = address.strip()
     if ":" in address:
         base, dtype = address.split(":", 1)
-        return base.strip(), dtype.strip().upper(), None
+        return base.strip(), _require_dtype(dtype), None
     if "." in address:
         base, bit_str = address.split(".", 1)
         bit_text = bit_str.strip()
         if len(bit_text) == 1 and bit_text.upper() in "0123456789ABCDEF":
             return base.strip(), "BIT_IN_WORD", int(bit_text, 16)
         raise ValueError(f"Invalid bit-in-word index {bit_str!r}; use one hex digit 0-F or ':' for dtype.")
-    return address.strip(), "U", None
+    raise ValueError(f"Address {address!r} requires an explicit dtype such as ':U', ':D', or ':BIT'.")
+
+
+def _require_dtype(dtype: str) -> str:
+    key = str(dtype).strip().upper()
+    if not key:
+        raise ValueError("dtype is required; specify BIT/U/S/D/L/F explicitly.")
+    if key == "BIT_IN_WORD":
+        raise ValueError("BIT_IN_WORD requires '.bit' notation such as 'D50.A'.")
+    if key not in {"BIT", "U", "S", "D", "L", "F"}:
+        raise ValueError(f"Unsupported dtype {key!r}; expected BIT/U/S/D/L/F")
+    return key
+
+
+def _require_bit_in_word_index(address: str, bit_index: int | None) -> int:
+    if bit_index is None:
+        raise ValueError(f"bit-in-word address requires explicit bit index 0-F: {address!r}")
+    if not 0 <= bit_index <= 15:
+        raise ValueError(f"bit-in-word index must be 0-F: {address!r}")
+    return bit_index
 
 
 def _effective_address_profile(
@@ -510,13 +530,13 @@ def parse_address(
 ) -> SlmpAddress:
     """Parse public SLMP helper-layer address notation.
 
-    Supported forms match :func:`read_named`: ``"D100"``, ``"D200:F"``,
-    ``"D50.A"``, and direct bit devices such as ``"M100"``.
+    Supported forms match :func:`read_named`: ``"D100:U"``, ``"D200:F"``,
+    ``"D50.A"``, and direct bit devices such as ``"M100:BIT"``.
     """
 
     if not isinstance(address, str):
         text = str(address)
-        return SlmpAddress(text=text, base_device=text, dtype="U")
+        raise ValueError(f"Address {text!r} requires an explicit dtype; pass a string such as '{text}:U'.")
 
     effective_address_profile = _effective_address_profile(plc_profile=plc_profile)
     raw_text = address.strip()
@@ -537,12 +557,10 @@ def parse_address(
         )
 
     resolved_dtype = _resolve_dtype_for_address(raw_text, device, dtype, bit_index)
-    if resolved_dtype not in {"BIT", "U", "S", "D", "L", "F"}:
-        raise ValueError(f"Unsupported dtype {resolved_dtype!r}; expected BIT/U/S/D/L/F")
-    explicit_dtype = ":" in raw_text
-    suffix = f":{resolved_dtype}" if explicit_dtype else ""
+    _validate_device_dtype(raw_text, device, resolved_dtype)
+    explicit_dtype = True
     return SlmpAddress(
-        text=f"{canonical_base}{suffix}",
+        text=f"{canonical_base}:{resolved_dtype}",
         base_device=canonical_base,
         dtype=resolved_dtype,
         bit_index=None,
@@ -573,16 +591,14 @@ def format_address(
     if not isinstance(address, SlmpAddress):
         return parse_address(address, plc_profile=plc_profile).text
 
-    canonical_base = normalize_address(address.base_device, plc_profile=plc_profile)
+    effective_address_profile = _effective_address_profile(plc_profile=plc_profile)
+    canonical_base = str(parse_device(address.base_device, plc_profile=effective_address_profile))
     if address.dtype == "BIT_IN_WORD":
         if address.bit_index is None or not 0 <= address.bit_index <= 15:
             raise ValueError("bit-in-word address requires bit_index 0-F")
         return f"{canonical_base}.{address.bit_index:X}"
-    if address.explicit_dtype:
-        if address.dtype not in {"BIT", "U", "S", "D", "L", "F"}:
-            raise ValueError(f"Unsupported dtype {address.dtype!r}; expected BIT/U/S/D/L/F")
-        return f"{canonical_base}:{address.dtype}"
-    return canonical_base
+    dtype = _require_dtype(address.dtype)
+    return f"{canonical_base}:{dtype}"
 
 
 def normalize_address(
@@ -604,15 +620,15 @@ def normalize_address(
 
     text = address.strip()
     if ":" not in text and "." not in text:
-        return str(parse_device(text, plc_profile=effective_address_profile))
+        raise ValueError(f"Address {text!r} requires an explicit dtype such as ':U', ':D', or ':BIT'.")
 
     base, dtype, bit_index = _parse_address(text)
     canonical_base = str(parse_device(base, plc_profile=effective_address_profile))
     if bit_index is not None:
         return f"{canonical_base}.{bit_index:X}"
-    if ":" in text:
-        return f"{canonical_base}:{dtype}"
-    return canonical_base
+    device = parse_device(base, plc_profile=effective_address_profile)
+    _validate_device_dtype(text, device, dtype)
+    return f"{canonical_base}:{dtype}"
 
 
 def _is_batchable_word_device(device: DeviceRef) -> bool:
@@ -620,22 +636,28 @@ def _is_batchable_word_device(device: DeviceRef) -> bool:
     return code is not None and code.unit == DeviceUnit.WORD and device.code not in _UNBATCHED_DEVICE_CODES
 
 
-def _address_has_explicit_dtype(address: str) -> bool:
-    return ":" in address
-
-
 def _normalize_dtype_for_device(device: DeviceRef, dtype: str) -> str:
-    code = DEVICE_CODES.get(device.code)
-    if code is not None and code.unit == DeviceUnit.BIT and dtype == "U":
-        return "BIT"
-    return dtype
+    return _require_dtype(dtype)
 
 
 def _resolve_dtype_for_address(address: str, device: DeviceRef, dtype: str, bit_index: int | None) -> str:
-    normalized = _normalize_dtype_for_device(device, dtype or "U")
-    if not _address_has_explicit_dtype(address) and bit_index is None and device.code in _DEFAULT_DWORD_DEVICE_CODES:
-        return "D"
-    return normalized
+    if bit_index is not None:
+        return "BIT_IN_WORD"
+    return _normalize_dtype_for_device(device, dtype)
+
+
+def _validate_device_dtype(address: str, device: DeviceRef, dtype: str) -> None:
+    if dtype == "BIT_IN_WORD":
+        return
+    code = DEVICE_CODES.get(device.code)
+    is_bit_device = code is not None and code.unit == DeviceUnit.BIT
+    if is_bit_device and dtype != "BIT":
+        raise ValueError(f"Address '{address}' is a bit device and requires ':BIT'.")
+    if not is_bit_device and dtype == "BIT":
+        raise ValueError(
+            f"Address '{address}' uses ':BIT', which is only valid for bit devices. "
+            "Use '.bit' notation for a bit inside a word device."
+        )
 
 
 def _get_long_timer_read(device: DeviceRef) -> tuple[str, str] | None:
@@ -649,14 +671,10 @@ def _validate_long_timer_entry(address: str, device: DeviceRef, dtype: str) -> N
     _, role = long_read
     if role == "current":
         if dtype not in {"D", "L"}:
-            raise ValueError(
-                f"Address '{address}' uses a 32-bit long current value. Use the plain form or ':D' / ':L'."
-            )
+            raise ValueError(f"Address '{address}' uses a 32-bit long current value. Specify ':D' or ':L'.")
         return
     if dtype != "BIT":
-        raise ValueError(
-            f"Address '{address}' is a long timer state device. Use the plain device form without a dtype override."
-        )
+        raise ValueError(f"Address '{address}' is a long timer state device. Specify ':BIT'.")
 
 
 async def _write_long_family_value(
@@ -792,11 +810,23 @@ def _compile_read_plan(
     for address in addresses:
         base, dtype, bit_index = _parse_address(address)
         device = _parse_device_for_address_profile(base, address_profile)
-        dtype = _resolve_dtype_for_address(address, device, dtype, bit_index)
-        _validate_long_timer_entry(address, device, dtype)
         batch_kind: str | None = None
         long_timer_read = _get_long_timer_read(device)
 
+        if dtype == "BIT_IN_WORD":
+            dtype = _resolve_dtype_for_address(address, device, dtype, bit_index)
+            bit_index = _require_bit_in_word_index(address, bit_index)
+            _validate_bit_in_word_target(address, device)
+            if _is_batchable_word_device(device):
+                batch_kind = "WORD"
+                if device not in seen_words:
+                    word_devices.append(device)
+                    seen_words.add(device)
+        else:
+            dtype = _resolve_dtype_for_address(address, device, dtype, bit_index)
+            _validate_device_dtype(address, device, dtype)
+            _validate_long_timer_entry(address, device, dtype)
+
         if long_timer_read is not None and not (device.code == "LCN" and long_timer_read[1] == "current"):
             batch_kind = "LONG_TIMER"
         elif long_timer_read is not None:
@@ -804,13 +834,6 @@ def _compile_read_plan(
             if device not in seen_dwords:
                 dword_devices.append(device)
                 seen_dwords.add(device)
-        elif dtype == "BIT_IN_WORD":
-            _validate_bit_in_word_target(address, device)
-            if _is_batchable_word_device(device):
-                batch_kind = "WORD"
-                if device not in seen_words:
-                    word_devices.append(device)
-                    seen_words.add(device)
         elif dtype in _WORD_DTYPES:
             if _is_batchable_word_device(device):
                 batch_kind = "WORD"
@@ -1019,7 +1042,8 @@ async def _read_named_with_plan(
         if entry.batch_kind == "WORD":
             word = word_values[str(entry.device)]
             if entry.dtype == "BIT_IN_WORD":
-                result[entry.address] = bool((word >> (entry.bit_index or 0)) & 1)
+                bit_index = _require_bit_in_word_index(entry.address, entry.bit_index)
+                result[entry.address] = bool((word >> bit_index) & 1)
             else:
                 result[entry.address] = _decode_word_value(word, entry.dtype)
             continue
@@ -1028,9 +1052,10 @@ async def _read_named_with_plan(
             continue
         if entry.dtype == "BIT_IN_WORD":
             words = await client.read_devices(entry.device, 1, bit_unit=False)
-            result[entry.address] = bool((words[0] >> (entry.bit_index or 0)) & 1)
+            bit_index = _require_bit_in_word_index(entry.address, entry.bit_index)
+            result[entry.address] = bool((words[0] >> bit_index) & 1)
         else:
-            result[entry.address] = await read_typed(client, entry.device, entry.dtype or "U")
+            result[entry.address] = await read_typed(client, entry.device, entry.dtype)
 
     return result
 
@@ -1065,7 +1090,8 @@ def _read_named_with_plan_sync(
         if entry.batch_kind == "WORD":
             word = word_values[str(entry.device)]
             if entry.dtype == "BIT_IN_WORD":
-                result[entry.address] = bool((word >> (entry.bit_index or 0)) & 1)
+                bit_index = _require_bit_in_word_index(entry.address, entry.bit_index)
+                result[entry.address] = bool((word >> bit_index) & 1)
             else:
                 result[entry.address] = _decode_word_value(word, entry.dtype)
             continue
@@ -1074,9 +1100,10 @@ def _read_named_with_plan_sync(
             continue
         if entry.dtype == "BIT_IN_WORD":
             words = client.read_devices(entry.device, 1, bit_unit=False)
-            result[entry.address] = bool((words[0] >> (entry.bit_index or 0)) & 1)
+            bit_index = _require_bit_in_word_index(entry.address, entry.bit_index)
+            result[entry.address] = bool((words[0] >> bit_index) & 1)
         else:
-            result[entry.address] = read_typed_sync(client, entry.device, entry.dtype or "U")
+            result[entry.address] = read_typed_sync(client, entry.device, entry.dtype)
 
     return result
 

{slmp_connect_python-1.0.1 → slmp_connect_python-1.1.1/slmp_connect_python.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: slmp-connect-python
-Version: 1.0.1
+Version: 1.1.1
 Summary: SLMP Connect Python: client library for MELSEC SLMP binary communication
 Author: fa-yoshinobu
 License-Expression: MIT
@@ -93,3 +93,9 @@ See that page for verified PLC models, transports, dates, limitations, and retai
 | License | [MIT](LICENSE) |
 | Registry | [PyPI](https://pypi.org/project/slmp-connect-python/) |
 | Package | `slmp-connect-python` |
+
+## Commercial support
+
+If you plan to embed this library in a paid or commercial product, please consider a separate support agreement or supporting the project as a sponsor.
+
+Contact: <https://fa-labo.com/contact.html>