utcp-socket 1.0.2__tar.gz

utcp_socket-1.0.2/PKG-INFO

@@ -0,0 +1,69 @@
+Metadata-Version: 2.4
+Name: utcp-socket
+Version: 1.0.2
+Summary: UTCP communication protocol plugin for TCP and UDP protocols. (Work in progress)
+Author: UTCP Contributors
+License-Expression: MPL-2.0
+Project-URL: Homepage, https://utcp.io
+Project-URL: Source, https://github.com/universal-tool-calling-protocol/python-utcp
+Project-URL: Issues, https://github.com/universal-tool-calling-protocol/python-utcp/issues
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: pydantic>=2.0
+Requires-Dist: utcp>=1.0
+Provides-Extra: dev
+Requires-Dist: build; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: coverage; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+
+# UTCP Socket Plugin (UDP/TCP)
+
+This plugin adds UDP and TCP communication protocols to UTCP 1.0.
+
+## Running Tests
+
+Prerequisites:
+- Python 3.10+
+- `pip`
+- (Optional) a virtual environment
+
+1) Install core and the socket plugin in editable mode with dev extras:
+
+```bash
+pip install -e "./core[dev]"
+pip install -e ./plugins/communication_protocols/socket[dev]
+```
+
+2) Run the socket plugin tests:
+
+```bash
+python -m pytest plugins/communication_protocols/socket/tests -v
+```
+
+3) Run a single test or filter by keyword:
+
+```bash
+# One file
+python -m pytest plugins/communication_protocols/socket/tests/test_tcp_communication_protocol.py -v
+
+# Filter by keyword (e.g., delimiter framing)
+python -m pytest plugins/communication_protocols/socket/tests -k delimiter -q
+```
+
+4) Optional end-to-end sanity check (mock UDP/TCP servers):
+
+```bash
+python scripts/socket_sanity.py
+```
+
+Notes:
+- On Windows, your firewall may prompt the first time tests open UDP/TCP sockets; allow access or run as admin if needed.
+- Tests use `pytest-asyncio`. The dev extras installed above provide required dependencies.
+- Streaming is single-chunk by design, consistent with HTTP/Text transports. Multi-chunk streaming can be added later behind provider configuration.

utcp_socket-1.0.2/README.md

@@ -0,0 +1,44 @@
+# UTCP Socket Plugin (UDP/TCP)
+
+This plugin adds UDP and TCP communication protocols to UTCP 1.0.
+
+## Running Tests
+
+Prerequisites:
+- Python 3.10+
+- `pip`
+- (Optional) a virtual environment
+
+1) Install core and the socket plugin in editable mode with dev extras:
+
+```bash
+pip install -e "./core[dev]"
+pip install -e ./plugins/communication_protocols/socket[dev]
+```
+
+2) Run the socket plugin tests:
+
+```bash
+python -m pytest plugins/communication_protocols/socket/tests -v
+```
+
+3) Run a single test or filter by keyword:
+
+```bash
+# One file
+python -m pytest plugins/communication_protocols/socket/tests/test_tcp_communication_protocol.py -v
+
+# Filter by keyword (e.g., delimiter framing)
+python -m pytest plugins/communication_protocols/socket/tests -k delimiter -q
+```
+
+4) Optional end-to-end sanity check (mock UDP/TCP servers):
+
+```bash
+python scripts/socket_sanity.py
+```
+
+Notes:
+- On Windows, your firewall may prompt the first time tests open UDP/TCP sockets; allow access or run as admin if needed.
+- Tests use `pytest-asyncio`. The dev extras installed above provide required dependencies.
+- Streaming is single-chunk by design, consistent with HTTP/Text transports. Multi-chunk streaming can be added later behind provider configuration.

utcp_socket-1.0.2/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "utcp-socket"
+version = "1.0.2"
+authors = [
+  { name = "UTCP Contributors" },
+]
+description = "UTCP communication protocol plugin for TCP and UDP protocols. (Work in progress)"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "pydantic>=2.0",
+    "utcp>=1.0"
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+license = "MPL-2.0"
+
+[project.optional-dependencies]
+dev = [
+    "build",
+    "pytest",
+    "pytest-asyncio",
+    "pytest-cov",
+    "coverage",
+    "twine",
+]
+
+[project.urls]
+Homepage = "https://utcp.io"
+Source = "https://github.com/universal-tool-calling-protocol/python-utcp"
+Issues = "https://github.com/universal-tool-calling-protocol/python-utcp/issues"
+
+[project.entry-points."utcp.plugins"]
+socket = "utcp_socket:register"

utcp_socket-1.0.2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

utcp_socket-1.0.2/src/utcp_socket/__init__.py

