comettextel 1.3.0__py3-none-any.whl

comettextel/__init__.py

@@ -0,0 +1,39 @@
+"""CometTextel — thin Python FFI for the C ABI (PDU + modem).
+
+Requires the shared library from the C SDK (`comettextel.dll` / `libcomettextel.so`).
+Does not reimplement PDU codecs.
+
+Copyright (c) Ji-Feng Tsai. All rights reserved.
+Code released under the MIT license.
+"""
+
+from __future__ import annotations
+
+from .errors import CometTextelError, Status
+from .modem import GsmModem
+from .pdu import (
+    DCS_8BIT,
+    DCS_GSM7,
+    DCS_UCS2,
+    Message,
+    decode,
+    encode_submit,
+    encode_submit_segments,
+    status_string,
+)
+
+__all__ = [
+    "CometTextelError",
+    "Status",
+    "DCS_GSM7",
+    "DCS_8BIT",
+    "DCS_UCS2",
+    "Message",
+    "GsmModem",
+    "decode",
+    "encode_submit",
+    "encode_submit_segments",
+    "status_string",
+]
+
+__version__ = "1.3.0"

comettextel/_lib.py

@@ -0,0 +1,207 @@
+"""Locate and load ``comettextel`` shared library; bind C ABI exports.
+
+Copyright (c) Ji-Feng Tsai. All rights reserved.
+Code released under the MIT license.
+"""
+
+from __future__ import annotations
+
+import ctypes
+import os
+import sys
+from ctypes import (
+    POINTER,
+    c_char,
+    c_char_p,
+    c_int,
+    c_int32,
+    c_size_t,
+    c_uint32,
+    c_void_p,
+)
+from pathlib import Path
+from typing import Optional
+
+# Layout must match struct ct_message in include/comettextel/c_api.h.
+class CtMessage(ctypes.Structure):
+    """Structure representing a CT message."""
+
+    _fields_ = [
+        ("index", c_int32),
+        ("dcs", c_int32),
+        ("has_udh", c_int32),
+        ("service_center", c_char * 32),
+        ("peer_address", c_char * 32),
+        ("service_timestamp", c_char * 32),
+        ("user_data", c_char * 512),
+        ("is_concatenated", c_int32),
+        ("concat_ref", c_int32),
+        ("concat_total", c_int32),
+        ("concat_seq", c_int32),
+    ]
+
+
+_lib: Optional[ctypes.CDLL] = None
+
+
+def _candidate_names() -> list[str]:
+    """Return a list of candidate library names."""
+
+    if sys.platform == "win32":
+        return ["comettextel.dll"]
+    if sys.platform == "darwin":
+        return ["libcomettextel.dylib", "comettextel.dylib"]
+    return ["libcomettextel.so", "libcomettextel.so.1", "comettextel.so"]
+
+
+def _search_dirs(explicit: Optional[Path]) -> list[Path]:
+    """Search for the shared library in the given directories."""
+    
+    dirs: list[Path] = []
+    if explicit is not None:
+        dirs.append(explicit if explicit.is_dir() else explicit.parent)
+
+    env = os.environ.get("COMETTEXTEL_LIB")
+    if env:
+        p = Path(env)
+        dirs.append(p if p.is_dir() else p.parent)
+
+    # sdk/python/comettextel/_lib.py → parents[1]=sdk/python, [2]=sdk, [3]=repo root
+    here = Path(__file__).resolve()
+    sdk_python = here.parents[1]
+    repo = here.parents[3] if len(here.parents) > 3 else here.parents[-1]
+
+    dirs.extend(
+        [
+            Path.cwd(),
+            sdk_python,
+            sdk_python / "examples",
+            repo / "artifact" / "comettextel-c-sdk-windows-x64" / "bin",
+            repo / "artifact" / "comettextel-c-sdk-linux-x64" / "lib",
+            repo / "build-c-sdk" / "Release",
+            repo / "build-c-sdk" / "Debug",
+            repo / "build" / "Release",
+            repo / "build" / "Debug",
+        ]
+    )
+
+    # Deduplicate while preserving order.
+    seen: set[str] = set()
+    out: list[Path] = []
+    for d in dirs:
+        key = str(d.resolve()) if d.exists() else str(d)
+        if key not in seen:
+            seen.add(key)
+            out.append(d)
+    return out
+
+
+def find_library(path: Optional[str | Path] = None) -> Path:
+    """Resolve the shared library path.
+
+    Search order: explicit path / ``COMETTEXTEL_LIB`` / cwd / common build &
+    artifact folders next to this package.
+    """
+
+    explicit: Optional[Path] = Path(path) if path else None
+    if explicit is not None and explicit.is_file():
+        return explicit.resolve()
+
+    names = _candidate_names()
+    for directory in _search_dirs(explicit):
+        if not directory.is_dir():
+            continue
+        for name in names:
+            candidate = directory / name
+            if candidate.is_file():
+                return candidate.resolve()
+
+    raise FileNotFoundError(
+        "comettextel shared library not found. Set COMETTEXTEL_LIB to the DLL/SO "
+        "path (or its directory), or place it next to the example / on PATH. "
+        f"Looked for: {', '.join(names)}"
+    )
+
+
+def load(path: Optional[str | Path] = None) -> ctypes.CDLL:
+    """Load (or return cached) shared library and configure C ABI prototypes."""
+
+    global _lib
+    if _lib is not None and path is None:
+        return _lib
+
+    lib_path = find_library(path)
+    if sys.platform == "win32":
+        # Ensure dependent MSVC runtime resolution from the DLL folder.
+        os.add_dll_directory(str(lib_path.parent))
+        loaded = ctypes.WinDLL(str(lib_path))
+    else:
+        loaded = ctypes.CDLL(str(lib_path))
+
+    loaded.ct_status_string.argtypes = [c_int]
+    loaded.ct_status_string.restype = c_char_p
+
+    loaded.ct_modem_create.argtypes = []
+    loaded.ct_modem_create.restype = c_void_p
+
+    loaded.ct_modem_destroy.argtypes = [c_void_p]
+    loaded.ct_modem_destroy.restype = None
+
+    loaded.ct_modem_open.argtypes = [c_void_p, c_char_p, c_uint32]
+    loaded.ct_modem_open.restype = c_int
+
+    loaded.ct_modem_send.argtypes = [
+        c_void_p,
+        c_char_p,
+        c_char_p,
+        c_char_p,
+        c_int,
+        c_int,
+    ]
+    loaded.ct_modem_send.restype = c_int
+
+    loaded.ct_modem_list.argtypes = [
+        c_void_p,
+        POINTER(CtMessage),
+        c_int,
+        POINTER(c_int),
+        c_int,
+    ]
+    loaded.ct_modem_list.restype = c_int
+
+    loaded.ct_modem_delete.argtypes = [c_void_p, c_int, c_int]
+    loaded.ct_modem_delete.restype = c_int
+
+    loaded.ct_pdu_encode_submit.argtypes = [
+        c_char_p,
+        c_char_p,
+        c_char_p,
+        c_int,
+        c_void_p,
+        c_size_t,
+    ]
+    loaded.ct_pdu_encode_submit.restype = c_int
+
+    loaded.ct_pdu_encode_submit_segments.argtypes = [
+        c_char_p,
+        c_char_p,
+        c_char_p,
+        c_int,
+        c_void_p,
+        c_size_t,
+        POINTER(c_int),
+    ]
+    loaded.ct_pdu_encode_submit_segments.restype = c_int
+
+    loaded.ct_pdu_decode.argtypes = [c_char_p, POINTER(CtMessage)]
+    loaded.ct_pdu_decode.restype = c_int
+
+    _lib = loaded
+    return _lib
+
+
+def reset() -> None:
+    """Drop the cached CDLL (mainly for tests)."""
+
+    global _lib
+    _lib = None

