Working with Folders
====================

Folders organise data inside a project. They can be nested arbitrarily deep
and support relative-path navigation.

Get the root folder
-------------------

.. code-block:: python

   root_folder = agora.get_myagora().get_root_folder()
   print(f'Root folder ID: {root_folder.id}')

Get a folder by ID
------------------

.. code-block:: python

   folder = agora.get_folder(45)

List sub-folders
----------------

.. code-block:: python

   for f in folder.get_folders():
       print(f.name)

Get a sub-folder by name
------------------------

Returns ``None`` when the folder does not exist.

.. code-block:: python

   my_folder = folder.get_folder('MySubFolder')

Navigate with a relative path
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The path separator is ``/`` and ``..`` is supported:

.. code-block:: python

   target = folder.get_folder('../../data/results')

Create a folder
---------------

Raises an exception if a folder with the same name already exists.

.. code-block:: python

   new_folder = root_folder.create_folder('TestFolder')
   print(f'Created folder with ID {new_folder.id}')

Get or create a folder
-----------------------

Safe to call from automation scripts — returns the existing folder if found.

.. code-block:: python

   folder = root_folder.get_or_create('TestFolder')

Create a nested path in one call
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: python

   from pathlib import Path

   deep_folder = agora.get_or_create_folder(
       Path('Results/2024/Q1'),
       base_folder=root_folder,
   )

List folder contents
--------------------

An *item* can be an exam, series, dataset or a link to another object.

.. code-block:: python

   for item in folder.get_items():
       print(item)

Get all exams in a folder
~~~~~~~~~~~~~~~~~~~~~~~~~

Pass ``recursive=True`` to include exams in sub-folders:

.. code-block:: python

   exams = folder.get_exams(recursive=True)

Get all datasets in a folder
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: python

   datasets = folder.get_datasets(recursive=False)

Get a dataset by name
~~~~~~~~~~~~~~~~~~~~~

Returns ``None`` when not found:

.. code-block:: python

   ds = folder.get_dataset('my_dataset')

Get the folder breadcrumb (path in Agora)
-----------------------------------------

.. code-block:: python

   breadcrumb = folder.get_breadcrumb()
   print(breadcrumb)

Delete a folder
---------------

.. warning::

   Deletion is **recursive** — all items inside the folder are deleted.
   Links are not followed during deletion.

.. code-block:: python

   folder.delete()