RunDB Class Reference

Public Member Functions
def	__init__ (self, apikey=None, username=None)
def	get_run_info (self, **search_params)
def	get_details (self, run_summary)

Static Public Attributes
str	URL = "https://rundb.belle2.org"
	URL of where the RunDB is hosted.

Protected Member Functions
def	_pagination (self, request)

Protected Attributes
	_session
	session object for connection to the RunDB

Detailed Description

Simple API class to just get run information from the RunDB.

Parameters:
    apikey (str): RunDB API key (see
      `this question <https://questions.belle2.org/question/11145/obtaining-an-access-token-for-rundb-api-2021-version/>`_
      or `this Confluence page <https://confluence.desy.de/x/DZ8CCg>`_ how to get one)
    username (str): DESY username

Definition at line 24 of file rundb.py.

Constructor & Destructor Documentation

__init__()

def __init__	(		self,
			apikey = None,
			username = None
	)

Create an object and setup authentication.

Definition at line 38 of file rundb.py.

    def __init__(self, apikey=None, username=None):
        """Create an object and setup authentication."""
        
        self._session = requests.Session()
        if apikey is None:
            # If no specific username use the local system username
            if username is None:
                username = getpass.getuser()
            # If we don't have an api key use desy username/password
            self._session.auth = (username, getpass.getpass(f"DESY password ({username}): "))
        else:
            # Otherwise use the api key
            self._session.headers.update({'Authorization': f'Bearer {apikey}'})
        # And request json output ...
        self._session.headers.update({'Content-Type': 'application/json'})
 

Member Function Documentation

_pagination()

def _pagination (   self,   request  )

protected

Deal with API pagination of an initial request to the API.

It will return all the objects from all pages lazily requesting new pages
as objects are consumed. Will work for all list requests to the server.

Definition at line 54 of file rundb.py.

    def _pagination(self, request):
        """Deal with API pagination of an initial request to the API.
 
        It will return all the objects from all pages lazily requesting new pages
        as objects are consumed. Will work for all list requests to the server.
        """
        while True:
            # check the return value and raise exception on error
            request.raise_for_status()
            # and otherwise get the json
            result = request.json()
            # and return the objects one by one by yielding objects from the list
            # of results
            yield from result['results']
            # check if there's a next page, if not done
            if result['next'] is None:
                break
            # otherwise continue with the next page
            # yees, global variable ...
            request = self._session.get(result['next'])
 

get_details()

def get_details	(		self,
			run_summary
	)

Return details for a run summary object returned from `get_run_info`
if ``expand`` was not set to True

Parameters:
    run_summary: a run summary object returned from `get_run_info`

Definition at line 103 of file rundb.py.

    def get_details(self, run_summary):
        """
        Return details for a run summary object returned from `get_run_info`
        if ``expand`` was not set to True
 
        Parameters:
            run_summary: a run summary object returned from `get_run_info`
        """
        # Get the url object
        req = self._session.get(run_summary['url'])
        # Raise an exception in case of any error
        req.raise_for_status()
        # And return the json object
        return req.json()

get_run_info()

def get_run_info	(		self,
		**	search_params
	)

Return the run information from the run registry.

All arguments are forwarded to the run registry ``/run/`` method
documented at the following `link <https://rundb.belle2.org/rest/v1/swagger/>`_.
Please check there for up to date documentation, at the time of
this writing the supported arguments are:

  * min_experiment (int)
  * min_run (int)
  * max_experiment (int)
  * max_run (int)
  * min_date (iso8601 date string, e.g. 2020-05-06)
  * max_date (iso8601 date string, e.g. 2020-05-06)
  * all_detectors_running (bool)
  * expand (bool): If true return full run objects, not just a summary
    links to the run objects

If ``expand=False`` you can request the full objects for each run by calling
`get_details` with the returned run summary object as argument.
``expand=False`` is much faster if no further details are needed but
getting the details in a separate step for many many runs will be slow
so depending on how many runs are selected one or the other may be
faster.

Definition at line 75 of file rundb.py.

    def get_run_info(self, **search_params):
        """Return the run information from the run registry.
 
        All arguments are forwarded to the run registry ``/run/`` method
        documented at the following `link <https://rundb.belle2.org/rest/v1/swagger/>`_.
        Please check there for up to date documentation, at the time of
        this writing the supported arguments are:
 
          * min_experiment (int)
          * min_run (int)
          * max_experiment (int)
          * max_run (int)
          * min_date (iso8601 date string, e.g. 2020-05-06)
          * max_date (iso8601 date string, e.g. 2020-05-06)
          * all_detectors_running (bool)
          * expand (bool): If true return full run objects, not just a summary
            links to the run objects
 
        If ``expand=False`` you can request the full objects for each run by calling
        `get_details` with the returned run summary object as argument.
        ``expand=False`` is much faster if no further details are needed but
        getting the details in a separate step for many many runs will be slow
        so depending on how many runs are selected one or the other may be
        faster.
        """
        req = self._session.get(f'{self.URL}/rest/v1/runs/', params=search_params)
        return self._pagination(req)
 

Member Data Documentation

_session

_session

protected

session object for connection to the RunDB

Definition at line 41 of file rundb.py.

URL

str URL = "https://rundb.belle2.org"

static

URL of where the RunDB is hosted.

Definition at line 36 of file rundb.py.

---

The documentation for this class was generated from the following file:

• framework/scripts/rundb.py