5250bd7d5625566c1a26c958c82d467f9441e81e
[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 time
32 import zlib
33
34 from dulwich.errors import (
35     NotBlobError,
36     NotCommitError,
37     NotTagError,
38     NotTreeError,
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 serializable_property(name, docstring=None):
88     def set(obj, value):
89         obj._ensure_parsed()
90         setattr(obj, "_"+name, value)
91         obj._needs_serialization = True
92     def get(obj):
93         obj._ensure_parsed()
94         return getattr(obj, "_"+name)
95     return property(get, set, doc=docstring)
96
97
98 def object_class(type):
99     """Get the object class corresponding to the given type.
100
101     :param type: Either a type name string or a numeric type.
102     :return: The ShaFile subclass corresponding to the given type.
103     """
104     return _TYPE_MAP[type]
105
106
107 class ShaFile(object):
108     """A git SHA file."""
109
110     @classmethod
111     def _parse_legacy_object(cls, map):
112         """Parse a legacy object, creating it and setting object._text"""
113         text = _decompress(map)
114         object = None
115         for cls in OBJECT_CLASSES:
116             if text.startswith(cls.type_name):
117                 object = cls()
118                 text = text[len(cls.type_name):]
119                 break
120         assert object is not None, "%s is not a known object type" % text[:9]
121         assert text[0] == ' ', "%s is not a space" % text[0]
122         text = text[1:]
123         size = 0
124         i = 0
125         while text[0] >= '0' and text[0] <= '9':
126             if i > 0 and size == 0:
127                 raise AssertionError("Size is not in canonical format")
128             size = (size * 10) + int(text[0])
129             text = text[1:]
130             i += 1
131         object._size = size
132         assert text[0] == "\0", "Size not followed by null"
133         text = text[1:]
134         object.set_raw_string(text)
135         return object
136
137     def as_legacy_object_chunks(self):
138         compobj = zlib.compressobj()
139         yield compobj.compress(self._header())
140         for chunk in self.as_raw_chunks():
141             yield compobj.compress(chunk)
142         yield compobj.flush()
143
144     def as_legacy_object(self):
145         return "".join(self.as_legacy_object_chunks())
146
147     def as_raw_chunks(self):
148         if self._needs_serialization:
149             self._chunked_text = self._serialize()
150             self._needs_serialization = False
151         return self._chunked_text
152
153     def as_raw_string(self):
154         return "".join(self.as_raw_chunks())
155
156     def __str__(self):
157         return self.as_raw_string()
158
159     def __hash__(self):
160         return hash(self.id)
161
162     def as_pretty_string(self):
163         return self.as_raw_string()
164
165     def _ensure_parsed(self):
166         if self._needs_parsing:
167             self._deserialize(self._chunked_text)
168             self._needs_parsing = False
169
170     def set_raw_string(self, text):
171         if type(text) != str:
172             raise TypeError(text)
173         self.set_raw_chunks([text])
174
175     def set_raw_chunks(self, chunks):
176         self._chunked_text = chunks
177         self._sha = None
178         self._needs_parsing = True
179         self._needs_serialization = False
180
181     @classmethod
182     def _parse_object(cls, map):
183         """Parse a new style object , creating it and setting object._text"""
184         used = 0
185         byte = ord(map[used])
186         used += 1
187         type_num = (byte >> 4) & 7
188         try:
189             object = object_class(type_num)()
190         except KeyError:
191             raise AssertionError("Not a known type: %d" % type_num)
192         while (byte & 0x80) != 0:
193             byte = ord(map[used])
194             used += 1
195         raw = map[used:]
196         object.set_raw_string(_decompress(raw))
197         return object
198
199     @classmethod
200     def _parse_file(cls, map):
201         word = (ord(map[0]) << 8) + ord(map[1])
202         if ord(map[0]) == 0x78 and (word % 31) == 0:
203             return cls._parse_legacy_object(map)
204         else:
205             return cls._parse_object(map)
206
207     def __init__(self):
208         """Don't call this directly"""
209         self._sha = None
210
211     def _deserialize(self, chunks):
212         raise NotImplementedError(self._deserialize)
213
214     def _serialize(self):
215         raise NotImplementedError(self._serialize)
216
217     @classmethod
218     def from_file(cls, filename):
219         """Get the contents of a SHA file on disk"""
220         size = os.path.getsize(filename)
221         f = GitFile(filename, 'rb')
222         try:
223             map = mmap.mmap(f.fileno(), size, access=mmap.ACCESS_READ)
224             shafile = cls._parse_file(map)
225             return shafile
226         finally:
227             f.close()
228
229     @staticmethod
230     def from_raw_string(type_num, string):
231         """Creates an object of the indicated type from the raw string given.
232
233         :param type_num: The numeric type of the object.
234         :param string: The raw uncompressed contents.
235         """
236         obj = object_class(type_num)()
237         obj.set_raw_string(string)
238         return obj
239
240     @staticmethod
241     def from_raw_chunks(type_num, chunks):
242         """Creates an object of the indicated type from the raw chunks given.
243
244         :param type_num: The numeric type of the object.
245         :param chunks: An iterable of the raw uncompressed contents.
246         """
247         obj = object_class(type_num)()
248         obj.set_raw_chunks(chunks)
249         return obj
250
251     @classmethod
252     def from_string(cls, string):
253         """Create a blob from a string."""
254         obj = cls()
255         obj.set_raw_string(string)
256         return obj
257
258     def _header(self):
259         return "%s %lu\0" % (self.type_name, self.raw_length())
260
261     def raw_length(self):
262         """Returns the length of the raw string of this object."""
263         ret = 0
264         for chunk in self.as_raw_chunks():
265             ret += len(chunk)
266         return ret
267
268     def _make_sha(self):
269         ret = make_sha()
270         ret.update(self._header())
271         for chunk in self.as_raw_chunks():
272             ret.update(chunk)
273         return ret
274
275     def sha(self):
276         """The SHA1 object that is the name of this object."""
277         if self._needs_serialization or self._sha is None:
278             self._sha = self._make_sha()
279         return self._sha
280
281     @property
282     def id(self):
283         return self.sha().hexdigest()
284
285     def get_type(self):
286         return self.type_num
287
288     def set_type(self, type):
289         self.type_num = type
290
291     # DEPRECATED: use type_num or type_name as needed.
292     type = property(get_type, set_type)
293
294     def __repr__(self):
295         return "<%s %s>" % (self.__class__.__name__, self.id)
296
297     def __ne__(self, other):
298         return self.id != other.id
299
300     def __eq__(self, other):
301         """Return true if the sha of the two objects match.
302
303         The __le__ etc methods aren't overriden as they make no sense,
304         certainly at this level.
305         """
306         return self.id == other.id
307
308
309 class Blob(ShaFile):
310     """A Git Blob object."""
311
312     type_name = 'blob'
313     type_num = 3
314
315     def __init__(self):
316         super(Blob, self).__init__()
317         self._chunked_text = []
318         self._needs_parsing = False
319         self._needs_serialization = False
320
321     def _get_data(self):
322         return self.as_raw_string()
323
324     def _set_data(self, data):
325         self.set_raw_string(data)
326
327     data = property(_get_data, _set_data,
328             "The text contained within the blob object.")
329
330     def _get_chunked(self):
331         return self._chunked_text
332
333     def _set_chunked(self, chunks):
334         self._chunked_text = chunks
335
336     chunked = property(_get_chunked, _set_chunked,
337         "The text within the blob object, as chunks (not necessarily lines).")
338
339     @classmethod
340     def from_file(cls, filename):
341         blob = ShaFile.from_file(filename)
342         if not isinstance(blob, cls):
343             raise NotBlobError(filename)
344         return blob
345
346
347 class Tag(ShaFile):
348     """A Git Tag object."""
349
350     type_name = 'tag'
351     type_num = 4
352
353     def __init__(self):
354         super(Tag, self).__init__()
355         self._needs_parsing = False
356         self._needs_serialization = True
357
358     @classmethod
359     def from_file(cls, filename):
360         tag = ShaFile.from_file(filename)
361         if not isinstance(tag, cls):
362             raise NotTagError(filename)
363         return tag
364
365     @classmethod
366     def from_string(cls, string):
367         """Create a blob from a string."""
368         shafile = cls()
369         shafile.set_raw_string(string)
370         return shafile
371
372     def _serialize(self):
373         chunks = []
374         chunks.append("%s %s\n" % (_OBJECT_HEADER, self._object_sha))
375         chunks.append("%s %s\n" % (_TYPE_HEADER, self._object_class.type_name))
376         chunks.append("%s %s\n" % (_TAG_HEADER, self._name))
377         if self._tagger:
378             if self._tag_time is None:
379                 chunks.append("%s %s\n" % (_TAGGER_HEADER, self._tagger))
380             else:
381                 chunks.append("%s %s %d %s\n" % (
382                   _TAGGER_HEADER, self._tagger, self._tag_time,
383                   format_timezone(self._tag_timezone)))
384         chunks.append("\n") # To close headers
385         chunks.append(self._message)
386         return chunks
387
388     def _deserialize(self, chunks):
389         """Grab the metadata attached to the tag"""
390         self._tagger = None
391         f = StringIO("".join(chunks))
392         for l in f:
393             l = l.rstrip("\n")
394             if l == "":
395                 break # empty line indicates end of headers
396             (field, value) = l.split(" ", 1)
397             if field == _OBJECT_HEADER:
398                 self._object_sha = value
399             elif field == _TYPE_HEADER:
400                 self._object_class = object_class(value)
401             elif field == _TAG_HEADER:
402                 self._name = value
403             elif field == _TAGGER_HEADER:
404                 try:
405                     sep = value.index("> ")
406                 except ValueError:
407                     self._tagger = value
408                     self._tag_time = None
409                     self._tag_timezone = None
410                 else:
411                     self._tagger = value[0:sep+1]
412                     (timetext, timezonetext) = value[sep+2:].rsplit(" ", 1)
413                     try:
414                         self._tag_time = int(timetext)
415                     except ValueError: #Not a unix timestamp
416                         self._tag_time = time.strptime(timetext)
417                     self._tag_timezone = parse_timezone(timezonetext)
418             else:
419                 raise AssertionError("Unknown field %s" % field)
420         self._message = f.read()
421
422     def _get_object(self):
423         """Get the object pointed to by this tag.
424
425         :return: tuple of (object class, sha).
426         """
427         self._ensure_parsed()
428         return (self._object_class, self._object_sha)
429
430     def _set_object(self, value):
431         self._ensure_parsed()
432         (self._object_class, self._object_sha) = value
433         self._needs_serialization = True
434
435     object = property(_get_object, _set_object)
436
437     name = serializable_property("name", "The name of this tag")
438     tagger = serializable_property("tagger",
439         "Returns the name of the person who created this tag")
440     tag_time = serializable_property("tag_time",
441         "The creation timestamp of the tag.  As the number of seconds since the epoch")
442     tag_timezone = serializable_property("tag_timezone",
443         "The timezone that tag_time is in.")
444     message = serializable_property("message", "The message attached to this tag")
445
446
447 def parse_tree(text):
448     """Parse a tree text.
449
450     :param text: Serialized text to parse
451     :yields: tuples of (name, mode, sha)
452     """
453     count = 0
454     l = len(text)
455     while count < l:
456         mode_end = text.index(' ', count)
457         mode = int(text[count:mode_end], 8)
458         name_end = text.index('\0', mode_end)
459         name = text[mode_end+1:name_end]
460         count = name_end+21
461         sha = text[name_end+1:count]
462         yield (name, mode, sha_to_hex(sha))
463
464
465 def serialize_tree(items):
466     """Serialize the items in a tree to a text.
467
468     :param items: Sorted iterable over (name, mode, sha) tuples
469     :return: Serialized tree text as chunks
470     """
471     for name, mode, hexsha in items:
472         yield "%04o %s\0%s" % (mode, name, hex_to_sha(hexsha))
473
474
475 def sorted_tree_items(entries):
476     """Iterate over a tree entries dictionary in the order in which 
477     the items would be serialized.
478
479     :param entries: Dictionary mapping names to (mode, sha) tuples
480     :return: Iterator over (name, mode, sha)
481     """
482     def cmp_entry((name1, value1), (name2, value2)):
483         if stat.S_ISDIR(value1[0]):
484             name1 += "/"
485         if stat.S_ISDIR(value2[0]):
486             name2 += "/"
487         return cmp(name1, name2)
488     for name, entry in sorted(entries.iteritems(), cmp=cmp_entry):
489         yield name, entry[0], entry[1]
490
491
492 class Tree(ShaFile):
493     """A Git tree object"""
494
495     type_name = 'tree'
496     type_num = 2
497
498     def __init__(self):
499         super(Tree, self).__init__()
500         self._entries = {}
501         self._needs_parsing = False
502         self._needs_serialization = True
503
504     @classmethod
505     def from_file(cls, filename):
506         tree = ShaFile.from_file(filename)
507         if not isinstance(tree, cls):
508             raise NotTreeError(filename)
509         return tree
510
511     def __contains__(self, name):
512         self._ensure_parsed()
513         return name in self._entries
514
515     def __getitem__(self, name):
516         self._ensure_parsed()
517         return self._entries[name]
518
519     def __setitem__(self, name, value):
520         assert isinstance(value, tuple)
521         assert len(value) == 2
522         self._ensure_parsed()
523         self._entries[name] = value
524         self._needs_serialization = True
525
526     def __delitem__(self, name):
527         self._ensure_parsed()
528         del self._entries[name]
529         self._needs_serialization = True
530
531     def __len__(self):
532         self._ensure_parsed()
533         return len(self._entries)
534
535     def add(self, mode, name, hexsha):
536         assert type(mode) == int
537         assert type(name) == str
538         assert type(hexsha) == str
539         self._ensure_parsed()
540         self._entries[name] = mode, hexsha
541         self._needs_serialization = True
542
543     def entries(self):
544         """Return a list of tuples describing the tree entries"""
545         self._ensure_parsed()
546         # The order of this is different from iteritems() for historical
547         # reasons
548         return [
549             (mode, name, hexsha) for (name, mode, hexsha) in self.iteritems()]
550
551     def iteritems(self):
552         """Iterate over all entries in the order in which they would be
553         serialized.
554
555         :return: Iterator over (name, mode, sha) tuples
556         """
557         self._ensure_parsed()
558         return sorted_tree_items(self._entries)
559
560     def _deserialize(self, chunks):
561         """Grab the entries in the tree"""
562         parsed_entries = parse_tree("".join(chunks))
563         # TODO: list comprehension is for efficiency in the common (small) case;
564         # if memory efficiency in the large case is a concern, use a genexp.
565         self._entries = dict([(n, (m, s)) for n, m, s in parsed_entries])
566         self._needs_parsing = False
567
568     def _serialize(self):
569         return list(serialize_tree(self.iteritems()))
570
571     def as_pretty_string(self):
572         text = []
573         for name, mode, hexsha in self.iteritems():
574             if mode & stat.S_IFDIR:
575                 kind = "tree"
576             else:
577                 kind = "blob"
578             text.append("%04o %s %s\t%s\n" % (mode, kind, hexsha, name))
579         return "".join(text)
580
581
582 def parse_timezone(text):
583     offset = int(text)
584     signum = (offset < 0) and -1 or 1
585     offset = abs(offset)
586     hours = int(offset / 100)
587     minutes = (offset % 100)
588     return signum * (hours * 3600 + minutes * 60)
589
590
591 def format_timezone(offset):
592     if offset % 60 != 0:
593         raise ValueError("Unable to handle non-minute offset.")
594     sign = (offset < 0) and '-' or '+'
595     offset = abs(offset)
596     return '%c%02d%02d' % (sign, offset / 3600, (offset / 60) % 60)
597
598
599 class Commit(ShaFile):
600     """A git commit object"""
601
602     type_name = 'commit'
603     type_num = 1
604
605     def __init__(self):
606         super(Commit, self).__init__()
607         self._parents = []
608         self._encoding = None
609         self._needs_parsing = False
610         self._needs_serialization = True
611         self._extra = {}
612
613     @classmethod
614     def from_file(cls, filename):
615         commit = ShaFile.from_file(filename)
616         if not isinstance(commit, cls):
617             raise NotCommitError(filename)
618         return commit
619
620     def _deserialize(self, chunks):
621         self._parents = []
622         self._extra = []
623         self._author = None
624         f = StringIO("".join(chunks))
625         for l in f:
626             l = l.rstrip("\n")
627             if l == "":
628                 # Empty line indicates end of headers
629                 break
630             (field, value) = l.split(" ", 1)
631             if field == _TREE_HEADER:
632                 self._tree = value
633             elif field == _PARENT_HEADER:
634                 self._parents.append(value)
635             elif field == _AUTHOR_HEADER:
636                 self._author, timetext, timezonetext = value.rsplit(" ", 2)
637                 self._author_time = int(timetext)
638                 self._author_timezone = parse_timezone(timezonetext)
639             elif field == _COMMITTER_HEADER:
640                 self._committer, timetext, timezonetext = value.rsplit(" ", 2)
641                 self._commit_time = int(timetext)
642                 self._commit_timezone = parse_timezone(timezonetext)
643             elif field == _ENCODING_HEADER:
644                 self._encoding = value
645             else:
646                 self._extra.append((field, value))
647         self._message = f.read()
648
649     def _serialize(self):
650         chunks = []
651         chunks.append("%s %s\n" % (_TREE_HEADER, self._tree))
652         for p in self._parents:
653             chunks.append("%s %s\n" % (_PARENT_HEADER, p))
654         chunks.append("%s %s %s %s\n" % (
655           _AUTHOR_HEADER, self._author, str(self._author_time),
656           format_timezone(self._author_timezone)))
657         chunks.append("%s %s %s %s\n" % (
658           _COMMITTER_HEADER, self._committer, str(self._commit_time),
659           format_timezone(self._commit_timezone)))
660         if self.encoding:
661             chunks.append("%s %s\n" % (_ENCODING_HEADER, self.encoding))
662         for k, v in self.extra:
663             if "\n" in k or "\n" in v:
664                 raise AssertionError("newline in extra data: %r -> %r" % (k, v))
665             chunks.append("%s %s\n" % (k, v))
666         chunks.append("\n") # There must be a new line after the headers
667         chunks.append(self._message)
668         return chunks
669
670     tree = serializable_property("tree", "Tree that is the state of this commit")
671
672     def _get_parents(self):
673         """Return a list of parents of this commit."""
674         self._ensure_parsed()
675         return self._parents
676
677     def _set_parents(self, value):
678         """Set a list of parents of this commit."""
679         self._ensure_parsed()
680         self._needs_serialization = True
681         self._parents = value
682
683     parents = property(_get_parents, _set_parents)
684
685     def _get_extra(self):
686         """Return extra settings of this commit."""
687         self._ensure_parsed()
688         return self._extra
689
690     extra = property(_get_extra)
691
692     author = serializable_property("author",
693         "The name of the author of the commit")
694
695     committer = serializable_property("committer",
696         "The name of the committer of the commit")
697
698     message = serializable_property("message",
699         "The commit message")
700
701     commit_time = serializable_property("commit_time",
702         "The timestamp of the commit. As the number of seconds since the epoch.")
703
704     commit_timezone = serializable_property("commit_timezone",
705         "The zone the commit time is in")
706
707     author_time = serializable_property("author_time",
708         "The timestamp the commit was written. as the number of seconds since the epoch.")
709
710     author_timezone = serializable_property("author_timezone",
711         "Returns the zone the author time is in.")
712
713     encoding = serializable_property("encoding",
714         "Encoding of the commit message.")
715
716
717 OBJECT_CLASSES = (
718     Commit,
719     Tree,
720     Blob,
721     Tag,
722     )
723
724 _TYPE_MAP = {}
725
726 for cls in OBJECT_CLASSES:
727     _TYPE_MAP[cls.type_name] = cls
728     _TYPE_MAP[cls.type_num] = cls
729
730
731
732 # Hold on to the pure-python implementations for testing
733 _parse_tree_py = parse_tree
734 _sorted_tree_items_py = sorted_tree_items
735 try:
736     # Try to import C versions
737     from dulwich._objects import parse_tree, sorted_tree_items
738 except ImportError:
739     pass