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