Remote: add documentation for credentials

docs/remotes.rst

@@ -52,3 +52,19 @@ The Refspec type
 .. automethod:: pygit2.Refspec.dst_matches
 .. automethod:: pygit2.Refspec.transform
 .. automethod:: pygit2.Refspec.rtransform
+
+Credentials
+================
+
+.. automethod:: pygit2.Remote.credentials
+
+There are two types of credentials: username/password and SSH key
+pairs. Both :py:class:`pygit2.UserPass` and :py:class:`pygit2.Keypair`
+are callable objects, with the appropriate signature for the
+credentials callback. They will ignore all the arguments and return
+themselves. This is useful for scripts where the credentials are known
+ahead of time. More complete interfaces would want to look up in their
+keychain or ask the user for the data to use in the credentials.
+
+.. autoclass:: pygit2.UserPass
+.. autoclass:: pygit2.Keypair

pygit2/credentials.py

@@ -33,7 +33,7 @@ class UserPass(CredUsernamePassword):
     """Username/Password credentials
 
     This is an object suitable for passing to a remote's credentials
-    callback.
+    callback and for returning from said callback.
 
     """
 
@@ -44,7 +44,7 @@ class Keypair(CredSshKey):
     """SSH key pair credentials
 
     This is an object suitable for passing to a remote's credentials
-    callback.
+    callback and for returning from said callback.
 
     """
 

src/remote.c

@@ -705,7 +705,18 @@ PyGetSetDef Remote_getseters[] = {
 
 PyMemberDef Remote_members[] = {
     MEMBER(Remote, progress, T_OBJECT_EX, "Progress output callback"),
-    MEMBER(Remote, credentials, T_OBJECT_EX, "Credentials callback"),
+    MEMBER(Remote, credentials, T_OBJECT_EX,
+  "credentials(url, username_from_url, allowed_types) -> credential\n"
+  "\n"
+  "Credentials callback\n"
+  "\n"
+  "If the remote server requires authentication, this function will\n"
+  "be called and its return value used for authentication.\n"
+  "\n"
+  ":param str url: The url of the remote\n"
+  ":param username_from_url: Username extracted from the url, if any\n"
+  ":type username_from_url: str or None\n"
+  ":param int allowed_types: credential types supported by the remote "),
     MEMBER(Remote, transfer_progress, T_OBJECT_EX, "Transfer progress callback"),
     MEMBER(Remote, update_tips, T_OBJECT_EX, "update tips callback"),
     {NULL},