Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

Commit2454ae8

Browse files
committed
Added missing information to docstrings of commit and stats module
1 parent8496831 commit2454ae8

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
importstats
1515

1616
classCommit(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 theshaid 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 thecorrespdonding tree id (will be converted into a Tree object)
37+
``tree`` : Tree
38+
is thecorresponding 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
defid_abbrev(self):
92+
"""
93+
Returns
94+
First 7 bytes of the commit's sha id as an abbreviation of the full string.
95+
"""
8296
returnself.id[0:7]
8397

8498
@property
8599
defsummary(self):
100+
"""
101+
Returns
102+
First line of the commit message.
103+
"""
86104
returnself.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
defdiff(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=pathsor []
196218

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

210232
@property
211233
defdiffs(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
ifnotself.parents:
213241
d=self.repo.git.show(self.id,'-M',full_index=True,pretty='raw')
214242
ifre.search(r'diff --git a',d):
@@ -223,6 +251,13 @@ def diffs(self):
223251

224252
@property
225253
defstats(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
ifnotself.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
classStats(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
deflist_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
forlineintext.splitlines():
1749
(raw_insertions,raw_deletions,filename)=line.split("\t")

0 commit comments

Comments
 (0)
[8]ページ先頭
©2009-2025 Movatter.jp