iframe-proxy | Sunbelt Computer Software

526 lines (415 loc) · 16.7 KB
# -*- coding: utf-8 -*-
"""Module containing the Issue logic."""
from __future__ import unicode_literals
from json import dumps
from uritemplate import URITemplate
from . import comment
from . import event
from . import label
from . import milestone
from .. import models
from .. import users
from ..decorators import requires_auth
class _Issue(models.GitHubCore):
    """The :class:`Issue <Issue>` object.
    Please see GitHub's `Issue Documentation`_ for more information.
    .. _Issue Documentation:
        http://developer.github.com/v3/issues
    class_name = '_Issue'
    def _update_attributes(self, issue):
        self._api = issue['url']
        self.assignee = issue['assignee']
        if self.assignee:
            self.assignee = users.ShortUser(self.assignee, self)
        self.assignees = issue['assignees']
        if self.assignees:
            self.assignees = [
                users.ShortUser(assignee, self) for assignee in self.assignees
        self.body = issue['body']
        self.closed_at = self._strptime(issue['closed_at'])
        self.comments_count = issue['comments']
        self.comments_url = issue['comments_url']
        self.created_at = self._strptime(issue['created_at'])
        self.events_url = issue['events_url']
        self.html_url = issue['html_url']
        self.id = issue['id']
        self.labels_urlt = URITemplate(issue['labels_url'])
        self.locked = issue['locked']
        self.milestone = issue['milestone']
        if self.milestone:
            self.milestone = milestone.Milestone(self.milestone, self)
        self.number = issue['number']
        self.original_labels = issue['labels']
        if self.original_labels:
            self.original_labels = [
                label.Label(lbl, self) for lbl in self.original_labels
        self.pull_request_urls = issue.get('pull_request')
        self.state = issue['state']
        self.title = issue['title']
        self.updated_at = self._strptime(issue['updated_at'])
        self.user = users.ShortUser(issue['user'], self)
    def _repr(self):
        return '<{class_name} [#{n}]>'.format(
            n=self.number, class_name=self.class_name,
    @requires_auth
    def add_labels(self, *args):
        """Add labels to this issue.
        :param str args:
            (required), names of the labels you wish to add
        :returns:
            list of labels
        :rtype:
            :class:`~github3.issues.label.Label`
        """
        url = self._build_url('labels', base_url=self._api)
        json = self._json(self._post(url, data=args), 200)
        return [label.Label(lbl, self) for lbl in json] if json else []
    @requires_auth
    def assign(self, username):
        """Assign user ``username`` to this issue.
        This is a short cut for :meth:`~github3.issues.issue.Issue.edit`.
        :param str username:
            username of the person to assign this issue to
        :returns:
            True if successful, False, otherwise
        :rtype:
            bool
        """
        if not username:
            return False
        number = self.milestone.number if self.milestone else None
        labels = [str(lbl) for lbl in self.original_labels]
        return self.edit(self.title, self.body, username, self.state, number,
                         labels)
    @requires_auth
    def close(self):
        """Close this issue.
        :returns:
            True if successful, False otherwise
        :rtype:
            bool
        """
        assignee = self.assignee.login if self.assignee else ''
        number = self.milestone.number if self.milestone else None
        labels = [lbl.name for lbl in self.original_labels]
        return self.edit(self.title, self.body, assignee, 'closed',
                         number, labels)
    def comment(self, id_num):
        """Get a single comment by its id.
        The catch here is that id is NOT a simple number to obtain. If
        you were to look at the comments on issue #15 in
        sigmavirus24/Todo.txt-python, the first comment's id is 4150787.
        :param int id_num:
            (required), comment id, see example above
        :returns:
            the comment identified by ``id_num``
        :rtype:
            :class:`~github3.issues.comment.IssueComment`
        """
        json = None
        if int(id_num) > 0:  # Might as well check that it's positive
            base_url, _ = self.url.rsplit('/', 1)
            url = self._build_url('comments', str(id_num),
                                  base_url=base_url)
            json = self._json(self._get(url), 200)
        return self._instance_or_null(comment.IssueComment, json)
    def comments(self, number=-1, sort='', direction='', since=None):
        """Iterate over the comments on this issue.
        :param int number:
            (optional), number of comments to iterate over
            Default: -1 returns all comments
        :param str sort:
            accepted valuees: ('created', 'updated') api-default: created
        :param str direction:
            accepted values: ('asc', 'desc') Ignored without the sort parameter
        :param since:
            (optional), Only issues after this date will be returned. This can
            be a ``datetime`` or an ISO8601 formatted date string, e.g.,
            ``2012-05-20T23:10:27Z``
        :type since:
            datetime or string
        :returns:
            iterator of comments
        :rtype:
            :class:`~github3.issues.comment.IssueComment`
        """
        url = self._build_url('comments', base_url=self._api)
        params = comment.issue_comment_params(sort, direction, since)
        return self._iter(int(number), url, comment.IssueComment, params)
    @requires_auth
    def create_comment(self, body):
        """Create a comment on this issue.
        :param str body:
            (required), comment body
        :returns:
            the created comment
        :rtype:
            :class:`~github3.issues.comment.IssueComment`
        """
        json = None
        if body:
            url = self._build_url('comments', base_url=self._api)
            json = self._json(self._post(url, data={'body': body}),
        return self._instance_or_null(comment.IssueComment, json)
    @requires_auth
    def edit(self, title=None, body=None, assignee=None, state=None,
             milestone=None, labels=None, assignees=None):
        """Edit this issue.
        :param str title:
            title of the issue
        :param str body:
            markdown formatted body (description) of the issue
        :param str assignee:
            login name of user the issue should be assigned to
        :param str state:
            accepted values: ('open', 'closed')
        :param int milestone:
            the NUMBER (not title) of the milestone to assign this to [1]_, or
            0 to remove the milestone
        :param list labels:
            list of labels to apply this to
        :param assignees:
            (optional), login of the users to assign the issue to
        :type assignees:
            list of strings
        :returns:
            True if successful, False otherwise
        :rtype:
            bool
        .. [1] Milestone numbering starts at 1, i.e. the first milestone you
               create is 1, the second is 2, etc.
        """
        json = None
        data = {'title': title, 'body': body, 'assignee': assignee,
                'state': state, 'milestone': milestone, 'labels': labels,
                'assignees': assignees}
        self._remove_none(data)
        if data:
            if 'milestone' in data and data['milestone'] == 0:
                data['milestone'] = None
            json = self._json(self._patch(self._api, data=dumps(data)), 200)
        if json:
            self._update_attributes(json)
            return True
        return False
    def events(self, number=-1):
        """Iterate over events associated with this issue only.
        :param int number:
            (optional), number of events to return. Default: -1 returns all
            events available.
        :returns:
            generator of events on this issues
        :rtype:
            :class:`~github3.issues.event.IssueEvent`
        """
        url = self._build_url('events', base_url=self._api)
        return self._iter(int(number), url, event.IssueEvent)
    def is_closed(self):
        """Check if the issue is closed.
        :returns:
            True if successful, False otherwise
        :rtype:
            bool
        """
        if self.closed_at or (self.state == 'closed'):
            return True
        return False
    def labels(self, number=-1, etag=None):
        """Iterate over the labels associated with this issue.
        :param int number:
            (optional), number of labels to return. Default: -1 returns all
            labels applied to this issue.
        :param str etag:
            (optional), ETag from a previous request to the same endpoint
        :returns:
            generator of labels on this issue
        :rtype:
            :class:`~github3.issues.label.Label`
        """
        url = self._build_url('labels', base_url=self._api)
        return self._iter(int(number), url, label.Label, etag=etag)
    @requires_auth
    def lock(self):
        """Lock an issue.
        :returns:
            True if successful, False otherwise
        :rtype:
            bool
        """
        url = self._build_url('lock', base_url=self._api)
        return self._boolean(self._put(url), 204, 404)
    def pull_request(self):
        """Retrieve the pull request associated with this issue.
        :returns:
            the pull request associated with this issue
        :rtype:
            :class:`~github3.pulls.PullRequest`
        """
        from .. import pulls
        json = None
        pull_request_url = self.pull_request_urls.get('url')
        if pull_request_url:
            json = self._json(self._get(pull_request_url), 200)
        return self._instance_or_null(pulls.PullRequest, json)
    @requires_auth
    def remove_label(self, name):
        """Remove label ``name`` from this issue.
        :param str name:
            (required), name of the label to remove
        :returns:
            list of removed labels
        :rtype:
            :class:`~github3.issues.label.Label`
        """
        url = self._build_url('labels', name, base_url=self._api)
        json = self._json(self._delete(url), 200, 404)
        labels = [label.Label(lbl, self) for lbl in json] if json else []
        return labels
    @requires_auth
    def remove_all_labels(self):
        """Remove all labels from this issue.
        :returns:
            the list of current labels (empty) if successful
        :rtype:
            list
        """
        # Can either send DELETE or [] to remove all labels
        return self.replace_labels([])
    @requires_auth
    def replace_labels(self, labels):
        """Replace all labels on this issue with ``labels``.
        :param list labels:
            label names
        :returns:
            list of labels
        :rtype:
            :class:`~github3.issues.label.Label`
        """
        url = self._build_url('labels', base_url=self._api)
        json = self._json(self._put(url, data=dumps(labels)), 200)
        return [label.Label(lbl, self) for lbl in json] if json else []
    @requires_auth
    def reopen(self):
        """Re-open a closed issue.
        .. note:: This is a short cut to using :meth:`edit`.
        :returns:
            True if successful, False otherwise
        :rtype:
            bool
        """
        assignee = self.assignee.login if self.assignee else ''
        number = self.milestone.number if self.milestone else None
        labels = [str(lbl) for lbl in self.original_labels]
        return self.edit(self.title, self.body, assignee, 'open',
                         number, labels)
    @requires_auth
    def unlock(self):
        """Unlock an issue.
        :returns:
            True if successful, False otherwise
        :rtype:
            bool
        """
        url = self._build_url('lock', base_url=self._api)
        return self._boolean(self._delete(url), 204, 404)
class Issue(_Issue):
    """Object for the full representation of an Issue.
    GitHub's API returns different amounts of information about issues based
    upon how that information is retrieved. This object exists to represent
    the full amount of information returned for a specific issue. For example,
    you would receive this class when calling
    :meth:`~github3.github.GitHub.issue`. To provide a clear
    distinction between the types of issues, github3.py uses different classes
    with different sets of attributes.
    .. versionchanged:: 1.0.0
    This object has all of the same attributes as a
    :class:`~github3.issues.issue.ShortIssue` as well as the following:
    .. attribute:: body_html
        The HTML formatted body of this issue.
    .. attribute:: body_text
        The plain-text formatted body of this issue.
    .. attribute:: closed_by
        If the issue is closed, a :class:`~github3.users.ShortUser`
        representing the user who closed the issue.
    class_name = 'Issue'
    def _update_attributes(self, issue):
        super(Issue, self)._update_attributes(issue)
        self.body_html = issue['body_html']
        self.body_text = issue['body_text']
        self.closed_by = issue['closed_by']
        if self.closed_by:
            self.closed_by = users.ShortUser(self.closed_by, self)
