Dulwich.io dulwich / 0dee0a7
Convert more docstrings to google style. Jelmer Vernooij 1 year, 2 months ago
3 changed file(s) with 91 addition(s) and 66 deletion(s). Raw diff Collapse all Expand all
+62
-47
dulwich/diff_tree.py less more
7676 def _merge_entries(path, tree1, tree2):
7777 """Merge the entries of two trees.
7878
79 :param path: A path to prepend to all tree entry names.
80 :param tree1: The first Tree object to iterate, or None.
81 :param tree2: The second Tree object to iterate, or None.
82 :return: A list of pairs of TreeEntry objects for each pair of entries in
79 Args:
80 path: A path to prepend to all tree entry names.
81 tree1: The first Tree object to iterate, or None.
82 tree2: The second Tree object to iterate, or None.
83 Returns:
84 A list of pairs of TreeEntry objects for each pair of entries in
8385 the trees. If an entry exists in one tree but not the other, the other
8486 entry will have all attributes set to None. If neither entry's path is
8587 None, they are guaranteed to match.
123125
124126 Iteration is depth-first pre-order, as in e.g. os.walk.
125127
126 :param store: An ObjectStore for looking up objects.
127 :param tree1_id: The SHA of the first Tree object to iterate, or None.
128 :param tree2_id: The SHA of the second Tree object to iterate, or None.
129 :param prune_identical: If True, identical subtrees will not be walked.
130 :return: Iterator over Pairs of TreeEntry objects for each pair of entries
128 Args:
129 store: An ObjectStore for looking up objects.
130 tree1_id: The SHA of the first Tree object to iterate, or None.
131 tree2_id: The SHA of the second Tree object to iterate, or None.
132 param prune_identical: If True, identical subtrees will not be walked.
133 Returns:
134 Iterator over Pairs of TreeEntry objects for each pair of entries
131135 in the trees and their subtrees recursively. If an entry exists in one
132136 tree but not the other, the other entry will have all attributes set
133137 to None. If neither entry's path is None, they are guaranteed to
163167 change_type_same=False):
164168 """Find the differences between the contents of two trees.
165169
166 :param store: An ObjectStore for looking up objects.
167 :param tree1_id: The SHA of the source tree.
168 :param tree2_id: The SHA of the target tree.
169 :param want_unchanged: If True, include TreeChanges for unmodified entries
170 Args:
171 store: An ObjectStore for looking up objects.
172 tree1_id: The SHA of the source tree.
173 tree2_id: The SHA of the target tree.
174 want_unchanged: If True, include TreeChanges for unmodified entries
170175 as well.
171 :param include_trees: Whether to include trees
172 :param rename_detector: RenameDetector object for detecting renames.
173 :param change_type_same: Whether to report change types in the same
176 include_trees: Whether to include trees
177 rename_detector: RenameDetector object for detecting renames.
178 change_type_same: Whether to report change types in the same
174179 entry or as delete+add.
175 :return: Iterator over TreeChange instances for each change between the
180 Returns:
181 Iterator over TreeChange instances for each change between the
176182 source and target tree.
177183 """
178184 if include_trees and rename_detector is not None:
231237 rename_detector=None):
232238 """Get the tree changes for a merge tree relative to all its parents.
233239
234 :param store: An ObjectStore for looking up objects.
235 :param parent_tree_ids: An iterable of the SHAs of the parent trees.
236 :param tree_id: The SHA of the merge tree.
237 :param rename_detector: RenameDetector object for detecting renames.
238
239 :return: Iterator over lists of TreeChange objects, one per conflicted path
240 in the merge.
241
242 Each list contains one element per parent, with the TreeChange for that
243 path relative to that parent. An element may be None if it never
244 existed in one parent and was deleted in two others.
245
246 A path is only included in the output if it is a conflict, i.e. its SHA
247 in the merge tree is not found in any of the parents, or in the case of
248 deletes, if not all of the old SHAs match.
240 Args:
241 store: An ObjectStore for looking up objects.
242 parent_tree_ids: An iterable of the SHAs of the parent trees.
243 tree_id: The SHA of the merge tree.
244 rename_detector: RenameDetector object for detecting renames.
245
246 Returns:
247 Iterator over lists of TreeChange objects, one per conflicted path
248 in the merge.
249
250 Each list contains one element per parent, with the TreeChange for that
251 path relative to that parent. An element may be None if it never
252 existed in one parent and was deleted in two others.
253
254 A path is only included in the output if it is a conflict, i.e. its SHA
255 in the merge tree is not found in any of the parents, or in the case of
256 deletes, if not all of the old SHAs match.
249257 """
250258 all_parent_changes = [tree_changes(store, t, tree_id,
251259 rename_detector=rename_detector)
292300
293301 Splits the data into blocks either on lines or <=64-byte chunks of lines.
294302
295 :param obj: The object to count blocks for.
296 :return: A dict of block hashcode -> total bytes occurring.
303 Args:
304 obj: The object to count blocks for.
305 Returns:
306 A dict of block hashcode -> total bytes occurring.
297307 """
298308 block_counts = defaultdict(int)
299309 block = BytesIO()
325335 def _common_bytes(blocks1, blocks2):
326336 """Count the number of common bytes in two block count dicts.
327337
328 :param block1: The first dict of block hashcode -> total bytes.
329 :param block2: The second dict of block hashcode -> total bytes.
330 :return: The number of bytes in common between blocks1 and blocks2. This is
331 only approximate due to possible hash collisions.
338 Args:
339 block1: The first dict of block hashcode -> total bytes.
340 block2: The second dict of block hashcode -> total bytes.
341 Returns:
342 The number of bytes in common between blocks1 and blocks2. This is
343 only approximate due to possible hash collisions.
332344 """
333345 # Iterate over the smaller of the two dicts, since this is symmetrical.
334346 if len(blocks1) > len(blocks2):
344356 def _similarity_score(obj1, obj2, block_cache=None):
345357 """Compute a similarity score for two objects.
346358
347 :param obj1: The first object to score.
348 :param obj2: The second object to score.
349 :param block_cache: An optional dict of SHA to block counts to cache
359 Args:
360 obj1: The first object to score.
361 obj2: The second object to score.
362 block_cache: An optional dict of SHA to block counts to cache
350363 results between calls.
351 :return: The similarity score between the two objects, defined as the
364 Returns:
365 The similarity score between the two objects, defined as the
352366 number of bytes in common between the two objects divided by the
353367 maximum size, scaled to the range 0-100.
354368 """
386400 find_copies_harder=False):
387401 """Initialize the rename detector.
388402
389 :param store: An ObjectStore for looking up objects.
390 :param rename_threshold: The threshold similarity score for considering
403 Args:
404 store: An ObjectStore for looking up objects.
405 rename_threshold: The threshold similarity score for considering
391406 an add/delete pair to be a rename/copy; see _similarity_score.
392 :param max_files: The maximum number of adds and deletes to consider,
407 max_files: The maximum number of adds and deletes to consider,
393408 or None for no limit. The detector is guaranteed to compare no more
394409 than max_files ** 2 add/delete pairs. This limit is provided
395410 because rename detection can be quadratic in the project size. If
396411 the limit is exceeded, no content rename detection is attempted.
397 :param rewrite_threshold: The threshold similarity score below which a
412 rewrite_threshold: The threshold similarity score below which a
398413 modify should be considered a delete/add, or None to not break
399414 modifies; see _similarity_score.
400 :param find_copies_harder: If True, consider unmodified files when
415 find_copies_harder: If True, consider unmodified files when
401416 detecting copies.
402417 """
403418 self._store = store
+17
-11
dulwich/hooks.py less more
3535 def execute(self, *args):
3636 """Execute the hook with the given args
3737
38 :param args: argument list to hook
39 :raise HookError: hook execution failure
40 :return: a hook may return a useful value
38 Args:
39 args: argument list to hook
40 Raises:
41 HookError: hook execution failure
42 Returns:
43 a hook may return a useful value
4144 """
4245 raise NotImplementedError(self.execute)
4346
5558 cwd=None):
5659 """Setup shell hook definition
5760
58 :param name: name of hook for error messages
59 :param path: absolute path to executable file
60 :param numparam: number of requirements parameters
61 :param pre_exec_callback: closure for setup before execution
61 Args:
62 name: name of hook for error messages
63 path: absolute path to executable file
64 numparam: number of requirements parameters
65 pre_exec_callback: closure for setup before execution
6266 Defaults to None. Takes in the variable argument list from the
6367 execute functions and returns a modified argument list for the
6468 shell hook.
65 :param post_exec_callback: closure for cleanup after execution
69 post_exec_callback: closure for cleanup after execution
6670 Defaults to None. Takes in a boolean for hook success and the
6771 modified argument list and returns the final hook return value
6872 if applicable
69 :param cwd: working directory to switch to when executing the hook
73 cwd: working directory to switch to when executing the hook
7074 """
7175 self.name = name
7276 self.filepath = path
128132 class CommitMsgShellHook(ShellHook):
129133 """commit-msg shell hook
130134
131 :param args[0]: commit message
132 :return: new commit message or None
135 Args:
136 args[0]: commit message
137 Returns:
138 new commit message or None
133139 """
134140
135141 def __init__(self, controldir):
+12
-8
dulwich/ignore.py less more
101101 def read_ignore_patterns(f):
102102 """Read a git ignore file.
103103
104 :param f: File-like object to read from
105 :return: List of patterns
104 Args:
105 f: File-like object to read from
106 Returns: List of patterns
106107 """
107108
108109 for line in f:
127128 def match_pattern(path, pattern, ignorecase=False):
128129 """Match a gitignore-style pattern against a path.
129130
130 :param path: Path to match
131 :param pattern: Pattern to match
132 :param ignorecase: Whether to do case-sensitive matching
133 :return: bool indicating whether the pattern matched
131 Args:
132 path: Path to match
133 pattern: Pattern to match
134 ignorecase: Whether to do case-sensitive matching
135 Returns:
136 bool indicating whether the pattern matched
134137 """
135138 return Pattern(pattern, ignorecase).match(path)
136139
171174 def match(self, path):
172175 """Try to match a path against this ignore pattern.
173176
174 :param path: Path to match (relative to ignore location)
175 :return: boolean
177 Args:
178 path: Path to match (relative to ignore location)
179 Returns: boolean
176180 """
177181 return bool(self._re.match(path))
178182