omfit-github 2020.12.2.22.59
omfit_github
Requires Python: >=3.6

**GITHUB** files used as part of the OMFIT project: https://omfit.io/

Provides:
=========
* get_gh_remote_org_repo_branch
* on_latest_gh_commit
* convert_gh_time_str_datetime
* get_OMFIT_GitHub_token
* set_OMFIT_GitHub_token
* OMFITgithub_paged_fetcher
* get_pull_request_number
* get_git_branch_info
* post_comment_to_github
* find_gh_comments
* delete_matching_gh_comments
* edit_github_comment
* set_gh_status

Requires:
=========
* numpy>=1.12
* requests>=2.20
* uncertainties>=3
* omfit_commonclasses==2020.12.2.22.59

Authors:
=========
https://omfit.io/contributors.html

Documentation:
==============
get_gh_remote_org_repo_branch
-----------------------------

    Looks up local name for upstream remote repo, GitHub org, repository name, and current branch
    Like calling get_git_branch_info with `no_pr_lookup=True`

    :return: tuple containing 4 strings
        remote, org, repository, branch
    

on_latest_gh_commit
-------------------

    Returns true if the current working commit is the same as the github latest commit for this branch.
    

convert_gh_time_str_datetime
----------------------------

    Convert a GitHub (gh) time string to a datetime object

    :param t: A time string like
    

get_OMFIT_GitHub_token
----------------------

    :param token: string or None
        Token for accessing GitHub
        None triggers attempt to decrypt from $GHUSER@token.github.com credential file
        Must be set up in advance with set_OMFIT_GitHub_token() function

    :return: GitHub token
    

set_OMFIT_GitHub_token
----------------------

    :param token: 40 chars Token string to be encrypted in $GHUSER@token.github.com credential file
    

OMFITgithub_paged_fetcher
-------------------------

    Interact with GitHub via the GitHub api: https://developer.github.com/v3/
    to fetch data from a path
    https://api.github.com/repos/{org}/{repo}/{path}
    that has paged results
    

get_pull_request_number
-----------------------

    Gets the pull request number associated for the current git branch if there is an open pull request.

    Passes parameters org, destination_org, branch, and repository to get_git_branch_info().

    :param return_info: bool [optional]
        Return a dictionary of information instead of just the pull request number

    :return: int, dict-like, or None
        Pull request number if one can be found, otherwise None.
        If return_info: dictionary returned by OMFITgithub_paged_fetcher with 'org' key added. Contains 'number', too.
    

get_git_branch_info
-------------------

    Looks up local name for upstream remote repo, GitHub org, repository name, current branch, & open pull request info
    All parameters are optional and should only be provided if trying to override some results

    :param remote: string [optional]
        Local name for the upstream remote.
        If None, attempts to lookup with method based on git rev-parse.

    :param org: string [optional]
        The organization that the repo is under, like 'gafusion'.
        If None, attempts to lookup with method based on git rev-parse.
        Falls back to gafusion on failure.

    :param destination_org: string [optional]
        Used for cross-fork pull requests: specify the destination org of the pull request.
        The pull request actually exists on this org, but it is not where the source branch lives.
        If None it defaults to same as org

    :param repository: string [optional]
        The name of the repo on GitHub.
        If None, attempts to lookup with method based on git rev-parse.
        Falls back to OMFIT-source on failure.

    :param branch: string [optional]
        Local/remote name for the current branch
        NOTE: there is an assumption that the local and upstream branches have same name

    :param url: string [optional]
        Provided mainly for testing.
        Overrides the url that would be returned by `git config --get remote.origin.url`.

    :param omfit_fallback: bool
        Default org and repository are gafusion and OMFIT-source instead of None and None in case of failed lookup.

    :param no_pr_lookup: bool
        Improve speed by skipping lookup of pull request number

    :param return_pr_destination_org: bool
        If an open pull request is found, changes remote, org, repository,
        and branch to match the destination side of the pull request.
        If there is no pull request or this flag is False,
        remote/org/repo/branch will correspond to the source.

    :param server: string [optional]
        The server of the remote - usually github.com, but could also be something like vali.gat.com.

    :return: tuple containing 4 strings and a dict, with elements to be replaced with None for lookup failure
        remote (str), org (str), repository (str), branch (str), pull_request_info (dict)
    

