Fixed up docs for upcoming release. Bumped version to 0.5.3

Author: Byron

Makefile

@@ -23,5 +23,5 @@ clean::
 	rm -f *.so
 
 coverage:: build
-	PYTHONPATH=. $(PYTHON) $(TESTRUNNER) --cover-package=dulwich --with-coverage --cover-erase --cover-inclusive gitdb
+	PYTHONPATH=. $(PYTHON) $(TESTRUNNER) --cover-package=gitdb --with-coverage --cover-erase --cover-inclusive gitdb
 

gitdb/__init__.py

@@ -24,6 +24,13 @@ def _init_externals():
 
 _init_externals()
 
+__author__ = "Sebastian Thiel"
+__contact__ = "[email protected]"
+__homepage__ = "https://github.com/gitpython-developers/gitdb"
+version_info = (0, 5, 3)
+__version__ = '.'.join(str(i) for i in version_info)
+
+
 # default imports
 from db import *
 from base import *

gitdb/db/base.py

@@ -72,7 +72,8 @@ def stream_async(self, reader):
 		:param reader: see ``info``
 		:param max_threads: see ``ObjectDBW.store``
 		:return: async.Reader yielding OStream|InvalidOStream instances in any order
-		:note: depending on the system configuration, it might not be possible to 
+		
+		**Note:** depending on the system configuration, it might not be possible to 
 			read all OStreams at once. Instead, read them individually using reader.read(x)
 			where x is small enough."""
 		# base implementation just uses the stream method repeatedly
@@ -140,7 +141,7 @@ def store_async(self, reader):
 			The same instances will be used in the output channel as were received
 			in by the Reader.
 		
-		:note:As some ODB implementations implement this operation atomic, they might 
+		**Note:** As some ODB implementations implement this operation atomic, they might 
 			abort the whole operation if one item could not be processed. Hence check how 
 			many items have actually been produced."""
 		# base implementation uses store to perform the work
@@ -158,7 +159,7 @@ def __init__(self, root_path):
 		"""Initialize this instance to look for its files at the given root path
 		All subsequent operations will be relative to this path
 		:raise InvalidDBRoot: 
-		:note: The base will not perform any accessablity checking as the base
+		**Note:** The base will not perform any accessablity checking as the base
 			might not yet be accessible, but become accessible before the first 
 			access."""
 		super(FileDBBase, self).__init__()

gitdb/db/mem.py

@@ -33,7 +33,7 @@ class MemoryDB(ObjectDBR, ObjectDBW):
 	it to the actual physical storage, as it allows to query whether object already
 	exists in the target storage before introducing actual IO
 	
-	:note: memory is currently not threadsafe, hence the async methods cannot be used
+	**Note:** memory is currently not threadsafe, hence the async methods cannot be used
 		for storing"""
 
 	def __init__(self):
@@ -92,7 +92,7 @@ def sha_iter(self):
 	def stream_copy(self, sha_iter, odb):
 		"""Copy the streams as identified by sha's yielded by sha_iter into the given odb
 		The streams will be copied directly
-		:note: the object will only be written if it did not exist in the target db
+		**Note:** the object will only be written if it did not exist in the target db
 		:return: amount of streams actually copied into odb. If smaller than the amount
 			of input shas, one or more objects did already exist in odb"""
 		count = 0

gitdb/db/pack.py

@@ -58,7 +58,7 @@ def _pack_info(self, sha):
 		""":return: tuple(entity, index) for an item at the given sha
 		:param sha: 20 or 40 byte sha
 		:raise BadObject:
-		:note: This method is not thread-safe, but may be hit in multi-threaded
+		**Note:** This method is not thread-safe, but may be hit in multi-threaded
 			operation. The worst thing that can happen though is a counter that 
 			was not incremented, or the list being in wrong order. So we safe
 			the time for locking here, lets see how that goes"""

gitdb/ext/smmap

@@ -138,7 +138,7 @@ def _closest_index(dcl, absofs):
 	""":return: index at which the given absofs should be inserted. The index points
 	to the DeltaChunk with a target buffer absofs that equals or is greater than
 	absofs. 
