8000 Added missing information to docstrings of commit and stats module · perch/GitPython@2454ae8 · GitHub
[go: up one dir, main page]
Skip to content

Commit 2454ae8

Browse files
ByronByron
committed
Added missing information to docstrings of commit and stats module
1 parent 8496831 commit 2454ae8

File tree

2 files changed

+88
-21
lines changed

2 files changed

+88
-21
lines changed

‎lib/git/commit.py

Lines changed: 56 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -14,38 +14,44 @@
1414
import stats
1515

1616
class Commit(LazyMixin):
17+
"""
18+
Wraps a git Commit object.
19+
20+
This class will act lazily on some of its attributes and will query the
21+
value on demand only if it involves calling the git binary.
22+
"""
1723
def __init__(self, repo, id, tree=None, author=None, authored_date=None,
1824
committer=None, committed_date=None, message=None, parents=None):
1925
"""
20-
Instantiate a new Commit
26+
Instantiate a new Commit. All keyword arguments taking None as default will
27+
be implicitly set if id names a valid sha.
28+
29+
The parameter documentation indicates the type of the argument after a colon ':'.
2130
2231
``id``
23-
is the id of the commit
32+
is the sha id of the commit
2433
25-
``parents``
26-
is a list of commit ids (will be converted into Commit instances)
34+
``parents`` : list( Commit, ... )
35+
is a list of commit ids
2736
28-
``tree``
29-
is the correspdonding tree id (will be converted into a Tree object)
37+
``tree`` : Tree
38+
is the corresponding tree id
3039
31-
``author``
32-
is the author string
40+
``author`` : Actor
41+
is the author string ( will be implicitly converted into an Actor object )
3342
34-
``authored_date``
43+
``authored_date`` : (tm_year, tm_mon, tm_mday, tm_hour, tm_min, tm_sec, tm_wday, tm_yday, tm_isdst )
3544
is the authored DateTime
3645
37-
``committer``
46+
``committer`` : Actor
3847
is the committer string
3948
40-
``committed_date``
49+
``committed_date`` : (tm_year, tm_mon, tm_mday, tm_hour, tm_min, tm_sec, tm_wday, tm_yday, tm_isdst)
4150
is the committed DateTime
4251
43-
``message``
52+
``message`` : string
4453
is the commit message
4554
46-
``parents``
47-
is the list of the parents of the commit
48-
4955
Returns
5056
git.Commit
5157
"""
@@ -68,6 +74,10 @@ def __init__(self, repo, id, tree=None, author=None, authored_date=None,
6874
self.tree = Tree(repo, id=tree)
6975

7076
def __bake__(self):
77+
"""
78+
Called by LazyMixin superclass when the first uninitialized member needs
79+
to be set as it is queried.
80+
"""
7181
temp = Commit.find_all(self.repo, self.id, max_count=1)[0]
7282
self.parents = temp.parents
7383
self.tree = temp.tree
@@ -79,10 +89,18 @@ def __bake__(self):
7989

8090
@property
8191
def id_abbrev(self):
92+
"""
93+
Returns
94+
First 7 bytes of the commit's sha id as an abbreviation of the full string.
95+
"""
8296
return self.id[0:7]
8397

8498
@property
8599
def summary(self):
100+
"""
101+
Returns
102+
First line of the commit message.
103+
"""
86104
return self.message.split('\n', 1)[0]
87105

88106
@classmethod
@@ -115,7 +133,8 @@ def find_all(cls, repo, ref, path='', **kwargs):
115133
is the ref from which to begin (SHA1 or name)
116134
117135
``path``
118-
is an optinal path
136+
is an optinal path, if set only Commits that include the path
137+
will be considered
119138
120139
``options``
121140
is a Hash of optional arguments to git where
@@ -140,7 +159,7 @@ def list_from_string(cls, repo, text):
140159
is the Repo
141160
142161
``text``
143-
is the text output from the git command (raw format)
162+
is the text output from the git-rev-list command (raw format)
144163
145164
Returns
146165
git.Commit[]
@@ -173,7 +192,7 @@ def list_from_string(cls, repo, text):
173192
@classmethod
174193
def diff(cls, repo, a, b=None, paths=None):
175194
"""
176-
Show diffs between two trees:
195+
Creates diffs between a tree and the index or between two trees:
177196
178197
``repo``
179198
is the Repo
@@ -187,10 +206,13 @@ def diff(cls, repo, a, b=None, paths=None):
187206
given paths.
188207
189208
``paths``
190-
is a list of paths to limit the diff.
209+
is a list of paths to limit the diff to.
191210
192211
Returns
193-
git.Diff[]
212+
git.Diff[]::
213+
214+
between tree and the index if only a is given
215+
between two trees if a and b are given and are commits
194216
"""
195217
paths = paths or []
196218

@@ -209,6 +231,12 @@ def diff(cls, repo, a, b=None, paths=None):
209231

210232
@property
211233
def diffs(self):
234+
"""
235+
Returns
236+
git.Diff[]
237+
Diffs between this commit and its first parent or all changes if this
238+
commit is the first commit and has no parent.
239+
"""
212240
if not self.parents:
213241
d = self.repo.git.show(self.id, '-M', full_index=True, pretty='raw')
214242
if re.search(r'diff --git a', d):
@@ -223,6 +251,13 @@ def diffs(self):
223251

224252
@property
225253
def stats(self):
254+
"""
255+
Create a git stat from changes between this commit and its first parent
256+
or from all changes done if this is the very first commit.
257+
258+
Return
259+
git.Stats
260+
"""
226261
if not self.parents:
227262
text = self.repo.git.diff_tree(self.id, '--', numstat=True, root=True)
228263
text2 = ""
@@ -247,7 +282,7 @@ def actor(cls, line):
247282
Parse out the actor (author or committer) info
248283
249284
Returns
250-
[str (actor name and email), time (acted at time)]
285+
[Actor, gmtime(acted at time)]
251286
"""
252287
m = re.search(r'^.+? (.*) (\d+) .*$', line)
253288
actor, epoch = m.groups()

‎lib/git/stats.py

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,13 +5,45 @@
55
# the BSD License: http://www.opensource.org/licenses/bsd-license.php
66

77
class Stats(object):
8+
"""
9+
Represents stat information as presented by git at the end of a merge. It is
10+
created from the output of a diff operation.
11+
12+
``Example``::
13+
14+
c = Commit( sha1 )
15+
s = c.stats
16+
s.total # full-stat-dict
17+
s.files # dict( filepath : stat-dict )
18+
19+
``stat-dict``
20+
21+
A dictionary with the following keys and values::
22+
23+
deletions = number of deleted lines as int
24+
insertions = number of inserted lines as int
25+
lines = total number of lines changed as int, or deletions + insertions
26+
27+
``full-stat-dict``
28+
29+
In addition to the items in the stat-dict, it features additional information::
30+
31+
files = number of changed files as int
32+
33+
"""
834
def __init__(self, repo, total, files):
935
self.repo = repo
1036
self.total = total
1137
self.files = files
1238

1339
@classmethod
1440
def list_from_string(cls, repo, text):
41+
"""
42+
Create a Stat object from output retrieved by git-diff.
43+
44+
Returns
45+
git.Stat
46+
"""
1547
hsh = {'total': {'insertions': 0, 'deletions': 0, 'lines': 0, 'files': 0}, 'files': {}}
1648
for line in text.splitlines():
1749
(raw_insertions, raw_deletions, filename) = line.split("\t")

0 commit comments

Comments
 (0)
0