Skip to content
This repository was archived by the owner on May 22, 2021. It is now read-only.

Commit ab727a1

Browse files
sigmavirus24sigmavirus24
committed
Update Milestones for consistency and improve docs
1 parent 5659877 commit ab727a1

File tree

1 file changed

+86
-43
lines changed

1 file changed

+86
-43
lines changed

‎github3/issues/milestone.py

+86-43
Original file line numberDiff line numberDiff line change
@@ -11,50 +11,79 @@
1111

1212

1313
class Milestone(GitHubCore):
14-
"""The :class:`Milestone <Milestone>` object. This is a small class to
15-
handle information about milestones on repositories and issues.
14+
"""Representation of milestones on a repository.
1615
1716
See also: http://developer.github.com/v3/issues/milestones/
18-
"""
19-
def _update_attributes(self, milestone):
20-
self._api = self._get_attribute(milestone, 'url', '')
2117
22-
#: Identifying number associated with milestone.
23-
self.number = self._get_attribute(milestone, 'number')
18+
This object has the following attributes:
19+
20+
.. attribute:: closed_issues_count
21+
22+
The number of closed issues in this milestone.
23+
24+
.. attribute:: created_at
25+
26+
A :class:`~datetime.datetime` object representing the date and time
27+
when this milestone was created.
28+
29+
.. attribute:: creator
30+
31+
If present, a :class:`~github3.users.ShortUser` representing the user
32+
who created this milestone.
33+
34+
.. attribute:: description
2435
25-
#: State of the milestone, e.g., open or closed.
26-
self.state = self._get_attribute(milestone, 'state')
36+
The written description of this milestone and its purpose.
2737
28-
#: Title of the milestone, e.g., 0.2.
29-
self.title = self._get_attribute(milestone, 'title')
38+
.. attribute:: due_on
3039
31-
#: Description of this milestone.
32-
self.description = self._get_attribute(milestone, 'description')
40+
If set, a :class:`~datetime.datetime` object representing the date and
41+
time when this milestone is due.
3342
34-
#: :class:`User <github3.users.User>` object representing the creator
35-
#: of the milestone.
36-
self.creator = self._class_attribute(
37-
milestone, 'creator', users.ShortUser, self
38-
)
43+
.. attribute:: id
3944
40-
#: Number of issues associated with this milestone which are still
41-
#: open.
42-
self.open_issues = self._get_attribute(milestone, 'open_issues')
45+
The unique identifier of this milestone in GitHub.
4346
44-
#: The number of closed issues associated with this milestone.
45-
self.closed_issues = self._get_attribute(milestone, 'closed_issues')
47+
.. attribute:: number
4648
47-
#: datetime object representing when the milestone was created.
48-
self.created_at = self._strptime_attribute(milestone, 'created_at')
49+
The repository-local numeric identifier of this milestone. This starts
50+
at 1 like issues.
4951
50-
#: datetime representing when this milestone is due.
51-
self.due_on = self._strptime_attribute(milestone, 'due_on')
52+
.. attribute:: open_issues_count
5253
53-
#: datetime object representing when the milestone was updated.
54-
self.updated_at = self._strptime_attribute(milestone, 'updated_at')
54+
The number of open issues still in this milestone.
5555
56-
#: string representing the milestone's ID.
57-
self.id = self._get_attribute(milestone, 'id')
56+
.. attribute:: state
57+
58+
The state of this milestone, e.g., ``'open'`` or ``'closed'``.
59+
60+
.. attribute:: title
61+
62+
The title of this milestone.
63+
64+
.. attribute:: updated_at
65+
66+
A :class:`~datetime.datetime` object representing the date and time
67+
when this milestone was last updated.
68+
"""
69+
70+
def _update_attributes(self, milestone):
71+
self._api = milestone['url']
72+
self.closed_issues_count = milestone['closed_issues']
73+
self.closed_issues = self.closed_issues_count
74+
self.created_at = self._strptime(milestone['created_at'])
75+
self.creator = milestone['creator']
76+
if self.creator:
77+
self.creator = users.ShortUser(self.creator, self)
78+
self.description = milestone['description']
79+
self.due_on = self._strptime(milestone['due_on'])
80+
self.id = milestone['id']
81+
self.number = milestone['number']
82+
self.open_issues_count = milestone['open_issues']
83+
self.open_issues = self.open_issues_count
84+
self.state = milestone['state']
85+
self.title = milestone['title']
86+
self.updated_at = self._strptime(milestone['updated_at'])
5887

5988
def _repr(self):
6089
return '<Milestone [{0}]>'.format(self)
@@ -66,21 +95,29 @@ def __str__(self):
6695
def delete(self):
6796
"""Delete this milestone.
6897
69-
:returns: bool
98+
:returns:
99+
True if successful, False otherwise
100+
:rtype:
101+
bool
70102
"""
71103
return self._boolean(self._delete(self._api), 204, 404)
72104

73105
def labels(self, number=-1, etag=None):
74-
r"""Iterate over the labels of every associated issue.
106+
"""Iterate over the labels of every associated issue.
75107
76108
.. versionchanged:: 0.9
77109
78110
Add etag parameter.
79111
80-
:param int number: (optional), number of labels to return. Default: -1
81-
returns all available labels.
82-
:param str etag: (optional), ETag header from a previous response
83-
:returns: generator of :class:`Label <github3.issues.label.Label>`\ s
112+
:param int number:
113+
(optional), number of labels to return. Default: -1 returns all
114+
available labels.
115+
:param str etag:
116+
(optional), ETag header from a previous response
117+
:returns:
118+
generator of labels
119+
:rtype:
120+
:class:`~github3.issues.label.Label`
84121
"""
85122
url = self._build_url('labels', base_url=self._api)
86123
return self._iter(int(number), url, Label, etag=etag)
@@ -92,12 +129,18 @@ def update(self, title=None, state=None, description=None, due_on=None):
92129
All parameters are optional, but it makes no sense to omit all of them
93130
at once.
94131
95-
:param str title: (optional), new title of the milestone
96-
:param str state: (optional), ('open', 'closed')
97-
:param str description: (optional)
98-
:param str due_on: (optional), ISO 8601 time format:
99-
YYYY-MM-DDTHH:MM:SSZ
100-
:returns: bool
132+
:param str title:
133+
(optional), new title of the milestone
134+
:param str state:
135+
(optional), ('open', 'closed')
136+
:param str description:
137+
(optional)
138+
:param str due_on:
139+
(optional), ISO 8601 time format: YYYY-MM-DDTHH:MM:SSZ
140+
:returns:
141+
True if successful, False otherwise
142+
:rtype:
143+
bool
101144
"""
102145
data = {'title': title, 'state': state,
103146
'description': description, 'due_on': due_on}

0 commit comments

Comments
 (0)