biosimulators_utils.gh_action package — BioSimulators utils 0.1.154 documentation

# biosimulators_utils.gh_action package

## Submodules

## biosimulators_utils.gh_action.core module

Utilities for GitHub action workflows for reviewing and committing simulators to the BioSimulators registry

Author

  Jonathan Karr <karr@mssm.edu>

Date

  2020-12-08

Copyright

  2020, Center for Reproducible Biomedical Modeling

License

  MIT

class biosimulators_utils.gh_action.core.GitHubAction

  Bases: `abc.ABC`

  A GitHub continuous integration action

  gh_auth

    authorization for GitHub (user and access token

    Type

      `tuple` of `str`

  gh_repo

    owner and name of the repository which triggered the action

    Type

      `str`

  GH_ACTION_RUN_URL = 'https://github.com/{}/actions/runs/{}'
  ISSUE_ASIGNEES_ENDPOINT = 'https://api.github.com/repos/{}/issues/{}/assignees'
  ISSUE_COMMENTS_ENDPOINT = 'https://api.github.com/repos/{}/issues/{}/comments'
  ISSUE_ENDPOINT = 'https://api.github.com/repos/{}/issues/{}'
  ISSUE_LABELS_ENDPOINT = 'https://api.github.com/repos/{}/issues/{}/labels'
  classmethod add_comment_to_issue(issue_number, comment)

    Post a comment to the GitHub issue

    Parameters

      - issue_number (`str`) – issue number

      - comment (`str`) – comment

  classmethod add_error_comment_to_issue(issue_number, comments, raise_error=True)

    Post an error to the GitHub issue

    Parameters

      - issue_number (`str`) – issue number

      - comments (`list` of `Comment`) – comment

      - raise_error (`bool`, optional) – if `True`, raise error

    Raises

      ValueError –

  classmethod add_labels_to_issue(issue_number, labels)

    Add one or more labels to an issue

    Parameters

      - issue_number (`str`) – issue number

      - labels (`list` of `str`) – labels to add to the issue

  classmethod assign_issue(issue_number, users)

    Assign an issue to a list of users

    Parameters

      - issue_number (`str`) – issue number

      - users (`list` of `str`) – GitHub ids of users to assign to issue

  classmethod close_issue(issue_number)

    Close a GitHub issue

    Parameters

      issue_number (`str`) – issue number

  classmethod format_error_comment(comment)

    Format comment to display as error

    Parameters

      comment (`str`) – comment to format as error

    Returns

      formatted comment

    Return type

      `str`

  static get_data_in_issue(issue)

    Get the YAML-structured data in an issue

    Parameters

      issue (`dict`) – properties of the GitHub issue for the submission

    Returns

      YAML-structured data in an issue

    Return type

      `object`

  static get_gh_action_run_id()

    Get the id for the current GitHub action run

    Returns

      GitHub action run id

    Return type

      `str`

  classmethod get_gh_action_run_url()

    Get the URL for a GitHub action run

    Returns

      URL for a GitHub action run

    Return type

      `str`

  static get_gh_auth()

    Get authorization for GitHub

    Returns

      authorization for GitHub (user and access token)

    Return type

      `tuple` of `str`

  static get_gh_repo()

    Get the owner and name of the repository which triggered the action

    Returns

      owner and name of the repository which triggered the action

    Return type

      `str`

  classmethod get_issue(issue_number)

    Get the properties of the GitHub issue for the submission

    Parameters

      issue_number (`str`) – issue number

    Returns

      properties of the GitHub issue for the submission

    Return type

      `dict`

  static get_issue_number()

    Get the number of the issue which triggered the action

    Returns

      issue number

    Return type

      `str`

  classmethod get_labels_for_issue(issue_number)

    Get the labels for an issue

    Parameters

      issue_number (`str`) – issue number

    Returns

      labels

    Return type

      `list` of `str`

  classmethod remove_label_from_issue(issue_number, label)

    Remove a label from an issue

    Parameters

      - issue_number (`str`) – issue number

      - label (`str`) – labels to add to the issue

  classmethod reset_issue_labels(issue_number, labels_to_remove)

    Reset the labels for an issue

    Parameters

      - issue_number (`str`) – issue number

      - labels_to_remove (`list` of `str`) – labels to remove

  abstract run()

class biosimulators_utils.gh_action.core.GitHubActionErrorHandling

  Bases: `object`

  Methods for handing errors in the execution of GitHu actions

  classmethod catch_errors(uncaught_exception_msg_func=None, caught_error_labels=None, uncaught_error_labels=None)

    Generator for a decorator for CI actions that catches errors and reports them as comments to an issue

    Parameters

      - uncaught_exception_msg_func (`types.FunctionType`, optional) – function to calculate error message to display to users

      - caught_error_labels (`list` of `str`, optional) – labels to apply to caught errors

      - uncaught_error_labels (`list` of `str`, optional) – labels to apply to uncaught errors

  get_uncaught_exception_msg()

    Create an error message to display to users for all exceptions not caught during the exception of the `run` method for a GitHub action workflow (exceptions of all types except `GitHubActionCaughtError`)

    Parameters

      exception (`Exception`) – a failure encountered during the exception of the `run` method for the workflow

    Returns

      error message to display to users

    Return type

      `str`

## biosimulators_utils.gh_action.data_model module

Data model for GitHub action workflows

Author

  Jonathan Karr <karr@mssm.edu>

Date

  2020-12-08

Copyright

  2020, Center for Reproducible Biomedical Modeling

License

  MIT

class biosimulators_utils.gh_action.data_model.Comment(text=None, error=None)

  Bases: `object`

  A comment on an issue

  text

    text

    Type

      `str`

  error

    if `True`, format as error

    Type

      `bool`

exception biosimulators_utils.gh_action.data_model.GitHubActionCaughtError

  Bases: `biosimulators_utils.exceptions.BioSimulatorsException`

  An error caught during the execution of a GitHub action