py-rattler 0.22.0__cp38-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

rattler/pty/pty_process.py

@@ -0,0 +1,391 @@
+from __future__ import annotations
+
+import os
+from typing import BinaryIO, Optional
+
+# Try to import PTY classes - they may not be available on Windows or without pty feature
+try:
+    from rattler.rattler import PyPtyProcess, PyPtyProcessOptions
+
+    _PTY_AVAILABLE = True
+except (ImportError, AttributeError):
+    _PTY_AVAILABLE = False
+
+
+class PtyProcessOptions:
+    """
+    Options for creating a PTY process.
+
+    Controls behavior like whether input is echoed back to the terminal.
+    """
+
+    _inner: PyPtyProcessOptions
+
+    def __init__(self, echo: bool = True) -> None:
+        """
+        Create options for a PTY process.
+
+        Arguments:
+            echo: Whether to echo input back to the terminal. Defaults to True.
+
+        Examples
+        --------
+        ```python
+        >>> from rattler.pty import PtyProcessOptions
+        >>> # Create with echo enabled (default)
+        >>> opts = PtyProcessOptions()
+        >>> opts.echo
+        True
+        >>> # Create with echo disabled
+        >>> opts = PtyProcessOptions(echo=False)
+        >>> opts.echo
+        False
+        >>>
+        ```
+        """
+        if not _PTY_AVAILABLE:
+            raise ImportError("PTY functionality is not available on this platform")
+        self._inner = PyPtyProcessOptions(echo)
+
+    @classmethod
+    def _from_py_pty_process_options(cls, py_pty_process_options: PyPtyProcessOptions) -> PtyProcessOptions:
+        """Construct from FFI PyPtyProcessOptions object."""
+        opts = cls.__new__(cls)
+        opts._inner = py_pty_process_options
+        return opts
+
+    @property
+    def echo(self) -> bool:
+        """Whether input is echoed back to the terminal."""
+        return self._inner.echo
+
+    def __repr__(self) -> str:
+        return f"PtyProcessOptions(echo={self.echo})"
+
+
+class PtyProcess:
+    """
+    A pseudoterminal (PTY) process.
+
+    This is the lower-level PTY API that gives you more control over the process.
+    Use this when you need to:
+    - Read/write to the PTY manually using file handles
+    - Check process status
+    - Control process termination with specific signals
+
+    For interactive shell sessions, consider using `PtySession` instead, which
+    provides higher-level conveniences like `send_line()` and `interact()`.
+    """
+
+    _inner: PyPtyProcess
+
+    def __init__(self, command: list[str], options: Optional[PtyProcessOptions] = None) -> None:
+        """
+        Create a new PTY process with the given command.
+
+        Arguments:
+            command: A list of strings representing the command and its arguments.
+                     The first element is the executable, subsequent elements are arguments.
+            options: Optional PtyProcessOptions to configure the PTY behavior.
+                     If not provided, defaults to echo=True.
+
+        Raises:
+            RuntimeError: If the PTY process could not be created.
+
+        Examples
+        --------
+        ```python
+        >>> from rattler.pty import PtyProcess, PtyProcessOptions
+        >>> # Create with default options (echo enabled)
+        >>> process = PtyProcess(["bash"])
+        >>> # Create with custom options
+        >>> opts = PtyProcessOptions(echo=False)
+        >>> process = PtyProcess(["bash", "-l"], opts)
+        >>> # Check process status
+        >>> status = process.status()
+        >>> print(status)
+        StillAlive
+        >>>
+        ```
+        """
+        if not _PTY_AVAILABLE:
+            raise ImportError("PTY functionality is not available on this platform")
+        if options is None:
+            self._inner = PyPtyProcess(command)
+        else:
+            self._inner = PyPtyProcess(command, options._inner)
+
+    @classmethod
+    def _from_py_pty_process(cls, py_pty_process: PyPtyProcess) -> PtyProcess:
+        """Construct from FFI PyPtyProcess object."""
+        process = cls.__new__(cls)
+        process._inner = py_pty_process
+        return process
+
+    @property
+    def child_pid(self) -> int:
+        """
+        Get the process ID (PID) of the child process.
+
+        Returns:
+            The PID as an integer.
+
+        Examples
+        --------
+        ```python
+        >>> process = PtyProcess(["bash"])
+        >>> pid = process.child_pid
+        >>> print(f"Process ID: {pid}")
+        Process ID: 12345
+        >>>
+        ```
+        """
+        return self._inner.child_pid
+
+    def status(self) -> Optional[str]:
+        """
+        Check the status of the child process (non-blocking).
+
+        This runs waitpid() with WNOHANG, so it returns immediately.
+        Note: If you previously called exit() or status() returned an exit status,
+        subsequent calls may return None.
+
+        Returns:
+            A string representing the process status, or None if status cannot be determined.
+            Possible values:
+            - "StillAlive": Process is still running
+            - "Exited(code)": Process exited with the given exit code
+            - "Signaled(signal)": Process was terminated by a signal
+            - "Stopped": Process was stopped
+
+        Examples
+        --------
+        ```python
+        >>> import time
+        >>> process = PtyProcess(["sleep", "10"])
+        >>> print(process.status())
+        StillAlive
+        >>> time.sleep(11)
+        >>> print(process.status())
+        Exited(0)
+        >>>
+        ```
+        """
+        return self._inner.status()
+
+    def exit(self) -> str:
+        """
+        Exit the process gracefully by sending SIGTERM.
+
+        This method blocks until the process has exited. If the process doesn't
+        respond to SIGTERM, it will eventually be killed with SIGKILL if a
+        kill_timeout was set (not currently exposed to Python).
+
+        Returns:
+            A string describing the exit status.
+
+        Raises:
+            RuntimeError: If the process could not be terminated.
+
+        Examples
+        --------
+        ```python
+        >>> process = PtyProcess(["bash"])
+        >>> status = process.exit()
+        >>> print(status)
+        Exited(0)
+        >>>
+        ```
+        """
+        return self._inner.exit()
+
+    def get_file_handle(self) -> BinaryIO:
+        """
+        Get a file handle for reading from and writing to the PTY.
+
+        This returns a Python file-like object that can be used to read output
+        from the process and write input to it. This is useful for non-interactive
+        automation where you want to programmatically read the process output.
+
+        Returns:
+            A Python binary file object for reading/writing to the PTY.
+
+        Raises:
+            RuntimeError: If the file handle could not be created.
+
+        Examples
+        --------
+        ```python
+        >>> process = PtyProcess(["bash"])
+        >>> file = process.get_file_handle()
+        >>> # Write to the process
+        >>> file.write(b"echo hello\\n")
+        >>> file.flush()
+        >>> # Read output (this is a blocking operation)
+        >>> output = file.read(100)
+        >>> print(output)
+        >>>
+        ```
+        """
+        fd = self._inner.get_file_handle()
+        return os.fdopen(fd, "r+b", buffering=0)
+
+    @property
+    def kill_timeout(self) -> Optional[float]:
+        """
+        Get the kill timeout in seconds.
+
+        When calling exit() or async_exit(), if the process doesn't respond to
+        SIGTERM within this timeout, it will be forcefully killed with SIGKILL.
+
+        Returns:
+            The timeout in seconds, or None if no timeout is set.
+
+        Examples
+        --------
+        ```python
+        >>> process = PtyProcess(["bash"])
+        >>> print(process.kill_timeout)
+        None
+        >>>
+        ```
+        """
+        return self._inner.get_kill_timeout()
+
+    @kill_timeout.setter
+    def kill_timeout(self, timeout: Optional[float]) -> None:
+        """
+        Set the kill timeout in seconds.
+
+        Arguments:
+            timeout: Timeout in seconds, or None to disable timeout.
+
+        Examples
+        --------
+        ```python
+        >>> process = PtyProcess(["bash"])
+        >>> process.kill_timeout = 5.0  # 5 second timeout
+        >>> process.kill_timeout = None  # Disable timeout
+        >>>
+        ```
+        """
+        self._inner.set_kill_timeout(timeout)
+
+    async def async_read(self, size: int = 8192) -> bytes:
+        """
+        Read from the PTY asynchronously.
+
+        This is the async version of reading via get_file_handle(). It performs
+        non-blocking I/O using tokio on the Rust side, bridged to Python's asyncio.
+
+        Arguments:
+            size: Maximum number of bytes to read. Defaults to 8192.
+
+        Returns:
+            Bytes read from the PTY.
+
+        Raises:
+            RuntimeError: If the read operation fails.
+
+        Examples
+        --------
+        ```python
+        >>> import asyncio
+        >>> async def main():
+        ...     process = PtyProcess(["bash", "-c", "echo hello"])
+        ...     data = await process.async_read(1024)
+        ...     print(data)
+        >>> asyncio.run(main())
+        >>>
+        ```
+        """
+        return await self._inner.async_read(size)
+
+    async def async_write(self, data: bytes) -> int:
+        """
+        Write to the PTY asynchronously.
+
+        This is the async version of writing via get_file_handle(). It performs
+        non-blocking I/O using tokio on the Rust side.
+
+        Arguments:
+            data: Bytes to write to the PTY.
+
+        Returns:
+            The number of bytes written.
+
+        Raises:
+            RuntimeError: If the write operation fails.
+
+        Examples
+        --------
+        ```python
+        >>> import asyncio
+        >>> async def main():
+        ...     process = PtyProcess(["cat"])
+        ...     n = await process.async_write(b"hello\\n")
+        ...     print(f"Wrote {n} bytes")
+        ...     process.exit()
+        >>> asyncio.run(main())
+        >>>
+        ```
+        """
+        return await self._inner.async_write(data)
+
+    async def async_wait(self) -> str:
+        """
+        Wait for the process to exit asynchronously.
+
+        This is the async version of polling status() in a loop. It polls the
+        process status periodically without blocking the async runtime.
+
+        Returns:
+            A string describing the exit status.
+
+        Raises:
+            RuntimeError: If waiting fails.
+
+        Examples
+        --------
+        ```python
+        >>> import asyncio
+        >>> async def main():
+        ...     process = PtyProcess(["sleep", "1"])
+        ...     status = await process.async_wait()
+        ...     print(status)
+        >>> asyncio.run(main())
+        Exited(0)
+        >>>
+        ```
+        """
+        return await self._inner.async_wait()
+
+    async def async_exit(self) -> str:
+        """
+        Exit the process gracefully asynchronously by sending SIGTERM.
+
+        This is the async version of exit(). It sends SIGTERM and waits for
+        the process to terminate without blocking the async runtime.
+
+        Returns:
+            A string describing the exit status.
+
+        Raises:
+            RuntimeError: If the process could not be terminated.
+
+        Examples
+        --------
+        ```python
+        >>> import asyncio
+        >>> async def main():
+        ...     process = PtyProcess(["bash"])
+        ...     status = await process.async_exit()
+        ...     print(status)
+        >>> asyncio.run(main())
+        >>>
+        ```
+        """
+        return await self._inner.async_exit()
+
+    def __repr__(self) -> str:
+        return f"PtyProcess(child_pid={self.child_pid})"

