pybricks-client 1.0.0b1__tar.gz

pybricks_client-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_client-1.0.0b1/PKG-INFO

@@ -0,0 +1,57 @@
+Metadata-Version: 2.4
+Name: pybricks-client
+Version: 1.0.0b1
+Summary: Client library for the Pybricks service
+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: pybricks-core>=1.0.0b1
+Requires-Dist: anyio>=4.14
+Requires-Dist: mpy-cross-v6>=1.1.1
+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/reference/
+Project-URL: Changelog, https://github.com/pybricks/pybricks-tools/blob/main/packages/pb-client/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-client
+
+Talk to a [Pybricks](https://pybricks.com) hub from your own Python program.
+
+```python
+import anyio
+import pb_client
+
+
+async def main() -> None:
+    async with pb_client.connect() as pb:
+        hub = await pb.connect_hub(name="Rover")
+        print(f"connected to {hub.name}, firmware {hub.firmware}")
+
+
+anyio.run(main)
+```
+
+The connection is held by a background service that outlives your program, so
+the next one to run finds the hub already there. It is async throughout, and
+everything it opens is closed for you when the `async with` block ends.
+
+**Looking for the command line?** That is `pybricks-cli`, which installs `pb`
+and uses this library underneath.
+
+> **Status:** beta. Commands and APIs may still change before 1.0.0.

pybricks_client-1.0.0b1/README.md

@@ -0,0 +1,26 @@
+# pybricks-client
+
+Talk to a [Pybricks](https://pybricks.com) hub from your own Python program.
+
+```python
+import anyio
+import pb_client
+
+
+async def main() -> None:
+    async with pb_client.connect() as pb:
+        hub = await pb.connect_hub(name="Rover")
+        print(f"connected to {hub.name}, firmware {hub.firmware}")
+
+
+anyio.run(main)
+```
+
+The connection is held by a background service that outlives your program, so
+the next one to run finds the hub already there. It is async throughout, and
+everything it opens is closed for you when the `async with` block ends.
+
+**Looking for the command line?** That is `pybricks-cli`, which installs `pb`
+and uses this library underneath.
+
+> **Status:** beta. Commands and APIs may still change before 1.0.0.

pybricks_client-1.0.0b1/pyproject.toml

@@ -0,0 +1,56 @@
+[project]
+name = "pybricks-client"
+version = "1.0.0b1"
+description = "Client library for the Pybricks service"
+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 = [
+    "pybricks-core>=1.0.0b1",
+    "anyio>=4.14",
+    "mpy-cross-v6>=1.1.1",
+    "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/reference/"
+Changelog = "https://github.com/pybricks/pybricks-tools/blob/main/packages/pb-client/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_client"
+
+[tool.uv.sources.pybricks-core]
+workspace = true

pybricks_client-1.0.0b1/pyproject.toml.orig

@@ -0,0 +1,44 @@
+[project]
+name = "pybricks-client"
+version = "1.0.0b1"
+description = "Client library for the Pybricks service"
+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 = [
+    "pybricks-core>=1.0.0b1",
+    "anyio>=4.14",
+    "mpy-cross-v6>=1.1.1",
+    "typing-extensions>=4.15",
+]
+
+[project.urls]
+homepage = "https://pybricks.com"
+repository = "https://github.com/pybricks/pybricks-tools"
+documentation = "https://pybricks.com/pybricks-tools/reference/"
+"Changelog" = "https://github.com/pybricks/pybricks-tools/blob/main/packages/pb-client/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_client"
+
+[tool.uv.sources]
+pybricks-core = { workspace = true }

pybricks_client-1.0.0b1/src/pb_client/__init__.py

@@ -0,0 +1,70 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 The Pybricks Authors
+
+"""Client library for the Pybricks service.
+
+The public surface is deliberately shaped so that structured concurrency cannot
+be violated from outside: anything producing ongoing events is an async context
+manager yielding an async iterator, and no function takes a ``timeout``
+argument. Callers scope cancellation with
+[fail_after][anyio.fail_after] or
+[move_on_after][anyio.move_on_after] instead.
+"""
+
+__version__ = "1.0.0b1"
+
+from pb_client.compile import (
+    SOURCE_NAME,
+    CompiledProgram,
+    CompileError,
+    compile_program,
+    compile_script,
+    compile_source,
+    describe_compiler,
+)
+from pb_client.errors import (
+    PbClientError,
+    ServiceStartError,
+    ServiceTooOld,
+    ServiceUnavailable,
+)
+from pb_client.models import (
+    Choice,
+    DeviceInfo,
+    Downloaded,
+    HubInfo,
+    ServiceInfo,
+    UnusableAdapter,
+)
+from pb_client.service import Service, connect
+from pb_client.stdio import REPL_PROGRAM_ID, HubEvent, Output, State, Status
+from pb_core.jsonrpc import JsonRpcError
+
+__all__ = [
+    "REPL_PROGRAM_ID",
+    "SOURCE_NAME",
+    "Choice",
+    "CompileError",
+    "CompiledProgram",
+    "DeviceInfo",
+    "Downloaded",
+    "HubEvent",
+    "HubInfo",
+    "JsonRpcError",
+    "Output",
+    "PbClientError",
+    "Service",
+    "ServiceInfo",
+    "ServiceStartError",
+    "ServiceTooOld",
+    "ServiceUnavailable",
+    "State",
+    "Status",
+    "UnusableAdapter",
+    "__version__",
+    "compile_program",
+    "compile_script",
+    "compile_source",
+    "connect",
+    "describe_compiler",
+]

pybricks_client-1.0.0b1/src/pb_client/autostart.py

@@ -0,0 +1,216 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 The Pybricks Authors
+
+"""Starting a service on demand.
+
+Two clients running at once may both find no service and both start one. That is
+deliberately not coordinated: one wins the single-instance lock, the loser exits
+quietly, and both clients' readiness loops then connect to the winner. There are
+no PID files to go stale and no startup handshake to get wrong.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import shlex
+import shutil
+import subprocess
+import sys
+import time
+from collections.abc import AsyncGenerator
+from contextlib import AsyncExitStack, asynccontextmanager
+from pathlib import Path
+from typing import Any, cast
+
+import anyio
+from anyio.abc import ByteStream
+
+from pb_client.errors import ServiceStartError, ServiceUnavailable
+from pb_core import ipc, paths
+from pb_core.ipc import Endpoint
+
+logger = logging.getLogger(__name__)
+
+__all__ = [
+    "SERVICE_COMMAND_ENV_VAR",
+    "open_connection",
+    "spawn_service",
+]
+
+SERVICE_COMMAND_ENV_VAR = "PB_SERVICE_CMD"
+
+
+def neutral_directory() -> Path:
+    """Return where the service should be started from: the filesystem root.
+
+    Computed rather than a constant so that it cannot depend on what the
+    working directory happened to be when this module was imported -- ``pb -C``
+    may have moved to another drive since.
+
+    Returns:
+        The root of the current drive, which is always a directory that exists.
+    """
+    return Path(Path.cwd().anchor)
+
+
+READY_TIMEOUT = 15.0
+"""How long to keep polling for a service we just started.
+
+Deliberately a module constant rather than a parameter. The repository's async
+rules say public APIs take no ``timeout`` argument -- callers scope cancellation
+with ``anyio.fail_after`` instead. This is not a caller-facing deadline but an
+internal safety bound, whose real job is to turn "hung forever" into a message
+naming the service's log file.
+"""
+_FIRST_DELAY = 0.02
+_MAX_DELAY = 0.25
+_BACKOFF = 1.6
+
+_NOT_LISTENING = (ConnectionRefusedError, FileNotFoundError)
+"""What "no service there" looks like.
+
+On Windows, connecting to a pipe that does not exist raises FileNotFoundError
+straight away rather than waiting, so the retry loop is what supplies the
+patience.
+"""
+
+
+def _service_command() -> list[str]:
+    """Return the command that starts a service.
+
+    The fallback to ``-m pb_service`` is why the CLI package depends on the service
+    package even though it never imports it: installing the CLI alone must
+    still give a working autostart.
+    """
+    override = os.environ.get(SERVICE_COMMAND_ENV_VAR)
+    if override:
+        # posix=False on Windows, or shlex treats the backslashes in a path
+        # like C:\Python\python.exe as escapes and silently mangles it. That
+        # mode leaves quotes attached, so strip them.
+        if sys.platform == "win32":
+            return [token.strip('"') for token in shlex.split(override, posix=False)]
+
+        return shlex.split(override)
+
+    found = shutil.which("pb-service")
+    if found:
+        return [found]
+
+    return [sys.executable, "-m", "pb_service"]
+
+
+_spawned: list[subprocess.Popen[bytes]] = []
+"""Handles for services this process started.
+
+Kept only so that Popen objects are not garbage collected while the service is
+still running, which would emit a ResourceWarning. The service is meant to
+outlive us, so it is never waited on; Popen is simply not the right abstraction
+for a process we deliberately do not manage.
+"""
+
+
+def spawn_service(endpoint: Endpoint) -> None:
+    """Start a service in the background and return immediately.
+
+    Args:
+        endpoint: Where the service should listen.
+    """
+    command = [*_service_command(), "--endpoint", str(endpoint)]
+    logger.info("starting a service: %s", " ".join(command))
+
+    common: dict[str, Any] = {
+        "stdin": subprocess.DEVNULL,
+        "stdout": subprocess.DEVNULL,
+        "stderr": subprocess.DEVNULL,
+        "close_fds": True,
+        # The filesystem root, which is what a daemon has always done and for
+        # the same reason: a running process holds its working directory, so
+        # inheriting this one would stop that directory being renamed or
+        # deleted for as long as the service lives -- which is well past the
+        # shell that started it, and on Windows is enforced rather than
+        # merely untidy. The service never uses a relative path; everything
+        # it writes comes from pb_core.paths, which is absolute.
+        "cwd": neutral_directory(),
+    }
+
+    if sys.platform == "win32":
+        # CREATE_NO_WINDOW, emphatically not DETACHED_PROCESS. Both are
+        # described as freeing a child from the parent's console, and only one
+        # of them does it quietly: measured on Windows 11, a console
+        # application started with DETACHED_PROCESS has a *new* console
+        # allocated for it, and that console is visible. It is the terminal
+        # that used to flash up whenever a command started the service.
+        # Adding CREATE_NO_WINDOW alongside does not help -- it is documented
+        # as ignored in combination with DETACHED_PROCESS, and measurement
+        # agrees.
+        #
+        # On its own, CREATE_NO_WINDOW leaves the service with no console
+        # window of the parent's or of its own, so no console control event
+        # can reach it -- including the one Windows sends when the terminal
+        # that started it is closed. CREATE_NEW_PROCESS_GROUP keeps Ctrl+C out
+        # as well. Shutting down deliberately goes through service.shutdown.
+        child = subprocess.Popen(
+            command,
+            creationflags=subprocess.CREATE_NO_WINDOW
+            | subprocess.CREATE_NEW_PROCESS_GROUP,
+            **common,
+        )
+    else:
+        # Its own session, so it survives this terminal closing.
+        child = subprocess.Popen(command, start_new_session=True, **common)
+
+    # The shared options go in as **Any, so pyright picks the first Popen
+    # overload that matches -- the text-mode one -- although nothing here
+    # asks for text mode and every stream is DEVNULL. Say which it is.
+    _spawned.append(cast("subprocess.Popen[bytes]", child))
+
+
+async def _enter_with_retry(stack: AsyncExitStack, endpoint: Endpoint) -> ByteStream:
+    """Keep trying to connect until the service is up, or give up."""
+    deadline = time.monotonic() + READY_TIMEOUT
+    delay = _FIRST_DELAY
+
+    while True:
+        try:
+            return await stack.enter_async_context(ipc.connect(endpoint))
+        except _NOT_LISTENING:
+            if time.monotonic() >= deadline:
+                raise ServiceStartError(str(endpoint), paths.log_file()) from None
+
+            await anyio.sleep(delay)
+            delay = min(delay * _BACKOFF, _MAX_DELAY)
+
+
+@asynccontextmanager
+async def open_connection(
+    endpoint: Endpoint, *, autostart: bool = True
+) -> AsyncGenerator[ByteStream, None]:
+    """Connect to the service, starting one if necessary.
+
+    Args:
+        endpoint: Where the service is, or should be.
+        autostart: Whether to start a service when none is running.
+
+    Yields:
+        The connected stream.
+
+    Raises:
+        ServiceUnavailable: If no service is running and ``autostart`` is false.
+        ServiceStartError: If a service was started but never became reachable.
+    """
+
+    async with AsyncExitStack() as stack:
+        try:
+            stream = await stack.enter_async_context(ipc.connect(endpoint))
+        except _NOT_LISTENING:
+            if not autostart:
+                raise ServiceUnavailable(
+                    f"the background service is not running ({endpoint})"
+                ) from None
+
+            logger.debug("no service at %s; starting one", endpoint)
+            spawn_service(endpoint)
+            stream = await _enter_with_retry(stack, endpoint)
+
+        yield stream