Update docs

Author: jdavid

CHANGELOG.rst

@@ -7,27 +7,48 @@
 - Add Python 3.8 support
   `#918 <https://github.com/libgit2/pygit2/issues/918>`_
 
+- New ``Repository.odb`` returns new ``Odb`` type instance. And new
+  ``OdbBackend`` type.
+  `#940 <https://github.com/libgit2/pygit2/pull/940>`_
+  `#942 <https://github.com/libgit2/pygit2/pull/942>`_
+
 - New support for ``/`` operator to traverse trees
   `#903 <https://github.com/libgit2/pygit2/pull/903>`_
+  `#924 <https://github.com/libgit2/pygit2/issues/924>`_
 
 - New ``Index.remove_all()``
   `#920 <https://github.com/libgit2/pygit2/pull/920>`_
 
 - New ``Repository.lookup_reference_dwim(..)`` and ``Repository.resolve_refish(..)``
-  `#922 <https://github.com/libgit2/pygit2/pull/922>`_
+  `#922 <https://github.com/libgit2/pygit2/issues/922>`_
+  `#923 <https://github.com/libgit2/pygit2/pull/923>`_
 
 - New ``Remote.ls_remotes(..)``
+  `#935 <https://github.com/libgit2/pygit2/pull/935>`_
+  `#936 <https://github.com/libgit2/pygit2/issues/936>`_
 
 - Fix spurious exception in config
   `#916 <https://github.com/libgit2/pygit2/issues/916>`_
   `#917 <https://github.com/libgit2/pygit2/pull/917>`_
 
-- Minor fixes
+- Minor documentation and cosmetic changes
   `#919 <https://github.com/libgit2/pygit2/pull/919>`_
   `#921 <https://github.com/libgit2/pygit2/pull/921>`_
+  `#946 <https://github.com/libgit2/pygit2/pull/946>`_
+  `#950 <https://github.com/libgit2/pygit2/pull/950>`_
 
 Breaking changes:
 
+- Now the Repository has a new attribue ``odb`` for object database::
+
+    # Before
+    repository.read(...)
+    repository.write(...)
+
+    # Now
+    repository.odb.read(...)
+    repository.odb.write(...)
+
 - Now ``Tree[x]`` returns a ``Object`` instance instead of a ``TreeEntry``;
   ``Object.type`` returns an integer while ``TreeEntry.type`` returned a
   string::

Makefile

@@ -2,3 +2,6 @@
 
 build:
 	python setup.py build_ext --inplace
+
+html:
+	cd docs && find . -name "*rst" | entr make html

docs/install.rst

@@ -27,9 +27,6 @@ To install the source package:
 
    $ pip install pygit2 --no-binary
 
-It's preferable to install the source package, if it works for you. But the
-binary package will often be easier to install.
-
 
 Requirements
 ============
@@ -43,9 +40,8 @@ Python requirements (these are specified in ``setup.py``):
 
 - cffi 1.0+
 
-Libgit2 **v0.28.x** (see the version numbering section below for details).
-Binary wheels already include libgit2, so you only need to worry about this if
-you install the source package
+Libgit2 **v0.28.x**; binary wheels already include libgit2, so you only need to
+worry about this if you install the source package
 
 Optional libgit2 dependecies to support ssh and https:
 
@@ -60,31 +56,42 @@ To run the tests:
 Version numbers
 ===============
 
-.. warning::
+The version number of pygit2 is composed of three numbers separated by dots
+|lq| *major.minor.micro* |rq|:
 
-   One common mistake users do is to choose incompatible versions of libgit2
-   and pygit2. Double check the versions do match before filing a bug report.
-   Though you don't need to worry about this if you install a binary wheel.
+- *major* will always be 1 (until we release 2.0 in a far undefined future)
+- *minor* will increase whenever we make breaking changes, or add new features, or
+  upgrade to new versions of libgit2.
+- *micro* will increase for bug fixes.
 
-The version number of pygit2 is composed of three numbers separated by dots
-|lq| *major.minor.micro* |rq|, where the first two numbers
-|lq| *major.minor* |rq| match the first two numbers of the libgit2 version,
-while the last number |lq| *.micro* |rq| auto-increments independently.
+The table below summarizes the latest pygit2 versions with the supported versions
+of Python and the required libgit2 version.
 
-It is recommended to use the latest version in each series. Example of
-compatible releases:
++-----------+----------------+---------+
+| pygit2    | Python         | libgit2 |
++-----------+----------------+---------+
+| 1.0.x     | 3.5 - 3.8      | 0.28.x  |
++-----------+----------------+---------+
+| 0.28.2    | 2.7, 3.4 - 3.7 | 0.28.x  |
++-----------+----------------+---------+
 
