Skip to content

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.
Show JSON schema: 
{
  "description": "A class representing a folder in the Rowan API.\n\n:ivar uuid: UUID of the folder.\n:ivar name: Name of the folder.\n:ivar parent_uuid: UUID of the parent folder.\n:ivar notes: Folder notes.\n:ivar starred: Whether the folder is starred.\n:ivar public: Whether the folder is public.\n:ivar created_at: Date and time the folder was created.",
  "properties": {
    "uuid": {
      "title": "Uuid",
      "type": "string"
    },
    "name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Name"
    },
    "parent_uuid": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Parent Uuid"
    },
    "notes": {
      "default": "",
      "title": "Notes",
      "type": "string"
    },
    "starred": {
      "default": false,
      "title": "Starred",
      "type": "boolean"
    },
    "public": {
      "default": false,
      "title": "Public",
      "type": "boolean"
    },
    "created_at": {
      "anyOf": [
        {
          "format": "date-time",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Created At"
    }
  },
  "required": [
    "uuid"
  ],
  "title": "Folder",
  "type": "object"
}

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
HTTPError

If the 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
requests.HTTPError

if the 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
HTTPError

If the 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
HTTPError

If the 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
HTTPError

If the 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 :func:children or :func: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
HTTPError

If the 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
HTTPError

If the 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
HTTPError

If the 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 :func: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
requests.HTTPError

if the 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 :func: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 :func:set_project (or rowan.project_uuid), falling back to the default project.

Example::

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
HTTPError

If the 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.

Example::

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

If True (default), create missing folders. If False, raise ValueError if any segment is not found.

 True

Returns:

Type Description
Folder

Deepest :class:Folder in the path.

Raises:

Type Description
ValueError

If the 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
HTTPError

If the API request fails.