post_comment_to_github
----------------------

    Posts a comment to a thread (issue or pull request) on GitHub.
    Requires setup of a GitHub token to work.

    This function may be tested on fork='gafusion', thread=3208 if needed.

    Setup::

        1. Create a GitHub token with the "repo" (Full control of private repositories) box checked.
           See https://github.com/settings/tokens .

        2. [Optional] Safely store the token to disk by executing:
              set_OMFIT_GitHub_token(token)
           This step allows you to skip passing the token to the function every time.

    :param thread: int [optional]
        The number of the issue or pull request within the fork of interest
        If not supplied, the current branch name will be used to search for open pull requests on GitHub.

    :param comment: string
        The comment to be posted

    :param org: string [optional]
        Leave this as gafusion to post to the main OMFIT repo.
        Enter something else to post on a fork.

    :param fork: string [optional]
        Redundant with org. Use org instead. Fork is provided for backwards compatibility

    :param repository: string [optional]
        The name of the repo on GitHub.
        If None, attempts to lookup with method based on git rev-parse.
        Falls back to OMFIT-source on failure.
        You should probably leave this as None unless you're doing some testing,
        in which case you may use the regression_notifications repository under gafusion.

    :param token: string or None
        Token for accessing GitHub
        None triggers attempt to decrypt from $GHUSER@token.github.com credential file
        Must be set up in advance with set_OMFIT_GitHub_token() function

    :return: response instance
        As generated by requests.
        It should have a `status_code` attribute, which is normally int(201) for successful
        GitHub posts and probably 4xx for failures.
    

find_gh_comments
----------------

    Looks up comments on a GitHub issue or pull request and searches for ones with body text matching `contains`

    :param thread: int or None
        int: issue or pull request number
        None: look up pull request number based on active branch name. Only works if a pull request is open.

    :param contains: string or list of strings
        Check for these strings within comment body text. They all must be present.

    :param user: bool or string [optional]
        True: only consider comments made with the current username (looks up GITHUB_username from MainSettings)
        string: only comments made by the specified username.

    :param id_only: bool
        Return only the comment ID numbers instead of full dictionary of comment info

    :param org: string [optional] The organization that the repo is under, like 'gafusion'.
        If None, attempts to lookup with method based on git rev-parse.
        Falls back to gafusion on failure.

    :param repository: string [optional]
        The name of the repo on GitHub. If None, attempts to lookup with
        method based on git rev-parse. Falls back to OMFIT-source on failure.

    :param \**kw: keywords to pass to OMFITgithub_paged_fetcher

    :return: list of dicts (id_only=False) or list of ints (id_only=True)
    

delete_matching_gh_comments
---------------------------

    Deletes GitHub comments that contain a keyword. Use CAREFULLY for clearing obsolete automatic test report posts.

    :param thread: int [optional]
        Supply issue or comment number or leave as None to look up an open pull request # for the active branch

    :param keyword: string or list of strings
        CAREFUL! All comments which match this string will be deleted.
        If a list is provided, every substring in the list must be present in a comment.

    :param test: bool
        Report which comments would be deleted without actually deleting them.

    :param token: string or None
        Token for accessing GitHub
        None triggers attempt to decrypt from $GHUSER@token.github.com credential file
        Must be set up in advance with set_OMFIT_GitHub_token() function

    :param org: string [optional] The organization that the repo is under, like 'gafusion'.
        If None, attempts to lookup with method based on git rev-parse.
        Falls back to gafusion on failure.

    :param repository: string [optional]
        The name of the repo on GitHub.
        If None, attempts to lookup with method based on git rev-parse.
        Falls back to OMFIT-source on failure.

    :param quiet: bool
        Suppress print output

    :param exclude: list of strings [optional]
        List of CIDs to exclude / protect from deletion. In addition to actual CIDs, the special value of 'latest' is
        accepted and will trigger lookup of the matching comment with the most recent timestamp. Its CID will replace
        'latest' in the list.

    :param exclude_contain: list of strings [optional]
        If provided, comments must contain all of the strings listed in their body in order to qualify for exclusion.

    :param match_username: bool or string [optional]
        True: Only delete comments that match the current username.
        string: Only delete comments that match the specified username.

    :param \**kw: keywords to pass to find_gh_comments()

    :return: list of responses from requests (test=False) or list of dicts with comment info (test=True)
        response instances should have a `status_code` attribute, which is normally int(201) for successful
        GitHub posts and probably 4xx for failures.
    