comettextel/errors.py

@@ -0,0 +1,35 @@
+"""Status codes mirroring ``enum ct_status`` in ``c_api.h``.
+
+Copyright (c) Ji-Feng Tsai. All rights reserved.
+Code released under the MIT license.
+"""
+
+from __future__ import annotations
+
+from enum import IntEnum
+
+
+class Status(IntEnum):
+    OK = 0
+    INVALID_ARGUMENT = 1
+    NOT_OPEN = 2
+    ALREADY_OPEN = 3
+    IO = 4
+    TIMEOUT = 5
+    MODEM_REJECTED = 6
+    ENCODE = 7
+    DECODE = 8
+    UNSUPPORTED = 9
+    UNKNOWN = 100
+
+
+class CometTextelError(RuntimeError):
+    """Raised when a ``ct_*`` call returns a non-OK status."""
+
+    def __init__(self, status: int, what: str, detail: str = "") -> None:
+        self.status = int(status)
+        self.what = what
+        message = f"{what} failed ({self.status})"
+        if detail:
+            message = f"{message}: {detail}"
+        super().__init__(message)

comettextel/modem.py

@@ -0,0 +1,127 @@
+"""GSM modem helpers over ``ct_modem_*``.
+
+Copyright (c) Ji-Feng Tsai. All rights reserved.
+Code released under the MIT license.
+"""
+
+from __future__ import annotations
+
+import ctypes
+from types import TracebackType
+from typing import Optional, Type
+
+from . import _lib
+from .errors import CometTextelError
+from .pdu import DCS_UCS2, Message, _as_utf8, _check, message_from_ct
+
+
+class GsmModem:
+    """Context-managed wrapper around an opaque ``ct_modem`` handle."""
+
+    def __init__(self) -> None:
+        """Create a new modem object."""
+        
+        lib = _lib.load()
+        handle = lib.ct_modem_create()
+        if not handle:
+            raise CometTextelError(100, "ct_modem_create", "null handle")
+        self._handle = handle
+        self._closed = False
+
+    def close(self) -> None:
+        """Destroy the native modem (idempotent)."""
+
+        if self._closed:
+            return
+        lib = _lib.load()
+        lib.ct_modem_destroy(self._handle)
+        self._handle = None
+        self._closed = True
+
+    def __enter__(self) -> GsmModem:
+        """Return the modem when the context is entered."""
+
+        return self
+
+    def __exit__(
+        self,
+        exc_type: Optional[Type[BaseException]],
+        exc: Optional[BaseException],
+        tb: Optional[TracebackType],
+    ) -> None:
+        """Close the modem when the context is exited."""
+
+        self.close()
+
+    def __del__(self) -> None:
+        """Destroy the modem when the object is garbage collected."""
+
+        try:
+            self.close()
+        except Exception:
+            pass
+
+    def _ensure_open(self) -> ctypes.CDLL:
+        """Ensure the modem is open."""
+
+        if self._closed or not self._handle:
+            raise CometTextelError(2, "GsmModem", "modem is closed")
+        return _lib.load()
+
+    def open(self, port: str, baud_rate: int = 115200) -> None:
+        """Open the serial port and initialize PDU mode."""
+
+        if not port:
+            raise ValueError("port must be non-empty")
+        lib = self._ensure_open()
+        status = lib.ct_modem_open(self._handle, _as_utf8(port), int(baud_rate))
+        _check(status, "ct_modem_open")
+
+    def send(
+        self,
+        destination: str,
+        text: str,
+        smsc: str = "",
+        dcs: int = DCS_UCS2,
+        timeout_ms: int = 10000,
+    ) -> None:
+        """Send an SMS (long text auto-splits with concat UDH)."""
+
+        if not destination:
+            raise ValueError("destination must be non-empty")
+        lib = self._ensure_open()
+        status = lib.ct_modem_send(
+            self._handle,
+            _as_utf8(smsc),
+            _as_utf8(destination),
+            _as_utf8(text),
+            int(dcs),
+            int(timeout_ms),
+        )
+        _check(status, "ct_modem_send")
+
+    def list(self, max_count: int = 64, timeout_ms: int = 8000) -> list[Message]:
+        """List stored messages (complete concat sets are rejoined)."""
+
+        if max_count <= 0:
+            raise ValueError("max_count must be positive")
+        lib = self._ensure_open()
+        buffer = (_lib.CtMessage * max_count)()
+        count = ctypes.c_int(0)
+        status = lib.ct_modem_list(
+            self._handle,
+            buffer,
+            int(max_count),
+            ctypes.byref(count),
+            int(timeout_ms),
+        )
+        _check(status, "ct_modem_list")
+        n = int(count.value)
+        return [message_from_ct(buffer[i]) for i in range(n)]
+
+    def delete(self, index: int, timeout_ms: int = 5000) -> None:
+        """Delete one stored message by modem storage index."""
+
+        lib = self._ensure_open()
+        status = lib.ct_modem_delete(self._handle, int(index), int(timeout_ms))
+        _check(status, "ct_modem_delete")

