Guidelines

Basic API (low-level)

• public libgit2 structs should be python objects (classes)

  Example: git_repository => Repository()

• naming convention: strip git_struct_name_*

  Example: git_repository_config() => Repository.config()

• iterations should be implemented as a generator, if this is not possible we need to change libgit2 (other bindings will benefit from this as well)

• every method should map to one libgit2 function (exceptions are iterations)

• return values of methods

  • no lists use generators instead
  • no dictionaries use tuples or objects instead
  • no instantiation of objects use strings instead (important for generators) like sha1-hash for objects or names for references. The high-level API can instance them if necessary.

• if you add new features always do a memleak check with valgrind for the tests.

valgrind --leak-check=full --tool=memcheck --suppressions=misc/valgrind-python.supp python2 setup.py test

The output will be a bit messy. Just check for the summary ((in)definitely lost) . It should be something like the following

==23689== LEAK SUMMARY:
==23689==    definitely lost: 0 bytes in 0 blocks
==23689==    indirectly lost: 0 bytes in 0 blocks
==23689==      possibly lost: 498,605 bytes in 3,381 blocks
==23689==    still reachable: 1,329,196 bytes in 10,504 blocks
==23689==         suppressed: 0 bytes in 0 blocks

If you encounter memleaks check the verbose output of the log for git_* function calls.

High-Level API

• As it's easier, errorless, painless and faster to implement stuff in python we use Repository() as a our high level pythonic class. Here you should add every pythonic sugar like Repository.create_reference().

• We try to implement everything in the c extension as simple as possible. Therefore please do not put too much abstraction into the c extension layer. Use the Repository class for abstraction.

  Example: Implement several methods for each type/use case like for Diff:

  • Tree.diff_to_tree(),
  • Tree.diff_to_workdir()
  • Tree.diff_to_index()

  To have a user friendly api, you can now implement a high-level method in python to abstract these methods like Repository.diff()

• no return value restrictions