openstack/deb-python-pygit2
Code Issues Proposed changes

docs: remove manual singatures from py files

Browse Source 
These are only needed in C code. With Python files the signatures are
automatically generated. The only drawback is the return value is not
included in the signature, so document it in the body of the docstring.
This commit is contained in:
J. David Ibáñez
2015-05-03 11:16:17 +02:00
parent 6da3d8f8a8
commit deb50536f0
7 changed files with 80 additions and 147 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
pygit2/blame.py
View File

@@ -125,9 +125,7 @@ class Blame(object):
return BlameHunk._from_c(self, chunk) return BlameHunk._from_c(self, chunk)
def for_line(self, line_no): def for_line(self, line_no):
"""for_line(line_no) -> BlameHunk """Returns the <BlameHunk> object for a given line given its number
Returns the blame hunk data for a given line given its number
in the current Blame. in the current Blame.
Arguments: Arguments:

64
pygit2/config.py
View File

@@ -158,12 +158,11 @@ class Config(object):
return ConfigIterator(self, citer[0]) return ConfigIterator(self, citer[0])
def get_multivar(self, name, regex=None): def get_multivar(self, name, regex=None):
"""get_multivar(name[, regex]) -> [str, ...] """Get each value of a multivar ''name'' as a list of strings.
Get each value of a multivar ''name'' as a list. The optional ''regex''
parameter is expected to be a regular expression to filter the
variables we're interested in."""
The optional ''regex'' parameter is expected to be a regular expression
to filter the variables we're interested in.
"""
assert_string(name, "name") assert_string(name, "name")
citer = ffi.new('git_config_iterator **') citer = ffi.new('git_config_iterator **')
@@ -175,11 +174,9 @@ class Config(object):
return ConfigMultivarIterator(self, citer[0]) return ConfigMultivarIterator(self, citer[0])
def set_multivar(self, name, regex, value): def set_multivar(self, name, regex, value):
"""set_multivar(name, regex, value) """Set a multivar ''name'' to ''value''. ''regexp'' is a regular
expression to indicate which values to replace.
Set a multivar ''name'' to ''value''. ''regexp'' is a regular """
expression to indicate which values to replace"""
assert_string(name, "name") assert_string(name, "name")
assert_string(regex, "regex") assert_string(regex, "regex")
assert_string(value, "value") assert_string(value, "value")
@@ -189,14 +186,12 @@ class Config(object):
check_error(err) check_error(err)
def get_bool(self, key): def get_bool(self, key):
"""get_bool(key) -> Bool """Look up *key* and parse its value as a boolean as per the git-config
rules. Return a boolean value (True or False).
Look up *key* and parse its value as a boolean as per the git-config
rules
Truthy values are: 'true', 1, 'on' or 'yes'. Falsy values are: 'false', Truthy values are: 'true', 1, 'on' or 'yes'. Falsy values are: 'false',
0, 'off' and 'no'""" 0, 'off' and 'no'
"""
val = self._get_string(key) val = self._get_string(key)
res = ffi.new('int *') res = ffi.new('int *')
err = C.git_config_parse_bool(res, val) err = C.git_config_parse_bool(res, val)
@@ -205,14 +200,12 @@ class Config(object):
return res[0] != 0 return res[0] != 0
def get_int(self, key): def get_int(self, key):
"""get_int(key) -> int """Look up *key* and parse its value as an integer as per the git-config
rules. Return an integer.
Look up *key* and parse its value as an integer as per the git-config
rules.
A value can have a suffix 'k', 'm' or 'g' which stand for 'kilo', A value can have a suffix 'k', 'm' or 'g' which stand for 'kilo',
'mega' and 'giga' respectively""" 'mega' and 'giga' respectively.
"""
val = self._get_string(key) val = self._get_string(key)
res = ffi.new('int64_t *') res = ffi.new('int64_t *')
err = C.git_config_parse_int64(res, val) err = C.git_config_parse_int64(res, val)
@@ -221,21 +214,18 @@ class Config(object):
return res[0] return res[0]
def add_file(self, path, level=0, force=0): def add_file(self, path, level=0, force=0):
"""add_file(path, level=0, force=0) """Add a config file instance to an existing config."""
Add a config file instance to an existing config."""
err = C.git_config_add_file_ondisk(self._config, to_bytes(path), level, err = C.git_config_add_file_ondisk(self._config, to_bytes(path), level,
force) force)
check_error(err) check_error(err)
def snapshot(self): def snapshot(self):
"""Create a snapshot from this Config object """Create a snapshot from this Config object.
This means that looking up multiple values will use the same version This means that looking up multiple values will use the same version
of the configuration files of the configuration files.
""" """
ccfg = ffi.new('git_config **') ccfg = ffi.new('git_config **')
err = C.git_config_snapshot(ccfg, self._config) err = C.git_config_snapshot(ccfg, self._config)
check_error(err) check_error(err)
@@ -278,24 +268,18 @@ class Config(object):
@staticmethod @staticmethod
def get_system_config(): def get_system_config():
"""get_system_config() -> Config """Return a <Config> object representing the system configuration file.
"""
Return an object representing the system configuration file."""
return Config._from_found_config(C.git_config_find_system) return Config._from_found_config(C.git_config_find_system)
@staticmethod @staticmethod
def get_global_config(): def get_global_config():
"""get_global_config() -> Config """Return a <Config> object representing the global configuration file.
"""
Return an object representing the global configuration file."""
return Config._from_found_config(C.git_config_find_global) return Config._from_found_config(C.git_config_find_global)
@staticmethod @staticmethod
def get_xdg_config(): def get_xdg_config():
"""get_xdg_config() -> Config """Return a <Config> object representing the global configuration file.
"""
Return an object representing the global configuration file."""
return Config._from_found_config(C.git_config_find_xdg) return Config._from_found_config(C.git_config_find_xdg)

2
pygit2/credentials.py
View File

@@ -36,7 +36,6 @@ class UserPass(object):
This is an object suitable for passing to a remote's credentials This is an object suitable for passing to a remote's credentials
callback and for returning from said callback. callback and for returning from said callback.
""" """
def __init__(self, username, password): def __init__(self, username, password):
@@ -67,7 +66,6 @@ class Keypair(object):
:param str privkey: the path to the user's private key file :param str privkey: the path to the user's private key file
:param str passphrase: the password used to decrypt the private key file, :param str passphrase: the password used to decrypt the private key file,
or empty string if no passphrase is required. or empty string if no passphrase is required.
""" """
def __init__(self, username, pubkey, privkey, passphrase): def __init__(self, username, pubkey, privkey, passphrase):

39
pygit2/index.py
View File

@@ -110,8 +110,7 @@ class Index(object):
check_error(err, True) check_error(err, True)
def write(self): def write(self):
"""Write the contents of the Index to disk """Write the contents of the Index to disk."""
"""
err = C.git_index_write(self._index) err = C.git_index_write(self._index)
check_error(err, True) check_error(err, True)
@@ -120,9 +119,8 @@ class Index(object):
check_error(err) check_error(err)
def read_tree(self, tree): def read_tree(self, tree):
"""read_tree([Tree|Oid]) """Replace the contents of the Index with those of the given tree,
expressed either as a <Tree> object or as an oid (string or <Oid>).
Replace the contents of the Index with those of a tree
The tree will be read recursively and all its children will also be The tree will be read recursively and all its children will also be
inserted into the Index. inserted into the Index.
@@ -144,9 +142,8 @@ class Index(object):
check_error(err) check_error(err)
def write_tree(self, repo=None): def write_tree(self, repo=None):
"""write_tree([repo]) -> Oid """Create a tree out of the Index. Return the <Oid> object of the
written tree.
Create a tree out of the Index
The contents of the index will be written out to the object The contents of the index will be written out to the object
database. If there is no associated repository, 'repo' must be database. If there is no associated repository, 'repo' must be
@@ -181,13 +178,11 @@ class Index(object):
check_error(err, True) check_error(err, True)
def add(self, path_or_entry): def add(self, path_or_entry):
"""add([path|entry]) """Add or update an entry in the Index.
Add or update an entry in the Index If a path is given, that file will be added. The path must be relative
to the root of the worktree and the Index must be associated with a
If a path is given, that file will be added. The path must be repository.
relative to the root of the worktree and the Index must be associated
with a repository.
If an IndexEntry is given, that entry will be added or update in the If an IndexEntry is given, that entry will be added or update in the
Index without checking for the existence of the path or id. Index without checking for the existence of the path or id.
@@ -206,12 +201,8 @@ class Index(object):
check_error(err, True) check_error(err, True)
def diff_to_workdir(self, flags=0, context_lines=3, interhunk_lines=0): def diff_to_workdir(self, flags=0, context_lines=3, interhunk_lines=0):
"""diff_to_workdir(flags=0, context_lines=3, interhunk_lines=0) -> Diff """Diff the index against the working directory. Return a <Diff> object
with the differences between the index and the working copy.
Diff the index against the working directory
Return a :py:class:`~pygit2.Diff` object with the differences
between the index and the working copy.
Arguments: Arguments:
@@ -242,12 +233,8 @@ class Index(object):
return Diff.from_c(bytes(ffi.buffer(cdiff)[:]), self._repo) return Diff.from_c(bytes(ffi.buffer(cdiff)[:]), self._repo)
def diff_to_tree(self, tree, flags=0, context_lines=3, interhunk_lines=0): def diff_to_tree(self, tree, flags=0, context_lines=3, interhunk_lines=0):
"""diff_to_tree(tree, flags=0, context_lines=3, interhunk_lines=0) -> Diff """Diff the index against a tree. Return a <Diff> object with the
differences between the index and the given tree.
Diff the index against a tree
Return a :py:class:`~pygit2.Diff` object with the differences between
the index and the given tree.
Arguments: Arguments:

26
pygit2/refspec.py
View File

@@ -66,16 +66,14 @@ class Refspec(object):
return C.git_refspec_direction(self._refspec) return C.git_refspec_direction(self._refspec)
def src_matches(self, ref): def src_matches(self, ref):
"""src_matches(str) -> Bool """Return True if the given string matches the source of this refspec,
False otherwise.
Returns whether the given string matches the source of this refspec""" """
return bool(C.git_refspec_src_matches(self._refspec, to_bytes(ref))) return bool(C.git_refspec_src_matches(self._refspec, to_bytes(ref)))
def dst_matches(self, ref): def dst_matches(self, ref):
"""dst_matches(str) -> Bool """Return True if the given string matches the destination of this
refspec, False otherwise."""
Returns whether the given string matches the destination of this
refspec"""
return bool(C.git_refspec_dst_matches(self._refspec, to_bytes(ref))) return bool(C.git_refspec_dst_matches(self._refspec, to_bytes(ref)))
def _transform(self, ref, fn): def _transform(self, ref, fn):
@@ -89,15 +87,13 @@ class Refspec(object):
C.git_buf_free(buf) C.git_buf_free(buf)
def transform(self, ref): def transform(self, ref):
"""transform(str) -> str """Transform a reference name according to this refspec from the lhs to
the rhs. Return an string.
Transform a reference name according to this refspec from the lhs to """
the rhs."""
return self._transform(ref, C.git_refspec_transform) return self._transform(ref, C.git_refspec_transform)
def rtransform(self, ref): def rtransform(self, ref):
"""rtransform(str) -> str """Transform a reference name according to this refspec from the lhs to
the rhs. Return an string.
Transform a reference name according to this refspec from the lhs """
to the rhs"""
return self._transform(ref, C.git_refspec_rtransform) return self._transform(ref, C.git_refspec_rtransform)

50
pygit2/remote.py
View File

@@ -170,17 +170,14 @@ class Remote(object):
check_error(err) check_error(err)
def save(self): def save(self):
"""save() """Save a remote to its repository's configuration."""
Save a remote to its repository's configuration"""
err = C.git_remote_save(self._remote) err = C.git_remote_save(self._remote)
check_error(err) check_error(err)
def fetch(self, signature=None, message=None): def fetch(self, signature=None, message=None):
"""fetch([signature[, message]]) -> TransferProgress """Perform a fetch against this remote. Returns a <TransferProgress>
object.
Perform a fetch against this remote.
""" """
# Get the default callbacks first # Get the default callbacks first
@@ -234,10 +231,7 @@ class Remote(object):
return C.git_remote_refspec_count(self._remote) return C.git_remote_refspec_count(self._remote)
def get_refspec(self, n): def get_refspec(self, n):
"""get_refspec(n) -> Refspec """Return the <Refspec> object at the given position."""
Return the refspec at the given position
"""
spec = C.git_remote_get_refspec(self._remote, n) spec = C.git_remote_get_refspec(self._remote, n)
return Refspec(self, spec) return Refspec(self, spec)
@@ -273,32 +267,23 @@ class Remote(object):
err = C.git_remote_set_push_refspecs(self._remote, arr) err = C.git_remote_set_push_refspecs(self._remote, arr)
check_error(err) check_error(err)
def add_fetch(self, spec): def add_fetch(self, refspec):
"""add_fetch(refspec) """Add a fetch refspec (str) to the remote."""
err = C.git_remote_add_fetch(self._remote, to_bytes(refspec))
Add a fetch refspec (str) to the remote"""
err = C.git_remote_add_fetch(self._remote, to_bytes(spec))
check_error(err) check_error(err)
def add_push(self, spec): def add_push(self, refspec):
"""add_push(refspec) """Add a push refspec (str) to the remote."""
err = C.git_remote_add_push(self._remote, to_bytes(refspec))
Add a push refspec (str) to the remote"""
err = C.git_remote_add_push(self._remote, to_bytes(spec))
check_error(err) check_error(err)
def push(self, specs, signature=None, message=None): def push(self, specs, signature=None, message=None):
"""push(specs, signature, message) """Push the given refspec to the remote. Raises ``GitError`` on
Push the given refspec to the remote. Raises ``GitError`` on
protocol error or unpack failure. protocol error or unpack failure.
:param [str] specs: push refspecs to use :param [str] specs: push refspecs to use
:param Signature signature: signature to use when updating the tips (optional) :param Signature signature: signature to use when updating the tips (optional)
:param str message: message to use when updating the tips (optional) :param str message: message to use when updating the tips (optional)
""" """
# Get the default callbacks first # Get the default callbacks first
defaultcallbacks = ffi.new('git_remote_callbacks *') defaultcallbacks = ffi.new('git_remote_callbacks *')
@@ -519,9 +504,8 @@ class RemoteCollection(object):
return Remote(self._repo, cremote[0]) return Remote(self._repo, cremote[0])
def create(self, name, url, fetch=None): def create(self, name, url, fetch=None):
"""create(name, url [, fetch]) -> Remote """Create a new remote with the given name and url. Returns a <Remote>
object.
Create a new remote with the given name and url.
If 'fetch' is provided, this fetch refspec will be used instead of the default If 'fetch' is provided, this fetch refspec will be used instead of the default
""" """
@@ -538,13 +522,11 @@ class RemoteCollection(object):
return Remote(self._repo, cremote[0]) return Remote(self._repo, cremote[0])
def rename(self, name, new_name): def rename(self, name, new_name):
"""rename(name, new_name) -> [str] """Rename a remote in the configuration. The refspecs in strandard
Rename a remote in the configuration. The refspecs in strandard
format will be renamed. format will be renamed.
Returns a list of fetch refspecs which were not in the standard format Returns a list of fetch refspecs (list of strings) which were not in
and thus could not be remapped the standard format and thus could not be remapped.
""" """
if not new_name: if not new_name:

