dulwich/objects.py

   1 # objects.py -- Access to base git objects
   2 # Copyright (C) 2007 James Westby <jw+debian@jameswestby.net>
   3 # Copyright (C) 2008-2009 Jelmer Vernooij <jelmer@samba.org>
   4 #
   5 # This program is free software; you can redistribute it and/or
   6 # modify it under the terms of the GNU General Public License
   7 # as published by the Free Software Foundation; version 2
   8 # of the License or (at your option) a later version of the License.
   9 #
  10 # This program is distributed in the hope that it will be useful,
  11 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  12 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13 # GNU General Public License for more details.
  14 #
  15 # You should have received a copy of the GNU General Public License
  16 # along with this program; if not, write to the Free Software
  17 # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
  18 # MA  02110-1301, USA.
  19
  20 """Access to base git objects."""
  21
  22
  23 import binascii
  24 from cStringIO import (
  25     StringIO,
  26     )
  27 import mmap
  28 import os
  29 import stat
  30 import zlib
  31
  32 from dulwich.errors import (
  33     ChecksumMismatch,
  34     NotBlobError,
  35     NotCommitError,
  36     NotTagError,
  37     NotTreeError,
  38     ObjectFormatException,
  39     )
  40 from dulwich.file import GitFile
  41 from dulwich.misc import (
  42     make_sha,
  43     )
  44
  45
  46 # Header fields for commits
  47 _TREE_HEADER = "tree"
  48 _PARENT_HEADER = "parent"
  49 _AUTHOR_HEADER = "author"
  50 _COMMITTER_HEADER = "committer"
  51 _ENCODING_HEADER = "encoding"
  52
  53
  54 # Header fields for objects
  55 _OBJECT_HEADER = "object"
  56 _TYPE_HEADER = "type"
  57 _TAG_HEADER = "tag"
  58 _TAGGER_HEADER = "tagger"
  59
  60
  61 S_IFGITLINK = 0160000
  62
  63 def S_ISGITLINK(m):
  64     return (stat.S_IFMT(m) == S_IFGITLINK)
  65
  66
  67 def _decompress(string):
  68     dcomp = zlib.decompressobj()
  69     dcomped = dcomp.decompress(string)
  70     dcomped += dcomp.flush()
  71     return dcomped
  72
  73
  74 def sha_to_hex(sha):
  75     """Takes a string and returns the hex of the sha within"""
  76     hexsha = binascii.hexlify(sha)
  77     assert len(hexsha) == 40, "Incorrect length of sha1 string: %d" % hexsha
  78     return hexsha
  79
  80
  81 def hex_to_sha(hex):
  82     """Takes a hex sha and returns a binary sha"""
  83     assert len(hex) == 40, "Incorrent length of hexsha: %s" % hex
  84     return binascii.unhexlify(hex)
  85
  86
  87 def hex_to_filename(path, hex):
  88     """Takes a hex sha and returns its filename relative to the given path."""
  89     dir = hex[:2]
  90     file = hex[2:]
  91     # Check from object dir
  92     return os.path.join(path, dir, file)
  93
  94
  95 def filename_to_hex(filename):
  96     """Takes an object filename and returns its corresponding hex sha."""
  97     # grab the last (up to) two path components
  98     names = filename.rsplit(os.path.sep, 2)[-2:]
  99     errmsg = "Invalid object filename: %s" % filename
 100     assert len(names) == 2, errmsg
 101     base, rest = names
 102     assert len(base) == 2 and len(rest) == 38, errmsg
 103     hex = base + rest
 104     hex_to_sha(hex)
 105     return hex
 106
 107
 108 def object_header(num_type, length):
 109     """Return an object header for the given numeric type and text length."""
 110     return "%s %d\0" % (object_class(num_type).type_name, length)
 111
 112
 113 def serializable_property(name, docstring=None):
 114     def set(obj, value):
 115         obj._ensure_parsed()
 116         setattr(obj, "_"+name, value)
 117         obj._needs_serialization = True
 118     def get(obj):
 119         obj._ensure_parsed()
 120         return getattr(obj, "_"+name)
 121     return property(get, set, doc=docstring)
 122
 123
 124 def object_class(type):
 125     """Get the object class corresponding to the given type.
 126
 127     :param type: Either a type name string or a numeric type.
 128     :return: The ShaFile subclass corresponding to the given type, or None if
 129         type is not a valid type name/number.
 130     """
 131     return _TYPE_MAP.get(type, None)
 132
 133
 134 def check_hexsha(hex, error_msg):
 135     try:
 136         hex_to_sha(hex)
 137     except (TypeError, AssertionError):
 138         raise ObjectFormatException("%s %s" % (error_msg, hex))
 139
 140
 141 def check_identity(identity, error_msg):
 142     """Check if the specified identity is valid.
 143
 144     This will raise an exception if the identity is not valid.
 145
 146     :param identity: Identity string
 147     :param error_msg: Error message to use in exception
 148     """
 149     email_start = identity.find("<")
 150     email_end = identity.find(">")
 151     if (email_start < 0 or email_end < 0 or email_end <= email_start
 152         or identity.find("<", email_start + 1) >= 0
 153         or identity.find(">", email_end + 1) >= 0
 154         or not identity.endswith(">")):
 155         raise ObjectFormatException(error_msg)
 156
 157
 158 class FixedSha(object):
 159     """SHA object that behaves like hashlib's but is given a fixed value."""
 160
 161     def __init__(self, hexsha):
 162         self._hexsha = hexsha
 163         self._sha = hex_to_sha(hexsha)
 164
 165     def digest(self):
 166         return self._sha
 167
 168     def hexdigest(self):
 169         return self._hexsha
 170
 171
 172 class ShaFile(object):
 173     """A git SHA file."""
 174
 175     @staticmethod
 176     def _parse_legacy_object_header(magic, f):
 177         """Parse a legacy object, creating it but not reading the file."""
 178         bufsize = 1024
 179         decomp = zlib.decompressobj()
 180         header = decomp.decompress(magic)
 181         start = 0
 182         end = -1
 183         while end < 0:
 184             header += decomp.decompress(f.read(bufsize))
 185             end = header.find("\0", start)
 186             start = len(header)
 187         header = header[:end]
 188         type_name, size = header.split(" ", 1)
 189         size = int(size)  # sanity check
 190         obj_class = object_class(type_name)
 191         if not obj_class:
 192             raise ObjectFormatException("Not a known type: %s" % type_name)
 193         return obj_class()
 194
 195     def _parse_legacy_object(self, f):
 196         """Parse a legacy object, setting the raw string."""
 197         size = os.path.getsize(f.name)
 198         map = mmap.mmap(f.fileno(), size, access=mmap.ACCESS_READ)
 199         try:
 200             text = _decompress(map)
 201         finally:
 202             map.close()
 203         header_end = text.find('\0')
 204         if header_end < 0:
 205             raise ObjectFormatException("Invalid object header")
 206         self.set_raw_string(text[header_end+1:])
 207
 208     def as_legacy_object_chunks(self):
 209         compobj = zlib.compressobj()
 210         yield compobj.compress(self._header())
 211         for chunk in self.as_raw_chunks():
 212             yield compobj.compress(chunk)
 213         yield compobj.flush()
 214
 215     def as_legacy_object(self):
 216         return "".join(self.as_legacy_object_chunks())
 217
 218     def as_raw_chunks(self):
 219         if self._needs_parsing:
 220             self._ensure_parsed()
 221         elif self._needs_serialization:
 222             self._chunked_text = self._serialize()
 223         return self._chunked_text
 224
 225     def as_raw_string(self):
 226         return "".join(self.as_raw_chunks())
 227
 228     def __str__(self):
 229         return self.as_raw_string()
 230
 231     def __hash__(self):
 232         return hash(self.id)
 233
 234     def as_pretty_string(self):
 235         return self.as_raw_string()
 236
 237     def _ensure_parsed(self):
 238         if self._needs_parsing:
 239             if not self._chunked_text:
 240                 if self._file is not None:
 241                     self._parse_file(self._file)
 242                 elif self._path is not None:
 243                     self._parse_path()
 244                 else:
 245                     raise AssertionError(
 246                         "ShaFile needs either text or filename")
 247             self._deserialize(self._chunked_text)
 248             self._needs_parsing = False
 249
 250     def set_raw_string(self, text):
 251         if type(text) != str:
 252             raise TypeError(text)
 253         self.set_raw_chunks([text])
 254
 255     def set_raw_chunks(self, chunks):
 256         self._chunked_text = chunks
 257         self._deserialize(chunks)
 258         self._sha = None
 259         self._needs_parsing = False
 260         self._needs_serialization = False
 261
 262     @staticmethod
 263     def _parse_object_header(magic, f):
 264         """Parse a new style object, creating it but not reading the file."""
 265         num_type = (ord(magic[0]) >> 4) & 7
 266         obj_class = object_class(num_type)
 267         if not obj_class:
 268             raise ObjectFormatException("Not a known type: %d" % num_type)
 269         return obj_class()
 270
 271     def _parse_object(self, f):
 272         """Parse a new style object, setting self._text."""
 273         size = os.path.getsize(f.name)
 274         map = mmap.mmap(f.fileno(), size, access=mmap.ACCESS_READ)
 275         try:
 276             # skip type and size; type must have already been determined, and
 277             # we trust zlib to fail if it's otherwise corrupted
 278             byte = ord(map[0])
 279             used = 1
 280             while (byte & 0x80) != 0:
 281                 byte = ord(map[used])
 282                 used += 1
 283             raw = map[used:]
 284             self.set_raw_string(_decompress(raw))
 285         finally:
 286             map.close()
 287
 288     @classmethod
 289     def _is_legacy_object(cls, magic):
 290         b0, b1 = map(ord, magic)
 291         word = (b0 << 8) + b1
 292         return b0 == 0x78 and (word % 31) == 0
 293
 294     @classmethod
 295     def _parse_file_header(cls, f):
 296         magic = f.read(2)
 297         if cls._is_legacy_object(magic):
 298             return cls._parse_legacy_object_header(magic, f)
 299         else:
 300             return cls._parse_object_header(magic, f)
 301
 302     def __init__(self):
 303         """Don't call this directly"""
 304         self._sha = None
 305         self._path = None
 306         self._file = None
 307         self._chunked_text = []
 308         self._needs_parsing = False
 309         self._needs_serialization = True
 310
 311     def _deserialize(self, chunks):
 312         raise NotImplementedError(self._deserialize)
 313
 314     def _serialize(self):
 315         raise NotImplementedError(self._serialize)
 316
 317     def _parse_path(self):
 318         f = GitFile(self._path, 'rb')
 319         try:
 320             self._parse_file(f)
 321         finally:
 322             f.close()
 323
 324     def _parse_file(self, f):
 325         magic = f.read(2)
 326         if self._is_legacy_object(magic):
 327             self._parse_legacy_object(f)
 328         else:
 329             self._parse_object(f)
 330
 331     @classmethod
 332     def from_path(cls, path):
 333         f = GitFile(path, 'rb')
 334         try:
 335             obj = cls.from_file(f)
 336             obj._path = path
 337             obj._sha = FixedSha(filename_to_hex(path))
 338             obj._file = None
 339             return obj
 340         finally:
 341             f.close()
 342
 343     @classmethod
 344     def from_file(cls, f):
 345         """Get the contents of a SHA file on disk."""
 346         try:
 347             obj = cls._parse_file_header(f)
 348             obj._sha = None
 349             obj._needs_parsing = True
 350             obj._needs_serialization = True
 351             obj._file = f
 352             return obj
 353         except (IndexError, ValueError), e:
 354             raise ObjectFormatException("invalid object header")
 355
 356     @staticmethod
 357     def from_raw_string(type_num, string):
 358         """Creates an object of the indicated type from the raw string given.
 359
 360         :param type_num: The numeric type of the object.
 361         :param string: The raw uncompressed contents.
 362         """
 363         obj = object_class(type_num)()
 364         obj.set_raw_string(string)
 365         return obj
 366
 367     @staticmethod
 368     def from_raw_chunks(type_num, chunks):
 369         """Creates an object of the indicated type from the raw chunks given.
 370
 371         :param type_num: The numeric type of the object.
 372         :param chunks: An iterable of the raw uncompressed contents.
 373         """
 374         obj = object_class(type_num)()
 375         obj.set_raw_chunks(chunks)
 376         return obj
 377
 378     @classmethod
 379     def from_string(cls, string):
 380         """Create a ShaFile from a string."""
 381         obj = cls()
 382         obj.set_raw_string(string)
 383         return obj
 384
 385     def _check_has_member(self, member, error_msg):
 386         """Check that the object has a given member variable.
 387
 388         :param member: the member variable to check for
 389         :param error_msg: the message for an error if the member is missing
 390         :raise ObjectFormatException: with the given error_msg if member is
 391             missing or is None
 392         """
 393         if getattr(self, member, None) is None:
 394             raise ObjectFormatException(error_msg)
 395
 396     def check(self):
 397         """Check this object for internal consistency.
 398
 399         :raise ObjectFormatException: if the object is malformed in some way
 400         :raise ChecksumMismatch: if the object was created with a SHA that does
 401             not match its contents
 402         """
 403         # TODO: if we find that error-checking during object parsing is a
 404         # performance bottleneck, those checks should be moved to the class's
 405         # check() method during optimization so we can still check the object
 406         # when necessary.
 407         old_sha = self.id
 408         try:
 409             self._deserialize(self.as_raw_chunks())
 410             self._sha = None
 411             new_sha = self.id
 412         except Exception, e:
 413             raise ObjectFormatException(e)
 414         if old_sha != new_sha:
 415             raise ChecksumMismatch(new_sha, old_sha)
 416
 417     def _header(self):
 418         return object_header(self.type, self.raw_length())
 419
 420     def raw_length(self):
 421         """Returns the length of the raw string of this object."""
 422         ret = 0
 423         for chunk in self.as_raw_chunks():
 424             ret += len(chunk)
 425         return ret
 426
 427     def _make_sha(self):
 428         ret = make_sha()
 429         ret.update(self._header())
 430         for chunk in self.as_raw_chunks():
 431             ret.update(chunk)
 432         return ret
 433
 434     def sha(self):
 435         """The SHA1 object that is the name of this object."""
 436         if self._sha is None or self._needs_serialization:
 437             # this is a local because as_raw_chunks() overwrites self._sha
 438             new_sha = make_sha()
 439             new_sha.update(self._header())
 440             for chunk in self.as_raw_chunks():
 441                 new_sha.update(chunk)
 442             self._sha = new_sha
 443         return self._sha
 444
 445     @property
 446     def id(self):
 447         return self.sha().hexdigest()
 448
 449     def get_type(self):
 450         return self.type_num
 451
 452     def set_type(self, type):
 453         self.type_num = type
 454
 455     # DEPRECATED: use type_num or type_name as needed.
 456     type = property(get_type, set_type)
 457
 458     def __repr__(self):
 459         return "<%s %s>" % (self.__class__.__name__, self.id)
 460
 461     def __ne__(self, other):
 462         return self.id != other.id
 463
 464     def __eq__(self, other):
 465         """Return true if the sha of the two objects match.
 466
 467         The __le__ etc methods aren't overriden as they make no sense,
 468         certainly at this level.
 469         """
 470         return self.id == other.id
 471
 472
 473 class Blob(ShaFile):
 474     """A Git Blob object."""
 475
 476     type_name = 'blob'
 477     type_num = 3
 478
 479     def __init__(self):
 480         super(Blob, self).__init__()
 481         self._chunked_text = []
 482         self._needs_parsing = False
 483         self._needs_serialization = False
 484
 485     def _get_data(self):
 486         return self.as_raw_string()
 487
 488     def _set_data(self, data):
 489         self.set_raw_string(data)
 490
 491     data = property(_get_data, _set_data,
 492                     "The text contained within the blob object.")
 493
 494     def _get_chunked(self):
 495         self._ensure_parsed()
 496         return self._chunked_text
 497
 498     def _set_chunked(self, chunks):
 499         self._chunked_text = chunks
 500
 501     def _serialize(self):
 502         if not self._chunked_text:
 503             self._ensure_parsed()
 504         self._needs_serialization = False
 505         return self._chunked_text
 506
 507     def _deserialize(self, chunks):
 508         self._chunked_text = chunks
 509
 510     chunked = property(_get_chunked, _set_chunked,
 511         "The text within the blob object, as chunks (not necessarily lines).")
 512
 513     @classmethod
 514     def from_path(cls, path):
 515         blob = ShaFile.from_path(path)
 516         if not isinstance(blob, cls):
 517             raise NotBlobError(path)
 518         return blob
 519
 520     def check(self):
 521         """Check this object for internal consistency.
 522
 523         :raise ObjectFormatException: if the object is malformed in some way
 524         """
 525         super(Blob, self).check()
 526
 527
 528 def _parse_tag_or_commit(text):
 529     """Parse tag or commit text.
 530
 531     :param text: the raw text of the tag or commit object.
 532     :yield: tuples of (field, value), one per header line, in the order read
 533         from the text, possibly including duplicates. Includes a field named
 534         None for the freeform tag/commit text.
 535     """
 536     f = StringIO(text)
 537     for l in f:
 538         l = l.rstrip("\n")
 539         if l == "":
 540             # Empty line indicates end of headers
 541             break
 542         yield l.split(" ", 1)
 543     yield (None, f.read())
 544     f.close()
 545
 546
 547 def parse_tag(text):
 548     return _parse_tag_or_commit(text)
 549
 550
 551 class Tag(ShaFile):
 552     """A Git Tag object."""
 553
 554     type_name = 'tag'
 555     type_num = 4
 556
 557     def __init__(self):
 558         super(Tag, self).__init__()
 559         self._tag_timezone_neg_utc = False
 560
 561     @classmethod
 562     def from_path(cls, filename):
 563         tag = ShaFile.from_path(filename)
 564         if not isinstance(tag, cls):
 565             raise NotTagError(filename)
 566         return tag
 567
 568     def check(self):
 569         """Check this object for internal consistency.
 570
 571         :raise ObjectFormatException: if the object is malformed in some way
 572         """
 573         super(Tag, self).check()
 574         self._check_has_member("_object_sha", "missing object sha")
 575         self._check_has_member("_object_class", "missing object type")
 576         self._check_has_member("_name", "missing tag name")
 577
 578         if not self._name:
 579             raise ObjectFormatException("empty tag name")
 580
 581         check_hexsha(self._object_sha, "invalid object sha")
 582
 583         if getattr(self, "_tagger", None):
 584             check_identity(self._tagger, "invalid tagger")
 585
 586         last = None
 587         for field, _ in parse_tag("".join(self._chunked_text)):
 588             if field == _OBJECT_HEADER and last is not None:
 589                 raise ObjectFormatException("unexpected object")
 590             elif field == _TYPE_HEADER and last != _OBJECT_HEADER:
 591                 raise ObjectFormatException("unexpected type")
 592             elif field == _TAG_HEADER and last != _TYPE_HEADER:
 593                 raise ObjectFormatException("unexpected tag name")
 594             elif field == _TAGGER_HEADER and last != _TAG_HEADER:
 595                 raise ObjectFormatException("unexpected tagger")
 596             last = field
 597
 598     def _serialize(self):
 599         chunks = []
 600         chunks.append("%s %s\n" % (_OBJECT_HEADER, self._object_sha))
 601         chunks.append("%s %s\n" % (_TYPE_HEADER, self._object_class.type_name))
 602         chunks.append("%s %s\n" % (_TAG_HEADER, self._name))
 603         if self._tagger:
 604             if self._tag_time is None:
 605                 chunks.append("%s %s\n" % (_TAGGER_HEADER, self._tagger))
 606             else:
 607                 chunks.append("%s %s %d %s\n" % (
 608                   _TAGGER_HEADER, self._tagger, self._tag_time,
 609                   format_timezone(self._tag_timezone,
 610                     self._tag_timezone_neg_utc)))
 611         chunks.append("\n") # To close headers
 612         chunks.append(self._message)
 613         return chunks
 614
 615     def _deserialize(self, chunks):
 616         """Grab the metadata attached to the tag"""
 617         self._tagger = None
 618         for field, value in parse_tag("".join(chunks)):
 619             if field == _OBJECT_HEADER:
 620                 self._object_sha = value
 621             elif field == _TYPE_HEADER:
 622                 obj_class = object_class(value)
 623                 if not obj_class:
 624                     raise ObjectFormatException("Not a known type: %s" % value)
 625                 self._object_class = obj_class
 626             elif field == _TAG_HEADER:
 627                 self._name = value
 628             elif field == _TAGGER_HEADER:
 629                 try:
 630                     sep = value.index("> ")
 631                 except ValueError:
 632                     self._tagger = value
 633                     self._tag_time = None
 634                     self._tag_timezone = None
 635                     self._tag_timezone_neg_utc = False
 636                 else:
 637                     self._tagger = value[0:sep+1]
 638                     try:
 639                         (timetext, timezonetext) = value[sep+2:].rsplit(" ", 1)
 640                         self._tag_time = int(timetext)
 641                         self._tag_timezone, self._tag_timezone_neg_utc = \
 642                                 parse_timezone(timezonetext)
 643                     except ValueError, e:
 644                         raise ObjectFormatException(e)
 645             elif field is None:
 646                 self._message = value
 647             else:
 648                 raise ObjectFormatException("Unknown field %s" % field)
 649
 650     def _get_object(self):
 651         """Get the object pointed to by this tag.
 652
 653         :return: tuple of (object class, sha).
 654         """
 655         self._ensure_parsed()
 656         return (self._object_class, self._object_sha)
 657
 658     def _set_object(self, value):
 659         self._ensure_parsed()
 660         (self._object_class, self._object_sha) = value
 661         self._needs_serialization = True
 662
 663     object = property(_get_object, _set_object)
 664
 665     name = serializable_property("name", "The name of this tag")
 666     tagger = serializable_property("tagger",
 667         "Returns the name of the person who created this tag")
 668     tag_time = serializable_property("tag_time",
 669         "The creation timestamp of the tag.  As the number of seconds since the epoch")
 670     tag_timezone = serializable_property("tag_timezone",
 671         "The timezone that tag_time is in.")
 672     message = serializable_property("message", "The message attached to this tag")
 673
 674
 675 def parse_tree(text):
 676     """Parse a tree text.
 677
 678     :param text: Serialized text to parse
 679     :yields: tuples of (name, mode, sha)
 680     """
 681     count = 0
 682     l = len(text)
 683     while count < l:
 684         mode_end = text.index(' ', count)
 685         mode = int(text[count:mode_end], 8)
 686         name_end = text.index('\0', mode_end)
 687         name = text[mode_end+1:name_end]
 688         count = name_end+21
 689         sha = text[name_end+1:count]
 690         yield (name, mode, sha_to_hex(sha))
 691
 692
 693 def serialize_tree(items):
 694     """Serialize the items in a tree to a text.
 695
 696     :param items: Sorted iterable over (name, mode, sha) tuples
 697     :return: Serialized tree text as chunks
 698     """
 699     for name, mode, hexsha in items:
 700         yield "%04o %s\0%s" % (mode, name, hex_to_sha(hexsha))
 701
 702
 703 def sorted_tree_items(entries):
 704     """Iterate over a tree entries dictionary in the order in which
 705     the items would be serialized.
 706
 707     :param entries: Dictionary mapping names to (mode, sha) tuples
 708     :return: Iterator over (name, mode, hexsha)
 709     """
 710     for name, entry in sorted(entries.iteritems(), cmp=cmp_entry):
 711         mode, hexsha = entry
 712         # Stricter type checks than normal to mirror checks in the C version.
 713         mode = int(mode)
 714         if not isinstance(hexsha, str):
 715             raise TypeError('Expected a string for SHA, got %r' % hexsha)
 716         yield name, mode, hexsha
 717
 718
 719 def cmp_entry((name1, value1), (name2, value2)):
 720     """Compare two tree entries."""
 721     if stat.S_ISDIR(value1[0]):
 722         name1 += "/"
 723     if stat.S_ISDIR(value2[0]):
 724         name2 += "/"
 725     return cmp(name1, name2)
 726
 727
 728 class Tree(ShaFile):
 729     """A Git tree object"""
 730
 731     type_name = 'tree'
 732     type_num = 2
 733
 734     def __init__(self):
 735         super(Tree, self).__init__()
 736         self._entries = {}
 737
 738     @classmethod
 739     def from_path(cls, filename):
 740         tree = ShaFile.from_path(filename)
 741         if not isinstance(tree, cls):
 742             raise NotTreeError(filename)
 743         return tree
 744
 745     def __contains__(self, name):
 746         self._ensure_parsed()
 747         return name in self._entries
 748
 749     def __getitem__(self, name):
 750         self._ensure_parsed()
 751         return self._entries[name]
 752
 753     def __setitem__(self, name, value):
 754         """Set a tree entry by name.
 755
 756         :param name: The name of the entry, as a string.
 757         :param value: A tuple of (mode, hexsha), where mode is the mode of the
 758             entry as an integral type and hexsha is the hex SHA of the entry as
 759             a string.
 760         """
 761         mode, hexsha = value
 762         self._ensure_parsed()
 763         self._entries[name] = (mode, hexsha)
 764         self._needs_serialization = True
 765
 766     def __delitem__(self, name):
 767         self._ensure_parsed()
 768         del self._entries[name]
 769         self._needs_serialization = True
 770
 771     def __len__(self):
 772         self._ensure_parsed()
 773         return len(self._entries)
 774
 775     def __iter__(self):
 776         self._ensure_parsed()
 777         return iter(self._entries)
 778
 779     def add(self, mode, name, hexsha):
 780         """Add an entry to the tree.
 781
 782         :param mode: The mode of the entry as an integral type. Not all possible
 783             modes are supported by git; see check() for details.
 784         :param name: The name of the entry, as a string.
 785         :param hexsha: The hex SHA of the entry as a string.
 786         """
 787         self._ensure_parsed()
 788         self._entries[name] = mode, hexsha
 789         self._needs_serialization = True
 790
 791     def entries(self):
 792         """Return a list of tuples describing the tree entries"""
 793         self._ensure_parsed()
 794         # The order of this is different from iteritems() for historical
 795         # reasons
 796         return [
 797             (mode, name, hexsha) for (name, mode, hexsha) in self.iteritems()]
 798
 799     def iteritems(self):
 800         """Iterate over entries in the order in which they would be serialized.
 801
 802         :return: Iterator over (name, mode, sha) tuples
 803         """
 804         self._ensure_parsed()
 805         return sorted_tree_items(self._entries)
 806
 807     def _deserialize(self, chunks):
 808         """Grab the entries in the tree"""
 809         try:
 810             parsed_entries = parse_tree("".join(chunks))
 811         except ValueError, e:
 812             raise ObjectFormatException(e)
 813         # TODO: list comprehension is for efficiency in the common (small) case;
 814         # if memory efficiency in the large case is a concern, use a genexp.
 815         self._entries = dict([(n, (m, s)) for n, m, s in parsed_entries])
 816
 817     def check(self):
 818         """Check this object for internal consistency.
 819
 820         :raise ObjectFormatException: if the object is malformed in some way
 821         """
 822         super(Tree, self).check()
 823         last = None
 824         allowed_modes = (stat.S_IFREG | 0755, stat.S_IFREG | 0644,
 825                          stat.S_IFLNK, stat.S_IFDIR, S_IFGITLINK,
 826                          # TODO: optionally exclude as in git fsck --strict
 827                          stat.S_IFREG | 0664)
 828         for name, mode, sha in parse_tree("".join(self._chunked_text)):
 829             check_hexsha(sha, 'invalid sha %s' % sha)
 830             if '/' in name or name in ('', '.', '..'):
 831                 raise ObjectFormatException('invalid name %s' % name)
 832
 833             if mode not in allowed_modes:
 834                 raise ObjectFormatException('invalid mode %06o' % mode)
 835
 836             entry = (name, (mode, sha))
 837             if last:
 838                 if cmp_entry(last, entry) > 0:
 839                     raise ObjectFormatException('entries not sorted')
 840                 if name == last[0]:
 841                     raise ObjectFormatException('duplicate entry %s' % name)
 842             last = entry
 843
 844     def _serialize(self):
 845         return list(serialize_tree(self.iteritems()))
 846
 847     def as_pretty_string(self):
 848         text = []
 849         for name, mode, hexsha in self.iteritems():
 850             if mode & stat.S_IFDIR:
 851                 kind = "tree"
 852             else:
 853                 kind = "blob"
 854             text.append("%04o %s %s\t%s\n" % (mode, kind, hexsha, name))
 855         return "".join(text)
 856
 857
 858 def parse_timezone(text):
 859     offset = int(text)
 860     negative_utc = (offset == 0 and text[0] == '-')
 861     signum = (offset < 0) and -1 or 1
 862     offset = abs(offset)
 863     hours = int(offset / 100)
 864     minutes = (offset % 100)
 865     return signum * (hours * 3600 + minutes * 60), negative_utc
 866
 867
 868 def format_timezone(offset, negative_utc=False):
 869     if offset % 60 != 0:
 870         raise ValueError("Unable to handle non-minute offset.")
 871     if offset < 0 or (offset == 0 and negative_utc):
 872         sign = '-'
 873     else:
 874         sign = '+'
 875     offset = abs(offset)
 876     return '%c%02d%02d' % (sign, offset / 3600, (offset / 60) % 60)
 877
 878
 879 def parse_commit(text):
 880     return _parse_tag_or_commit(text)
 881
 882
 883 class Commit(ShaFile):
 884     """A git commit object"""
 885
 886     type_name = 'commit'
 887     type_num = 1
 888
 889     def __init__(self):
 890         super(Commit, self).__init__()
 891         self._parents = []
 892         self._encoding = None
 893         self._extra = {}
 894         self._author_timezone_neg_utc = False
 895         self._commit_timezone_neg_utc = False
 896
 897     @classmethod
 898     def from_path(cls, path):
 899         commit = ShaFile.from_path(path)
 900         if not isinstance(commit, cls):
 901             raise NotCommitError(path)
 902         return commit
 903
 904     def _deserialize(self, chunks):
 905         self._parents = []
 906         self._extra = []
 907         self._author = None
 908         for field, value in parse_commit("".join(self._chunked_text)):
 909             if field == _TREE_HEADER:
 910                 self._tree = value
 911             elif field == _PARENT_HEADER:
 912                 self._parents.append(value)
 913             elif field == _AUTHOR_HEADER:
 914                 self._author, timetext, timezonetext = value.rsplit(" ", 2)
 915                 self._author_time = int(timetext)
 916                 self._author_timezone, self._author_timezone_neg_utc =\
 917                     parse_timezone(timezonetext)
 918             elif field == _COMMITTER_HEADER:
 919                 self._committer, timetext, timezonetext = value.rsplit(" ", 2)
 920                 self._commit_time = int(timetext)
 921                 self._commit_timezone, self._commit_timezone_neg_utc =\
 922                     parse_timezone(timezonetext)
 923             elif field == _ENCODING_HEADER:
 924                 self._encoding = value
 925             elif field is None:
 926                 self._message = value
 927             else:
 928                 self._extra.append((field, value))
 929
 930     def check(self):
 931         """Check this object for internal consistency.
 932
 933         :raise ObjectFormatException: if the object is malformed in some way
 934         """
 935         super(Commit, self).check()
 936         self._check_has_member("_tree", "missing tree")
 937         self._check_has_member("_author", "missing author")
 938         self._check_has_member("_committer", "missing committer")
 939         # times are currently checked when set
 940
 941         for parent in self._parents:
 942             check_hexsha(parent, "invalid parent sha")
 943         check_hexsha(self._tree, "invalid tree sha")
 944
 945         check_identity(self._author, "invalid author")
 946         check_identity(self._committer, "invalid committer")
 947
 948         last = None
 949         for field, _ in parse_commit("".join(self._chunked_text)):
 950             if field == _TREE_HEADER and last is not None:
 951                 raise ObjectFormatException("unexpected tree")
 952             elif field == _PARENT_HEADER and last not in (_PARENT_HEADER,
 953                                                           _TREE_HEADER):
 954                 raise ObjectFormatException("unexpected parent")
 955             elif field == _AUTHOR_HEADER and last not in (_TREE_HEADER,
 956                                                           _PARENT_HEADER):
 957                 raise ObjectFormatException("unexpected author")
 958             elif field == _COMMITTER_HEADER and last != _AUTHOR_HEADER:
 959                 raise ObjectFormatException("unexpected committer")
 960             elif field == _ENCODING_HEADER and last != _COMMITTER_HEADER:
 961                 raise ObjectFormatException("unexpected encoding")
 962             last = field
 963
 964         # TODO: optionally check for duplicate parents
 965
 966     def _serialize(self):
 967         chunks = []
 968         chunks.append("%s %s\n" % (_TREE_HEADER, self._tree))
 969         for p in self._parents:
 970             chunks.append("%s %s\n" % (_PARENT_HEADER, p))
 971         chunks.append("%s %s %s %s\n" % (
 972           _AUTHOR_HEADER, self._author, str(self._author_time),
 973           format_timezone(self._author_timezone,
 974                           self._author_timezone_neg_utc)))
 975         chunks.append("%s %s %s %s\n" % (
 976           _COMMITTER_HEADER, self._committer, str(self._commit_time),
 977           format_timezone(self._commit_timezone,
 978                           self._commit_timezone_neg_utc)))
 979         if self.encoding:
 980             chunks.append("%s %s\n" % (_ENCODING_HEADER, self.encoding))
 981         for k, v in self.extra:
 982             if "\n" in k or "\n" in v:
 983                 raise AssertionError("newline in extra data: %r -> %r" % (k, v))
 984             chunks.append("%s %s\n" % (k, v))
 985         chunks.append("\n") # There must be a new line after the headers
 986         chunks.append(self._message)
 987         return chunks
 988
 989     tree = serializable_property("tree", "Tree that is the state of this commit")
 990
 991     def _get_parents(self):
 992         """Return a list of parents of this commit."""
 993         self._ensure_parsed()
 994         return self._parents
 995
 996     def _set_parents(self, value):
 997         """Set a list of parents of this commit."""
 998         self._ensure_parsed()
 999         self._needs_serialization = True
1000         self._parents = value
1001
1002     parents = property(_get_parents, _set_parents)
1003
1004     def _get_extra(self):
1005         """Return extra settings of this commit."""
1006         self._ensure_parsed()
1007         return self._extra
1008
1009     extra = property(_get_extra)
1010
1011     author = serializable_property("author",
1012         "The name of the author of the commit")
1013
1014     committer = serializable_property("committer",
1015         "The name of the committer of the commit")
1016
1017     message = serializable_property("message",
1018         "The commit message")
1019
1020     commit_time = serializable_property("commit_time",
1021         "The timestamp of the commit. As the number of seconds since the epoch.")
1022
1023     commit_timezone = serializable_property("commit_timezone",
1024         "The zone the commit time is in")
1025
1026     author_time = serializable_property("author_time",
1027         "The timestamp the commit was written. as the number of seconds since the epoch.")
1028
1029     author_timezone = serializable_property("author_timezone",
1030         "Returns the zone the author time is in.")
1031
1032     encoding = serializable_property("encoding",
1033         "Encoding of the commit message.")
1034
1035
1036 OBJECT_CLASSES = (
1037     Commit,
1038     Tree,
1039     Blob,
1040     Tag,
1041     )
1042
1043 _TYPE_MAP = {}
1044
1045 for cls in OBJECT_CLASSES:
1046     _TYPE_MAP[cls.type_name] = cls
1047     _TYPE_MAP[cls.type_num] = cls
1048
1049
1050
1051 # Hold on to the pure-python implementations for testing
1052 _parse_tree_py = parse_tree
1053 _sorted_tree_items_py = sorted_tree_items
1054 try:
1055     # Try to import C versions
1056     from dulwich._objects import parse_tree, sorted_tree_items
1057 except ImportError:
1058     pass