-	:note: global method for performance only, it belongs to DeltaChunkList"""
+	**Note:** global method for performance only, it belongs to DeltaChunkList"""
 	lo = 0
 	hi = len(dcl)
 	while lo < hi:
@@ -414,9 +414,11 @@ def pack_object_header_info(data):
 	return (type_id, size, i)
 
 def create_pack_object_header(obj_type, obj_size):
-	""":return: string defining the pack header comprised of the object type
-	and its incompressed size in bytes
-	:parmam obj_type: pack type_id of the object
+	"""
+	:return: string defining the pack header comprised of the object type
+		and its incompressed size in bytes
+	
+	:param obj_type: pack type_id of the object
 	:param obj_size: uncompressed size in bytes of the following object stream"""
 	c = 0		# 1 byte
 	hdr = str()	# output string
@@ -483,7 +485,7 @@ def stream_copy(read, write, size, chunk_size):
 	Copy a stream up to size bytes using the provided read and write methods, 
 	in chunks of chunk_size
 	
-	:note: its much like stream_copy utility, but operates just using methods"""
+	**Note:** its much like stream_copy utility, but operates just using methods"""
 	dbw = 0												# num data bytes written
 
 	# WRITE ALL DATA UP TO SIZE
@@ -597,7 +599,8 @@ def apply_delta_data(src_buf, src_buf_size, delta_buf, delta_buf_size, write):
 	:param delta_buf_size: size fo the delta buffer in bytes
 	:param delta_buf: random access delta data
 	:param write: write method taking a chunk of bytes
-	:note: transcribed to python from the similar routine in patch-delta.c"""
+	
+	**Note:** transcribed to python from the similar routine in patch-delta.c"""
 	i = 0
 	db = delta_buf
 	while i < delta_buf_size:

gitdb/fun.py

@@ -173,7 +173,7 @@ def write_stream_to_pack(read, write, zstream, base_crc=None):
 class IndexWriter(object):
 	"""Utility to cache index information, allowing to write all information later
 	in one go to the given stream
-	:note: currently only writes v2 indices"""
+	**Note:** currently only writes v2 indices"""
 	__slots__ = '_objs'
 
 	def __init__(self):
