From cf2703998e42c36c65dc2078377b693a8b41cd01 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Carlos=20Mart=C3=ADn=20Nieto?= Date: Sat, 12 Apr 2014 18:18:50 +0200 Subject: [PATCH] Remote: add documentation strings Now that it has the features of the old implementation, let's add documentation on how to use it. --- docs/remotes.rst | 6 +-- pygit2/remote.py | 104 +++++++++++++++++++++++++++++++++++++++++++++-- 2 files changed, 103 insertions(+), 7 deletions(-) diff --git a/docs/remotes.rst b/docs/remotes.rst index 58ab8ef..445bef2 100644 --- a/docs/remotes.rst +++ b/docs/remotes.rst @@ -16,9 +16,9 @@ The Remote type .. autoattribute:: pygit2.Remote.refspec_count .. autoattribute:: pygit2.Remote.push_refspecs .. autoattribute:: pygit2.Remote.fetch_refspecs -.. autoattribute:: pygit2.Remote.progress -.. autoattribute:: pygit2.Remote.transfer_progress -.. autoattribute:: pygit2.Remote.update_tips +.. automethod:: pygit2.Remote.progress +.. automethod:: pygit2.Remote.transfer_progress +.. automethod:: pygit2.Remote.update_tips .. automethod:: pygit2.Remote.get_refspec .. automethod:: pygit2.Remote.fetch .. automethod:: pygit2.Remote.push diff --git a/pygit2/remote.py b/pygit2/remote.py index d68c884..c7f122c 100644 --- a/pygit2/remote.py +++ b/pygit2/remote.py @@ -45,15 +45,73 @@ class TransferProgress(object): """Progress downloading and indexing data during a fetch""" def __init__(self, tp): + self.total_objects = tp.total_objects + """Total number objects to download""" + self.indexed_objects = tp.indexed_objects + """Objects which have been indexed""" + self.received_objects = tp.received_objects + """Objects which have been received up to now""" + self.local_objects = tp.local_objects + """Local objects which were used to fix the thin pack""" + self.total_deltas = tp.total_deltas + """Total number of deltas in the pack""" + self.indexed_deltas = tp.indexed_deltas + """Deltas which have been indexed""" + self.received_bytes = tp.received_bytes + """"Number of bytes received up to now""" class Remote(object): + + def progress(self, string): + """Progress output callback + + Override this function with your own progress reporting function + + :param str string: Progress otuput from the remote + """ + pass + + def credentials(self, url, username_from_url, allowed_types): + """Credentials callback + + If the remote server requires authentication, this function will + be called and its return value used for authentication. Override + it if you want to be able to perform authentication. + + :param str url: The url of the remote + :param username_from_url: Username extracted from the url, if any + :type username_from_url: str or None + :param int allowed_types: credential types supported by the remote + :rtype: credential + """ + pass + + def transfer_progress(self, stats): + """Transfer progress callback + + Override with your own function to report transfer progress. + + :param TransferProgress stats: The progress up to now + """ + pass + + def update_tips(self, refname, old, new): + """Update tips callabck + + Override with your own function to report reference updates + + :param str refname: the name of the reference that's being updated + :param Oid old: the reference's old value + :param Oid new: the reference's new value + """ + def __init__(self, repo, ptr): """The constructor is for internal use only""" @@ -80,6 +138,8 @@ class Remote(object): @property def name(self): + """Name of the remote""" + return maybe_string(C.git_remote_name(self._remote)) @name.setter @@ -89,6 +149,8 @@ class Remote(object): @property def url(self): + """Url of the remote""" + return maybe_string(C.git_remote_url(self._remote)) @url.setter @@ -97,6 +159,8 @@ class Remote(object): @property def push_url(self): + """Push url of the remote""" + return maybe_string(C.git_remote_pushurl(self._remote)) @push_url.setter @@ -105,10 +169,19 @@ class Remote(object): check_error(err) def save(self): + """save() + + Save a remote to its repository's configuration""" + err = C.git_remote_save(self._remote) check_error(err) def fetch(self): + """fetch() -> TransferProgress + + Perform a fetch against this remote. + """ + self._stored_exception = None err = C.git_remote_fetch(self._remote) if self._stored_exception: @@ -120,14 +193,22 @@ class Remote(object): @property def refspec_count(self): + """Total number of refspecs in this remote""" + return C.git_remote_refspec_count(self._remote) def get_refspec(self, n): + """get_refspec(n) -> Refspec + + Return the refspec at the given position + """ spec = C.git_remote_get_refspec(self._remote, n) return Refspec(self, spec) @property def fetch_refspecs(self): + """Refspecs that will be used for fetching""" + specs = ffi.new('git_strarray *') err = C.git_remote_get_fetch_refspecs(specs, self._remote) check_error(err) @@ -142,6 +223,8 @@ class Remote(object): @property def push_refspecs(self): + """Refspecs that will be used for pushing""" + specs = ffi.new('git_strarray *') err = C.git_remote_get_push_refspecs(specs, self._remote) check_error(err) @@ -155,9 +238,17 @@ class Remote(object): check_error(err) def add_fetch(self, spec): + """add_fetch(refspec) + + Add a fetch refspec to the remote""" + err = C.git_remote_add_fetch(self._remote, to_str(spec)) def add_push(self, spec): + """add_push(refspec) + + Add a push refspec to the remote""" + err = C.git_remote_add_push(self._remote, to_str(spec)) @ffi.callback("int (*cb)(const char *ref, const char *msg, void *data)") @@ -168,6 +259,10 @@ class Remote(object): return 0 def push(self, spec): + """push(refspec) + + Push the given refspec to the remote. Raises ``GitError`` on error""" + cpush = ffi.new('git_push **') err = C.git_push_new(cpush, self._remote) check_error(err) @@ -202,7 +297,8 @@ class Remote(object): @ffi.callback('int (*transfer_progress)(const git_transfer_progress *stats, void *data)') def _transfer_progress_cb(stats_ptr, data): self = ffi.from_handle(data) - if not hasattr(self, 'transfer_progress'): + + if not hasattr(self, 'transfer_progress') or not self.transfer_progress: return 0 try: @@ -217,7 +313,7 @@ class Remote(object): def _progress_cb(string, length, data): self = ffi.from_handle(data) - if not hasattr(self, 'progress'): + if not hasattr(self, 'progress') or not self.progress: return 0 try: @@ -233,7 +329,7 @@ class Remote(object): def _update_tips_cb(refname, a, b, data): self = ffi.from_handle(data) - if not hasattr(self, 'update_tips'): + if not hasattr(self, 'update_tips') or not self.update_tips: return 0 try: @@ -252,7 +348,7 @@ class Remote(object): def _credentials_cb(cred_out, url, username, allowed, data): self = ffi.from_handle(data) - if not hasattr(self, 'credentials'): + if not hasattr(self, 'credentials') or not self.credentials: return 0 try: