Dulwich.io dulwich / 7a21a35
Port more docstrings to Google style. Jelmer Vernooń≥ 8 days ago
5 changed file(s) with 128 addition(s) and 80 deletion(s). Raw diff Collapse all Expand all
5858 def get_recent_tags(projdir=PROJDIR):
5959 """Get list of tags in order from newest to oldest and their datetimes.
6060
61 :param projdir: path to ``.git``
62 :returns: list of tags sorted by commit time from newest to oldest
61 Args:
62 projdir: path to ``.git``
63 Returns:
64 list of tags sorted by commit time from newest to oldest
6365
6466 Each tag in the list contains the tag name, commit time, commit id, author
6567 and any tag meta. If a tag isn't annotated, then its tag meta is ``None``.
114116 version. *EG*: "Release-0.2.1-rc.1" will be come "0.2.1-rc.1". If no match
115117 is found, then the most recent tag is return without modification.
116118
117 :param projdir: path to ``.git``
118 :param pattern: regular expression pattern with group that matches version
119 :param logger: a Python logging instance to capture exception
120 :returns: tag matching first group in regular expression pattern
119 Args:
120 projdir: path to ``.git``
121 pattern: regular expression pattern with group that matches version
122 logger: a Python logging instance to capture exception
123 Returns:
124 tag matching first group in regular expression pattern
121125 """
122126 tags = get_recent_tags(projdir)
123127 try:
166166 def load_conf(path=None, file=None):
167167 """Load configuration in global var CONF
168168
169 :param path: The path to the configuration file
170 :param file: If provided read instead the file like object
169 Args:
170 path: The path to the configuration file
171 file: If provided read instead the file like object
171172 """
172173 conf = ConfigParser()
173174 if file:
194195 def swift_load_pack_index(scon, filename):
195196 """Read a pack index file from Swift
196197
197 :param scon: a `SwiftConnector` instance
198 :param filename: Path to the index file objectise
199 :return: a `PackIndexer` instance
198 Args:
199 scon: a `SwiftConnector` instance
200 filename: Path to the index file objectise
201 Returns: a `PackIndexer` instance
200202 """
201203 with scon.get_object(filename) as f:
202204 return load_pack_index_file(filename, f)
247249 def __init__(self, root, conf):
248250 """ Initialize a SwiftConnector
249251
250 :param root: The swift container that will act as Git bare repository
251 :param conf: A ConfigParser Object
252 Args:
253 root: The swift container that will act as Git bare repository
254 conf: A ConfigParser Object
252255 """
253256 self.conf = conf
254257 self.auth_ver = self.conf.get("swift", "auth_ver")
393396 def get_object_stat(self, name):
394397 """Retrieve object stat
395398
396 :param name: The object name
397 :return: A dict that describe the object
398 or None if object does not exist
399 Args:
400 name: The object name
401 Returns:
402 A dict that describe the object or None if object does not exist
399403 """
400404 path = self.base_path + '/' + name
401405 ret = self.httpclient.request('HEAD', path)
412416 def put_object(self, name, content):
413417 """Put an object
414418
415 :param name: The object name
416 :param content: A file object
417 :raise: `SwiftException` if unable to create
419 Args:
420 name: The object name
421 content: A file object
422 Raises:
423 SwiftException: if unable to create
418424 """
419425 content.seek(0)
420426 data = content.read()
441447 def get_object(self, name, range=None):
442448 """Retrieve an object
443449
444 :param name: The object name
445 :param range: A string range like "0-10" to
446 retrieve specified bytes in object content
447 :return: A file like instance
448 or bytestring if range is specified
450 Args:
451 name: The object name
452 range: A string range like "0-10" to
453 retrieve specified bytes in object content
454 Returns:
455 A file like instance or bytestring if range is specified
449456 """
450457 headers = {}
451458 if range:
466473 def del_object(self, name):
467474 """Delete an object
468475
469 :param name: The object name
470 :raise: `SwiftException` if unable to delete
476 Args:
477 name: The object name
478 Raises:
479 SwiftException: if unable to delete
471480 """
472481 path = self.base_path + '/' + name
473482 ret = self.httpclient.request('DELETE', path)
501510 def __init__(self, scon, filename, pack_length):
502511 """Initialize a SwiftPackReader
503512
504 :param scon: a `SwiftConnector` instance
505 :param filename: the pack filename
506 :param pack_length: The size of the pack object
513 Args:
514 scon: a `SwiftConnector` instance
515 filename: the pack filename
516 pack_length: The size of the pack object
507517 """
508518 self.scon = scon
509519 self.filename = filename
524534 def read(self, length):
525535 """Read a specified amount of Bytes form the pack object
526536
527 :param length: amount of bytes to read
528 :return: bytestring
537 Args:
538 length: amount of bytes to read
539 Returns:
540 a bytestring
529541 """
530542 end = self.offset+length
531543 if self.base_offset + end > self.pack_length:
543555 def seek(self, offset):
544556 """Seek to a specified offset
545557
546 :param offset: the offset to seek to
558 Args:
559 offset: the offset to seek to
547560 """
548561 self.base_offset = offset
549562 self._read()
567580 def __init__(self, scon, filename):
568581 """ Initialize a SwiftPackReader
569582
570 :param scon: a `SwiftConnector` instance
571 :param filename: the pack filename
583 Args:
584 scon: a `SwiftConnector` instance
585 filename: the pack filename
572586 """
573587 self.scon = scon
574588 self._filename = filename
638652 def __init__(self, scon):
639653 """Open a Swift object store.
640654
641 :param scon: A `SwiftConnector` instance
655 Args:
656 scon: A `SwiftConnector` instance
642657 """
643658 super(SwiftObjectStore, self).__init__()
644659 self.scon = scon
900915 `SwiftInfoRefsContainer`. The root attribute is the Swift
901916 container that contain the Git bare repository.
902917
903 :param root: The container which contains the bare repo
904 :param conf: A ConfigParser object
918 Args:
919 root: The container which contains the bare repo
920 conf: A ConfigParser object
905921 """
906922 self.root = root.lstrip('/')
907923 self.conf = conf
928944 def _put_named_file(self, filename, contents):
929945 """Put an object in a Swift container
930946
931 :param filename: the path to the object to put on Swift
932 :param contents: the content as bytestring
947 Args:
948 filename: the path to the object to put on Swift
949 contents: the content as bytestring
933950 """
934951 with BytesIO() as f:
935952 f.write(contents)
939956 def init_bare(cls, scon, conf):
940957 """Create a new bare repository.
941958
942 :param scon: a `SwiftConnector` instance
943 :param conf: a ConfigParser object
944 :return: a `SwiftRepo` instance
959 Args:
960 scon: a `SwiftConnector` instance
961 conf: a ConfigParser object
962 Returns:
963 a `SwiftRepo` instance
945964 """
946965 scon.create_root()
947966 for obj in [posixpath.join(OBJECTDIR, PACKDIR),
196196 def find_matching(self, path):
197197 """Yield all matching patterns for path.
198198
199 :param path: Path to match
200 :return: Iterator over iterators
199 Args:
200 path: Path to match
201 Returns:
202 Iterator over iterators
201203 """
202204 if not isinstance(path, bytes):
203205 path = path.encode(sys.getfilesystemencoding())
241243 def is_ignored(self, path):
242244 """Check whether a path is explicitly included or excluded in ignores.
243245
244 :param path: Path to check
245 :return: None if the file is not mentioned, True if it is included,
246 False if it is explicitly excluded.
246 Args:
247 path: Path to check
248 Returns:
249 None if the file is not mentioned, True if it is included,
250 False if it is explicitly excluded.
247251 """
248252 status = None
249253 for filter in self._filters:
256260 def default_user_ignore_filter_path(config):
257261 """Return default user ignore filter path.
258262
259 :param config: A Config object
260 :return: Path to a global ignore file
263 Args:
264 config: A Config object
265 Returns:
266 Path to a global ignore file
261267 """
262268 try:
263269 return config.get((b'core', ), b'excludesFile')
304310
305311 Stops after the first ignore file with matches.
306312
307 :param path: Path to check
308 :return: Iterator over Pattern instances
313 Args:
314 path: Path to check
315 Returns:
316 Iterator over Pattern instances
309317 """
310318 if os.path.isabs(path):
311319 raise ValueError('%s is an absolute path' % path)
332340 def is_ignored(self, path):
333341 """Check whether a path is explicitly included or excluded in ignores.
334342
335 :param path: Path to check
336 :return: None if the file is not mentioned, True if it is included,
337 False if it is explicitly excluded.
343 Args:
344 path: Path to check
345 Returns:
346 None if the file is not mentioned, True if it is included,
347 False if it is explicitly excluded.
338348 """
339349 matches = list(self.find_matching(path))
340350 if matches:
345355 def from_repo(cls, repo):
346356 """Create a IgnoreFilterManager from a repository.
347357
348 :param repo: Repository object
349 :return: A `IgnoreFilterManager` object
358 Args:
359 repo: Repository object
360 Returns:
361 A `IgnoreFilterManager` object
350362 """
351363 global_filters = []
352364 for p in [
5555 def pathsplit(path):
5656 """Split a /-delimited path into a directory part and a basename.
5757
58 :param path: The path to split.
59 :return: Tuple with directory name and basename
58 Args:
59 path: The path to split.
60 Returns:
61 Tuple with directory name and basename
6062 """
6163 try:
6264 (dirname, basename) = path.rsplit(b"/", 1)
7678 def read_cache_time(f):
7779 """Read a cache time.
7880
79 :param f: File-like object to read from
80 :return: Tuple with seconds and nanoseconds
81 Args:
82 f: File-like object to read from
83 Returns:
84 Tuple with seconds and nanoseconds
8185 """
8286 return struct.unpack(">LL", f.read(8))
8387
8589 def write_cache_time(f, t):
8690 """Write a cache time.
8791
88 :param f: File-like object to write to
89 :param t: Time to write (as int, float or tuple with secs and nsecs)
92 Args:
93 f: File-like object to write to
94 t: Time to write (as int, float or tuple with secs and nsecs)
9095 """
9196 if isinstance(t, int):
9297 t = (t, 0)
101106 def read_cache_entry(f):
102107 """Read an entry from a cache file.
103108
104 :param f: File-like object to read from
105 :return: tuple with: device, inode, mode, uid, gid, size, sha, flags
109 Args:
110 f: File-like object to read from
111 Returns:
112 tuple with: device, inode, mode, uid, gid, size, sha, flags
106113 """
107114 beginoffset = f.tell()
108115 ctime = read_cache_time(f)
120127 def write_cache_entry(f, entry):
121128 """Write an index entry to a file.
122129
123 :param f: File object
124 :param entry: Entry to write, tuple with:
130 Args:
131 f: File object
132 entry: Entry to write, tuple with:
125133 (name, ctime, mtime, dev, ino, mode, uid, gid, size, sha, flags)
126134 """
127135 beginoffset = f.tell()
151159 def read_index_dict(f):
152160 """Read an index file and return it as a dictionary.
153161
154 :param f: File object to read from
162 Args:
163 f: File object to read from
155164 """
156165 ret = {}
157166 for x in read_index(f):
11901190 prune=False, prune_tags=False, **kwargs):
11911191 """Fetch objects from a remote server.
11921192
1193 :param repo: Path to the repository
1194 :param remote_location: String identifying a remote server
1195 :param remote_name: Name for remote server
1196 :param outstream: Output stream (defaults to stdout)
1197 :param errstream: Error stream (defaults to stderr)
1198 :param message: Reflog message (defaults to b"fetch: from <remote_name>")
1199 :param depth: Depth to fetch at
1200 :param prune: Prune remote removed refs
1201 :param prune_tags: Prune reomte removed tags
1202 :return: Dictionary with refs on the remote
1193 Args:
1194 repo: Path to the repository
1195 remote_location: String identifying a remote server
1196 remote_name: Name for remote server
1197 outstream: Output stream (defaults to stdout)
1198 errstream: Error stream (defaults to stderr)
1199 message: Reflog message (defaults to b"fetch: from <remote_name>")
1200 depth: Depth to fetch at
1201 prune: Prune remote removed refs
1202 prune_tags: Prune reomte removed tags
1203 Returns:
1204 Dictionary with refs on the remote
12031205 """
12041206 if message is None:
12051207 message = b'fetch: from ' + remote_location.encode("utf-8")
12281230 def ls_remote(remote, config=None, **kwargs):
12291231 """List the refs in a remote.
12301232
1231 :param remote: Remote repository location
1232 :param config: Configuration to use
1233 :return: Dictionary with remote refs
1233 Args:
1234 remote: Remote repository location
1235 config: Configuration to use
1236 Returns:
1237 Dictionary with remote refs
12341238 """
12351239 if config is None:
12361240 config = StackedConfig.default()