# Copyright (C) 2010, 2011 Sebastian Thiel (byronimo@gmail.com) and contributors
#
# This module is part of GitDB and is released under
# the New BSD License: http://www.opensource.org/licenses/bsd-license.php
"""Contains interfaces for basic database building blocks"""
__all__ = ('ObjectDBR', 'ObjectDBW', 'RootPathDB', 'CompoundDB', 'CachingDB',
'TransportDB', 'ConfigurationMixin', 'RepositoryPathsMixin',
'RefSpec', 'FetchInfo', 'PushInfo', 'ReferencesMixin', 'SubmoduleDB',
'IndexDB', 'HighLevelRepository')
class ObjectDBR(object):
"""Defines an interface for object database lookup.
Objects are identified either by their 20 byte bin sha"""
def __contains__(self, sha):
return self.has_obj(sha)
#{ Query Interface
def has_object(self, sha):
"""
:return: True if the object identified by the given 20 bytes
binary sha is contained in the database"""
raise NotImplementedError("To be implemented in subclass")
def has_object_async(self, reader):
"""Return a reader yielding information about the membership of objects
as identified by shas
:param reader: Reader yielding 20 byte shas.
:return: async.Reader yielding tuples of (sha, bool) pairs which indicate
whether the given sha exists in the database or not"""
raise NotImplementedError("To be implemented in subclass")
def info(self, sha):
""" :return: OInfo instance
:param sha: bytes binary sha
:raise BadObject:"""
raise NotImplementedError("To be implemented in subclass")
def info_async(self, reader):
"""Retrieve information of a multitude of objects asynchronously
:param reader: Channel yielding the sha's of the objects of interest
:return: async.Reader yielding OInfo|InvalidOInfo, in any order"""
raise NotImplementedError("To be implemented in subclass")
def stream(self, sha):
""":return: OStream instance
:param sha: 20 bytes binary sha
:raise BadObject:"""
raise NotImplementedError("To be implemented in subclass")
def stream_async(self, reader):
"""Retrieve the OStream of multiple objects
: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
read all OStreams at once. Instead, read them individually using reader.read(x)
where x is small enough."""
raise NotImplementedError("To be implemented in subclass")
def size(self):
""":return: amount of objects in this database"""
raise NotImplementedError()
def sha_iter(self):
"""Return iterator yielding 20 byte shas for all objects in this data base"""
raise NotImplementedError()
def partial_to_complete_sha_hex(self, partial_hexsha):
"""
:return: 20 byte binary sha1 from the given less-than-40 byte hexsha
:param partial_hexsha: hexsha with less than 40 byte
:raise AmbiguousObjectName: If multiple objects would match the given sha
:raies BadObject: If object was not found"""
raise NotImplementedError()
def partial_to_complete_sha(self, partial_binsha, canonical_length):
""":return: 20 byte sha as inferred by the given partial binary sha
:param partial_binsha: binary sha with less than 20 bytes
:param canonical_length: length of the corresponding canonical (hexadecimal) representation.
It is required as binary sha's cannot display whether the original hex sha
had an odd or even number of characters
:raise AmbiguousObjectName:
:raise BadObject: """
#} END query interface
class ObjectDBW(object):
"""Defines an interface to create objects in the database"""
#{ Edit Interface
def set_ostream(self, stream):
"""
Adjusts the stream to which all data should be sent when storing new objects
:param stream: if not None, the stream to use, if None the default stream
will be used.
:return: previously installed stream, or None if there was no override
:raise TypeError: if the stream doesn't have the supported functionality"""
raise NotImplementedError("To be implemented in subclass")
def ostream(self):
"""
:return: overridden output stream this instance will write to, or None
if it will write to the default stream"""
raise NotImplementedError("To be implemented in subclass")
def store(self, istream):
"""
Create a new object in the database
:return: the input istream object with its sha set to its corresponding value
:param istream: IStream compatible instance. If its sha is already set
to a value, the object will just be stored in the our database format,
in which case the input stream is expected to be in object format ( header + contents ).
:raise IOError: if data could not be written"""
raise NotImplementedError("To be implemented in subclass")
def store_async(self, reader):
"""
Create multiple new objects in the database asynchronously. The method will
return right away, returning an output channel which receives the results as
they are computed.
:return: Channel yielding your IStream which served as input, in any order.
The IStreams sha will be set to the sha it received during the process,
or its error attribute will be set to the exception informing about the error.
:param reader: async.Reader yielding IStream instances.
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
abort the whole operation if one item could not be processed. Hence check how
many items have actually been produced."""
raise NotImplementedError("To be implemented in subclass")
#} END edit interface
class RootPathDB(object):
"""Provides basic facilities to retrieve files of interest"""
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
might not yet be accessible, but become accessible before the first
access."""
try:
super(RootPathDB, self).__init__(root_path)
except TypeError:
pass
# END handle py 2.6
#{ Interface
def root_path(self):
""":return: path at which this db operates"""
raise NotImplementedError()
def db_path(self, rela_path):
"""
:return: the given relative path relative to our database root, allowing
to pontentially access datafiles
:param rela_path: if not None or '', the relative path will be appended
to the database root path. Otherwise you will obtain the database root path itself"""
raise NotImplementedError()
#} END interface
class CachingDB(object):
"""A database which uses caches to speed-up access"""
#{ Interface
def update_cache(self, force=False):
"""
Call this method if the underlying data changed to trigger an update
of the internal caching structures.
:param force: if True, the update must be performed. Otherwise the implementation
may decide not to perform an update if it thinks nothing has changed.
:return: True if an update was performed as something change indeed"""
# END interface
class CompoundDB(object):
"""A database which delegates calls to sub-databases.
They should usually be cached and lazy-loaded"""
#{ Interface
def databases(self):
""":return: tuple of database instances we use for lookups"""
raise NotImplementedError()
#} END interface
class IndexDB(object):
"""A database which provides a flattened index to all objects in its currently
active tree."""
@property
def index(self):
""":return: IndexFile compatible instance"""
raise NotImplementedError()
class RefSpec(object):
"""A refspec is a simple container which provides information about the way
something should be fetched or pushed. It requires to use symbols to describe
the actual objects which is done using reference names (or respective instances
which resolve to actual reference names)."""
__slots__ = ('source', 'destination', 'force')
def __init__(self, source, destination, force=False):
"""initalize the instance with the required values
:param source: reference name or instance. If None, the Destination
is supposed to be deleted."""
self.source = source
self.destination = destination
self.force = force
if self.destination is None:
raise ValueError("Destination must be set")
def __str__(self):
""":return: a git-style refspec"""
s = str(self.source)
if self.source is None:
s = ''
# END handle source
d = str(self.destination)
p = ''
if self.force:
p = '+'
# END handle force
res = "%s%s:%s" % (p, s, d)
def delete_destination(self):
return self.source is None
class RemoteProgress(object):
"""
Handler providing an interface to parse progress information emitted by git-push
and git-fetch and to dispatch callbacks allowing subclasses to react to the progress.
Subclasses should derive from this type.
"""
_num_op_codes = 7
BEGIN, END, COUNTING, COMPRESSING, WRITING, RECEIVING, RESOLVING = [1