class ShortIssue(_Issue):
    """Object for the shortened representation of an Issue.
    GitHub's API returns different amounts of information about issues based
    upon how that information is retrieved. Often times, when iterating over
    several issues, GitHub will return less information. To provide a clear
    distinction between the types of issues, github3.py uses different classes
    with different sets of attributes.
    .. versionadded:: 1.0.0
    This object has the following attributes:
    .. attribute:: assignee
        .. deprecated:: 1.0.0
            While the API still returns this attribute, it's not as useful in
            the context of multiple assignees.
        If a user is assigned to this issue, then it will be represented as a
        :class:`~github3.users.ShortUser`.
    .. attribute:: assignees
        If users are assigned to this issue, then they will be represented as
        a list of :class:`~github3.users.ShortUser`.
    .. attribute:: body
        The markdown formatted text of the issue as writen by the user who
        opened the issue.
    .. attribute:: closed_at
        If this issue is closed, this will be a :class:`~datetime.datetime`
        object representing the date and time this issue was closed. Otherwise
        it will be ``None``.
    .. attribute:: comments_count
        The number of comments on this issue.
    .. attribute:: comments_url
        The URL to retrieve the comments on this issue from the API.
    .. attribute:: created_at
        A :class:`~datetime.datetime` object representing the date and time
        this issue was created.
    .. attribute:: events_url
        The URL to retrieve the events related to this issue from the API.
    .. attribute:: html_url
        The URL to view this issue in a browser.
    .. attribute:: id
        The unique identifier for this issue in GitHub.
    .. attribute:: labels_urlt
        A :class:`~uritemplate.URITemplate` object that can expand to a URL to
        retrieve the labels on this issue from the API.
    .. attribute:: locked
        A boolean attribute representing whether or not this issue is locked.
    .. attribute:: milestone
        A :class:`~github3.issues.milestone.Milestone` object representing the
        milestone to which this issue was assigned.
    .. attribute:: number
        The number identifying this issue on its parent repository.
    .. attribute:: original_labels
        If any are assigned to this issue, the list of
        :class:`~github3.issues.label.Label` objects representing the labels
        returned by the API for this issue.
    .. attribute:: pull_request_urls
        If present, a dictionary of URLs for retrieving information about the
        associated pull request for this issue.
    .. attribute:: state
        The current state of this issue, e.g., ``'closed'`` or ``'open'``.
    .. attribute:: title
        The title for this issue.
    .. attribute:: updated_at
        A :class:`~datetime.datetime` object representing the date and time
        when this issue was last updated.
    .. attribute:: user
        A :class:`~github3.users.ShortUser` representing the user who opened
        this issue.
    class_name = 'ShortIssue'
    _refresh_to = Issue
Sunbelt Computer Software

PL/B Language Development and Support

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Sunbelt Computer Software

PL/B Language Development and Support

FilesExpand file tree

issue.py

Latest commit

History

issue.py

File metadata and controls