42
pygit2/repository.py
View File

@@ -109,13 +109,10 @@ class Repository(_Repository):
# Remotes # Remotes
# #
def create_remote(self, name, url): def create_remote(self, name, url):
"""create_remote(name, url) -> Remote """Create a new remote. Return a <Remote> object.
Creates a new remote.
This method is deprecated, please use Remote.remotes.create() This method is deprecated, please use Remote.remotes.create()
""" """
return self.remotes.create(name, url) return self.remotes.create(name, url)
# #
@@ -123,12 +120,12 @@ class Repository(_Repository):
# #
@property @property
def config(self): def config(self):
"""The configuration file for this repository """The configuration file for this repository.
If a the configuration hasn't been set yet, the default config for If a the configuration hasn't been set yet, the default config for
repository will be returned, including global and system configurations repository will be returned, including global and system configurations
(if they are available).""" (if they are available).
"""
cconfig = ffi.new('git_config **') cconfig = ffi.new('git_config **')
err = C.git_repository_config(cconfig, self._repo) err = C.git_repository_config(cconfig, self._repo)
check_error(err) check_error(err)
@@ -140,8 +137,8 @@ class Repository(_Repository):
"""A snapshot for this repositiory's configuration """A snapshot for this repositiory's configuration
This allows reads over multiple values to use the same version This allows reads over multiple values to use the same version
of the configuration files""" of the configuration files.
"""
cconfig = ffi.new('git_config **') cconfig = ffi.new('git_config **')
err = C.git_repository_config_snapshot(cconfig, self._repo) err = C.git_repository_config_snapshot(cconfig, self._repo)
check_error(err) check_error(err)
@@ -152,9 +149,8 @@ class Repository(_Repository):
# References # References
# #
def create_reference(self, name, target, force=False): def create_reference(self, name, target, force=False):
""" """Create a new reference "name" which points to an object or to
Create a new reference "name" which points to an object or to another another reference.
reference.
Based on the type and value of the target parameter, this method tries Based on the type and value of the target parameter, this method tries
to guess whether it is a direct or a symbolic reference. to guess whether it is a direct or a symbolic reference.
@@ -427,8 +423,7 @@ class Repository(_Repository):
raise ValueError("Only blobs and treeish can be diffed") raise ValueError("Only blobs and treeish can be diffed")
def state_cleanup(self): def state_cleanup(self):
""" """Remove all the metadata associated with an ongoing command like
Remove all the metadata associated with an ongoing command like
merge, revert, cherry-pick, etc. For example: MERGE_HEAD, MERGE_MSG, merge, revert, cherry-pick, etc. For example: MERGE_HEAD, MERGE_MSG,
etc. etc.
""" """
@@ -493,8 +488,7 @@ class Repository(_Repository):
# #
@property @property
def index(self): def index(self):
"""Index representing the repository's index file """Index representing the repository's index file."""
"""
cindex = ffi.new('git_index **') cindex = ffi.new('git_index **')
err = C.git_repository_index(cindex, self._repo) err = C.git_repository_index(cindex, self._repo)
check_error(err, True) check_error(err, True)
@@ -507,8 +501,7 @@ class Repository(_Repository):
@staticmethod @staticmethod
def _merge_options(favor): def _merge_options(favor):
"""Return a 'git_merge_opts *' """Return a 'git_merge_opts *'"""
"""
def favor_to_enum(favor): def favor_to_enum(favor):
if favor == 'normal': if favor == 'normal':
return C.GIT_MERGE_FILE_FAVOR_NORMAL return C.GIT_MERGE_FILE_FAVOR_NORMAL
@@ -534,11 +527,7 @@ class Repository(_Repository):
return opts return opts
def merge_file_from_index(self, ancestor, ours, theirs): def merge_file_from_index(self, ancestor, ours, theirs):
"""merge_file_from_index(ancestor, ours, theirs) -> str """Merge files from index. Return a string with the merge result
Merge files from index.
Return a :py:class:`str` object with the merge result
containing possible conflicts. containing possible conflicts.
ancestor ancestor
@@ -740,9 +729,7 @@ class Repository(_Repository):
# Ahead-behind, which mostly lives on its own namespace # Ahead-behind, which mostly lives on its own namespace
# #
def ahead_behind(self, local, upstream): def ahead_behind(self, local, upstream):
"""ahead_behind(local, upstream) -> (int, int) """Calculate how many different commits are in the non-common parts
Calculate how many different commits are in the non-common parts
of the history between the two given ids. of the history between the two given ids.
Ahead is how many commits are in the ancestry of the 'local' Ahead is how many commits are in the ancestry of the 'local'
@@ -756,7 +743,8 @@ class Repository(_Repository):
upstream upstream
The commit which is considered the upstream The commit which is considered the upstream
Returns a tuple with the number of commits ahead and behind respectively. Returns a tuple of two integers with the number of commits ahead and
behind respectively.
""" """
if not isinstance(local, Oid): if not isinstance(local, Oid):