edit_github_comment
-------------------

    Edits GitHub comments to update automatically generated information, such as regression test reports.

    :param comment_mark: str or None
        None: edit top comment.
        str: Search for a comment (not including top comment) containing comment_mark as a substring.

    :param new_content: str
        New content to put into the comment

        Special cases:
        If content is None and mode == 'replace_between':
            Separate close separator and close separator present in target: del between 1st open sep and next close sep
            Separate close separator & close separator not present in target: del everything after 1st open sep
            All same separator & one instance present in target: delete it and everything after
            All same separator & multiple instances present: delete the first two and everything in between.
        If content is None and mode != 'replace_between', raise ValueError
        If None and mode == 'replace_between', but separator not in comment, abort but do not raise.

    :param separator: str or list of strings
        Substring that separates parts that should be edited from parts that should not be edited.
        `'---'` will put a horizontal rule in GitHub comments, which seems like a good idea for this application.
        If this is a list, the first and second elements will be used as the opening and closing separators to allow for
        different open/close around a section.

    :param mode: str
        Replacement behavior.
        'replace': Replace entire comment. Ignores separator.
        'append': Append new content to old comment. Places separator between old and new if separator is supplied.
           Closes with another separator if separate open/close separators are supplied; otherwise just places one
           separator between the original content and the addition.
        'replace_between: Replace between first & second appearances of separator (or between open & close separators).
           Raises ValueError if separator is not specified.
           Acts like mode == 'append' if separator (or opening separator) is not already present in target comment.
        other: raises ValueError

    :param thread: int [optional]
        Issue or pull request number. Looked up automatically if not provided

    :param org: str [optional]
        GitHub org. Determined automatically if not supplied.

    :param repository: str [optional]
        GitHub repository. Determined automatically if not supplied.

    :param token: str
        Token for accessing GitHub. Decrypted automatically if not supplied.

    :return: response instance or None
        None if aborted before attempting to post, otherwise response instance, which is an object generated
        by the requests module. It should have a `status_code` attribute which is 2** on success
        and often 4** for failures.
    

set_gh_status
-------------

    Updates the status of a pull request on GitHub. Appears as green check mark or red X at the end of the thread.

    :param org: string [optional] The organization that the repo is under, like 'gafusion'.
        If None, attempts to lookup with method based on git rev-parse.
        Falls back to gafusion on failure.

    :param destination_org: string [optional]
        Used for cross-fork pull requests: specify the destination org of the pull request.
        The pull request actually exists on this org, but it is not where the source branch lives.
        Passed to get_pull_request_number when determining whether a pull request is open.
        Defines first org to check.
        If None it defaults to same as org

    :param repository: string [optional]
        The name of the repo on GitHub.
        If None, attempts to lookup with method based on git rev-parse.
        Falls back to OMFIT-source on failure.

    :param commit: commit hash or keyword
        'latest' or 'HEAD~0':
                Look up latest commit. This is appropriate if you have reloaded modules and classes as needed.
        'omfit' or None:
                use commit that was active when OMFIT launched.
                Appropriate if testing classes as loaded during launch and not reloaded since.
        else: treats input as a commit hash and will fail if it is not one.

    :param state: string or bool
        'success' or True: success -> green check
        'failure' or False: problem -> red X
        'pending' -> yellow circle

    :param context: string
        Match the context later to update the status

    :param description: string
        A string with a description of the status. Up to 140 characters. Long strings will be truncated.
        Line breaks, quotes, parentheses, etc. are allowed.

    :param target_url: string
       URL to associate with the status

    :return: response instance s generated by `requests`.
        It should have a `status_code` attribute, which is normally int(201) for successful GitHub posts and probably 4xx for failures.