diff --git a/.github/workflows/js_sdk_tests.yml b/.github/workflows/js_sdk_tests.yml index 49491c1c8..da09a9cbc 100644 --- a/.github/workflows/js_sdk_tests.yml +++ b/.github/workflows/js_sdk_tests.yml @@ -40,7 +40,9 @@ jobs: pnpm config set exclude-links-from-lockfile true - name: Install dependencies - run: pnpm install --frozen-lockfile + run: | + pnpm install --frozen-lockfile + npx playwright install --with-deps - name: Test build run: pnpm build diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 3076d6d1b..0b2030087 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -169,6 +169,9 @@ jobs: NPM_TOKEN: ${{ secrets.NPM_TOKEN }} PYPI_TOKEN: ${{ secrets.PYPI_TOKEN }} + - name: Generate API Ref + run: pnpm run generate-api-reference + - name: Update lock file run: pnpm i --no-link --no-frozen-lockfile @@ -176,6 +179,7 @@ jobs: run: | git config user.name "github-actions[bot]" git config user.email "github-actions[bot]@users.noreply.github.com" + git add apps/web/src/app/\(docs\)/docs/api-reference git commit -am "[skip ci] Release new versions" || exit 0 git push env: diff --git a/.github/workflows/release_candidates.yml b/.github/workflows/release_candidates.yml index e66aee54e..bc3b99d6d 100644 --- a/.github/workflows/release_candidates.yml +++ b/.github/workflows/release_candidates.yml @@ -71,14 +71,6 @@ jobs: env: PYPI_TOKEN: ${{ secrets.PYPI_TOKEN }} - - - name: Generate Python SDK API reference - id: python-sdk-api-ref - if: ${{ contains( github.event.pull_request.labels.*.name, 'python-rc') }} - working-directory: ./packages/python-sdk - run: | - ./scripts/generate_api_ref.sh - - name: Install JS dependencies if: ${{ contains( github.event.pull_request.labels.*.name, 'js-rc') || contains( github.event.pull_request.labels.*.name, 'cli-rc') }} run: | @@ -102,14 +94,6 @@ jobs: env: NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} - - - name: Generate JS SDK API reference - id: js-sdk-api-ref - if: ${{ contains( github.event.pull_request.labels.*.name, 'js-rc') }} - working-directory: packages/js-sdk - run: ./scripts/generate_api_ref.sh - - - name: Install dependencies if: ${{ contains( github.event.pull_request.labels.*.name, 'js-rc') || contains( github.event.pull_request.labels.*.name, 'cli-rc') }} run: | @@ -124,20 +108,11 @@ jobs: env: NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} - - name: Generate CLI API reference - if: ${{ contains( github.event.pull_request.labels.*.name, 'cli-rc') }} - id: cli-api-ref - working-directory: packages/cli - run: ./scripts/generate_api_ref.sh - - name: Commit new versions if: ${{ contains( github.event.pull_request.labels.*.name, 'js-rc') || contains( github.event.pull_request.labels.*.name, 'cli-rc') || contains( github.event.pull_request.labels.*.name, 'python-rc') }} run: | git config user.name "github-actions[bot]" git config user.email "github-actions[bot]@users.noreply.github.com" - - git add apps/web/src/app/\(docs\)/docs/api-reference - git commit -am "[skip ci] Release new versions" || exit 0 git push env: diff --git a/apps/web/src/app/(docs)/docs/api-reference/python-sdk/v0.17.1/sandbox_async/page.mdx b/apps/web/src/app/(docs)/docs/api-reference/python-sdk/v0.17.1/sandbox_async/page.mdx index f5e5b2641..49b328c3b 100644 --- a/apps/web/src/app/(docs)/docs/api-reference/python-sdk/v0.17.1/sandbox_async/page.mdx +++ b/apps/web/src/app/(docs)/docs/api-reference/python-sdk/v0.17.1/sandbox_async/page.mdx @@ -1,6 +1,207 @@ +## AsyncWatchHandle + +```python +class AsyncWatchHandle() +``` + +Class representing the watch operation. It provides method to stop the watch operation. + + +#### stop + +```python +async def stop() +``` + +Stop watching the directory. + + + + +## Filesystem + +```python +class Filesystem() +``` + +Manager for interacting with the filesystem in the sandbox. + + +#### read + +```python +async def read(path: str, + format: Literal["text", "bytes", "stream"] = "text", + user: Username = "user", + request_timeout: Optional[float] = None) +``` + +Reads a whole file content and returns it in requested format (text by default). + +:param path: Path to the file +:param format: Format of the file content +:param user: Run the operation as this user +:param request_timeout: Timeout for the request +:return File content in requested format + + + +#### write + +```python +async def write(path: str, + data: Union[str, bytes, IO], + user: Username = "user", + request_timeout: Optional[float] = None) -> EntryInfo +``` + +Writes content to a file on the path. + +When writing to a file that doesn't exist, the file will get created. +When writing to a file that already exists, the file will get overwritten. +When writing to a file that's in a directory that doesn't exist, the directory will get created. + +**Arguments**: + +- `path`: Path to the file +- `data`: Data to write to the file +- `user`: Run the operation as this user +- `request_timeout`: Timeout for the request + +**Returns**: + +Information about the written file + + +#### list + +```python +async def list(path: str, + user: Username = "user", + request_timeout: Optional[float] = None) -> List[EntryInfo] +``` + +Lists entries in a directory. + +**Arguments**: + +- `path`: Path to the directory +- `user`: Run the operation as this user +- `request_timeout`: Timeout for the request + +**Returns**: + +List of entries in the directory + + +#### exists + +```python +async def exists(path: str, + user: Username = "user", + request_timeout: Optional[float] = None) -> bool +``` + +Checks if a file or a directory exists. + +:param path: Path to a file or a directory +:param user Run the operation as this user +:param request_timeout Timeout for the request + + + +#### remove + +```python +async def remove(path: str, + user: Username = "user", + request_timeout: Optional[float] = None) -> None +``` + +Removes a file or a directory. + +**Arguments**: + +- `path`: Path to a file or a directory +- `user`: Run the operation as this user +- `request_timeout`: Timeout for the request + + +#### rename + +```python +async def rename(old_path: str, + new_path: str, + user: Username = "user", + request_timeout: Optional[float] = None) -> EntryInfo +``` + +Renames a file or directory from one path to another. + +:param old_path Path to the file or directory to move +:param new_path Path to move the file or directory to +:param user Run the operation as this user +:param request_timeout Timeout for the request + +:return: Information about the renamed file or directory + + + +#### make\_dir + +```python +async def make_dir(path: str, + user: Username = "user", + request_timeout: Optional[float] = None) -> bool +``` + +Creates a new directory and all directories along the way if needed on the specified path. + +**Arguments**: + +- `path`: Path to a new directory. For example '/dirA/dirB' when creating 'dirB'. +- `user`: Run the operation as this user +- `request_timeout`: Timeout for the request + +**Returns**: + +True if the directory was created, False if the directory already exists + + +#### watch\_dir + +```python +async def watch_dir(path: str, + on_event: OutputHandler[FilesystemEvent], + on_exit: Optional[OutputHandler[Exception]] = None, + user: Username = "user", + request_timeout: Optional[float] = None, + timeout: Optional[float] = 60) -> AsyncWatchHandle +``` + +Watches directory for filesystem events. + +**Arguments**: + +- `path`: Path to a directory that will be watched +- `on_event`: Callback that will be called on each event +- `on_exit`: Callback that will be called when the watch is closed +- `user`: Run the operation as this user +- `request_timeout`: Timeout for the request +- `timeout`: Timeout for the watch, after which the watch will be closed + +**Returns**: + +Watcher handle + + + + + + ## AsyncSandbox @@ -212,118 +413,100 @@ If you try to set the timeout to a period, which exceeds the maximum limit, the -## Process +## AsyncProcessHandle ```python -class Process() +class AsyncProcessHandle() ``` -Manager for starting and interacting with processes in the sandbox. +Class representing a process. It provides methods for waiting and killing the process. -#### list +#### pid ```python -async def list(request_timeout: Optional[float] = None) -> List[ProcessInfo] +@property +def pid() ``` -Lists all running processes. +Get the process ID. -**Arguments**: -- `request_timeout`: Request timeout +#### stdout -**Returns**: +```python +@property +def stdout() +``` -List of running processes +Stdout of the process. -#### kill +#### stderr ```python -async def kill(pid: int, request_timeout: Optional[float] = None) -> bool +@property +def stderr() ``` -Kills a process. +Stderr of the process. -**Arguments**: -- `pid`: Process ID to connect to. You can get the list of processes using `sandbox.commands.list()`. -- `request_timeout`: Request timeout +#### error -**Returns**: +```python +@property +def error() +``` -`True` if the process was killed, `False` if the process was not found +Error message of the process. It is `None` if the process is still running. -#### send\_stdin +#### exit\_code ```python -async def send_stdin(pid: int, - data: str, - request_timeout: Optional[float] = None) -> None +@property +def exit_code() ``` -Sends data to the stdin of a process. - -:param pid Process ID to send data to. You can get the list of processes using `sandbox.commands.list()`. -:param data: Data to send to the process -:param request_timeout: Request timeout +Exit code of the process. It is `None` if the process is still running. +#### disconnect -#### run +```python +async def disconnect() -> None +``` + +Disconnects from the process. It does not kill the process. It only stops receiving events from the process. + + +#### wait ```python -async def run(cmd: str, - background: Union[bool, None] = None, - envs: Optional[Dict[str, str]] = None, - user: Username = "user", - cwd: Optional[str] = None, - on_stdout: Optional[OutputHandler[Stdout]] = None, - on_stderr: Optional[OutputHandler[Stderr]] = None, - timeout: Optional[float] = 60, - request_timeout: Optional[float] = None) +async def wait() -> ProcessResult ``` -Starts a new process and depending on the `background` parameter, waits for the process to finish or not. +Waits for the process to finish and returns the result. -:param cmd Command to execute -:param background: - If `True`, the function will return a `ProcessHandle` object that can be used to interact with the process. - If `False`, the function will wait for the process to finish and return a `ProcessResult` object. -:param envs: Environment variables -:param user: User to run the process as -:param cwd: Working directory -:param on_stdout: Callback for stdout -:param on_stderr: Callback for stderr -:param timeout: Timeout for the maximum time the process is allowed to run -:param request_timeout: Timeout for the request -:return: `ProcessHandle` if `background` is `True`, `ProcessResult` if `background` is `False` +If the process exits with a non-zero exit code, it throws a `ProcessExitException`. +**Returns**: +Process result -#### connect + +#### kill ```python -async def connect( - pid: int, - timeout: Optional[float] = 60, - request_timeout: Optional[float] = None, - on_stdout: Optional[OutputHandler[Stdout]] = None, - on_stderr: Optional[OutputHandler[Stderr]] = None -) -> AsyncProcessHandle +async def kill() -> bool ``` -Connects to an existing process. +Kills the process. -**Arguments**: +**Returns**: -- `pid`: Process ID to connect to. You can get the list of processes using `sandbox.commands.list()`. -- `timeout`: Timeout for the connection -- `request_timeout`: Request timeout -- `on_stdout`: Callback for stdout -- `on_stderr`: Callback for stderr +Whether the process was killed successfully @@ -421,299 +604,116 @@ Resizes a PTY process (changes the number of columns and rows in the terminal). -## AsyncProcessHandle - -```python -class AsyncProcessHandle() -``` - -Class representing a process. It provides methods for waiting and killing the process. - - -#### pid - -```python -@property -def pid() -``` - -Get the process ID. - - -#### stdout - -```python -@property -def stdout() -``` - -Stdout of the process. - - -#### stderr - -```python -@property -def stderr() -``` - -Stderr of the process. - - -#### error - -```python -@property -def error() -``` - -Error message of the process. It is `None` if the process is still running. - - -#### exit\_code - -```python -@property -def exit_code() -``` - -Exit code of the process. It is `None` if the process is still running. - - -#### disconnect - -```python -async def disconnect() -> None -``` - -Disconnects from the process. It does not kill the process. It only stops receiving events from the process. - - -#### wait - -```python -async def wait() -> ProcessResult -``` - -Waits for the process to finish and returns the result. - -If the process exits with a non-zero exit code, it throws a `ProcessExitException`. - -**Returns**: - -Process result - - -#### kill - -```python -async def kill() -> bool -``` - -Kills the process. - -**Returns**: - -Whether the process was killed successfully - - - - - - -## AsyncWatchHandle - -```python -class AsyncWatchHandle() -``` - -Class representing the watch operation. It provides method to stop the watch operation. - - -#### stop - -```python -async def stop() -``` - -Stop watching the directory. - - - - -## Filesystem - -```python -class Filesystem() -``` - -Manager for interacting with the filesystem in the sandbox. - - -#### read +## Process ```python -async def read(path: str, - format: Literal["text", "bytes", "stream"] = "text", - user: Username = "user", - request_timeout: Optional[float] = None) +class Process() ``` -Reads a whole file content and returns it in requested format (text by default). - -:param path: Path to the file -:param format: Format of the file content -:param user: Run the operation as this user -:param request_timeout: Timeout for the request -:return File content in requested format - +Manager for starting and interacting with processes in the sandbox. -#### write +#### list ```python -async def write(path: str, - data: Union[str, bytes, IO], - user: Username = "user", - request_timeout: Optional[float] = None) -> EntryInfo +async def list(request_timeout: Optional[float] = None) -> List[ProcessInfo] ``` -Writes content to a file on the path. - -When writing to a file that doesn't exist, the file will get created. -When writing to a file that already exists, the file will get overwritten. -When writing to a file that's in a directory that doesn't exist, the directory will get created. +Lists all running processes. **Arguments**: -- `path`: Path to the file -- `data`: Data to write to the file -- `user`: Run the operation as this user -- `request_timeout`: Timeout for the request +- `request_timeout`: Request timeout **Returns**: -Information about the written file +List of running processes -#### list +#### kill ```python -async def list(path: str, - user: Username = "user", - request_timeout: Optional[float] = None) -> List[EntryInfo] +async def kill(pid: int, request_timeout: Optional[float] = None) -> bool ``` -Lists entries in a directory. +Kills a process. **Arguments**: -- `path`: Path to the directory -- `user`: Run the operation as this user -- `request_timeout`: Timeout for the request +- `pid`: Process ID to connect to. You can get the list of processes using `sandbox.commands.list()`. +- `request_timeout`: Request timeout **Returns**: -List of entries in the directory - - -#### exists - -```python -async def exists(path: str, - user: Username = "user", - request_timeout: Optional[float] = None) -> bool -``` - -Checks if a file or a directory exists. - -:param path: Path to a file or a directory -:param user Run the operation as this user -:param request_timeout Timeout for the request - - - -#### remove - -```python -async def remove(path: str, - user: Username = "user", - request_timeout: Optional[float] = None) -> None -``` - -Removes a file or a directory. - -**Arguments**: - -- `path`: Path to a file or a directory -- `user`: Run the operation as this user -- `request_timeout`: Timeout for the request +`True` if the process was killed, `False` if the process was not found -#### rename +#### send\_stdin ```python -async def rename(old_path: str, - new_path: str, - user: Username = "user", - request_timeout: Optional[float] = None) -> EntryInfo +async def send_stdin(pid: int, + data: str, + request_timeout: Optional[float] = None) -> None ``` -Renames a file or directory from one path to another. - -:param old_path Path to the file or directory to move -:param new_path Path to move the file or directory to -:param user Run the operation as this user -:param request_timeout Timeout for the request +Sends data to the stdin of a process. -:return: Information about the renamed file or directory +:param pid Process ID to send data to. You can get the list of processes using `sandbox.commands.list()`. +:param data: Data to send to the process +:param request_timeout: Request timeout -#### make\_dir +#### run ```python -async def make_dir(path: str, - user: Username = "user", - request_timeout: Optional[float] = None) -> bool +async def run(cmd: str, + background: Union[bool, None] = None, + envs: Optional[Dict[str, str]] = None, + user: Username = "user", + cwd: Optional[str] = None, + on_stdout: Optional[OutputHandler[Stdout]] = None, + on_stderr: Optional[OutputHandler[Stderr]] = None, + timeout: Optional[float] = 60, + request_timeout: Optional[float] = None) ``` -Creates a new directory and all directories along the way if needed on the specified path. - -**Arguments**: - -- `path`: Path to a new directory. For example '/dirA/dirB' when creating 'dirB'. -- `user`: Run the operation as this user -- `request_timeout`: Timeout for the request +Starts a new process and depending on the `background` parameter, waits for the process to finish or not. -**Returns**: +:param cmd Command to execute +:param background: + If `True`, the function will return a `ProcessHandle` object that can be used to interact with the process. + If `False`, the function will wait for the process to finish and return a `ProcessResult` object. +:param envs: Environment variables +:param user: User to run the process as +:param cwd: Working directory +:param on_stdout: Callback for stdout +:param on_stderr: Callback for stderr +:param timeout: Timeout for the maximum time the process is allowed to run +:param request_timeout: Timeout for the request +:return: `ProcessHandle` if `background` is `True`, `ProcessResult` if `background` is `False` -True if the directory was created, False if the directory already exists -#### watch\_dir +#### connect ```python -async def watch_dir(path: str, - on_event: OutputHandler[FilesystemEvent], - on_exit: Optional[OutputHandler[Exception]] = None, - user: Username = "user", - request_timeout: Optional[float] = None, - timeout: Optional[float] = 60) -> AsyncWatchHandle +async def connect( + pid: int, + timeout: Optional[float] = 60, + request_timeout: Optional[float] = None, + on_stdout: Optional[OutputHandler[Stdout]] = None, + on_stderr: Optional[OutputHandler[Stderr]] = None +) -> AsyncProcessHandle ``` -Watches directory for filesystem events. +Connects to an existing process. **Arguments**: -- `path`: Path to a directory that will be watched -- `on_event`: Callback that will be called on each event -- `on_exit`: Callback that will be called when the watch is closed -- `user`: Run the operation as this user -- `request_timeout`: Timeout for the request -- `timeout`: Timeout for the watch, after which the watch will be closed - -**Returns**: - -Watcher handle +- `pid`: Process ID to connect to. You can get the list of processes using `sandbox.commands.list()`. +- `timeout`: Timeout for the connection +- `request_timeout`: Request timeout +- `on_stdout`: Callback for stdout +- `on_stderr`: Callback for stderr diff --git a/apps/web/src/app/(docs)/docs/api-reference/python-sdk/v0.17.1/sandbox_sync/page.mdx b/apps/web/src/app/(docs)/docs/api-reference/python-sdk/v0.17.1/sandbox_sync/page.mdx index 6d406eecf..fff09d92d 100644 --- a/apps/web/src/app/(docs)/docs/api-reference/python-sdk/v0.17.1/sandbox_sync/page.mdx +++ b/apps/web/src/app/(docs)/docs/api-reference/python-sdk/v0.17.1/sandbox_sync/page.mdx @@ -1,6 +1,210 @@ +## WatchHandle + +```python +class WatchHandle() +``` + +Handle for watching filesystem events. It is used to iterate over the events in the watched directory. + + +#### stop + +```python +def stop() +``` + +Stop watching the directory. After you stop the watcher you won't be able to get the events anymore. + + +#### get\_new\_events + +```python +def get_new_events() -> List[FilesystemEvent] +``` + +Get the latest events that have occurred in the watched directory since the last call, or from the beginning of the watching, up to now. + + + + +## Filesystem + +```python +class Filesystem() +``` + +Manager for interacting with the filesystem in the sandbox. + + +#### read + +```python +def read(path: str, + format: Literal["text", "bytes", "stream"] = "text", + user: Username = "user", + request_timeout: Optional[float] = None) +``` + +Reads a whole file content and returns it in requested format (text by default). + +:param path: Path to the file +:param format: Format of the file content +:param user: Run the operation as this user +:param request_timeout: Timeout for the request +:return File content in requested format + + + +#### write + +```python +def write(path: str, + data: Union[str, bytes, IO], + user: Username = "user", + request_timeout: Optional[float] = None) -> EntryInfo +``` + +Writes content to a file on the path. + +When writing to a file that doesn't exist, the file will get created. +When writing to a file that already exists, the file will get overwritten. +When writing to a file that's in a directory that doesn't exist, the directory will get created. + +**Arguments**: + +- `path`: Path to the file +- `data`: Data to write to the file +- `user`: Run the operation as this user +- `request_timeout`: Timeout for the request + +**Returns**: + +Information about the written file + + +#### list + +```python +def list(path: str, + user: Username = "user", + request_timeout: Optional[float] = None) -> List[EntryInfo] +``` + +Lists entries in a directory. + +**Arguments**: + +- `path`: Path to the directory +- `user`: Run the operation as this user +- `request_timeout`: Timeout for the request + +**Returns**: + +List of entries in the directory + + +#### exists + +```python +def exists(path: str, + user: Username = "user", + request_timeout: Optional[float] = None) -> bool +``` + +Checks if a file or a directory exists. + +:param path: Path to a file or a directory +:param user Run the operation as this user +:param request_timeout Timeout for the request + + + +#### remove + +```python +def remove(path: str, + user: Username = "user", + request_timeout: Optional[float] = None) -> None +``` + +Removes a file or a directory. + +**Arguments**: + +- `path`: Path to a file or a directory +- `user`: Run the operation as this user +- `request_timeout`: Timeout for the request + + +#### rename + +```python +def rename(old_path: str, + new_path: str, + user: Username = "user", + request_timeout: Optional[float] = None) -> EntryInfo +``` + +Renames a file or directory from one path to another. + +:param old_path Path to the file or directory to move +:param new_path Path to move the file or directory to +:param user Run the operation as this user +:param request_timeout Timeout for the request + +:return: Information about the renamed file or directory + + + +#### make\_dir + +```python +def make_dir(path: str, + user: Username = "user", + request_timeout: Optional[float] = None) -> bool +``` + +Creates a new directory and all directories along the way if needed on the specified path. + +**Arguments**: + +- `path`: Path to a new directory. For example '/dirA/dirB' when creating 'dirB'. +- `user`: Run the operation as this user +- `request_timeout`: Timeout for the request + +**Returns**: + +True if the directory was created, False if the directory already exists + + +#### watch\_dir + +```python +def watch_dir(path: str, + user: Username = "user", + request_timeout: Optional[float] = None) -> WatchHandle +``` + +Watches directory for filesystem events. + +To get events, use the `get_new_events` method on the returned handle. + +**Arguments**: + +- `path`: Path to a directory that will be watched +- `user`: Run the operation as this user +- `request_timeout`: Timeout for the request + +**Returns**: + +Watcher handle + + + + ## Sandbox @@ -198,108 +402,69 @@ If you try to set the timeout to a period, which exceeds the maximum limit, the -## Process +## ProcessHandle ```python -class Process() +class ProcessHandle() ``` +Class representing a process. It provides methods for waiting and killing the process. +It is also used to iterate over the process output. -#### list + +#### pid ```python -def list(request_timeout: Optional[float] = None) -> List[ProcessInfo] +@property +def pid() ``` -Lists all running processes. +Get the process ID. -**Arguments**: -- `request_timeout`: Request timeout +#### disconnect -**Returns**: +```python +def disconnect() -> None +``` -List of running processes +Disconnect from the process. It does not kill the process. It only stops receiving events from the process. -#### kill +#### wait ```python -def kill(pid: int, request_timeout: Optional[float] = None) -> bool +def wait(on_pty: Optional[Callable[[PtyOutput], None]] = None, + on_stdout: Optional[Callable[[str], None]] = None, + on_stderr: Optional[Callable[[str], None]] = None) -> ProcessResult ``` -Kills a process. +Waits for the process to finish and returns the result. + +If the process exits with a non-zero exit code, it throws a `ProcessExitException`. **Arguments**: -- `pid`: Process ID to connect to. You can get the list of processes using `sandbox.commands.list()`. -- `request_timeout`: Request timeout +- `on_pty`: Callback for pty output +- `on_stdout`: Callback for stdout output +- `on_stderr`: Callback for stderr output **Returns**: -`True` if the process was killed, `False` if the process was not found +Process result -#### send\_stdin +#### kill ```python -def send_stdin(pid: int, data: str, request_timeout: Optional[float] = None) +def kill() -> bool ``` -Sends data to the stdin of a process. +Kills the process. -:param pid Process ID to send data to. You can get the list of processes using `sandbox.commands.list()`. -:param data: Data to send to the process -:param request_timeout: Request timeout +**Returns**: - - -#### run - -```python -def run(cmd: str, - background: Union[bool, None] = None, - envs: Optional[Dict[str, str]] = None, - user: Username = "user", - cwd: Optional[str] = None, - on_stdout: Optional[Callable[[str], None]] = None, - on_stderr: Optional[Callable[[str], None]] = None, - timeout: Optional[float] = 60, - request_timeout: Optional[float] = None) -``` - -Starts a new process and depending on the `background` parameter, waits for the process to finish or not. - -:param cmd Command to execute -:param background: - If `True`, the function will return a `ProcessHandle` object that can be used to interact with the process. - If `False`, the function will wait for the process to finish and return a `ProcessResult` object. -:param envs: Environment variables -:param user: User to run the process as -:param cwd: Working directory -:param on_stdout: Callback for stdout -:param on_stderr: Callback for stderr -:param timeout: Timeout for the maximum time the process is allowed to run -:param request_timeout: Timeout for the request -:return: `ProcessHandle` if `background` is `True`, `ProcessResult` if `background` is `False` - - - -#### connect - -```python -def connect(pid: int, - timeout: Optional[float] = 60, - request_timeout: Optional[float] = None) -``` - -Connects to an existing process. - -**Arguments**: - -- `pid`: Process ID to connect to. You can get the list of processes using `sandbox.commands.list()`. -- `timeout`: Timeout for the connection -- `request_timeout`: Request timeout +Whether the process was killed successfully @@ -394,271 +559,106 @@ Resizes a PTY process (changes the number of columns and rows in the terminal). -## ProcessHandle - -```python -class ProcessHandle() -``` - -Class representing a process. It provides methods for waiting and killing the process. -It is also used to iterate over the process output. - - -#### pid - -```python -@property -def pid() -``` - -Get the process ID. - - -#### disconnect +## Process ```python -def disconnect() -> None +class Process() ``` -Disconnect from the process. It does not kill the process. It only stops receiving events from the process. - -#### wait +#### list ```python -def wait(on_pty: Optional[Callable[[PtyOutput], None]] = None, - on_stdout: Optional[Callable[[str], None]] = None, - on_stderr: Optional[Callable[[str], None]] = None) -> ProcessResult +def list(request_timeout: Optional[float] = None) -> List[ProcessInfo] ``` -Waits for the process to finish and returns the result. - -If the process exits with a non-zero exit code, it throws a `ProcessExitException`. +Lists all running processes. **Arguments**: -- `on_pty`: Callback for pty output -- `on_stdout`: Callback for stdout output -- `on_stderr`: Callback for stderr output +- `request_timeout`: Request timeout **Returns**: -Process result +List of running processes #### kill ```python -def kill() -> bool -``` - -Kills the process. - -**Returns**: - -Whether the process was killed successfully - - - - -## WatchHandle - -```python -class WatchHandle() -``` - -Handle for watching filesystem events. It is used to iterate over the events in the watched directory. - - -#### stop - -```python -def stop() -``` - -Stop watching the directory. After you stop the watcher you won't be able to get the events anymore. - - -#### get\_new\_events - -```python -def get_new_events() -> List[FilesystemEvent] -``` - -Get the latest events that have occurred in the watched directory since the last call, or from the beginning of the watching, up to now. - - - - -## Filesystem - -```python -class Filesystem() -``` - -Manager for interacting with the filesystem in the sandbox. - - -#### read - -```python -def read(path: str, - format: Literal["text", "bytes", "stream"] = "text", - user: Username = "user", - request_timeout: Optional[float] = None) -``` - -Reads a whole file content and returns it in requested format (text by default). - -:param path: Path to the file -:param format: Format of the file content -:param user: Run the operation as this user -:param request_timeout: Timeout for the request -:return File content in requested format - - - -#### write - -```python -def write(path: str, - data: Union[str, bytes, IO], - user: Username = "user", - request_timeout: Optional[float] = None) -> EntryInfo -``` - -Writes content to a file on the path. - -When writing to a file that doesn't exist, the file will get created. -When writing to a file that already exists, the file will get overwritten. -When writing to a file that's in a directory that doesn't exist, the directory will get created. - -**Arguments**: - -- `path`: Path to the file -- `data`: Data to write to the file -- `user`: Run the operation as this user -- `request_timeout`: Timeout for the request - -**Returns**: - -Information about the written file - - -#### list - -```python -def list(path: str, - user: Username = "user", - request_timeout: Optional[float] = None) -> List[EntryInfo] +def kill(pid: int, request_timeout: Optional[float] = None) -> bool ``` -Lists entries in a directory. +Kills a process. **Arguments**: -- `path`: Path to the directory -- `user`: Run the operation as this user -- `request_timeout`: Timeout for the request +- `pid`: Process ID to connect to. You can get the list of processes using `sandbox.commands.list()`. +- `request_timeout`: Request timeout **Returns**: -List of entries in the directory - - -#### exists - -```python -def exists(path: str, - user: Username = "user", - request_timeout: Optional[float] = None) -> bool -``` - -Checks if a file or a directory exists. - -:param path: Path to a file or a directory -:param user Run the operation as this user -:param request_timeout Timeout for the request - - - -#### remove - -```python -def remove(path: str, - user: Username = "user", - request_timeout: Optional[float] = None) -> None -``` - -Removes a file or a directory. - -**Arguments**: - -- `path`: Path to a file or a directory -- `user`: Run the operation as this user -- `request_timeout`: Timeout for the request +`True` if the process was killed, `False` if the process was not found -#### rename +#### send\_stdin ```python -def rename(old_path: str, - new_path: str, - user: Username = "user", - request_timeout: Optional[float] = None) -> EntryInfo +def send_stdin(pid: int, data: str, request_timeout: Optional[float] = None) ``` -Renames a file or directory from one path to another. - -:param old_path Path to the file or directory to move -:param new_path Path to move the file or directory to -:param user Run the operation as this user -:param request_timeout Timeout for the request +Sends data to the stdin of a process. -:return: Information about the renamed file or directory +:param pid Process ID to send data to. You can get the list of processes using `sandbox.commands.list()`. +:param data: Data to send to the process +:param request_timeout: Request timeout -#### make\_dir +#### run ```python -def make_dir(path: str, - user: Username = "user", - request_timeout: Optional[float] = None) -> bool +def run(cmd: str, + background: Union[bool, None] = None, + envs: Optional[Dict[str, str]] = None, + user: Username = "user", + cwd: Optional[str] = None, + on_stdout: Optional[Callable[[str], None]] = None, + on_stderr: Optional[Callable[[str], None]] = None, + timeout: Optional[float] = 60, + request_timeout: Optional[float] = None) ``` -Creates a new directory and all directories along the way if needed on the specified path. - -**Arguments**: - -- `path`: Path to a new directory. For example '/dirA/dirB' when creating 'dirB'. -- `user`: Run the operation as this user -- `request_timeout`: Timeout for the request +Starts a new process and depending on the `background` parameter, waits for the process to finish or not. -**Returns**: +:param cmd Command to execute +:param background: + If `True`, the function will return a `ProcessHandle` object that can be used to interact with the process. + If `False`, the function will wait for the process to finish and return a `ProcessResult` object. +:param envs: Environment variables +:param user: User to run the process as +:param cwd: Working directory +:param on_stdout: Callback for stdout +:param on_stderr: Callback for stderr +:param timeout: Timeout for the maximum time the process is allowed to run +:param request_timeout: Timeout for the request +:return: `ProcessHandle` if `background` is `True`, `ProcessResult` if `background` is `False` -True if the directory was created, False if the directory already exists -#### watch\_dir +#### connect ```python -def watch_dir(path: str, - user: Username = "user", - request_timeout: Optional[float] = None) -> WatchHandle +def connect(pid: int, + timeout: Optional[float] = 60, + request_timeout: Optional[float] = None) ``` -Watches directory for filesystem events. - -To get events, use the `get_new_events` method on the returned handle. +Connects to an existing process. **Arguments**: -- `path`: Path to a directory that will be watched -- `user`: Run the operation as this user -- `request_timeout`: Timeout for the request - -**Returns**: - -Watcher handle +- `pid`: Process ID to connect to. You can get the list of processes using `sandbox.commands.list()`. +- `timeout`: Timeout for the connection +- `request_timeout`: Request timeout diff --git a/package.json b/package.json index a4efbf54e..a8fe38d5a 100644 --- a/package.json +++ b/package.json @@ -7,7 +7,8 @@ "test": "pnpm test --recursive --if-present", "dev:web": "pnpm --prefix apps/web run dev", "rm-node-modules": "find . -name 'node_modules' -type d -prune -exec rm -rf '{}' +", - "pnpm-install-hack": "cd packages/js-sdk && sed -i '' 's/\"version\": \".*\"/\"version\": \"9.9.9\"/g' package.json && cd ../.. && pnpm i && git checkout -- packages/js-sdk/package.json" + "pnpm-install-hack": "cd packages/js-sdk && sed -i '' 's/\"version\": \".*\"/\"version\": \"9.9.9\"/g' package.json && cd ../.. && pnpm i && git checkout -- packages/js-sdk/package.json", + "generate-api-reference": "pnpm --recursive run generate-api-reference --if-present" }, "packageManager": "pnpm@8.7.6", "dependencies": { diff --git a/packages/cli/package.json b/packages/cli/package.json index 48f6e2232..c03f98e91 100644 --- a/packages/cli/package.json +++ b/packages/cli/package.json @@ -25,7 +25,8 @@ "dev": "tsup --watch", "test": "pnpm build && cd testground/demo-basic && ../../dist/index.js template build", "check-deps": "knip", - "update-deps": "ncu -u && pnpm i" + "update-deps": "ncu -u && pnpm i", + "generate-api-reference": "./scripts/generate_api_ref.sh" }, "devDependencies": { "@types/command-exists": "^1.2.3", diff --git a/packages/js-sdk/package.json b/packages/js-sdk/package.json index 2d52b242f..7d99515b7 100644 --- a/packages/js-sdk/package.json +++ b/packages/js-sdk/package.json @@ -30,6 +30,7 @@ "test": "vitest run", "generate": "openapi-typescript ../../spec/openapi.yml -x api_key --support-array-length --alphabetize --output src/api/schema.gen.ts", "generate-envd-api": "openapi-typescript ../../spec/envd/envd.yaml -x api_key --support-array-length --alphabetize --output src/envd/schema.gen.ts", + "generate-api-reference": "./scripts/generate_api_ref.sh", "check-deps": "knip", "update-deps": "ncu -u && pnpm i", "postPublish": "./scripts/post-publish.sh || true", diff --git a/packages/python-sdk/package.json b/packages/python-sdk/package.json index bc0a1b465..8aaef2f05 100644 --- a/packages/python-sdk/package.json +++ b/packages/python-sdk/package.json @@ -7,6 +7,7 @@ "test": "poetry run pytest -n 4 --verbose -x", "postVersion": "poetry version $(pnpm pkg get version --workspaces=false | tr -d \\\")", "postPublish": "poetry build && poetry config pypi-token.pypi ${PYPI_TOKEN} && poetry publish --skip-existing", - "pretest": "poetry install" + "pretest": "poetry install", + "generate-api-reference": "./scripts/generate_api_ref.sh" } -} \ No newline at end of file +}