File Browser¶
file_browser(initial_path: Union[str, Path] = '', filetypes: Optional[Sequence[str]] = None, selection_mode: Literal['file', 'directory'] = 'file', multiple: bool = True, restrict_navigation: bool = False, *, limit: Optional[int] = None, label: str = '', on_change: Optional[Callable[[Sequence[FileBrowserFileInfo]], None]] = None, ignore_empty_dirs: bool = False)
Bases: UIElement[list[TypedFileBrowserFileInfo], Sequence[FileBrowserFileInfo]]
File browser for browsing and selecting server-side files. This element supports local files, S3, GCS, and Azure.
Examples:
Selecting multiple files:
file_browser = mo.ui.file_browser(
initial_path=Path("path/to/dir"), multiple=True
)
# Access the selected file path(s):
file_browser.path(index=0) # returns a Path object
# Get name of selected file(s)
file_browser.name(index=0)
Connecting to an S3 (or GCS, Azure) bucket:
from cloudpathlib import S3Path
file_browser = mo.ui.file_browser(
initial_path=S3Path("s3://my-bucket/folder/")
)
# Access the selected file path(s):
file_browser.path(index=0) # returns a S3Path object
# Read the contents of the selected file(s):
file_browser.path(index=0).read_text()
Using with client credentials:
from cloudpathlib import GSClient, GSPath
# Create a client with credentials
gs_client = GSClient("storage_credentials.json", project="my-project")
# Create a path with the client
cloudpath = GSPath("gs://my-bucket/folder", client=gs_client)
# Use the path with file_browser
file_browser = mo.ui.file_browser(initial_path=cloudpath)
| ATTRIBUTE | DESCRIPTION |
|---|---|
value |
A sequence of file paths representing selected files.
TYPE:
|
| PARAMETER | DESCRIPTION |
|---|---|
initial_path
|
Starting directory. Defaults to current working directory. If a string, it will be interpreted as a local path. If a Path, it will be interpreted as a local path. If a CloudPath (from cloudpathlib), such as S3Path, GCSPath, or AzurePath, files will be loaded from the respective cloud storage bucket. If a CloudPath with a client is provided, that client will be used for all operations. |
filetypes
|
The file types to display in each directory; for example, filetypes=[".txt", ".csv"]. If None, all files are displayed. Defaults to None. |
selection_mode
|
Either "file" or "directory". Defaults to "file".
TYPE:
|
multiple
|
If True, allow the user to select multiple files. Defaults to True.
TYPE:
|
restrict_navigation
|
If True, prevent the user from navigating any level above the given path. Defaults to False.
TYPE:
|
ignore_empty_dirs
|
If True, hide directories that contain no files (recursively). Directories are scanned up to 100 levels deep to prevent stack overflow from deeply nested structures. Directory symlinks are skipped during traversal to prevent infinite loops. Filetype filtering is applied recursively and is case-insensitive. This may impact performance for large directory trees. Defaults to False.
TYPE:
|
limit
|
Maximum number of files to display. If None (default), automatically chooses 50 for cloud storage (S3, GCS, Azure) or 10000 for local filesystems. Set explicitly to override defaults.
TYPE:
|
label
|
Markdown label for the element. Defaults to "".
TYPE:
|
on_change
|
Optional callback to run when this element's value changes. Defaults to None. |
Convert an HTML object with templated text into a UI element.
This method lets you create custom UI elements that are represented by arbitrary HTML.
Example
user_info = mo.md(
'''
- What's your name?: {name}
- When were you born?: {birthday}
'''
).batch(name=mo.ui.text(), birthday=mo.ui.date())
In this example, user_info is a UI Element whose output is markdown
and whose value is a dict with keys 'name' and 'birthday'
(and values equal to the values of their corresponding elements).
| PARAMETER | DESCRIPTION |
|---|---|
elements
|
the UI elements to interpolate into the HTML template.
TYPE:
|
Create a callout containing this HTML element.
A callout wraps your HTML element in a raised box, emphasizing its
importance. You can style the callout for different situations with the
kind argument.
Examples:
form(label: str = '', *, bordered: bool = True, loading: bool = False, submit_button_label: str = 'Submit', submit_button_tooltip: Optional[str] = None, submit_button_disabled: bool = False, clear_on_submit: bool = False, show_clear_button: bool = False, clear_button_label: str = 'Clear', clear_button_tooltip: Optional[str] = None, validate: Optional[Callable[[Optional[JSONType]], Optional[str]]] = None, on_change: Optional[Callable[[Optional[T]], None]] = None) -> form[S, T]
Create a submittable form out of this UIElement.
Creates a form that gates submission of a UIElement's value until a submit button is clicked.
The form's value is the value of the underlying element from the last submission.
Examples:
Convert any UIElement into a form:
Combine with HTML.batch to create a form made out of multiple UIElements:
form = (
mo.ui.md(
'''
**Enter your prompt.**
{prompt}
**Choose a random seed.**
{seed}
'''
)
.batch(
prompt=mo.ui.text_area(),
seed=mo.ui.number(),
)
.form()
)
| PARAMETER | DESCRIPTION |
|---|---|
label
|
A text label for the form.
TYPE:
|
bordered
|
Whether the form should have a border.
TYPE:
|
loading
|
Whether the form should be in a loading state.
TYPE:
|
submit_button_label
|
The label of the submit button.
TYPE:
|
submit_button_tooltip
|
The tooltip of the submit button. |
submit_button_disabled
|
Whether the submit button should be disabled.
TYPE:
|
clear_on_submit
|
Whether the form should clear its contents after submitting.
TYPE:
|
show_clear_button
|
Whether the form should show a clear button.
TYPE:
|
clear_button_label
|
The label of the clear button.
TYPE:
|
clear_button_tooltip
|
The tooltip of the clear button. |
validate
|
A function that takes the form's value and returns an error message if invalid,
or
TYPE:
|
on_change
|
Optional callback to run when this element's value changes. Defaults to None. |
classmethod
¶
from_args(data: dict[str, int], args: InitializationArgs[S, T], memo: dict[int, Any] | None = None, basis: UIElement[S, T] | None = None) -> UIElement[S, T]