-+-----------+--------+--------+--------+--------+--------+
-|**libgit2**| 0.28.2 | 0.27.8 | 0.26.8 | 0.25.1 | 0.24.6 |
-+-----------+--------+--------+--------+--------+--------+
-|**pygit2** | 0.28.2 | 0.27.4 | 0.26.4 | 0.25.1 | 0.24.2 |
-+-----------+--------+--------+--------+--------+--------+
+.. warning::
+
+   It is recommended to use the latest 1.x.y release. Because only the latest
+   is supported.
 
 .. warning::
 
-   Backwards compatibility is not guaranteed even between micro releases.
-   Please check the release notes for incompatible changes before upgrading to
-   a new release.
+   Backwards compatibility is not guaranteed in minor releases. Please check
+   the release notes for incompatible changes before upgrading to a new
+   release.
+
+History: the 0.x series
+-----------------------
+
+The development of pygit2 started in October 2010, the release of 1.0.0
+happened in November 2019. In the 0.x series the version numbering was
+lockstep with libgit2, e.g. pygit2 0.28.x worked with libgit2 0.28.x
 
 
 Advanced

docs/objects.rst

@@ -79,7 +79,12 @@ New objects are created using an specific API we will see later.
 This is the common interface for all Git objects:
 
 .. autoclass:: pygit2.Object
-   :members: id, type, short_id, read_raw, peel, name, filemode, __eq__, __ne__, __hash__
+   :members: id, type, type_str, short_id, read_raw, peel, name, filemode
+
+   .. automethod:: __eq__(other)
+   .. automethod:: __ne__(other)
+   .. automethod:: __hash__()
+
 
 Blobs
 =================
@@ -141,64 +146,61 @@ creating the blob object:
 Trees
 =================
 
-A tree is a sorted collection of tree entries. It is similar to a folder or
-directory in a file system. Each entry points to another tree or a blob.  A
-tree can be iterated, and partially implements the sequence and mapping
+At the low level (libgit2) a tree is a sorted collection of tree entries. In
+pygit2 accessing an entry directly returns the object.
+
+A tree can be iterated, and partially implements the sequence and mapping
 interfaces.
 
 .. method:: Tree.__getitem__(name)
 
-   Return the TreeEntry object for the given *name*. Raise ``KeyError`` if
-   there is not a tree entry with that name.
+   ``Tree[name]``
+
+   Return the Object subclass instance for the given *name*. Raise ``KeyError``
+   if there is not a tree entry with that name.
 
 .. method:: Tree.__truediv__(name)
 
-   Return the TreeEntry object for the given *name*. Raise ``KeyError`` if
-   there is not a tree entry with that name. This allows navigating the tree
-   similarly to Pathlib using the slash operator via:
+   ``Tree / name``
 
-Example::
+   Return the Object subclass instance for the given *name*. Raise ``KeyError``
+   if there is not a tree entry with that name. This allows navigating the tree
+   similarly to Pathlib using the slash operator via.
+
+   Example::
 
-    >>> entry = tree / 'path' / 'deeper' / 'some.file'
+       >>> entry = tree / 'path' / 'deeper' / 'some.file'
 
 .. method:: Tree.__contains__(name)
 
+   ``name in Tree``
+
    Return True if there is a tree entry with the given name, False otherwise.
 
 .. method:: Tree.__len__()
 
-   Return the number of entries in the tree.
+   ``len(Tree)``
+
+   Return the number of objects in the tree.
 
 .. method:: Tree.__iter__()
 
-   Return an iterator over the entries of the tree.
+   ``for object in Tree``
+
+   Return an iterator over the objects in the tree.
 
 .. automethod:: pygit2.Tree.diff_to_tree
 .. automethod:: pygit2.Tree.diff_to_workdir
 .. automethod:: pygit2.Tree.diff_to_index
 
-Tree entries
-------------
-
-.. autoattribute:: pygit2.TreeEntry.name
-.. autoattribute:: pygit2.TreeEntry.id
-.. autoattribute:: pygit2.TreeEntry.hex
-.. autoattribute:: pygit2.TreeEntry.filemode
-.. autoattribute:: pygit2.TreeEntry.type
-.. autoattribute:: pygit2.TreeEntry.obj
-
-.. method:: TreeEntry.__cmp__(TreeEntry)
-
-   Rich comparison between tree entries.
-
 Example::
 
     >>> tree = commit.tree
     >>> len(tree)                        # Number of entries
     6
 
-    >>> for entry in tree:               # Iteration
-    ...     print(entry.id, entry.type, entry.name)
+    >>> for obj in tree:                 # Iteration
+    ...     print(obj.id, obj.type_str, obj.name)
     ...
     7151ca7cd3e59f3eab19c485cfbf3cb30928d7fa blob .gitignore
     c36f4cf1e38ec1bb9d9ad146ed572b89ecfc9f18 blob COPYING
@@ -207,13 +209,9 @@ Example::
     85a67270a49ef16cdd3d328f06a3e4b459f09b27 blob setup.py
     3d8985bbec338eb4d47c5b01b863ee89d044bd53 tree test
 
