gitbot package

Submodules

gitbot.github_issues_bot module

class gitbot.github_issues_bot.Issue(url, comments_url, labels, state_open, title, body, number, reponame)

Bases: object

Class representing an issue on GitHub. It contains information relevant to labelling of the issue, but not all the information that GitHub provides.

static parse(json_response, repository)

Create an issue from GitHub API response.

Usage example:
>>> issue_json = json.loads('''{
...    "url": "https://api.github.com/repos/somethingsomething",
...    "comments_url": "https://api.github.com/repos/somethingsomething/comments",
...    "labels":[
...       {
...           "id": 208045946,
...           "url": "https://api.github.com/repos/somethingsomething/labels/bug",
...           "name": "bug",
...           "color": "f29513",
...           "default": true
...       }
...    ],
...    "body": "This is a body of the issue.",
...    "title": "This is a title.",
...    "number": 666
... }''')
>>> issue  = Issue.parse(issue_json, "somethingsomething")
>>> issue.body
'This is a body of the issue.'
>>> issue.title
'This is a title.'
>>> issue.number
666
>>> len(issue.labels)
1
>>> issue.url
'https://api.github.com/repos/somethingsomething'
>>> issue.comments_url
'https://api.github.com/repos/somethingsomething/comments'

>>> issue_json = json.loads('''{
...    "url": "https://api.github.com/repos/somethingsomething",
...    "comment": "this is an invalid json"
... }''')
>>> issue = Issue.parse(issue_json, "something")
>>> issue is None
True
Parameters:
  • json_response (json) – GitHub API response encoded in a json object. It must contain a single object, not a list of objects. For details, refer to Issues.
  • repository (str) – Name of the repository the issue belongs to, e.g. username/somerepo.
Returns:Issue instance if parsing succeeded, None otherwise.
Return type:Issue
class gitbot.github_issues_bot.Rule(regex, label)

Bases: object

Class representing a Gitbot labelling rule.

It contains two pieces of information - a regexp pattern and the associated label.

It also provides methods for ease of work with rules.

check_fits(text)

Check if this rule fits (applies to) the given text.

Usage example:
>>> rule = Rule("[Hh]ello", "welcoming")
>>> rule.check_fits("hello dev!")
'welcoming'
>>> rule.check_fits("Hello, how are you?")
'welcoming'
>>> rule.check_fits("Hell no.") is None
True
Parameters:text (str) – Text for which to test the rule.
Returns:Label name if the rule does fit, or None if it does not fit.
Return type:str
static parse(text)

Create a new Rule instance from a line of text.

Usage example:
>>> rule = Rule.parse("some\s+regexp=>new label")
>>> rule is not None
True
>>> rule.regex.pattern
'some\\s+regexp'
>>> rule.label
'new label'
Parameters:text (str) – String defining the Rule instance. The syntax is “regexp=>label_name”.
Returns:Returns a new instance of Rule if parsing succeeded, None otherwise.
Return type:Rule
gitbot.github_issues_bot.apply_labels(issue, labels)

Apply given labels to an issue on GitHub.

Parameters:
  • issue (Issue) – Issue object to which to apply labels.
  • labels (list of str) – List of labels to apply.
Returns:

None
gitbot.github_issues_bot.fetch_comments(issue, session=None)

Fetches text of all comments of the given issue.

Parameters:
  • issue (Issue) – Issue for which to fetch comments.
  • session (requests.Session, optional) – If supplied, use this session object instead of the internal.
Returns:

Returns list of strings - contents of comments.
Return type:

list of str
gitbot.github_issues_bot.fetch_issues(repository, state, session=None)

Fetches all issues in a repository with the given state. :param repository: :param state: :return: List of Issue objects.

Parameters:
  • repository (str) – Name of the repository to fetch.
  • state (str) – Issues in which states to fetch. Allowed string values: all, open, closed.
  • session (requests.Session, optional) – If supplied, use this session object instead of the internal.
Returns:

Returns list of Issue objects parsed from the given repository.
Return type:

list of Issue
gitbot.github_issues_bot.init_rules_logic(filename)

Initialize global rules store with rules defined in a file. This method does not handle file existence, permissions etc. That is the responsibility of its caller.

