pybricks-core 1.0.0b1__tar.gz

pybricks_core-1.0.0b1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The Pybricks Authors
+
+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.

pybricks_core-1.0.0b1/PKG-INFO

@@ -0,0 +1,42 @@
+Metadata-Version: 2.4
+Name: pybricks-core
+Version: 1.0.0b1
+Summary: Shared protocol, IPC transport and logging for the Pybricks tools
+Keywords: pybricks,lego,micropython,bluetooth,robotics
+Author: The Pybricks Authors
+Author-email: The Pybricks Authors <dev@pybricks.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Embedded Systems
+Classifier: Typing :: Typed
+Requires-Dist: anyio>=4.14
+Requires-Dist: platformdirs>=4
+Requires-Dist: typing-extensions>=4.15
+Maintainer: David Lechner
+Maintainer-email: David Lechner <david@pybricks.com>
+Requires-Python: >=3.11
+Project-URL: homepage, https://pybricks.com
+Project-URL: repository, https://github.com/pybricks/pybricks-tools
+Project-URL: documentation, https://pybricks.com/pybricks-tools/design/
+Project-URL: Changelog, https://github.com/pybricks/pybricks-tools/blob/main/packages/pb-core/CHANGELOG.md
+Project-URL: Support, https://github.com/pybricks/support/discussions
+Project-URL: Issues, https://github.com/pybricks/support/issues
+Description-Content-Type: text/markdown
+
+# pybricks-core
+
+The pieces shared by the [Pybricks](https://pybricks.com) tools: the JSON-RPC
+protocol the client and the service speak, the transports underneath it, the
+compiler that turns a script into something a hub can run, and the logging and
+file locations all of them use.
+
+**You do not install this yourself.** It comes with `pybricks-cli` and with
+`pybricks-client`, which is the one to reach for if you want to drive a hub from
+your own Python.
+
+> **Status:** beta. Commands and APIs may still change before 1.0.0.

pybricks_core-1.0.0b1/README.md

@@ -0,0 +1,12 @@
+# pybricks-core
+
+The pieces shared by the [Pybricks](https://pybricks.com) tools: the JSON-RPC
+protocol the client and the service speak, the transports underneath it, the
+compiler that turns a script into something a hub can run, and the logging and
+file locations all of them use.
+
+**You do not install this yourself.** It comes with `pybricks-cli` and with
+`pybricks-client`, which is the one to reach for if you want to drive a hub from
+your own Python.
+
+> **Status:** beta. Commands and APIs may still change before 1.0.0.

pybricks_core-1.0.0b1/pyproject.toml

@@ -0,0 +1,52 @@
+[project]
+name = "pybricks-core"
+version = "1.0.0b1"
+description = "Shared protocol, IPC transport and logging for the Pybricks tools"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+keywords = [
+    "pybricks",
+    "lego",
+    "micropython",
+    "bluetooth",
+    "robotics",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Education",
+    "Natural Language :: English",
+    "Operating System :: OS Independent",
+    "Topic :: Software Development :: Embedded Systems",
+    "Typing :: Typed",
+]
+dependencies = [
+    "anyio>=4.14",
+    "platformdirs>=4",
+    "typing-extensions>=4.15",
+]
+
+[[project.authors]]
+name = "The Pybricks Authors"
+email = "dev@pybricks.com"
+
+[[project.maintainers]]
+name = "David Lechner"
+email = "david@pybricks.com"
+
+[project.urls]
+homepage = "https://pybricks.com"
+repository = "https://github.com/pybricks/pybricks-tools"
+documentation = "https://pybricks.com/pybricks-tools/design/"
+Changelog = "https://github.com/pybricks/pybricks-tools/blob/main/packages/pb-core/CHANGELOG.md"
+Support = "https://github.com/pybricks/support/discussions"
+Issues = "https://github.com/pybricks/support/issues"
+
+[build-system]
+requires = ["uv_build>=0.12.7,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "pb_core"

pybricks_core-1.0.0b1/pyproject.toml.orig

@@ -0,0 +1,40 @@
+[project]
+name = "pybricks-core"
+version = "1.0.0b1"
+description = "Shared protocol, IPC transport and logging for the Pybricks tools"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "The Pybricks Authors", email = "dev@pybricks.com" }]
+maintainers = [{ name = "David Lechner", email = "david@pybricks.com" }]
+requires-python = ">=3.11"
+keywords = ["pybricks", "lego", "micropython", "bluetooth", "robotics"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Education",
+    "Natural Language :: English",
+    "Operating System :: OS Independent",
+    "Topic :: Software Development :: Embedded Systems",
+    "Typing :: Typed",
+]
+dependencies = [
+    "anyio>=4.14",
+    "platformdirs>=4",
+    "typing-extensions>=4.15",
+]
+
+[project.urls]
+homepage = "https://pybricks.com"
+repository = "https://github.com/pybricks/pybricks-tools"
+documentation = "https://pybricks.com/pybricks-tools/design/"
+"Changelog" = "https://github.com/pybricks/pybricks-tools/blob/main/packages/pb-core/CHANGELOG.md"
+"Support" = "https://github.com/pybricks/support/discussions"
+"Issues" = "https://github.com/pybricks/support/issues"
+
+[build-system]
+requires = ["uv_build>=0.12.7,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "pb_core"

pybricks_core-1.0.0b1/src/pb_core/__init__.py

@@ -0,0 +1,13 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 The Pybricks Authors
+
+"""Shared building blocks for the Pybricks tool suite.
+
+This package holds everything both the service and the client need to agree on:
+the JSON-RPC wire protocol, the per-platform IPC transport, logging setup and
+platform paths. It deliberately depends on neither ``pb_service`` nor ``pb_client``.
+"""
+
+__version__ = "1.0.0b1"
+
+__all__ = ["__version__"]

pybricks_core-1.0.0b1/src/pb_core/auth.py

@@ -0,0 +1,90 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 The Pybricks Authors
+
+"""Shared-secret authentication between the client and the service.
+
+The service writes a random token to a file only the current user can read, and
+every client presents it in the mandatory first call. This is the X11
+magic-cookie scheme.
+
+It is required on every transport rather than only on TCP. The default
+discretionary access control list on a Windows named pipe grants Everyone read
+access, so without a secret another local user could not issue commands but
+could still watch a hub's output. It is not sufficient on its own for a service
+reachable beyond loopback, where the token crosses the network in clear and
+needs TLS or an SSH tunnel around it.
+"""
+
+from __future__ import annotations
+
+import logging
+import secrets
+import sys
+from pathlib import Path
+
+from pb_core import paths
+
+logger = logging.getLogger(__name__)
+
+__all__ = ["TOKEN_BYTES", "load_token", "read_or_create_token"]
+
+TOKEN_BYTES = 32
+
+
+def read_or_create_token(path: Path | None = None) -> str:
+    """Return the service's token, creating one if there is none.
+
+    Called by the service at startup.
+
+    Args:
+        path: Override the cookie file location.
+
+    Returns:
+        The token as hexadecimal text.
+    """
+    cookie = path or paths.cookie_file()
+    paths.ensure_private_dir(cookie.parent)
+
+    if cookie.exists():
+        existing = cookie.read_text(encoding="ascii").strip()
+        if existing:
+            return existing
+
+    token = secrets.token_hex(TOKEN_BYTES)
+    # Create with restrictive permissions from the outset rather than widening
+    # then narrowing, which would leave a window where the token is readable.
+    descriptor = cookie.open("w", encoding="ascii")
+
+    try:
+        if sys.platform != "win32":
+            import os
+
+            os.fchmod(descriptor.fileno(), 0o600)
+
+        descriptor.write(token)
+    finally:
+        descriptor.close()
+
+    logger.debug("wrote a new authentication token to %s", cookie)
+    return token
+
+
+def load_token(path: Path | None = None) -> str | None:
+    """Return the service's token if it can be read.
+
+    Called by clients before connecting.
+
+    Args:
+        path: Override the cookie file location.
+
+    Returns:
+        The token, or ``None`` if no service has ever run for this user.
+    """
+    cookie = path or paths.cookie_file()
+
+    try:
+        token = cookie.read_text(encoding="ascii").strip()
+    except OSError:
+        return None
+
+    return token or None

pybricks_core-1.0.0b1/src/pb_core/ipc/__init__.py

@@ -0,0 +1,66 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 The Pybricks Authors
+
+"""Transport between the client and the service.
+
+The user never types an address: :func:`pb_core.ipc.address.resolve` picks the
+right one for the platform. Everything above this package deals only in
+:class:`anyio.abc.ByteStream`, so neither the service nor the client contains any
+platform-specific code.
+"""
+
+from __future__ import annotations
+
+from contextlib import AbstractAsyncContextManager
+
+from anyio.abc import ByteStream
+
+from pb_core.ipc.address import ENDPOINT_ENV_VAR, Endpoint, default, resolve
+from pb_core.ipc.backend import IpcBackend, IpcListener, StreamHandler, get_backend
+from pb_core.ipc.errors import AddressInUseError, EndpointError
+
+__all__ = [
+    "ENDPOINT_ENV_VAR",
+    "AddressInUseError",
+    "Endpoint",
+    "EndpointError",
+    "IpcBackend",
+    "IpcListener",
+    "StreamHandler",
+    "connect",
+    "create_listener",
+    "default",
+    "get_backend",
+    "resolve",
+]
+
+
+def connect(endpoint: Endpoint) -> AbstractAsyncContextManager[ByteStream]:
+    """Connect to the service listening at ``endpoint``.
+
+    Args:
+        endpoint: Where the service is listening.
+
+    Returns:
+        An async context manager yielding the connected stream.
+
+    Raises:
+        ConnectionRefusedError: If nothing is listening. Callers treat this as
+            "the service is not running" and may start one.
+    """
+    return get_backend(endpoint).connect(endpoint)
+
+
+def create_listener(endpoint: Endpoint) -> AbstractAsyncContextManager[IpcListener]:
+    """Listen for clients at ``endpoint``.
+
+    Args:
+        endpoint: Where to listen.
+
+    Returns:
+        An async context manager yielding the listener.
+
+    Raises:
+        AddressInUseError: If another service already holds the address.
+    """
+    return get_backend(endpoint).create_listener(endpoint)

pybricks_core-1.0.0b1/src/pb_core/ipc/address.py

@@ -0,0 +1,151 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 The Pybricks Authors
+
+"""Endpoint addressing for the service.
+
+An endpoint is written as a URI so that one string can name any transport:
+
+* ``unix:///run/user/1000/pybricks/pb-service.sock`` -- AF_UNIX socket (Linux, macOS)
+* ``pipe://pybricks-pb-service-david`` -- Windows named pipe
+* ``tcp://127.0.0.1:47823`` -- TCP, for remote services and for tests
+* ``memory://name`` -- in-process, used by the test suite
+
+Users are not expected to type these. :func:`resolve` picks the right default
+for the platform, and ``PB_ENDPOINT`` overrides it.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from dataclasses import dataclass
+from typing import Literal
+
+from pb_core import paths
+from pb_core.ipc.errors import EndpointError
+
+__all__ = ["ENDPOINT_ENV_VAR", "Endpoint", "Scheme", "default", "resolve"]
+
+ENDPOINT_ENV_VAR = "PB_ENDPOINT"
+
+Scheme = Literal["unix", "pipe", "tcp", "memory"]
+
+
+@dataclass(frozen=True, slots=True)
+class Endpoint:
+    """A transport-independent address for the service."""
+
+    scheme: Scheme
+    target: str
+    """Socket path, pipe name, ``host:port``, or in-process key."""
+
+    @classmethod
+    def parse(cls, uri: str) -> Endpoint:
+        """Parse an endpoint URI.
+
+        Args:
+            uri: A string such as ``tcp://127.0.0.1:47823``.
+
+        Returns:
+            The parsed endpoint.
+
+        Raises:
+            EndpointError: If the URI is malformed or names an unknown
+                scheme. It is a :class:`ValueError`.
+        """
+        scheme, separator, rest = uri.partition("://")
+        if not separator:
+            raise EndpointError(f"endpoint is not a URI: {uri!r}")
+
+        if scheme not in ("unix", "pipe", "tcp", "memory"):
+            raise EndpointError(f"unknown endpoint scheme: {scheme!r}")
+
+        if not rest:
+            raise EndpointError(f"endpoint has no target: {uri!r}")
+
+        if scheme == "tcp":
+            host, colon, port = rest.rpartition(":")
+            if not colon or not host:
+                raise EndpointError(f"tcp endpoint needs host:port: {uri!r}")
+
+            try:
+                number = int(port)
+            except ValueError:
+                raise EndpointError(
+                    f"tcp endpoint port is not a number: {uri!r}"
+                ) from None
+
+            if not 0 <= number <= 65535:
+                raise EndpointError(f"tcp endpoint port out of range: {uri!r}")
+
+        return cls(scheme, rest)
+
+    @property
+    def tcp_address(self) -> tuple[str, int]:
+        """Return ``(host, port)`` for a TCP endpoint.
+
+        Raises:
+            ValueError: If this is not a TCP endpoint.
+        """
+
+        if self.scheme != "tcp":
+            raise EndpointError(f"not a tcp endpoint: {self}")
+
+        host, _, port = self.target.rpartition(":")
+        return host, int(port)
+
+    @property
+    def is_loopback(self) -> bool:
+        """Whether a TCP endpoint is confined to this machine.
+
+        Non-loopback TCP carries the shared secret over a plaintext socket, so
+        callers should require TLS or an SSH tunnel for it.
+        """
+
+        if self.scheme != "tcp":
+            return True
+
+        host, _ = self.tcp_address
+        return host in ("127.0.0.1", "::1", "localhost")
+
+    def __str__(self) -> str:
+        """Render the endpoint back as a URI."""
+        return f"{self.scheme}://{self.target}"
+
+
+def default() -> Endpoint:
+    """Return the platform's default endpoint.
+
+    Windows uses a named pipe because asyncio cannot serve AF_UNIX sockets on
+    the proactor event loop, which the service requires for other reasons.
+    """
+
+    if sys.platform == "win32":
+        return Endpoint(
+            "pipe", paths.windows_pipe_name().removeprefix(r"\.\pipe" + "\\")
+        )
+
+    return Endpoint("unix", str(paths.socket_path()))
+
+
+def resolve(uri: str | None = None) -> Endpoint:
+    """Return the endpoint to use.
+
+    Precedence is the explicit argument, then ``PB_ENDPOINT``, then the
+    platform default.
+
+    Args:
+        uri: An explicit endpoint URI, if the caller has one.
+
+    Returns:
+        The endpoint to connect to or listen on.
+    """
+
+    if uri:
+        return Endpoint.parse(uri)
+
+    from_env = os.environ.get(ENDPOINT_ENV_VAR)
+    if from_env:
+        return Endpoint.parse(from_env)
+
+    return default()

pybricks_core-1.0.0b1/src/pb_core/ipc/backend/__init__.py

@@ -0,0 +1,58 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 The Pybricks Authors
+
+"""Per-transport backends, selected by endpoint scheme."""
+
+from __future__ import annotations
+
+import sys
+
+from pb_core.ipc.address import Endpoint
+from pb_core.ipc.backend.provider import IpcBackend, IpcListener, StreamHandler
+
+__all__ = ["IpcBackend", "IpcListener", "StreamHandler", "get_backend"]
+
+
+def get_backend(endpoint: Endpoint) -> IpcBackend:
+    """Return the backend that implements ``endpoint``.
+
+    Backends are imported lazily so that, for example, importing the client on
+    Linux never touches the Windows pipe module.
+
+    Args:
+        endpoint: The endpoint to be connected to or served.
+
+    Returns:
+        A backend for that endpoint's scheme.
+
+    Raises:
+        NotImplementedError: If the scheme is not supported on this platform.
+    """
+
+    if endpoint.scheme == "memory":
+        from pb_core.ipc.backend.memory import MemoryBackend
+
+        return MemoryBackend()
+
+    if endpoint.scheme == "tcp":
+        from pb_core.ipc.backend.tcp import TcpBackend
+
+        return TcpBackend()
+
+    if endpoint.scheme == "pipe":
+        if sys.platform != "win32":
+            raise NotImplementedError("named pipes are only available on Windows")
+
+        from pb_core.ipc.backend.windows import WindowsPipeBackend
+
+        return WindowsPipeBackend()
+
+    if sys.platform == "win32":
+        raise NotImplementedError(
+            "asyncio cannot serve AF_UNIX sockets on the Windows proactor loop; "
+            "use a pipe:// endpoint"
+        )
+
+    from pb_core.ipc.backend.posix import PosixBackend
+
+    return PosixBackend()

pybricks_core-1.0.0b1/src/pb_core/ipc/backend/_anyio_listener.py

@@ -0,0 +1,31 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 The Pybricks Authors
+
+"""Adapter presenting an anyio listener through the :class:`IpcListener` API."""
+
+from __future__ import annotations
+
+from typing import Any, final
+
+from anyio.abc import Listener, TaskGroup
+from typing_extensions import override
+
+from pb_core.ipc.backend.provider import IpcListener, StreamHandler, owned
+
+__all__ = ["AnyioListener"]
+
+
+@final
+class AnyioListener(IpcListener):
+    """Wraps :class:`anyio.abc.Listener` so all backends share one interface."""
+
+    def __init__(self, inner: Listener[Any]) -> None:
+        self._inner = inner
+
+    @override
+    async def serve(self, handler: StreamHandler, task_group: TaskGroup) -> None:
+        await self._inner.serve(owned(handler), task_group)
+
+    @override
+    async def aclose(self) -> None:
+        await self._inner.aclose()