rattler/pty/pty_session.py

@@ -0,0 +1,241 @@
+from __future__ import annotations
+
+from typing import Optional
+
+# Try to import PTY classes - they may not be available on Windows or without pty feature
+try:
+    from rattler.rattler import PyPtySession
+
+    _PTY_AVAILABLE = True
+except (ImportError, AttributeError):
+    _PTY_AVAILABLE = False
+
+
+class PtySession:
+    """
+    A pseudoterminal (PTY) session for interactive shell use.
+
+    This is the higher-level PTY API built on top of PtyProcess.
+    It provides convenient methods for interactive shell sessions with:
+    - Easy command sending via send_line()
+    - Interactive mode with wait_until pattern matching
+    - Automatic buffering and flushing
+
+    Use this for interactive shell sessions where you want to send commands
+    and optionally hand over control to the user.
+    """
+
+    _inner: PyPtySession
+
+    def __init__(self, command: list[str]) -> None:
+        """
+        Create a new PTY session with the given command.
+
+        The PTY session is created with echo enabled by default, which is
+        appropriate for interactive shell use.
+
+        Arguments:
+            command: A list of strings representing the command and its arguments.
+                     The first element is the executable, subsequent elements are arguments.
+
+        Raises:
+            RuntimeError: If the PTY session could not be created.
+
+        Examples
+        --------
+        ```python
+        >>> from rattler.pty import PtySession
+        >>> # Start an interactive bash session
+        >>> session = PtySession(["bash"])
+        >>> session.send_line("export MY_VAR=hello")
+        >>> # Hand over control to the user (blocks until shell exits)
+        >>> exit_code = session.interact()
+        >>>
+        ```
+
+        If you want to send commands without using interact() (which blocks),
+        use exit() to clean up when done:
+
+        ```python
+        >>> from rattler.pty import PtySession
+        >>> session = PtySession(["bash"])
+        >>> session.send_line("echo hello")
+        >>> status = session.exit()  # Clean up the session
+        >>>
+        ```
+        """
+        if not _PTY_AVAILABLE:
+            raise ImportError("PTY functionality is not available on this platform")
+        self._inner = PyPtySession(command)
+
+    @classmethod
+    def _from_py_pty_session(cls, py_pty_session: PyPtySession) -> PtySession:
+        """Construct from FFI PyPtySession object."""
+        session = cls.__new__(cls)
+        session._inner = py_pty_session
+        return session
+
+    def send_line(self, line: str) -> int:
+        """
+        Send a string followed by a newline to the PTY session.
+
+        This is like typing a command and pressing Enter. The command is flushed
+        immediately, so the shell will receive it right away.
+
+        Arguments:
+            line: The string to send (newline will be added automatically).
+
+        Returns:
+            The number of bytes written.
+
+        Raises:
+            RuntimeError: If the write operation fails.
+
+        Examples
+        --------
+        ```python
+        >>> from rattler.pty import PtySession
+        >>> session = PtySession(["bash"])
+        >>> session.send_line("export MY_VAR=hello")
+        22
+        >>> session.send_line("echo $MY_VAR")
+        13
+        >>> session.exit()  # Clean up when done
+        'Signaled(SIGTERM)'
+        >>>
+        ```
+        """
+        return self._inner.send_line(line)
+
+    def send(self, data: str) -> int:
+        """
+        Send a string to the PTY session without adding a newline.
+
+        Note: You'll need to call flush() to ensure the data is sent.
+
+        Arguments:
+            data: The string to send.
+
+        Returns:
+            The number of bytes written.
+
+        Raises:
+            RuntimeError: If the write operation fails.
+
+        Examples
+        --------
+        ```python
+        >>> from rattler.pty import PtySession
+        >>> session = PtySession(["bash"])
+        >>> session.send("echo")
+        4
+        >>> session.send(" hello\\n")
+        7
+        >>> session.flush()
+        >>> session.exit()  # Clean up when done
+        'Signaled(SIGTERM)'
+        >>>
+        ```
+        """
+        return self._inner.send(data)
+
+    def flush(self) -> None:
+        """
+        Flush any pending output to the PTY.
+
+        This is automatically called by send_line(), but can be called manually
+        if you use send().
+
+        Raises:
+            RuntimeError: If the flush operation fails.
+
+        Examples
+        --------
+        ```python
+        >>> from rattler.pty import PtySession
+        >>> session = PtySession(["bash"])
+        >>> session.send("echo hello\\n")
+        11
+        >>> session.flush()  # Make sure the command is sent
+        >>> session.exit()  # Clean up when done
+        'Signaled(SIGTERM)'
+        >>>
+        ```
+        """
+        self._inner.flush()
+
+    def exit(self) -> str:
+        """
+        Exit the process gracefully by sending SIGTERM.
+
+        This method blocks until the process has exited. Useful for cleaning up
+        PTY sessions when you're done sending commands but don't want to use interact().
+
+        Returns:
+            A string describing the exit status.
+
+        Raises:
+            RuntimeError: If the process could not be terminated.
+
+        Examples
+        --------
+        ```python
+        >>> from rattler.pty import PtySession
+        >>> session = PtySession(["bash"])
+        >>> session.send_line("echo hello")
+        11
+        >>> status = session.exit()
+        >>> print(status)
+        Signaled(SIGTERM)
+        >>>
+        ```
+        """
+        return self._inner.exit()
+
+    def interact(self, wait_until: Optional[str] = None) -> Optional[int]:
+        """
+        Start an interactive session, optionally waiting for a pattern first.
+
+        This method:
+        1. Sets the terminal to raw mode
+        2. If wait_until is provided, buffers output until that pattern appears
+        3. Then forwards all I/O between the user's terminal and the PTY
+        4. Returns when the shell process exits
+
+        Arguments:
+            wait_until: Optional pattern to wait for before showing output.
+                        Useful for waiting for shell initialization to complete.
+                        If not found within 1 second, a warning is shown and
+                        interaction begins anyway.
+
+        Returns:
+            The exit code of the shell process, or None if terminated by signal.
+
+        Raises:
+            RuntimeError: If interaction fails.
+
+        Examples
+        --------
+        ```python
+        >>> session = PtySession(["bash"])
+        >>> # Send some setup commands
+        >>> session.send_line("export MY_VAR=hello")
+        >>> session.send_line("echo 'READY'")
+        >>> # Wait for "READY" before handing control to user
+        >>> exit_code = session.interact(wait_until="READY")
+        >>> print(f"Session exited with code: {exit_code}")
+        Session exited with code: 0
+        >>>
+        ```
+
+        ```python
+        >>> session = PtySession(["bash"])
+        >>> # Interact immediately without waiting
+        >>> exit_code = session.interact()
+        >>>
+        ```
+        """
+        return self._inner.interact(wait_until)
+
+    def __repr__(self) -> str:
+        return "PtySession()"

rattler/repo_data/__init__.py

@@ -0,0 +1,19 @@
+from rattler.repo_data.package_record import PackageRecord
+from rattler.repo_data.repo_data import RepoData
+from rattler.repo_data.patch_instructions import PatchInstructions
+from rattler.repo_data.record import RepoDataRecord
+from rattler.repo_data.sparse import SparseRepoData, PackageFormatSelection
+from rattler.repo_data.gateway import Gateway, SourceConfig
+from rattler.repo_data.source import RepoDataSource
+
+__all__ = [
+    "PackageRecord",
+    "RepoData",
+    "PatchInstructions",
+    "RepoDataRecord",
+    "SparseRepoData",
+    "Gateway",
+    "SourceConfig",
+    "PackageFormatSelection",
+    "RepoDataSource",
+]