Parameters:filename (str) – Path to file containing the rules.
Returns:None.
gitbot.github_issues_bot.init_session(token, session=None)

Create an authorized session object for GitHub.

Parameters:
  • token (str) – Authentication token for GitHub. See Tokens.
  • session (requests.Session, optional) – A session object to be used, if supplied, this method simply sets the internal session object to the one passed in this parameter (instead of creating a new one).

Returns: None, the session is set internally via a member variable.

gitbot.github_issues_bot.process_issue(issue, default_label='', process_comments=True, process_title=True, remove_current=False, predef_comments=None, predef_rules=None, dry_run=False)

Handle logic of rule matching and labelling of a given issue, including sending a request to GitHub.

For details about parameters, see process_issues().

Usage example:
  • Create issue and expect a label to be assigned to it.
    >>> test_issue = Issue("<url>", "<url>",
...    [{'name':'labelA'}, {'name':'labelB'}], True, "Test issue",
...    "Test body. My cool string.", 42, "example/foo")
>>> labels = process_issue(test_issue,
...    predef_rules=[Rule(r'cool', 'cool label')], predef_comments=['comment'], dry_run=True)
>>> 'cool label' in labels
True
>>> sorted(labels)
['cool label', 'labelA', 'labelB']
  • Create issue and expect a label NOT to be assigned to it, only the original labels should stay.
    >>> test_issue = Issue("<url>", "<url>",
...    [{'name':'labelA'}, {'name':'labelB'}], True, "Test issue",
...    "Test body. My cool string.", 42, "example/foo")
>>> labels = process_issue(test_issue,
...   predef_rules=[Rule(r'hot', 'hot label')], predef_comments=['comment'], dry_run=True)
>>> 'hot label' in labels
False
>>> sorted(labels)
['labelA', 'labelB']
Parameters:
  • issue (Issue) – Issue to be processed.
  • default_label (str) –
  • process_comments (bool) –
  • process_title (bool) –
  • remove_current (bool) –
  • predef_comments (list of str, optional) – If set, comments are not fetched from the issue, but instead the ones supplied through this parameter are used. Useful for testing, not much else.
  • predef_rules (list of Rule, optional) – If set, rules are not loaded from the rules file, but instead the ones supplied through this parameter are used. Useful for testing, not much else.
  • dry_run (bool, optional) – If true, issue is processed, but nothing is actually pushed to GitHub.
Returns:

Returns list of labels newly associated with the issue.
Return type:

list of str
gitbot.github_issues_bot.process_issues(token, repository, default_label='', skip_labelled=True, process_comments=True, process_closed_issues=False, process_title=True, remove_current=False)

Main handling logic of app. Processes issues in a given repository with the given settings. Parameters correspond to command-line arguments.

Parameters:
  • token (str) – GitHub authentication token. Refer to Issues.
  • repository (str) – Name of the repository being processed. E.g. foobar/repo
  • default_label (str, optional) – Label that should be applied to an issue if no rule fits. If empty or None, no default label is applied.
  • skip_labelled (bool) – If true, issues that are already labelled will be skipped.
  • process_comments (bool) – If true, comments on the issue will be processed as well. Otherwise, only body of the issue is.
  • process_closed_issues (bool) – If true, issues that are marked as closed will be processed as well as open ones.
  • process_title (bool) – If true, title of the issue will be processed as well as its body.
  • remove_current (bool) – If true, all current labels on issues will be removed and replaced by newly added ones.
Returns:

None.
gitbot.github_issues_bot.read_auth(filename, section, key)

Reads a key from a section in a configuration ini-formatted file.

Parameters:
  • filename (str) – Name of the authentication file.
  • section (str) – Section to read from, i.e. [section] in the auth file.
  • key (str) – Particular key inside the given section to read.
Returns:

Value read from the file.
Return type:

str

gitbot.web_listener module

gitbot.web_listener.handle_callback()

Handle GitHub issue callback. :return:

gitbot.web_listener.parse_repo(json_data)

Parse repository full name from request json. :param json_data: :return:

gitbot.web_listener.should_process_issue(json_data)

Check request json to see if reported issue should be processed. :param json_data: :return:

Module contents