diff options
Diffstat (limited to 'git/objects')
| -rw-r--r-- | git/objects/base.py | 3 | ||||
| -rw-r--r-- | git/objects/blob.py | 2 | ||||
| -rw-r--r-- | git/objects/commit.py | 6 | ||||
| -rw-r--r-- | git/objects/fun.py | 6 | ||||
| -rw-r--r-- | git/objects/submodule/base.py | 5 | ||||
| -rw-r--r-- | git/objects/submodule/root.py | 5 | ||||
| -rw-r--r-- | git/objects/submodule/util.py | 7 | ||||
| -rw-r--r-- | git/objects/tag.py | 2 | ||||
| -rw-r--r-- | git/objects/tree.py | 6 | ||||
| -rw-r--r-- | git/objects/util.py | 10 |
10 files changed, 37 insertions, 15 deletions
diff --git a/git/objects/base.py b/git/objects/base.py index 9e73e2f3..fce41a3d 100644 --- a/git/objects/base.py +++ b/git/objects/base.py @@ -17,7 +17,9 @@ _assertion_msg_format = "Created object %r whose python type %r disagrees with t __all__ = ("Object", "IndexObject") + class Object(LazyMixin): + """Implements an Object which may be Blobs, Trees, Commits and Tags""" NULL_HEX_SHA = '0'*40 NULL_BIN_SHA = '\0'*20 @@ -120,6 +122,7 @@ class Object(LazyMixin): class IndexObject(Object): + """Base for all objects that can be part of the index file , namely Tree, Blob and SubModule objects""" __slots__ = ("path", "mode") diff --git a/git/objects/blob.py b/git/objects/blob.py index fd748537..5f00a1ff 100644 --- a/git/objects/blob.py +++ b/git/objects/blob.py @@ -9,7 +9,9 @@ import base __all__ = ('Blob', ) + class Blob(base.IndexObject): + """A Blob encapsulates a git blob object""" DEFAULT_MIME_TYPE = "text/plain" type = "blob" diff --git a/git/objects/commit.py b/git/objects/commit.py index db1493d5..b2ed02c0 100644 --- a/git/objects/commit.py +++ b/git/objects/commit.py @@ -35,7 +35,9 @@ import sys __all__ = ('Commit', ) + class Commit(base.Object, Iterable, Diffable, Traversable, Serializable): + """Wraps a git Commit object. This class will act lazily on some of its attributes and will query the @@ -52,7 +54,6 @@ class Commit(base.Object, Iterable, Diffable, Traversable, Serializable): # INVARIANTS default_encoding = "UTF-8" - # object configuration type = "commit" __slots__ = ("tree", @@ -158,7 +159,6 @@ class Commit(base.Object, Iterable, Diffable, Traversable, Serializable): else: return len(self.repo.git.rev_list(self.hexsha, **kwargs).splitlines()) - @property def name_rev(self): """ @@ -257,7 +257,6 @@ class Commit(base.Object, Iterable, Diffable, Traversable, Serializable): if hasattr(proc_or_stream, 'wait'): finalize_process(proc_or_stream) - @classmethod def create_from_tree(cls, repo, tree, message, parent_commits=None, head=False): """Commit the given tree, creating a commit object. @@ -329,7 +328,6 @@ class Commit(base.Object, Iterable, Diffable, Traversable, Serializable): enc_section, enc_option = cls.conf_encoding.split('.') conf_encoding = cr.get_value(enc_section, enc_option, cls.default_encoding) - # if the tree is no object, make sure we create one - otherwise # the created commit object is invalid if isinstance(tree, str): diff --git a/git/objects/fun.py b/git/objects/fun.py index a046d6d5..8f5a5cc2 100644 --- a/git/objects/fun.py +++ b/git/objects/fun.py @@ -5,8 +5,6 @@ __all__ = ('tree_to_stream', 'tree_entries_from_data', 'traverse_trees_recursive 'traverse_tree_recursive') - - def tree_to_stream(entries, write): """Write the give list of entries into a stream using its write method :param entries: **sorted** list of tuples with (binsha, mode, name) @@ -88,7 +86,6 @@ def tree_entries_from_data(data): return out - def _find_by_name(tree_data, name, is_dir, start_at): """return data entry matching the given name and tree mode or None. @@ -110,12 +107,14 @@ def _find_by_name(tree_data, name, is_dir, start_at): # END for each item return None + def _to_full_path(item, path_prefix): """Rebuild entry with given path prefix""" if not item: return item return (item[0], item[1], path_prefix+item[2]) + def traverse_trees_recursive(odb, tree_shas, path_prefix): """ :return: list with entries according to the given binary tree-shas. @@ -182,6 +181,7 @@ def traverse_trees_recursive(odb, tree_shas, path_prefix): # END for each tree_data chunk return out + def traverse_tree_recursive(odb, tree_sha, path_prefix): """ :return: list of entries of the tree pointed to by the binary tree_sha. An entry diff --git a/git/objects/submodule/base.py b/git/objects/submodule/base.py index 730642ed..42048028 100644 --- a/git/objects/submodule/base.py +++ b/git/objects/submodule/base.py @@ -34,6 +34,7 @@ __all__ = ["Submodule", "UpdateProgress"] class UpdateProgress(RemoteProgress): + """Class providing detailed progress information to the caller who should derive from it and implement the ``update(...)`` message""" CLONE, FETCH, UPDWKTREE = [1 << x for x in range(RemoteProgress._num_op_codes, RemoteProgress._num_op_codes+3)] @@ -53,6 +54,7 @@ UPDWKTREE = UpdateProgress.UPDWKTREE # mechanism which cause plenty of trouble of the only reason for packages and # modules is refactoring - subpackages shoudn't depend on parent packages class Submodule(util.IndexObject, Iterable, Traversable): + """Implements access to a git submodule. They are special in that their sha represents a commit in the submodule's repository which is to be checked out at the path of this instance. @@ -387,7 +389,6 @@ class Submodule(util.IndexObject, Iterable, Traversable): #END handle dry-run progress.update(END|CLONE, 0, 1, prefix+"Done cloning to %s" % module_path) - if not dry_run: # see whether we have a valid branch to checkout try: @@ -415,7 +416,6 @@ class Submodule(util.IndexObject, Iterable, Traversable): #END handle dry_run #END handle initalization - # DETERMINE SHAS TO CHECKOUT ############################ binsha = self.binsha @@ -549,7 +549,6 @@ class Submodule(util.IndexObject, Iterable, Traversable): renamed_module = True #END move physical module - # rename the index entry - have to manipulate the index directly as # git-mv cannot be used on submodules ... yeah try: diff --git a/git/objects/submodule/root.py b/git/objects/submodule/root.py index fb0a65c3..62ad1f05 100644 --- a/git/objects/submodule/root.py +++ b/git/objects/submodule/root.py @@ -11,6 +11,7 @@ __all__ = ["RootModule", "RootUpdateProgress"] class RootUpdateProgress(UpdateProgress): + """Utility class which adds more opcodes to the UpdateProgress""" REMOVE, PATHCHANGE, BRANCHCHANGE, URLCHANGE = [1 << x for x in range(UpdateProgress._num_op_codes, UpdateProgress._num_op_codes+4)] _num_op_codes = UpdateProgress._num_op_codes+4 @@ -24,7 +25,9 @@ BRANCHCHANGE = RootUpdateProgress.BRANCHCHANGE URLCHANGE = RootUpdateProgress.URLCHANGE PATHCHANGE = RootUpdateProgress.PATHCHANGE + class RootModule(Submodule): + """A (virtual) Root of all submodules in the given repository. It can be used to more easily traverse all submodules of the master repository""" @@ -45,7 +48,6 @@ class RootModule(Submodule): branch_path = git.Head.to_full_path(self.k_head_default) ) - def _clear_cache(self): """May not do anything""" pass @@ -107,7 +109,6 @@ class RootModule(Submodule): previous_commit = repo.commit(previous_commit) # obtain commit object # END handle previous commit - psms = self.list_items(repo, parent_commit=previous_commit) sms = self.list_items(repo) spsms = set(psms) diff --git a/git/objects/submodule/util.py b/git/objects/submodule/util.py index 237321e2..47b45109 100644 --- a/git/objects/submodule/util.py +++ b/git/objects/submodule/util.py @@ -9,22 +9,27 @@ __all__ = ( 'sm_section', 'sm_name', 'mkhead', 'unbare_repo', 'find_first_remote #{ Utilities + def sm_section(name): """:return: section title used in .gitmodules configuration file""" return 'submodule "%s"' % name + def sm_name(section): """:return: name of the submodule as parsed from the section name""" section = section.strip() return section[11:-1] + def mkhead(repo, path): """:return: New branch/head instance""" return git.Head(repo, git.Head.to_full_path(path)) + def unbare_repo(func): """Methods with this decorator raise InvalidGitRepositoryError if they encounter a bare repository""" + def wrapper(self, *args, **kwargs): if self.repo.bare: raise InvalidGitRepositoryError("Method '%s' cannot operate on bare repositories" % func.__name__) @@ -34,6 +39,7 @@ def unbare_repo(func): wrapper.__name__ = func.__name__ return wrapper + def find_first_remote_branch(remotes, branch_name): """Find the remote branch matching the name of the given branch or raise InvalidGitRepositoryError""" for remote in remotes: @@ -51,6 +57,7 @@ def find_first_remote_branch(remotes, branch_name): #{ Classes class SubmoduleConfigParser(GitConfigParser): + """ Catches calls to _write, and updates the .gitmodules blob in the index with the new data, if we have written into a stream. Otherwise it will diff --git a/git/objects/tag.py b/git/objects/tag.py index b34c5945..3690dc45 100644 --- a/git/objects/tag.py +++ b/git/objects/tag.py @@ -13,7 +13,9 @@ from util import ( __all__ = ("TagObject", ) + class TagObject(base.Object): + """Non-Lightweight tag carrying additional information about an object we are pointing to.""" type = "tag" __slots__ = ( "object", "tag", "tagger", "tagged_date", "tagger_tz_offset", "message" ) diff --git a/git/objects/tree.py b/git/objects/tree.py index 92b0feca..4984823e 100644 --- a/git/objects/tree.py +++ b/git/objects/tree.py @@ -21,7 +21,9 @@ from gitdb.util import ( __all__ = ("TreeModifier", "Tree") + class TreeModifier(object): + """A utility class providing methods to alter the underlying cache in a list-like fashion. Once all adjustments are complete, the _cache, which really is a refernce to @@ -101,6 +103,7 @@ class TreeModifier(object): class Tree(IndexObject, diff.Diffable, util.Traversable, util.Serializable): + """Tree objects represent an ordered list of Blobs and other Trees. ``Tree as a list``:: @@ -128,7 +131,6 @@ class Tree(IndexObject, diff.Diffable, util.Traversable, util.Serializable): # tree id added once Tree is defined } - def __init__(self, repo, binsha, mode=tree_id<<12, path=None): super(Tree, self).__init__(repo, binsha, mode, path) @@ -190,7 +192,6 @@ class Tree(IndexObject, diff.Diffable, util.Traversable, util.Serializable): raise KeyError( msg % file ) # END handle long paths - @property def trees(self): """:return: list(Tree, ...) list of trees directly below this tree""" @@ -239,7 +240,6 @@ class Tree(IndexObject, diff.Diffable, util.Traversable, util.Serializable): raise TypeError( "Invalid index type: %r" % item ) - def __contains__(self, item): if isinstance(item, IndexObject): for info in self._cache: diff --git a/git/objects/util.py b/git/objects/util.py index f9dffd81..9f947fcc 100644 --- a/git/objects/util.py +++ b/git/objects/util.py @@ -22,6 +22,7 @@ __all__ = ('get_object_type_by_name', 'parse_date', 'parse_actor_and_date', #{ Functions + def mode_str_to_int(modestr): """ :param modestr: string like 755 or 644 or 100644 - only the last 6 chars will be used @@ -36,6 +37,7 @@ def mode_str_to_int(modestr): # END for each char return mode + def get_object_type_by_name(object_type_name): """ :return: type suitable to handle the given object type name. @@ -59,6 +61,7 @@ def get_object_type_by_name(object_type_name): else: raise ValueError("Cannot handle unknown object type: %s" % object_type_name) + def utctz_to_altz(utctz): """we convert utctz to the timezone in seconds, it is the format time.altzone returns. Git stores it as UTC timezone which has the opposite sign as well, @@ -66,6 +69,7 @@ def utctz_to_altz(utctz): :param utctz: git utc timezone string, i.e. +0200""" return -1 * int(float(utctz)/100*3600) + def altz_to_utctz_str(altz): """As above, but inverses the operation, returning a string that can be used in commit objects""" @@ -92,6 +96,7 @@ def verify_utctz(offset): # END for each char return offset + def parse_date(string_date): """ Parse the given date as one of the following @@ -169,6 +174,7 @@ def parse_date(string_date): _re_actor_epoch = re.compile(r'^.+? (.*) (\d+) ([+-]\d+).*$') _re_only_actor = re.compile(r'^.+? (.*)$') + def parse_actor_and_date(line): """Parse out the actor (author or committer) info from a line like:: @@ -190,12 +196,14 @@ def parse_actor_and_date(line): #{ Classes class ProcessStreamAdapter(object): + """Class wireing all calls to the contained Process instance. Use this type to hide the underlying process to provide access only to a specified stream. The process is usually wrapped into an AutoInterrupt class to kill it if the instance goes out of scope.""" __slots__ = ("_proc", "_stream") + def __init__(self, process, stream_name): self._proc = process self._stream = getattr(process, stream_name) @@ -205,6 +213,7 @@ class ProcessStreamAdapter(object): class Traversable(object): + """Simple interface to perforam depth-first or breadth-first traversals into one direction. Subclasses only need to implement one function. @@ -303,6 +312,7 @@ class Traversable(object): class Serializable(object): + """Defines methods to serialize and deserialize objects from and into a data stream""" __slots__ = tuple() |