comettextel/pdu.py

@@ -0,0 +1,167 @@
+"""PDU encode / decode helpers over ``ct_pdu_*``.
+
+Copyright (c) Ji-Feng Tsai. All rights reserved.
+Code released under the MIT license.
+"""
+
+from __future__ import annotations
+
+import ctypes
+from dataclasses import dataclass
+from typing import Optional
+
+from . import _lib
+from .errors import CometTextelError, Status
+
+DCS_GSM7 = 0
+DCS_8BIT = 4
+DCS_UCS2 = 8
+
+_DEFAULT_HEX_CAP = 65536
+
+
+@dataclass(frozen=True)
+class Message:
+    """Decoded message fields (UTF-8 text)."""
+
+    peer_address: str
+    user_data: str
+    dcs: int
+    has_udh: bool = False
+    is_concatenated: bool = False
+    concat_ref: int = 0
+    concat_total: int = 0
+    concat_seq: int = 0
+    service_center: str = ""
+    service_timestamp: str = ""
+    index: int = -1
+
+    @property
+    def is_reassembled_concat(self) -> bool:
+        """True when list/reassembly joined a complete multi-part set."""
+        return self.is_concatenated and self.concat_seq == 0 and self.concat_total > 0
+
+
+def _as_utf8(text: str) -> bytes:
+    """Convert a Python string to a UTF-8 encoded bytes object."""
+    
+    return text.encode("utf-8")
+
+
+def _c_z(buf: ctypes.Array) -> str:
+    """Convert a C string buffer to a Python string."""
+
+    raw = bytes(buf)
+    nul = raw.find(b"\x00")
+    if nul >= 0:
+        raw = raw[:nul]
+    return raw.decode("utf-8", errors="replace")
+
+
+def message_from_ct(out: _lib.CtMessage) -> Message:
+    """Build a :class:`Message` from a native ``ct_message``."""
+
+    return Message(
+        index=int(out.index),
+        dcs=int(out.dcs),
+        has_udh=bool(out.has_udh),
+        service_center=_c_z(out.service_center),
+        peer_address=_c_z(out.peer_address),
+        service_timestamp=_c_z(out.service_timestamp),
+        user_data=_c_z(out.user_data),
+        is_concatenated=bool(out.is_concatenated),
+        concat_ref=int(out.concat_ref),
+        concat_total=int(out.concat_total),
+        concat_seq=int(out.concat_seq),
+    )
+
+
+def status_string(status: int) -> str:
+    """Convert a status code to a string."""
+
+    lib = _lib.load()
+    ptr = lib.ct_status_string(int(status))
+    if not ptr:
+        return ""
+    return ptr.decode("utf-8", errors="replace")
+
+
+def _check(status: int, what: str) -> None:
+    """Check if a status code is OK."""
+
+    if status != Status.OK:
+        raise CometTextelError(status, what, status_string(status))
+
+
+def encode_submit(
+    destination: str,
+    text: str,
+    smsc: str = "",
+    dcs: int = DCS_UCS2,
+    *,
+    out_hex_cap: int = _DEFAULT_HEX_CAP,
+) -> str:
+    """Encode a single-segment submit PDU (hex). Raises if the text needs split."""
+
+    lib = _lib.load()
+    buf = ctypes.create_string_buffer(out_hex_cap)
+    status = lib.ct_pdu_encode_submit(
+        _as_utf8(smsc),
+        _as_utf8(destination),
+        _as_utf8(text),
+        int(dcs),
+        buf,
+        out_hex_cap,
+    )
+    _check(status, "ct_pdu_encode_submit")
+    return buf.value.decode("ascii")
+
+
+def encode_submit_segments(
+    destination: str,
+    text: str,
+    smsc: str = "",
+    dcs: int = DCS_UCS2,
+    *,
+    out_hex_cap: int = _DEFAULT_HEX_CAP,
+) -> list[str]:
+    """Encode one or more submit PDUs; auto-splits with concat UDH when needed."""
+
+    lib = _lib.load()
+    buf = ctypes.create_string_buffer(out_hex_cap)
+    count = ctypes.c_int(0)
+    status = lib.ct_pdu_encode_submit_segments(
+        _as_utf8(smsc),
+        _as_utf8(destination),
+        _as_utf8(text),
+        int(dcs),
+        buf,
+        out_hex_cap,
+        ctypes.byref(count),
+    )
+    _check(status, "ct_pdu_encode_submit_segments")
+    joined = buf.value.decode("ascii")
+    parts = [p for p in joined.split("\n") if p]
+    if count.value and len(parts) != int(count.value):
+        raise CometTextelError(
+            Status.ENCODE,
+            "ct_pdu_encode_submit_segments",
+            f"segment count mismatch (api={count.value}, parsed={len(parts)})",
+        )
+    return parts
+
+
+def decode(pdu_hex: str) -> Message:
+    """Decode a PDU hex string into a :class:`Message`."""
+
+    lib = _lib.load()
+    out = _lib.CtMessage()
+    status = lib.ct_pdu_decode(_as_utf8(pdu_hex.strip()), ctypes.byref(out))
+    _check(status, "ct_pdu_decode")
+    return message_from_ct(out)
+
+
+def load_library(path: Optional[str] = None) -> None:
+    """Eagerly load the native library (optional; otherwise lazy on first call)."""
+
+    _lib.load(path)

