Folder

Folder pydantic-model

Bases: BaseModel

A class representing a folder in the Rowan API.

Attributes:

Name	Type	Description
uuid	str	UUID of the folder
name	str | None	name of the folder
parent_uuid	str | None	UUID of the parent folder
notes	str	folder notes
starred	bool	whether the folder is starred
public	bool	whether the folder is public
created_at	datetime | None	date and time the folder was created

Fields:

• uuid (str)
• name (str | None)
• parent_uuid (str | None)
• notes (str)
• starred (bool)
• public (bool)
• created_at (datetime | None)

fetch_latest

fetch_latest(in_place: bool = False) -> Self

Fetch the latest folder data from the API.

This method refreshes the folder object with the latest data from the API.

Parameters:

Name	Type	Description	Default
in_place	bool	whether to update the current instance in-place	False

Returns:

Type	Description
Self	updated instance (self)

Raises:

Type	Description
HTTPStatusError	API request fails

update

update(name: str | None = None, parent_uuid: str | None = None, notes: str | None = None, starred: bool | None = None, public: bool | None = None) -> Self

Update a folder.

Parameters:

Name	Type	Description	Default
name	str | None	new name of the folder	None
parent_uuid	str | None	UUID of the new parent folder	None
notes	str | None	description of the folder	None
starred	bool | None	whether the folder is starred	None
public	bool | None	whether the folder is public	None

Returns:

Type	Description
Self	updated folder object

delete

delete() -> None

Delete the folder and all its contents.

This is a destructive action, it will delete all the folders and workflows that are inside this folder.

Raises:

Type	Description
HTTPStatusError	request to the API fails

print_folder_tree

print_folder_tree(max_depth: int = 10, show_uuids: bool = False) -> None

Retrieves a folder tree from the API.

Parameters:

Name	Type	Description	Default
max_depth	int	maximum depth of the folder tree	10
show_uuids	bool	whether to show the UUIDs of the folders	False

Raises:

Type	Description
HTTPStatusError	API request fails

children

children(size: int = 100) -> list[Folder]

List all child folders directly inside this folder.

Parameters:

Name	Type	Description	Default
size	int	maximum number of child folders to return	100

Returns:

Type	Description
list[Folder]	list of child Folder objects

Raises:

Type	Description
HTTPStatusError	API request fails

workflows

workflows(size: int = 100) -> list[Workflow]

List all workflows directly inside this folder.

Parameters:

Name	Type	Description	Default
size	int	maximum number of workflows to return	100

Returns:

Type	Description
list[Workflow]	list of Workflow objects

Raises:

Type	Description
HTTPStatusError	API request fails

contents

contents(size: int = 100) -> list[Folder | Workflow]

List everything directly inside this folder, both child folders and workflows.

Folders come first, followed by workflows. For a single type, use children or workflows.

Parameters:

Name	Type	Description	Default
size	int	maximum number of items of each type to return	100

Returns:

Type	Description
list[Folder | Workflow]	list of Folder and Workflow objects

Raises:

Type	Description
HTTPStatusError	API request fails

parent

parent() -> Folder | None

Retrieve the parent folder, or None if this is a root folder.

Returns:

Type	Description
Folder | None	parent Folder, or None if there is no parent

Raises:

Type	Description
HTTPStatusError	API request fails

retrieve_folder

retrieve_folder(uuid: str) -> Folder

Retrieves a folder from the API by UUID. Folder UUID can be found in the folder's URL.

Parameters:

Name	Type	Description	Default
uuid	str	UUID of the folder to retrieve	required

Returns:

Type	Description
Folder	folder object representing the retrieved folder

Raises:

Type	Description
HTTPStatusError	API request fails

list_folders

list_folders(parent_uuid: str | None = None, name_contains: str | None = None, public: bool | None = None, starred: bool | None = None, page: int = 0, size: int = 10) -> list[Folder]

Retrieve a list of folders based on the specified criteria.

If no parent_uuid is given and a project is active (via set_project or rowan.project_uuid), lists folders rooted at that project's root folder.

Parameters:

Name	Type	Description	Default
parent_uuid	str | None	UUID of the parent folder to filter by	None
name_contains	str | None	substring to search for in folder names	None
public	bool | None	filter folders by their public status	None
starred	bool | None	filter folders by their starred status	None
page	int	pagination parameter to specify the page number	0
size	int	pagination parameter to specify the number of items per page	10

Returns:

Type	Description
list[Folder]	list of Folder objects that match the search criteria

Raises:

Type	Description
HTTPStatusError	request to the API fails

create_folder

create_folder(name: str, parent_uuid: str | None = None, notes: str = '', starred: bool = False, public: bool = False) -> Folder

Create a new folder.

If no parent_uuid is given and a project is active (via set_project or rowan.project_uuid), the folder is created inside that project's root folder.

Parameters:

Name	Type	Description	Default
name	str	name of the folder	required
parent_uuid	str | None	UUID of the parent folder	None
notes	str	description of the folder	''
starred	bool	whether the folder is starred	False
public	bool	whether the folder is public	False

Returns:

Type	Description
Folder	newly created folder

root_folder

root_folder() -> Folder

Get the root folder of the active project.

The root folder is the top of the folder tree you navigate and store workflows in. Use the active project set via set_project (or rowan.project_uuid), falling back to the default project.

Examples:

root = rowan.root_folder()
for child in root.children():
    print(child.name)
batch = root / "CDK2" / "docking"

Returns:

Type	Description
Folder	root Folder of the active or default project

Raises:

Type	Description
HTTPStatusError	API request fails

get_folder

get_folder(path: str, create: bool = True) -> Folder

Get a folder by name or nested path within the default project.

This is the easiest way to get a folder to use as a location for calculations. By default, any missing folders along the path are created automatically.

Examples:

folder = rowan.get_folder("CDK2/docking/batch_1")
workflow = rowan.submit_docking_workflow(..., folder_uuid=folder.uuid)

Parameters:

Name	Type	Description	Default
path	str	folder name or /-separated path, e.g. "project/subdir/run1"	required
create	bool	create missing folders; otherwise raise ValueError if any segment is not found	True

Returns:

Type	Description
Folder	deepest Folder in the path

Raises:

Type	Description
ValueError	path is empty, or create=False and a folder is not found

print_folder_tree

print_folder_tree(uuid: str, max_depth: int = 10, show_uuids: bool = False) -> None

Retrieves a folder tree from the API.

Parameters:

Name	Type	Description	Default
uuid	str	UUID of the root of the folder tree	required
max_depth	int	maximum depth of the folder tree	10
show_uuids	bool	whether to show the UUIDs of the folders	False

Raises:

Type	Description
HTTPStatusError	API request fails