**********************************************************************
Object IDs
**********************************************************************

In the first place Git is a key-value storage system. The keys are called
OIDs, for Object ID, and the  values stored are called Objects.

.. contents:: Contents
   :local:


The three forms of an object id
===============================

The oid is the `SHA-1 <http://en.wikipedia.org/wiki/SHA-1>`_ hash of an
object. It is 20 bytes long.

These are the three forms of an oid in pygit2:

Raw oid
  A raw oid is represented as a Python byte string of 20 bytes length.
  This form can only be used to create an Oid object.

Hex oid
  A hex oid is represented as a Python string of 40 hexadecimal chars.  This
  form can be used to create Oid objects, just like raw oids. Also, the pygit2
  API directly accepts hex oids everywhere.

Oid object
  An ``Oid`` object can be built from the raw or hexadecimal representations
  (see below). The pygit2 API always returns, and accepts, ``Oid`` objects.

  This is the preferred way to represent an Oid, with the hexadecimal form
  being used for interaction with the user.


The Oid type
============

.. c:type:: pygit2.Oid(raw=None, hex=None)

   The constructor expects either a raw or a hex oid, but not both.

   An Oid object is created from the hexadecimal form this way::

     >>> from pygit2 import Oid

     >>> hex = "cff3ceaefc955f0dbe1957017db181bc49913781"
     >>> oid1 = Oid(hex=hex)

   An Oid object is created from the raw form this way::

     >>> from binascii import unhexlify
     >>> from pygit2 import Oid

     >>> raw = unhexlify("cff3ceaefc955f0dbe1957017db181bc49913781")
     >>> oid2 = Oid(raw=raw)

And the other way around, from an Oid object we can get the hexadecimal and raw
forms. You can use the built-in `str()` (or `unicode()` in python 2) to get the
hexadecimal representation of the Oid.

.. method:: Oid.__str__()
.. autoattribute:: pygit2.Oid.raw

The Oid type supports:

- rich comparisons, not just for equality, also: lesser-than, lesser-or-equal,
  etc.

- hashing, so Oid objects can be used as keys in a dictionary.


Constants
=========

.. py:data:: GIT_OID_RAWSZ
.. py:data:: GIT_OID_HEXSZ
.. py:data:: GIT_OID_HEX_ZERO
.. py:data:: GIT_OID_MINPREFIXLEN