roboto.domain.files.file_system
Module Contents
FileSystem
The files and directories under one association: a dataset, a device, or the org itself.
A FileSystem holds that association’s directory tree and the operations on it: listing, uploading, downloading, renaming, and deleting files, and creating and renaming directories. Datasets, devices, and orgs each return one as files, files, and files.
Every relative path a method takes or returns is relative to the root of the association’s tree, which files of other associations do not share.
Parameters
association roboto.roboto_client Optional[roboto.file_service Optional[roboto.org_id Optional[str]Properties
FileSystem.association
The dataset, device, or org whose files this object works on.
FileSystem.create_directory()
Create a directory among the association’s files.
Parameters
name strName of the directory to create.
error_if_exists boolIf True, raises an exception if the directory already exists.
parent_path Optional[pathlib.Path of the parent directory. If None, creates the directory at the root of the association’s files.
origination Optional[str]Optional string describing the source or context of the directory creation.
create_intermediate_dirs boolIf True, creates intermediate directories in the path if they don’t exist. If False, requires all parent directories to already exist.
Raises
If the directory already exists and error_if_exists is True.
If the caller lacks permission to create the directory.
If the directory name is invalid or the parent path does not exist (when create_intermediate_dirs is False).
Returns
DirectoryRecord of the created directory.
Usage
from roboto.domain import devices
device = devices.Device.from_id("rover-01")
directory = device.files.create_directory("calib")
print(directory.relative_path)
# calibdirectory = device.files.create_directory(
name="final",
parent_path=pathlib.Path("path/to/deep"),
create_intermediate_dirs=True,
)
print(directory.relative_path)
# path/to/deep/finalFileSystem.create_link()
Put a link to another file at relative_path among the association’s files.
A link lets one file, such as a URDF in the org’s own files, appear in many devices’ files without being copied. It pins one version of its target: passing a File pins that file’s version, and passing a file ID pins the target’s current version. Later versions of the target do not move the link; create the link again at the same path to re-point it, which adds a version to the link unless it already pins that target version. Missing parent directories are created. Downloading the link, or asking it for a signed URL, fetches the pinned version of the target.
Parameters
target Union[roboto.The file to link to, or its ID. It must be a file in the same org, not a link or a directory.
relative_path strWhere the link sits, relative to the root of the association’s files.
Returns
The link, whose is_link is True.
Raises
A file or a directory already occupies relative_path. The reverse is refused too: uploading a file to a link’s path is a conflict until the link is deleted.
The target is a link or a directory, is in another org, or does not exist at the version to pin.
The caller cannot edit the association’s files or view the target.
Usage
from roboto.domain import devices, orgs
urdf = orgs.Org.from_id("og_abc123").files.get_file_by_path("urdf/rover/rover.urdf")
device = devices.Device.from_id("rover-01")
link = device.files.create_link(urdf, "urdf/rover.urdf")
link.download(pathlib.Path("/tmp/rover.urdf"))FileSystem.delete_files()
Delete the association’s files that match the given patterns.
Deletes files that match the specified include patterns while excluding those that match exclude patterns. Uses gitignore-style pattern matching for flexible file selection.
Parameters
include_patterns Optional[list[str]]List of gitignore-style patterns for files to include. If None or empty, all files are considered for deletion. An empty list is treated as no filter (all files), not as “include nothing”.
exclude_patterns Optional[list[str]]List of gitignore-style patterns for files to exclude from deletion. Takes precedence over include patterns. If None or empty, no files are excluded.
Raises
Caller lacks permission to delete files.
Return type
Notes
Pattern matching follows gitignore syntax. See https://git-scm.com/docs/gitignore for detailed pattern format documentation.
Usage
from roboto.domain import orgs
org = orgs.Org.from_id("og_abc123")
org.files.delete_files(include_patterns=["**/*.png"], exclude_patterns=["**/back_camera/**"])FileSystem.download_files()
Download the association’s files to a local directory.
Downloads files that match the specified patterns to the given local directory. The files’ directory structure is preserved in the download location. If the output directory doesn’t exist, it will be created. Files are found with list_files(), which does not return links yet, so no link is downloaded; download one with download().
Parameters
out_path pathlib.Local directory path where files should be downloaded.
include_patterns Optional[list[str]]List of gitignore-style patterns for files to include. If None or empty, all files are downloaded. An empty list is treated as no filter (all files), not as “include nothing”.
exclude_patterns Optional[list[str]]List of gitignore-style patterns for files to exclude from download. Takes precedence over include patterns. If None or empty, no files are excluded.
print_progress boolWhether to show a progress bar during download.
Returns
List of tuples containing (FileRecord, local_path) for each downloaded file.
Raises
A selected file’s path resolves outside out_path; nothing is downloaded.
Caller lacks permission to download files.
Notes
Pattern matching follows gitignore syntax. See https://git-scm.com/docs/gitignore for detailed pattern format documentation.
Usage
import pathlib
from roboto.domain import devices
device = devices.Device.from_id("rover-01")
downloaded = device.files.download_files(pathlib.Path("/tmp/rover-01"), include_patterns=["calib/**"])
print(f"Downloaded {len(downloaded)} files")
# Downloaded 2 filesFileSystem.get_file_by_path()
Get a File instance for the association’s file at the specified path.
Parameters
relative_path Union[str, pathlib.Path of the file relative to the root of the association’s files.
version_id Optional[int]Specific version of the file to retrieve. If None, gets the latest version.
Returns
File instance representing the file at the specified path.
Raises
The association has no file at the given path.
Caller lacks permission to access the file.
Usage
from roboto.domain import devices
device = devices.Device.from_id("rover-01")
file = device.files.get_file_by_path("manifest.json")
print(file.file_id)
# fl_xyz789old_file = device.files.get_file_by_path("manifest.json", version_id=1)
print(old_file.version)
# 1FileSystem.list_directories()
Yield every directory among the association’s files, at any depth.
Usage
from roboto.domain import devices
device = devices.Device.from_id("rover-01")
for directory in device.files.list_directories():
print(directory.relative_path)
# calib
# urdfReturn type
FileSystem.list_files()
List the association’s files with optional pattern-based filtering.
Returns all of the association’s files that match the specified include patterns while excluding those that match exclude patterns. Uses gitignore-style pattern matching for flexible file selection.
Parameters
include_patterns Optional[list[str]]List of gitignore-style patterns for files to include. If None or empty, all files are considered. An empty list is treated as no filter (all files), not as “include nothing”.
exclude_patterns Optional[list[str]]List of gitignore-style patterns for files to exclude. Takes precedence over include patterns. If None or empty, no files are excluded.
Yields
File instances that match the specified patterns.
Raises
Caller lacks permission to list files.
Return type
Notes
Pattern matching follows gitignore syntax. See https://git-scm.com/docs/gitignore for detailed pattern format documentation.
Files appear in this list shortly after their upload completes, not instantly.
Usage
from roboto.domain import devices
device = devices.Device.from_id("rover-01")
for file in device.files.list_files():
print(file.relative_path)
# manifest.json
# calib/front_cam.yamlfor file in device.files.list_files(include_patterns=["calib/**"], exclude_patterns=["**/*.bak"]):
print(file.relative_path)
# calib/front_cam.yamlFileSystem.rename_directory()
Rename or move a directory among the association’s files.
Both old_path and new_path are relative to the root of the association’s files. Pass a new_path with fewer path components to move the directory up the tree, or a different leaf name at the same depth to rename in place.
Parameters
old_path strCurrent relative path of the directory (e.g. "logs/session1").
new_path strTarget relative path of the directory (e.g. "session1" to move up one level).
Returns
Updated DirectoryRecord reflecting the new path.
Raises
No directory exists at old_path.
new_path conflicts with an existing node or contains a cycle.
Usage
from roboto.domain import devices
device = devices.Device.from_id("rover-01")
device.files.rename_directory("calib/front", "front_calib")FileSystem.rename_file()
Rename or move a file among the association’s files.
new_path is relative to the root of the association’s files. Pass a path with fewer components to move the file up the tree, a different name at the same depth to rename in place, or a path under a different directory to move sideways.
The file’s storage URI is unchanged; only its relative path changes.
Parameters
file_id strID of the file to rename or move.
new_path strTarget relative path for the file (e.g. "file.bag" to move to the root, or "other_dir/file.bag" to move into an existing directory).
Returns
Updated FileRecord reflecting the new path.
Raises
No file with file_id exists.
new_path conflicts with an existing file, the parent directory does not exist, or the move would create a cycle.
Usage
from roboto.domain import devices
device = devices.Device.from_id("rover-01")
record = device.files.rename_file("fl_xyz789", "manifest.json")
record.relative_path
# 'manifest.json'FileSystem.upload_directory()
Upload all files and directories recursively from the specified directory path.
Use include_patterns and exclude_patterns to control what files and directories are uploaded, and delete_after_upload to clean up your local filesystem after the uploads succeed.
Parameters
directory_path pathlib.Local directory whose contents are uploaded, keeping its layout.
include_patterns Optional[list[str]]gitignore-style patterns for files to include. If None, every file is included.
exclude_patterns Optional[list[str]]gitignore-style patterns for files to exclude. Takes precedence over include_patterns.
delete_after_upload boolIf True, each uploaded local file is deleted once the uploads succeed.
max_batch_size intMaximum number of files per upload transaction.
print_progress boolWhether to display an upload progress bar.
device_id Optional[str]Optional identifier of the device that generated this data.
Return type
Notes
Both pattern lists follow the gitignore pattern format described in https://git-scm.com/docs/gitignore#_pattern_format.
Usage
import pathlib
from roboto.domain import devices
device = devices.Device.from_id("rover-01")
device.files.upload_directory(
pathlib.Path("/path/to/calibration"),
exclude_patterns=["**/*.log"],
)FileSystem.upload_file()
Upload a single file associated with association.
Parameters
file_path pathlib.Local file to upload.
file_destination_path Optional[str]Destination path among the association’s files. Defaults to the file’s own name at the root.
print_progress boolWhether to display an upload progress bar.
device_id Optional[str]Optional identifier of the device that generated this data.
Returns
The uploaded file. Its record is fetched from the platform the first time it is read.
Raises
The upload reported success without reporting a file ID.
Usage
import pathlib
from roboto.domain import devices
device = devices.Device.from_id("rover-01")
device.files.upload_file(pathlib.Path("/path/to/manifest.json"))FileSystem.upload_files()
Upload multiple files associated with association.
Parameters
files collections.Local files to upload.
file_destination_paths collections.Mapping from local path to destination path among the association’s files. Files not in the mapping upload to the root under their own name.
max_batch_size intMaximum number of files per upload transaction.
print_progress boolWhether to display an upload progress bar.
device_id Optional[str]Optional identifier of the device that generated this data.
Returns
Mapping from each uploaded local path to the ID of the file record it created.
Usage
import pathlib
from roboto.domain import devices
device = devices.Device.from_id("rover-01")
file_ids = device.files.upload_files(
[pathlib.Path("/path/to/front_cam.yaml")],
file_destination_paths={pathlib.Path("/path/to/front_cam.yaml"): "calib/front_cam.yaml"},
)
file_ids[pathlib.Path("/path/to/front_cam.yaml")]
# 'fl_0123456789abcdef'