comettextel-1.3.0.dist-info/METADATA

@@ -0,0 +1,119 @@
+Metadata-Version: 2.4
+Name: comettextel
+Version: 1.3.0
+Summary: Thin ctypes FFI for the CometTextel C ABI (PDU + GSM modem).
+Author-email: Ji-Feng Tsai <jiowcl@gmail.com>
+License: MIT
+Project-URL: Homepage, https://inwazy.com
+Project-URL: Source, https://github.com/jiowcl/CometTextel
+Project-URL: Issues, https://github.com/jiowcl/CometTextel/issues
+Keywords: sms,pdu,gsm,comettextel
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+
+# CometTextel — Python (thin FFI)
+
+Thin **ctypes** binding to the same C ABI as the C SDK and CometTextel.NET (`c_api.h`).  
+This is **not** a second native library: it runtime-loads `comettextel.dll` / `libcomettextel.so`.
+
+Covers **PDU** helpers and **GsmModem** (`open` / `send` / `list` / `delete`).  
+Hardware modem tests are optional; smoke tests run without a device.
+
+![Python](https://img.shields.io/badge/language-python-blue.svg)
+
+## Layout
+
+```text
+sdk/python/
+├── comettextel/              # package (ctypes + PDU + modem)
+├── examples/
+│   ├── pdu_example.py        # encode / decode + self-check
+│   └── modem_example.py      # list / send / delete
+├── tests/
+│   ├── test_pdu.py
+│   └── test_modem.py
+└── README.md
+```
+
+## Prerequisites
+
+| Item | Detail |
+|------|--------|
+| Python | 3.10+ (3.13 verified) |
+| Native | C SDK shared library (`comettextel.dll` or `libcomettextel.so`) |
+| Modem (optional) | AT modem in **PDU mode** (e.g. `COM3`, `/dev/ttyUSB0`) |
+
+Download `comettextel-c-sdk-*` from CI Artifacts or a GitHub Release, or use a local CMake build.
+
+### Finding the library
+
+Search order:
+
+1. Explicit path passed to `comettextel.pdu.load_library(...)`
+2. Environment variable **`COMETTEXTEL_LIB`** (file or directory)
+3. Current working directory
+4. Nearby build / artifact folders (`build-c-sdk/Release`, `artifact/comettextel-c-sdk-*/…`)
+
+```powershell
+# Windows
+$env:COMETTEXTEL_LIB = "D:\path\to\comettextel.dll"
+```
+
+```bash
+# Linux
+export COMETTEXTEL_LIB=/path/to/libcomettextel.so
+```
+
+## PDU example
+
+```powershell
+cd sdk\python
+python examples\pdu_example.py
+python examples\pdu_example.py 886912345678 "Hello" 886932000000
+python examples\pdu_example.py 886912345678 "測試中文簡訊" 886932000000
+```
+
+## Modem example
+
+```powershell
+python examples\modem_example.py list COM3
+python examples\modem_example.py send COM3 886932000000 886912345678 "Hello"
+python examples\modem_example.py delete COM3 1
+```
+
+`list` rejoins **complete** concatenated SMS sets (`concat_seq == 0` / `Message.is_reassembled_concat`).
+
+## Tests
+
+```powershell
+cd sdk\python
+pip install pytest
+pytest -q
+```
+
+## API sketch
+
+```python
+from comettextel import DCS_UCS2, GsmModem, decode, encode_submit_segments
+
+parts = encode_submit_segments("886912345678", "Hello", "886932000000", DCS_UCS2)
+msg = decode(parts[0])
+
+with GsmModem() as modem:
+    modem.open("COM3", 115200)
+    modem.send("886912345678", "Hello from Python", smsc="886932000000")
+    for m in modem.list():
+        print(m.index, m.peer_address, m.user_data, m.is_reassembled_concat)
+```
+
+All text at the native boundary is **UTF-8**. Do not reimplement PDU codecs in Python; if the C ABI changes, update this package only.
+
+## See also
+
+- [`include/comettextel/c_api.h`](../../include/comettextel/c_api.h)
+- [`sdk/c/README.md`](../c/README.md)
+- [`sdk/freebasic/README.md`](../freebasic/README.md)
+- [`sdk/purebasic/README.md`](../purebasic/README.md)
+- [`examples/c_api_example.c`](../../examples/c_api_example.c)

comettextel-1.3.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+comettextel/__init__.py,sha256=unJUyDfVdsDSB-oRsei7zgqidbdwznsRz7laUzjMtUo,819
+comettextel/_lib.py,sha256=4MMqL7sGB8avNaMCdYNQC4Sz1yWUwXLj0pzzeiP2wS8,5854
+comettextel/errors.py,sha256=jejEfEaMPfkaEQhUnzeG0oowCYqWQ7tYTjliJmZzF6A,852
+comettextel/modem.py,sha256=bOVoJkYcYzMyMOomsc1VAmFVnlDLJ-ftuqfDTYlrU9c,3867
+comettextel/pdu.py,sha256=NICvns0dBgI1zsl4bt5Y7MynvRwPsIeFo7WY5sNtXGw,4535
+comettextel-1.3.0.dist-info/METADATA,sha256=_qmtch8u1nEnUYsv3kfJfIT69FXvPSDE44CW15DBoIQ,3692
+comettextel-1.3.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+comettextel-1.3.0.dist-info/top_level.txt,sha256=OKfoCtq8MdBy3M_koAWo-tnaqCZJQrsVUvsypYWYn0U,12
+comettextel-1.3.0.dist-info/RECORD,,

comettextel-1.3.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

comettextel-1.3.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+comettextel