Working with Projects
=====================

In Agora every piece of data lives inside a *project*. Each user automatically
has a personal **My Agora** project. Administrators can create additional
shared projects.

Get all projects
----------------

.. code-block:: python

   projects = agora.get_projects()
   for p in projects:
       print(f'{p.id:4d}  {p.display_name}')

Get a project by ID
-------------------

.. code-block:: python

   project = agora.get_project(2)
   print(project.display_name)

Get the personal "My Agora" project
------------------------------------

.. code-block:: python

   myagora = agora.get_myagora()

Get the root folder of a project
---------------------------------

.. code-block:: python

   project     = agora.get_project(2)
   root_folder = project.get_root_folder()

Get all exams in a project
--------------------------

.. code-block:: python

   exams = project.get_exams()
   for exam in exams:
       print(exam.name)

Filter exams by name
~~~~~~~~~~~~~~~~~~~~

.. code-block:: python

   exams = project.get_exams(filters={'name': 'Wrist'})

Create a project
----------------

.. code-block:: python

   new_project = agora.create_project('My New Project', description='Created via API')

Get or create a project
------------------------

Use this helper to avoid duplicate project creation in automation scripts:

.. code-block:: python

   project = agora.get_or_create_project('Automation Results')

Copy settings from an existing project
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: python

   new_project = agora.create_project(
       'Cloned Project',
       copy_from_id=2,   # copies members, tasks and hosts
   )

Empty the trash
---------------

.. code-block:: python

   project.empty_trash()