@@ -391,7 +391,8 @@ def indexfile_checksum(self):
 
 	def offsets(self):
 		""":return: sequence of all offsets in the order in which they were written
-		:note: return value can be random accessed, but may be immmutable"""
+		
+		**Note:** return value can be random accessed, but may be immmutable"""
 		if self._version == 2:
 			# read stream to array, convert to tuple
 			a = array.array('I')	# 4 byte unsigned int, long are 8 byte on 64 bit it appears
@@ -497,10 +498,10 @@ class PackFile(LazyMixin):
 	packs therefor is 32 bit on 32 bit systems. On 64 bit systems, this should be 
 	fine though.
 	
-	:note: at some point, this might be implemented using streams as well, or 
-		streams are an alternate path in the case memory maps cannot be created
-		for some reason - one clearly doesn't want to read 10GB at once in that 
-		case"""
+	**Note:** at some point, this might be implemented using streams as well, or 
+	streams are an alternate path in the case memory maps cannot be created
+	for some reason - one clearly doesn't want to read 10GB at once in that 
+	case"""
 
 	__slots__ = ('_packpath', '_cursor', '_size', '_version')
 	pack_signature = 0x5041434b		# 'PACK'
@@ -625,8 +626,9 @@ def stream_iter(self, start_offset=0):
 			to access the data in the pack directly.
 		:param start_offset: offset to the first object to iterate. If 0, iteration 
 			starts at the very first object in the pack.
-		:note: Iterating a pack directly is costly as the datastream has to be decompressed
-			to determine the bounds between the objects"""
+			
+		**Note:** Iterating a pack directly is costly as the datastream has to be decompressed
+		to determine the bounds between the objects"""
 		return self._iter_objects(start_offset, as_stream=True)
 
 	#} END Read-Database like Interface
@@ -902,9 +904,11 @@ def write_pack(cls, object_iter, pack_write, index_write=None,
 		:param zlib_compression: the zlib compression level to use
 		:return: tuple(pack_sha, index_binsha) binary sha over all the contents of the pack
 			and over all contents of the index. If index_write was None, index_binsha will be None
-		:note: The destination of the write functions is up to the user. It could
-			be a socket, or a file for instance
-		:note: writes only undeltified objects"""
+			
+		**Note:** The destination of the write functions is up to the user. It could
+		be a socket, or a file for instance
+		
+		**Note:** writes only undeltified objects"""
 		objs = object_iter
 		if not object_count:
 			if not isinstance(object_iter, (tuple, list)):
@@ -979,7 +983,8 @@ def create(cls, object_iter, base_dir, object_count = None, zlib_compression = z
 		and corresponding index file. The pack contains all OStream objects contained in object iter.
 		:param base_dir: directory which is to contain the files
 		:return: PackEntity instance initialized with the new pack
-		:note: for more information on the other parameters see the write_pack method"""
+		
+		**Note:** for more information on the other parameters see the write_pack method"""
 		pack_fd, pack_path = tempfile.mkstemp('', 'pack', base_dir)
 		index_fd, index_path = tempfile.mkstemp('', 'index', base_dir)
 		pack_write = lambda d: os.write(pack_fd, d)

gitdb/pack.py

@@ -51,7 +51,7 @@ class DecompressMemMapReader(LazyMixin):
 	To read efficiently, you clearly don't want to read individual bytes, instead, 
 	read a few kilobytes at least.
 	
-	:note: The chunk-size should be carefully selected as it will involve quite a bit 
+	**Note:** The chunk-size should be carefully selected as it will involve quite a bit 
 		of string copying due to the way the zlib is implemented. Its very wasteful, 
 		hence we try to find a good tradeoff between allocation time and number of 
 		times we actually allocate. An own zlib implementation would be good here
@@ -609,8 +609,8 @@ class FDCompressedSha1Writer(Sha1Writer):
 	"""Digests data written to it, making the sha available, then compress the 
 	data and write it to the file descriptor
 	
-	:note: operates on raw file descriptors
-	:note: for this to work, you have to use the close-method of this instance"""
+	**Note:** operates on raw file descriptors
+	**Note:** for this to work, you have to use the close-method of this instance"""
 	__slots__ = ("fd", "sha1", "zip")
 
 	# default exception

gitdb/stream.py

@@ -65,7 +65,7 @@ def _assert_object_writing_simple(self, db):
 
 	def _assert_object_writing(self, db):
 		"""General tests to verify object writing, compatible to ObjectDBW
-		:note: requires write access to the database"""
+		**Note:** requires write access to the database"""
 		# start in 'dry-run' mode, using a simple sha1 writer
 		ostreams = (ZippedStoreShaWriter, None)
 		for ostreamcls in ostreams:

gitdb/test/db/lib.py

@@ -119,8 +119,9 @@ def __getslice__(self, start, end):
 #{ Routines
 
 def make_sha(source=''):
-    """A python2.4 workaround for the sha/hashlib module fiasco 
-    :note: From the dulwich project """
+    """A python2.4 workaround for the sha/hashlib module fiasco
+    
+    **Note** From the dulwich project """
     try:
         return hashlib.sha1(source)
     except NameError:
@@ -146,6 +147,7 @@ def allocate_memory(size):
 
 def file_contents_ro(fd, stream=False, allow_mmap=True):
 	""":return: read-only contents of the file represented by the file descriptor fd
+	
 	:param fd: file descriptor opened for reading
 	:param stream: if False, random access is provided, otherwise the stream interface
 		is provided.
