Merge branch 'repo_interface' into improvements

* repo_interface:
  Improved archive function by allowing it to directly write to an output stream - previously it would cache everything to memory and try to provide zipping functionality itself
  repo: made init and clone methods less specific, previously they wanted to do it 'barely' only. New method names closely follow the default git command names
  repo.commit_delta_base: removed
  Object can now create objects of the proper type in case one attempts to create an object directly - this feature is used in several places now, allowing for additional type-checking
  repo: removed commits_between but added a note about how this can be achieved using the iter_commits method; reorganized methods within the type as a start for more interface changes
  Added Commit.iter_parents to iterate all parents
  repo: removed a few methods because of redundancy or because it will be obsolete once the interface overhaul is finished. This commit is just intermediate

Author: Byron

CHANGES

@@ -23,6 +23,11 @@ General
 * All dates, like authored_date and committer_date, are stored as seconds since epoc
   to consume less memory - they can be converted using time.gmtime in a more suitable 
   presentation format if needed.
+* Named method parameters changed on a wide scale to unify their use. Now git specific 
+  terms are used everywhere, such as "Reference" ( ref ) and "Revision" ( rev ).
+  Prevously multiple terms where used making it harder to know which type was allowed
+  or not.
+  
 
 Item Iteration
 --------------
@@ -44,7 +49,23 @@ Repo
   of the active branch.
 * tree method now requires a Ref instance as input and defaults to the active_branche
   instead of master
-* Removed 'log' method as it as effectively the same as the 'commits' method
+* Removed the following methods:
+  - 'log' method as it as effectively the same as the 'commits' method
+  - 'commits_since' as it is just a flag given to rev-list in Commit.iter_items
+  - 'commit_count' as it was just a redirection to the respective commit method
+  - 'commits_between', replaced by a note on the iter_commits method as it can 
+     achieve the same thing
+  - 'commit_delta_from' as it was a very special case by comparing two different
+     repositories which are likely to have completly different commits. For
+     related repositories, i.e. clones, git-rev-list would be sufficient to find 
+     commits that would need to be transferred for example.
+  - 'create' method which equals the 'init' method's functionality
+* Renamed the following methods:
+  - commits to iter_commits to improve the performance, adjusted signature
+  - init_bare to init, implying less about the options to be used
+  - fork_bare to clone, as it was to represent general clone functionality, but implied
+    a bare clone to be more versatile
+  - archive_tar_gz and archive_tar and replaced by archive method with different signature
 * 'commits' method has no max-count of returned commits anymore, it now behaves 
  like git-rev-list
 

lib/git/cmd.py

@@ -13,7 +13,8 @@
 GIT_PYTHON_TRACE = os.environ.get("GIT_PYTHON_TRACE", False)
 
 execute_kwargs = ('istream', 'with_keep_cwd', 'with_extended_output',
-				  'with_exceptions', 'with_raw_output', 'as_process')
+				  'with_exceptions', 'with_raw_output', 'as_process', 
+				  'output_stream' )
 
 extra = {}
 if sys.platform == 'win32':
@@ -102,7 +103,8 @@ def execute(self, command,
 				with_extended_output=False,
 				with_exceptions=True,
 				with_raw_output=False,
-				as_process=False
+				as_process=False, 
+				output_stream=None
 				):
 		"""
 		Handles executing the command on the shell and consumes and returns
@@ -130,16 +132,20 @@ def execute(self, command,
 		``with_raw_output``
 			Whether to avoid stripping off trailing whitespace.
 			
-		 ``as_process``
-		 	Whether to return the created process instance directly from which 
-		 	streams can be read on demand. This will render with_extended_output, 
-		 	with_exceptions and with_raw_output ineffective - the caller will have 
-		 	to deal with the details himself.
-		 	It is important to note that the process will be placed into an AutoInterrupt
-		 	wrapper that will interrupt the process once it goes out of scope. If you 
-		 	use the command in iterators, you should pass the whole process instance 
-		 	instead of a single stream.
-
+		``as_process``
+			Whether to return the created process instance directly from which 
+			streams can be read on demand. This will render with_extended_output, 
+			with_exceptions and with_raw_output ineffective - the caller will have 
+			to deal with the details himself.
+			It is important to note that the process will be placed into an AutoInterrupt
+			wrapper that will interrupt the process once it goes out of scope. If you 
+			use the command in iterators, you should pass the whole process instance 
+			instead of a single stream.
+		``output_stream``
+			If set to a file-like object, data produced by the git command will be 
+			output to the given stream directly. 
+			Otherwise a new file will be opened.
+		
 		Returns::
 		
 		 str(output)								  # extended_output = False (Default)
@@ -160,13 +166,17 @@ def execute(self, command,
 		  cwd = os.getcwd()
 		else:
 		  cwd=self.git_dir
+		  
+		ostream = subprocess.PIPE
+		if output_stream is not None:
+			ostream = output_stream
 
 		# Start the process
 		proc = subprocess.Popen(command,
 								cwd=cwd,
 								stdin=istream,
 								stderr=subprocess.PIPE,
-								stdout=subprocess.PIPE,
+								stdout=ostream,
 								**extra
 								)
 
@@ -223,6 +233,21 @@ def transform_kwargs(self, **kwargs):
 					args.append("--%s=%s" % (dashify(k), v))
 		return args
 
+	@classmethod
+	def __unpack_args(cls, arg_list):
+		if not isinstance(arg_list, (list,tuple)):
+			return [ str(arg_list) ]
+			
+		outlist = list()
+		for arg in arg_list:
+			if isinstance(arg_list, (list, tuple)):
+				outlist.extend(cls.__unpack_args( arg ))
+			# END recursion 
+			else:
+				outlist.append(str(arg))
+		# END for each arg
+		return outlist
+
 	def _call_process(self, method, *args, **kwargs):
 		"""
 		Run the given git command with the specified arguments and return
@@ -258,7 +283,8 @@ def _call_process(self, method, *args, **kwargs):
 
 		# Prepare the argument list
 		opt_args = self.transform_kwargs(**kwargs)
-		ext_args = map(str, args)
+		
+		ext_args = self.__unpack_args(args)
 		args = opt_args + ext_args
 
 		call = ["git", dashify(method)]

lib/git/objects/base.py

@@ -5,17 +5,32 @@
 # the BSD License: http://www.opensource.org/licenses/bsd-license.php
 import os
 from git.utils import LazyMixin
+import utils
 
 _assertion_msg_format = "Created object %r whose python type %r disagrees with the acutal git object type %r"
 
 class Object(LazyMixin):
 	"""
 	Implements an Object which may be Blobs, Trees, Commits and Tags
+	
+	This Object also serves as a constructor for instances of the correct type::
+	
+		inst = Object(repo,id)
 	"""
 	TYPES = ("blob", "tree", "commit", "tag")
 	__slots__ = ("repo", "id", "size", "data" )
 	type = None			# to be set by subclass
 
+	def __new__(cls, repo, id, *args, **kwargs):
+		if cls is Object:
+			hexsha, typename, size = repo.git.get_object_header(id)
+			obj_type = utils.get_object_type_by_name(typename)
+			inst = super(Object,cls).__new__(obj_type, repo, hexsha, *args, **kwargs)
+			inst.size = size
+			return inst
+		else:
+			return super(Object,cls).__new__(cls, repo, id, *args, **kwargs)
+	
 	def __init__(self, repo, id):
 		"""
 		Initialize an object by identifying it by its id. All keyword arguments

lib/git/objects/commit.py

@@ -100,45 +100,49 @@ def summary(self):
 			First line of the commit message.
 		"""
 		return self.message.split('\n', 1)[0]
-
+		
 	@classmethod
-	def count(cls, repo, ref, path=''):
+	def count(cls, repo, rev, paths='', **kwargs):
 		"""
-		Count the number of commits reachable from this ref
+		Count the number of commits reachable from this revision
 
 		``repo``
 			is the Repo
 
-		``ref``
-			is the ref from which to begin (SHA1 or name)
+		``rev``
+			revision specifier, see git-rev-parse for viable options
 
-		``path``
-			is an optinal path
+		``paths``
+			is an optinal path or a list of paths restricting the return value 
+			to commits actually containing the paths
 
+		``kwargs``
+			Additional options to be passed to git-rev-list
 		Returns
 			int
 		"""
-		return len(repo.git.rev_list(ref, '--', path).strip().splitlines())
+		return len(repo.git.rev_list(rev, '--', paths, **kwargs).strip().splitlines())
 
 	@classmethod