@@ -0,0 +1,18 @@
+from utcp.plugins.discovery import register_communication_protocol, register_call_template
+from utcp_socket.tcp_communication_protocol import TCPTransport
+from utcp_socket.udp_communication_protocol import UDPTransport
+from utcp_socket.tcp_call_template import TCPProviderSerializer
+from utcp_socket.udp_call_template import UDPProviderSerializer
+
+
+def register() -> None:
+    # Register communication protocols
+    register_communication_protocol("tcp", TCPTransport())
+    register_communication_protocol("udp", UDPTransport())
+
+    # Register call templates and their serializers
+    register_call_template("tcp", TCPProviderSerializer())
+    register_call_template("udp", UDPProviderSerializer())
+
+
+__all__ = ["register"]

utcp_socket-1.0.2/src/utcp_socket/tcp_call_template.py

@@ -0,0 +1,99 @@
+from utcp.data.call_template import CallTemplate
+from typing import Optional, Literal
+from pydantic import Field
+from utcp.interfaces.serializer import Serializer
+from utcp.exceptions import UtcpSerializerValidationError
+import traceback
+
+class TCPProvider(CallTemplate):
+    """Provider configuration for raw TCP socket tools.
+
+    Enables direct communication with TCP servers using custom protocols.
+    Supports flexible request formatting, response decoding, and multiple
+    framing strategies for message boundaries.
+
+    Request Data Handling:
+        - 'json' format: Arguments formatted as JSON object
+        - 'text' format: Template-based with UTCP_ARG_argname_UTCP_ARG placeholders
+
+    Response Data Handling:
+        - If response_byte_format is None: Returns raw bytes
+        - If response_byte_format is encoding string: Decodes bytes to text
+
+    TCP Stream Framing Options:
+        1. Length-prefix: Set framing_strategy='length_prefix' + length_prefix_bytes
+        2. Delimiter-based: Set framing_strategy='delimiter' + message_delimiter
+        3. Fixed-length: Set framing_strategy='fixed_length' + fixed_message_length
+        4. Stream-based: Set framing_strategy='stream' (reads until connection closes)
+
+    Attributes:
+        call_template_type: Always "tcp" for TCP providers.
+        host: The hostname or IP address of the TCP server.
+        port: The port number of the TCP server.
+        request_data_format: Format for request data ('json' or 'text').
+        request_data_template: Template string for 'text' format with placeholders.
+        response_byte_format: Encoding for response decoding (None for raw bytes).
+        framing_strategy: Method for detecting message boundaries.
+        length_prefix_bytes: Number of bytes for length prefix (1, 2, 4, or 8).
+        length_prefix_endian: Byte order for length prefix ('big' or 'little').
+        message_delimiter: Delimiter string for message boundaries.
+        fixed_message_length: Fixed length in bytes for each message.
+        max_response_size: Maximum bytes to read for stream-based framing.
+        timeout: Connection timeout in milliseconds.
+        auth: Always None - TCP providers don't support authentication.
+    """
+
+    call_template_type: Literal["tcp"] = "tcp"
+    host: str
+    port: int
+    request_data_format: Literal["json", "text"] = "json"
+    request_data_template: Optional[str] = None
+    response_byte_format: Optional[str] = Field(default="utf-8", description="Encoding to decode response bytes. If None, returns raw bytes.")
+    # TCP Framing Strategy
+    framing_strategy: Literal["length_prefix", "delimiter", "fixed_length", "stream"] = Field(
+        default="stream",
+        description="Strategy for framing TCP messages"
+    )
+    # Length-prefix framing options
+    length_prefix_bytes: Literal[1, 2, 4, 8] = Field(
+        default=4,
+        description="Number of bytes for length prefix (1, 2, 4, or 8). Used with 'length_prefix' framing."
+    )
+    length_prefix_endian: Literal["big", "little"] = Field(
+        default="big",
+        description="Byte order for length prefix. Used with 'length_prefix' framing."
+    )
+    # Delimiter-based framing options
+    message_delimiter: str = Field(
+        default='\x00',
+        description="Delimiter to detect end of TCP response (e.g., '\n', '\r\n', '\x00'). Used with 'delimiter' framing."
+    )
+    interpret_escape_sequences: bool = Field(
+        default=True,
+        description="If True, interpret Python-style escape sequences in message_delimiter (e.g., '\\n', '\\r\\n', '\\x00'). If False, use the delimiter literally as provided."
+    )
+    # Fixed-length framing options
+    fixed_message_length: Optional[int] = Field(
+        default=None,
+        description="Fixed length of each message in bytes. Used with 'fixed_length' framing."
+    )
+    # Stream-based options
+    max_response_size: int = Field(
+        default=65536,
+        description="Maximum bytes to read from TCP stream. Used with 'stream' framing."
+    )
+    timeout: int = 30000
+    auth: None = None
+
+
+class TCPProviderSerializer(Serializer[TCPProvider]):
+    def to_dict(self, obj: TCPProvider) -> dict:
+        return obj.model_dump()
+
+    def validate_dict(self, data: dict) -> TCPProvider:
+        try:
+            return TCPProvider.model_validate(data)
+        except Exception as e:
+            raise UtcpSerializerValidationError(
+                f"Invalid TCPProvider: {e}\n{traceback.format_exc()}"
+            )