@@ -173,14 +175,16 @@ def file_contents_ro(fd, stream=False, allow_mmap=True):
 
 def file_contents_ro_filepath(filepath, stream=False, allow_mmap=True, flags=0):
 	"""Get the file contents at filepath as fast as possible
+	
 	:return: random access compatible memory of the given filepath
 	:param stream: see ``file_contents_ro``
 	:param allow_mmap: see ``file_contents_ro``
 	:param flags: additional flags to pass to os.open
 	:raise OSError: If the file could not be opened
-	:note: for now we don't try to use O_NOATIME directly as the right value needs to be 
-		shared per database in fact. It only makes a real difference for loose object 
-		databases anyway, and they use it with the help of the ``flags`` parameter"""
+	
+	**Note** for now we don't try to use O_NOATIME directly as the right value needs to be 
+	shared per database in fact. It only makes a real difference for loose object 
+	databases anyway, and they use it with the help of the ``flags`` parameter"""
 	fd = os.open(filepath, os.O_RDONLY|getattr(os, 'O_BINARY', 0)|flags)
 	try:
 		return file_contents_ro(fd, stream, allow_mmap)
@@ -189,7 +193,8 @@ def file_contents_ro_filepath(filepath, stream=False, allow_mmap=True, flags=0):
 	# END assure file is closed
 
 def sliding_ro_buffer(filepath, flags=0):
-	""":return: a buffer compatible object which uses our mapped memory manager internally
+	"""
+	:return: a buffer compatible object which uses our mapped memory manager internally
 		ready to read the whole given filepath"""
 	return SlidingWindowMapBuffer(mman.make_cursor(filepath), flags=flags)
 
@@ -254,7 +259,7 @@ class LockedFD(object):
 	This type handles error correctly in that it will assure a consistent state 
 	on destruction.
 	
-	:note: with this setup, parallel reading is not possible"""
+	**note** with this setup, parallel reading is not possible"""
 	__slots__ = ("_filepath", '_fd', '_write')
 
 	def __init__(self, filepath):
@@ -283,7 +288,8 @@ def open(self, write=False, stream=False):
 			and must not be closed directly
 		:raise IOError: if the lock could not be retrieved
 		:raise OSError: If the actual file could not be opened for reading
-		:note: must only be called once"""
+		
+		**note** must only be called once"""
 		if self._write is not None:
 			raise AssertionError("Called %s multiple times" % self.open)
 
@@ -327,13 +333,15 @@ def commit(self):
 		"""When done writing, call this function to commit your changes into the 
 		actual file. 
 		The file descriptor will be closed, and the lockfile handled.
-		:note: can be called multiple times"""
+		
+		**Note** can be called multiple times"""
 		self._end_writing(successful=True)
 
 	def rollback(self):
 		"""Abort your operation without any changes. The file descriptor will be 
 		closed, and the lock released.
-		:note: can be called multiple times"""
+		
+		**Note** can be called multiple times"""
 		self._end_writing(successful=False)
 
 	def _end_writing(self, successful=True):

gitdb/util.py

@@ -4,6 +4,7 @@
 from distutils.command.build_ext import build_ext
 
 import os, sys
+import gitdb as meta
 
 # wow, this is a mixed bag ... I am pretty upset about all of this ... 
 setuptools_build_py_module = None
@@ -69,11 +70,11 @@ def get_data_files(self):
 
 setup(cmdclass={'build_ext':build_ext_nofail},
       name = "gitdb",
-      version = "0.5.3",
+      version = meta.__version__,
       description = "Git Object Database",
-      author = "Sebastian Thiel",
-      author_email = "[email protected]",
-      url = "http://gitorious.org/git-python/gitdb",
+      author = meta.__author__,
+      author_email = meta.__contact__,
+      url = meta.__homepage__,
       packages = ('gitdb', 'gitdb.db', 'gitdb.test', 'gitdb.test.db', 'gitdb.test.performance'),
       package_data={ 'gitdb.test' : ['fixtures/packs/*', 'fixtures/objects/7b/*']},
       package_dir = {'gitdb':'gitdb'},