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

4
pygit2/blame.py

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

64
pygit2/config.py

@ -158,12 +158,11 @@ class Config(object):
return ConfigIterator(self, citer[0])
def get_multivar(self, name, regex=None):
"""get_multivar(name[, regex]) -> [str, ...]
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."""
"""Get each value of a multivar ''name'' as a list of strings.
The optional ''regex'' parameter is expected to be a regular expression
to filter the variables we're interested in.
"""
assert_string(name, "name")
citer = ffi.new('git_config_iterator **')
@ -175,11 +174,9 @@ class Config(object):
return ConfigMultivarIterator(self, citer[0])
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(regex, "regex")
assert_string(value, "value")
@ -189,14 +186,12 @@ class Config(object):
check_error(err)
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
"""Look up *key* and parse its value as a boolean as per the git-config
rules. Return a boolean value (True or 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)
res = ffi.new('int *')
err = C.git_config_parse_bool(res, val)
@ -205,14 +200,12 @@ class Config(object):
return res[0] != 0
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.
"""Look up *key* and parse its value as an integer as per the git-config
rules. Return an integer.
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)
res = ffi.new('int64_t *')
err = C.git_config_parse_int64(res, val)
@ -221,21 +214,18 @@ class Config(object):
return res[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,
force)
check_error(err)
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
of the configuration files
of the configuration files.
"""
ccfg = ffi.new('git_config **')
err = C.git_config_snapshot(ccfg, self._config)
check_error(err)
@ -278,24 +268,18 @@ class Config(object):
@staticmethod
def get_system_config():
"""get_system_config() -> Config
Return an object representing the system configuration file."""
"""Return a <Config> object representing the system configuration file.
"""
return Config._from_found_config(C.git_config_find_system)
@staticmethod
def get_global_config():
"""get_global_config() -> Config
Return an object representing the global configuration file."""
"""Return a <Config> object representing the global configuration file.
"""
return Config._from_found_config(C.git_config_find_global)
@staticmethod
def get_xdg_config():
"""get_xdg_config() -> Config
Return an object representing the global configuration file."""
"""Return a <Config> object representing the global configuration file.
"""
return Config._from_found_config(C.git_config_find_xdg)

2
pygit2/credentials.py

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

39
pygit2/index.py

@ -110,8 +110,7 @@ class Index(object):
check_error(err, True)
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)
check_error(err, True)
@ -120,9 +119,8 @@ class Index(object):
check_error(err)
def read_tree(self, tree):
"""read_tree([Tree|Oid])
Replace the contents of the Index with those of a tree
"""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>).
The tree will be read recursively and all its children will also be
inserted into the Index.
@ -144,9 +142,8 @@ class Index(object):
check_error(err)
def write_tree(self, repo=None):
"""write_tree([repo]) -> Oid
Create a tree out of the Index
"""Create a tree out of the Index. Return the <Oid> object of the
written tree.
The contents of the index will be written out to the object
database. If there is no associated repository, 'repo' must be
@ -181,13 +178,11 @@ class Index(object):
check_error(err, True)
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 repository.
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
repository.
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.
@ -206,12 +201,8 @@ class Index(object):
check_error(err, True)
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 :py:class:`~pygit2.Diff` object with the differences
between the index and the working copy.
"""Diff the index against the working directory. Return a <Diff> object
with the differences between the index and the working copy.
Arguments:
@ -242,12 +233,8 @@ class Index(object):
return Diff.from_c(bytes(ffi.buffer(cdiff)[:]), self._repo)
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 :py:class:`~pygit2.Diff` object with the differences between
the index and the given tree.
"""Diff the index against a tree. Return a <Diff> object with the
differences between the index and the given tree.
Arguments:

26
pygit2/refspec.py

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

50
pygit2/remote.py

@ -170,17 +170,14 @@ class Remote(object):
check_error(err)
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)
check_error(err)
def fetch(self, signature=None, message=None):
"""fetch([signature[, message]]) -> TransferProgress
Perform a fetch against this remote.
"""Perform a fetch against this remote. Returns a <TransferProgress>
object.
"""
# Get the default callbacks first
@ -234,10 +231,7 @@ class Remote(object):
return C.git_remote_refspec_count(self._remote)
def get_refspec(self, n):
"""get_refspec(n) -> Refspec
Return the refspec at the given position
"""
"""Return the <Refspec> object at the given position."""
spec = C.git_remote_get_refspec(self._remote, n)
return Refspec(self, spec)
@ -273,32 +267,23 @@ class Remote(object):
err = C.git_remote_set_push_refspecs(self._remote, arr)
check_error(err)
def add_fetch(self, spec):
"""add_fetch(refspec)
Add a fetch refspec (str) to the remote"""
err = C.git_remote_add_fetch(self._remote, to_bytes(spec))
def add_fetch(self, refspec):
"""Add a fetch refspec (str) to the remote."""
err = C.git_remote_add_fetch(self._remote, to_bytes(refspec))
check_error(err)
def add_push(self, spec):
"""add_push(refspec)
Add a push refspec (str) to the remote"""
err = C.git_remote_add_push(self._remote, to_bytes(spec))
def add_push(self, refspec):
"""Add a push refspec (str) to the remote."""
err = C.git_remote_add_push(self._remote, to_bytes(refspec))
check_error(err)
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.
:param [str] specs: push refspecs to use
:param Signature signature: signature to use when updating the tips (optional)
:param str message: message to use when updating the tips (optional)
"""
# Get the default callbacks first
defaultcallbacks = ffi.new('git_remote_callbacks *')
@ -519,9 +504,8 @@ class RemoteCollection(object):
return Remote(self._repo, cremote[0])
def create(self, name, url, fetch=None):
"""create(name, url [, fetch]) -> Remote
Create a new remote with the given name and url.
"""Create a new remote with the given name and url. Returns a <Remote>
object.
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])
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.
Returns a list of fetch refspecs which were not in the standard format
and thus could not be remapped
Returns a list of fetch refspecs (list of strings) which were not in
the standard format and thus could not be remapped.
"""
if not new_name:

42
pygit2/repository.py

@ -109,13 +109,10 @@ class Repository(_Repository):
# Remotes
#
def create_remote(self, name, url):
"""create_remote(name, url) -> Remote
Creates a new remote.
"""Create a new remote. Return a <Remote> object.
This method is deprecated, please use Remote.remotes.create()
"""
return self.remotes.create(name, url)
#
@ -123,12 +120,12 @@ class Repository(_Repository):
#
@property
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
repository will be returned, including global and system configurations
(if they are available)."""
(if they are available).
"""
cconfig = ffi.new('git_config **')
err = C.git_repository_config(cconfig, self._repo)
check_error(err)
@ -140,8 +137,8 @@ class Repository(_Repository):
"""A snapshot for this repositiory's configuration
This allows reads over multiple values to use the same version
of the configuration files"""
of the configuration files.
"""
cconfig = ffi.new('git_config **')
err = C.git_repository_config_snapshot(cconfig, self._repo)
check_error(err)
@ -152,9 +149,8 @@ class Repository(_Repository):
# References
#
def create_reference(self, name, target, force=False):
"""
Create a new reference "name" which points to an object or to another
reference.
"""Create a new reference "name" which points to an object or to
another reference.
Based on the type and value of the target parameter, this method tries
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")
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,
etc.
"""
@ -493,8 +488,7 @@ class Repository(_Repository):
#
@property
def index(self):
"""Index representing the repository's index file
"""
"""Index representing the repository's index file."""
cindex = ffi.new('git_index **')
err = C.git_repository_index(cindex, self._repo)
check_error(err, True)
@ -507,8 +501,7 @@ class Repository(_Repository):
@staticmethod
def _merge_options(favor):
"""Return a 'git_merge_opts *'
"""
"""Return a 'git_merge_opts *'"""
def favor_to_enum(favor):
if favor == 'normal':
return C.GIT_MERGE_FILE_FAVOR_NORMAL
@ -534,11 +527,7 @@ class Repository(_Repository):
return opts
def merge_file_from_index(self, ancestor, ours, theirs):
"""merge_file_from_index(ancestor, ours, theirs) -> str
Merge files from index.
Return a :py:class:`str` object with the merge result
"""Merge files from index. Return a string with the merge result
containing possible conflicts.
ancestor
@ -740,9 +729,7 @@ class Repository(_Repository):
# Ahead-behind, which mostly lives on its own namespace
#
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.
Ahead is how many commits are in the ancestry of the 'local'
@ -756,7 +743,8 @@ class Repository(_Repository):
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):