-	def iter_items(cls, repo, ref, path='', **kwargs):
+	def iter_items(cls, repo, rev, paths='', **kwargs):
 		"""
 		Find all commits matching the given criteria.
 
 		``repo``
 			is the Repo
 
-		``ref``
-			is the ref from which to begin (SHA1, Head or name)
+		``rev``
+			revision specifier, see git-rev-parse for viable options
 
-		``path``
-			is an optinal path, if set only Commits that include the path 
-			will be considered
+		``paths``
+			is an optinal path or list of paths, if set only Commits that include the path 
+			or paths will be considered
 
 		``kwargs``
-			optional keyword arguments to git where
+			optional keyword arguments to git rev-list where
 			``max_count`` is the maximum number of commits to fetch
 			``skip`` is the number of commits to skip
+			``since`` all commits since i.e. '1970-01-01'
 
 		Returns
 			iterator yielding Commit items
@@ -147,61 +151,30 @@ def iter_items(cls, repo, ref, path='', **kwargs):
 		options.update(kwargs)
 
 		# the test system might confront us with string values - 
-		proc = repo.git.rev_list(ref, '--', path, **options)
+		proc = repo.git.rev_list(rev, '--', paths, **options)
 		return cls._iter_from_process_or_stream(repo, proc)
-
-	@classmethod
-	def _iter_from_process_or_stream(cls, repo, proc_or_stream):
-		"""
-		Parse out commit information into a list of Commit objects
-
-		``repo``
-			is the Repo
-
-		``proc``
-			git-rev-list process instance (raw format)
-
-		Returns
-			iterator returning Commit objects
+		
+	def iter_parents(self, paths='', **kwargs):
 		"""
-		stream = proc_or_stream
-		if not hasattr(stream,'next'):
-			stream = proc_or_stream.stdout
-			
-		for line in stream:
-			id = line.split()[1]
-			assert line.split()[0] == "commit"
-			tree = stream.next().split()[1]
-
-			parents = []
-			next_line = None
-			for parent_line in stream:
-				if not parent_line.startswith('parent'):
-					next_line = parent_line
-					break
-				# END abort reading parents
-				parents.append(parent_line.split()[-1])
-			# END for each parent line
-			
-			author, authored_date = utils.parse_actor_and_date(next_line)
-			committer, committed_date = utils.parse_actor_and_date(stream.next())
-			
-			# empty line
-			stream.next()
-			
-			message_lines = []
-			next_line = None
-			for msg_line in stream:
-				if not msg_line.startswith('    '):
-					break
-				# END abort message reading 
-				message_lines.append(msg_line.strip())
-			# END while there are message lines
-			message = '\n'.join(message_lines)
+		Iterate _all_ parents of this commit.
+		
+		``paths``
+			Optional path or list of paths limiting the Commits to those that 
+			contain at least one of the paths
+		
+		``kwargs``
+			All arguments allowed by git-rev-list
 			
-			yield Commit(repo, id=id, parents=parents, tree=tree, author=author, authored_date=authored_date,
-						  committer=committer, committed_date=committed_date, message=message)
-		# END for each line in stream
+		Return:
+			Iterator yielding Commit objects which are parents of self
+		"""
+		# skip ourselves
+		skip = kwargs.get("skip", 1)
+		if skip == 0:	# skip ourselves 
+			skip = 1
+		kwargs['skip'] = skip
+		
+		return self.iter_items( self.repo, self, paths, **kwargs )
 
 	@classmethod
 	def diff(cls, repo, a, b=None, paths=None):
@@ -277,6 +250,60 @@ def stats(self):
 			text = self.repo.git.diff(self.parents[0].id, self.id, '--', numstat=True)
 		return stats.Stats._list_from_string(self.repo, text)
 
+	@classmethod
+	def _iter_from_process_or_stream(cls, repo, proc_or_stream):
+		"""
+		Parse out commit information into a list of Commit objects
+
+		``repo``
+			is the Repo
+
+		``proc``
+			git-rev-list process instance (raw format)
+
+		Returns
+			iterator returning Commit objects
+		"""
+		stream = proc_or_stream
+		if not hasattr(stream,'next'):
+			stream = proc_or_stream.stdout
+			
+		for line in stream:
+			id = line.split()[1]
+			assert line.split()[0] == "commit"
+			tree = stream.next().split()[1]
+
+			parents = []
+			next_line = None
+			for parent_line in stream:
+				if not parent_line.startswith('parent'):
+					next_line = parent_line
+					break
+				# END abort reading parents
+				parents.append(parent_line.split()[-1])
+			# END for each parent line
+			
+			author, authored_date = utils.parse_actor_and_date(next_line)
+			committer, committed_date = utils.parse_actor_and_date(stream.next())
+			
+			# empty line
+			stream.next()
+			
+			message_lines = []
+			next_line = None
+			for msg_line in stream:
+				if not msg_line.startswith('    '):
+					break
+				# END abort message reading 
+				message_lines.append(msg_line.strip())
+			# END while there are message lines
+			message = '\n'.join(message_lines)
+			
+			yield Commit(repo, id=id, parents=tuple(parents), tree=tree, author=author, authored_date=authored_date,
+						  committer=committer, committed_date=committed_date, message=message)
+		# END for each line in stream
+		
+		
 	def __str__(self):
 		""" Convert commit to string which is SHA1 """
 		return self.id

lib/git/objects/utils.py

@@ -7,7 +7,6 @@
 Module for general utility functions
 """
 import re
-import commit, tag, blob, tree
 from git.actor import Actor
 
 def get_object_type_by_name(object_type_name):