-    >>> entry = tree / 'pygit2.c'         # Get an entry by name
-    >>> entry
-    <pygit2.TreeEntry object at 0xcc10f0>
-
-    >>> obj = entry.obj                   # Get the blob the entry points to
+    >>> obj = tree / 'pygit2.c'          # Get an object by name
     >>> obj
-    <pygit2.Blob object at 0xcc12d0>
+    <_pygit2.Blob at 0x7f08a70acc10>
 
 Creating trees
 --------------------

docs/repository.rst

@@ -39,11 +39,24 @@ Functions
      >>> repository_path = discover_repository(current_working_directory)
      >>> repo = Repository(repository_path)
 
+.. autofunction:: pygit2.tree_entry_cmp(object, other)
+
 
 The Repository class
 ===================================
 
-.. py:class:: pygit2.Repository(path)
+The API of the Repository class is quite large. Since this documentation is
+organized by features, the related bits are explained in the related chapters,
+for instance the :py:meth:`pygit2.Repository.checkout` method is explained in
+the Checkout section.
+
+Below there are some general attributes and methods:
+
+.. autoclass:: pygit2.Repository
+   :members: ahead_behind, apply, create_reference, default_signature,
+             descendant_of, describe, free, is_bare, is_empty, odb, path,
+             path_is_ignored, reset, revert_commit, state_cleanup, workdir,
+             write_archive
 
    The Repository constructor only takes one argument, the path of the
    repository to open.
@@ -53,29 +66,12 @@ The Repository class
      >>> from pygit2 import Repository
      >>> repo = Repository('pygit2/.git')
 
-The API of the Repository class is quite large. Since this documentation is
-organized by features, the related bits are explained in the related chapters,
-for instance the :py:meth:`pygit2.Repository.checkout` method is explained in
-the Checkout section.
 
-Below there are some general attributes and methods:
+The Odb class
+===================================
+
+.. autoclass:: pygit2.Odb
+   :members:
 
-.. autoattribute:: pygit2.Repository.path
-.. autoattribute:: pygit2.Repository.workdir
-.. autoattribute:: pygit2.Repository.is_bare
-.. autoattribute:: pygit2.Repository.is_empty
-.. autoattribute:: pygit2.Repository.default_signature
-
-.. automethod:: pygit2.Repository.apply
-.. automethod:: pygit2.Repository.ahead_behind
-.. automethod:: pygit2.Repository.create_reference
-.. automethod:: pygit2.Repository.descendant_of
-.. automethod:: pygit2.Repository.describe
-.. automethod:: pygit2.Repository.free
-.. automethod:: pygit2.Repository.path_is_ignored
-.. automethod:: pygit2.Repository.read
-.. automethod:: pygit2.Repository.reset
-.. automethod:: pygit2.Repository.revert_commit
-.. automethod:: pygit2.Repository.state_cleanup
-.. automethod:: pygit2.Repository.write
-.. automethod:: pygit2.Repository.write_archive
+.. autoclass:: pygit2.OdbBackend
+   :members:

pygit2/remote.py

@@ -304,7 +304,7 @@ def _credentials_cb(cred_out, url, username, allowed, data):
         try:
             ccred = get_credentials(credentials, url, username, allowed)
             cred_out[0] = ccred[0]
-        except Passthrough as e:
+        except Passthrough:
             return C.GIT_PASSTHROUGH
         except Exception as e:
             self._stored_exception = e
@@ -331,7 +331,7 @@ def _certificate_cb(cert_i, valid, host, data):
             val = certificate_check(None, bool(valid), ffi.string(host))
             if not val:
                 return C.GIT_ECERTIFICATE
-        except Passthrough as e:
+        except Passthrough:
             if is_ssh:
                 return 0
             elif valid:
@@ -427,7 +427,10 @@ def fetch(self, refspecs=None, message=None, callbacks=None, prune=C.GIT_FETCH_P
         return TransferProgress(C.git_remote_stats(self._remote))
 
     def ls_remotes(self, callbacks=None):
-        """Return a list of dicts that maps to `git_remote_head` from a `ls_remotes` call."""
+        """
+        Return a list of dicts that maps to `git_remote_head` from a
+        `ls_remotes` call.
+        """
 
         self.connect(callbacks=callbacks)
 

src/pygit2.c

@@ -213,9 +213,12 @@ reference_is_valid_name(PyObject *self, PyObject *py_refname)
 PyDoc_STRVAR(tree_entry_cmp__doc__,
     "tree_entry_obj(a, b) -> int\n"
     "\n"
+    "Rich comparison for objects, only available when the objects have been\n"
+    "obtained through a tree. The sort criteria is the one Git uses to sort\n"
+    "tree entries in a tree object. This function wraps git_tree_entry_cmp.\n"
+    "\n"
     "Returns < 0 if a is before b, > 0 if a is after b, and 0 if a and b are\n"
-    "the same. The sort criteria is the one Git uses to sort tree entries in\n"
-    "a tree object. This function wraps git_tree_entry_cmp.");
+    "the same.");
 
 PyObject *
 tree_entry_cmp(PyObject *self, PyObject *args)