Bug#597054: python-apt: improvements to the documentation
Find attached a number of patches addressing your concerns.
--
blog: http://tshepang.tumblr.com
=== modified file 'apt/cache.py'
--- apt/cache.py 2010-09-03 10:08:20 +0000
+++ apt/cache.py 2010-09-17 14:00:53 +0000
@@ -46,15 +46,15 @@
class Cache(object):
"""Dictionary-like package cache.
- This class has all the packages that are available in it's
- dictionary.
+ All available packages are contained in the dictionary of this class.
Keyword arguments:
- progress -- a OpProgress object
- rootdir -- a alternative root directory. if that is given
- the system sources.list and system lists/ files are
- not read, only files relative to the given rootdir
- memonly -- build the cache in memory only
+
+ * progress -- an OpProgress object
+ * rootdir -- an alternative root directory; the system sources.list
+ and lists/files are skipped in favour of files relative to the
+ rootdir if given
+ * memonly -- build the cache in memory
"""
def __init__(self, progress=None, rootdir=None, memonly=False):
@@ -115,8 +115,9 @@
callback()
def open(self, progress=None):
- """ Open the package cache, after that it can be used like
- a dictionary
+ """Open the package cache.
+
+ After this, the package cache can be used like a dictionary.
"""
if progress is None:
progress = apt.progress.base.OpProgress()
@@ -174,7 +175,8 @@
raise StopIteration
def has_key(self, key):
- return (key in self._set)
+ """Return True if key (a package name), is found in the cache."""
+ return (pkgname in self._set)
def __contains__(self, key):
return (key in self._set)
@@ -183,10 +185,11 @@
return len(self._set)
def keys(self):
+ """Return a list of all package names in the cache."""
return list(self._set)
def get_changes(self):
- """ Get the marked changes """
+ """Get the marked changes."""
changes = []
marked_keep = self._depcache.marked_keep
for pkg in self._cache.packages:
@@ -220,7 +223,7 @@
@property
def required_space(self):
- """Get the size of the additional required space on the fs."""
+ """Get the size of the additional required space on the file system."""
return self._depcache.usr_size
@property
@@ -281,7 +284,7 @@
os.close(lock)
def is_virtual_package(self, pkgname):
- """Return whether the package is a virtual package."""
+ """Return True in case of a virtual package."""
try:
pkg = self._cache[pkgname]
except KeyError:
@@ -296,12 +299,12 @@
Return a list of packages which provide the virtual package of the
specified name.
- If 'candidate_only' is False, return all packages with at
+ If `candidate_only` is False, return all packages with at
least one version providing the virtual package. Otherwise,
return only those packages where the candidate version
provides the virtual package.
- If 'include_nonvirtual' is True then it will search for all
+ If `include_nonvirtual` is True then it will search for all
packages providing pkgname, even if pkgname is not itself
a virtual pkg.
"""
@@ -328,13 +331,14 @@
@deprecated_args
def update(self, fetch_progress=None, pulse_interval=0,
raise_on_error=True, sources_list=None):
- """Run the equivalent of apt-get update.
-
- The first parameter *fetch_progress* may be set to an instance of
- apt.progress.FetchProgress, the default is apt.progress.FetchProgress()
- .
+ """Run the equivalent of ``apt-get update``.
+
+ The first parameter, *fetch_progress*, may optionally be set to an
+ instance of apt.progress.FetchProgress (it's set to
+ apt.progress.base.AcquireProgress() by default)
+
sources_list -- Update a alternative sources.list than the default.
- Note that the sources.list.d directory is ignored in this case
+ Note that the sources.list.d directory is ignored in this case.
"""
lockfile = apt_pkg.config.find_dir("Dir::State::Lists") + "lock"
lock = apt_pkg.get_lock(lockfile)
@@ -439,18 +443,18 @@
return (res == pm.RESULT_COMPLETED)
def clear(self):
- """ Unmark all changes """
+ """Unmark all changes."""
self._depcache.init()
# cache changes
def cache_post_change(self):
- " called internally if the cache has changed, emit a signal then "
+ """Called internally if the cache has changed, emit a signal then."""
self._run_callbacks("cache_post_change")
def cache_pre_change(self):
- """ called internally if the cache is about to change, emit
- a signal then """
+ """Called internally if the cache is about to change, emit
+ a signal then."""
self._run_callbacks("cache_pre_change")
def connect(self, name, callback):
@@ -467,14 +471,14 @@
active as soon as it is created, and disabled when the object is
deleted or when release() is called.
- You can use the action group as a context manager, this is the
+ You can use the action group as a context manager; this is the
recommended way::
with cache.actiongroup():
for package in my_selected_packages:
package.mark_install()
- This way, the ActionGroup is automatically released as soon as the
+ This way, the action group is automatically released as soon as the
with statement block is left. It also has the benefit of making it
clear which parts of the code run with a action group and which
don't.
@@ -483,7 +487,7 @@
@property
def dpkg_journal_dirty(self):
- """Return True if the dpkg was interrupted
+ """Return True if the dpkg was interrupted.
All dpkg operations will fail until this is fixed, the action to
fix the system if dpkg got interrupted is to run
@@ -624,7 +628,7 @@
return (key in self._filtered)
def _reapply_filter(self):
- " internal helper to refilter "
+ "Internal helper to refilter."
self._filtered = {}
for pkg in self.cache:
for f in self._filters:
=== modified file 'debian/changelog'
--- debian/changelog 2010-09-07 12:02:50 +0000
+++ debian/changelog 2010-09-16 08:21:05 +0000
@@ -1,5 +1,8 @@
python-apt (0.7.97.2) UNRELEASED; urgency=low
+ [ Tshepang Lekhonkhobe ]
+ * a bunch of doc improvements (EG: consistency fixes, grammar improvements)
+
[ Michael Vogt ]
* python/acquire.cc:
- return long long when calling TotalNeeded(), FetchNeeded() and
=== modified file 'apt/debfile.py'
--- apt/debfile.py 2010-09-07 12:02:50 +0000
+++ apt/debfile.py 2010-09-17 14:00:53 +0000
@@ -16,7 +16,7 @@
# along with this program; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
# USA
-"""Classes for working with locally available Debian packages."""
+"""Classes for working with locally-available Debian packages."""
import apt
import apt_inst
import apt_pkg
@@ -31,7 +31,7 @@
"""Exception which is raised if a file is no Debian archive."""
class DebPackage(object):
- """A Debian Package (.deb file)."""
+ """An object representing a Debian Package (.deb file)."""
# Constants for comparing the local package file with the version
# in the cache
@@ -57,7 +57,7 @@
self.open(filename)
def open(self, filename):
- """ open given debfile """
+ """Open a given debfile."""
self._dbg(3, "open '%s'" % filename)
self._need_pkgs = []
self._installed_conflicts = set()
@@ -74,7 +74,7 @@
@property
def filelist(self):
- """return the list of files in the deb."""
+ """Return the list of files in the deb."""
files = []
try:
self._debfile.data.go(lambda item, data: files.append(item.name))
@@ -168,7 +168,7 @@
return False
def _check_single_pkg_conflict(self, pkgname, ver, oper):
- """Return True if a pkg conflicts with a real installed/marked pkg."""
+ """Return ``True`` if a pkg conflicts with a real installed/marked pkg."""
# FIXME: deal with conflicts against its own provides
# (e.g. Provides: ftp-server, Conflicts: ftp-server)
self._dbg(3, "_check_single_pkg_conflict() pkg='%s' ver='%s' oper='%s'" % (pkgname, ver, oper))
@@ -299,10 +299,9 @@
def check_breaks_existing_packages(self):
"""
- check if installing the package would break exsisting
- package on the system, e.g. system has:
- smc depends on smc-data (= 1.4)
- and user tries to installs smc-data 1.6
+ Check if installing the package would break existing
+ package(s) on the system, e.g. system has:
+ smc depends on smc-data (= 1.4) and user tries to install smc-data 1.6.
"""
# show progress information as this step may take some time
size = float(len(self._cache))
@@ -480,7 +479,7 @@
def required_changes(self):
"""Get the changes required to satisfy the dependencies.
- Returns: a tuple with (install, remove, unauthenticated)
+ Returns: a tuple with (install, remove, unauthenticated).
"""
install = []
remove = []
@@ -501,7 +500,7 @@
@property
def control_filelist(self):
- """ return the list of files in control.tar.gt """
+ """Return a list of files in control.tar.gz."""
try:
from debian.debfile import DebFile
except:
@@ -549,7 +548,7 @@
return data
def control_content(self, name):
- """ return the content of a specific control.tar.gz file """
+ """Return the content of a specific control.tar.gz file."""
try:
from debian.debfile import DebFile
except:
@@ -560,7 +559,7 @@
return ""
def data_content(self, name):
- """ return the content of a specific control.tar.gz file """
+ """Return the content of a specific control.tar.gz file."""
try:
from debian.debfile import DebFile
except:
@@ -647,7 +646,7 @@
self._sections["Description"] = s
def check(self):
- """Check if the package is installable.."""
+ """Check if the package is installable."""
if not self.check_conflicts():
for pkgname in self._installed_conflicts:
if self._cache[pkgname]._pkg.essential:
=== modified file 'apt/package.py'
--- apt/package.py 2010-08-27 13:06:54 +0000
+++ apt/package.py 2010-09-17 14:00:53 +0000
@@ -208,6 +208,12 @@
class Version(object):
"""Representation of a package version.
+
+ One way to create an instance::
+
+ cache = apt.Cache()
+ pkg = cache["python-apt"]
+ pkgv = pkg.candidate
.. versionadded:: 0.7.9
"""
=== modified file 'apt/package.py'
--- apt/package.py 2010-08-27 13:06:54 +0000
+++ apt/package.py 2010-09-17 14:00:53 +0000
@@ -300,7 +306,7 @@
@property
def downloadable(self):
- """Return whether the version of the package is downloadable."""
+ """Return True if the version of the package is downloadable."""
return bool(self._cand.downloadable)
@property
@@ -327,7 +333,7 @@
def description(self):
"""Return the formatted long description.
- Return the formated long description according to the Debian policy
+ Return the formatted long description according to the Debian policy
(Chapter 5.6.13).
See http://www.debian.org/doc/debian-policy/ch-controlfields.html
for more information.
@@ -539,9 +545,9 @@
is used.
The parameter *unpack* describes whether the source should be unpacked
- (``True``) or not (``False``). By default, it is unpacked.
+ (True) or not (False). By default, it is unpacked.
- If *unpack* is ``True``, the path to the extracted directory is
+ If *unpack* is True, the path to the extracted directory is
returned. Otherwise, the path to the .dsc file is returned.
"""
src = apt_pkg.SourceRecords()
@@ -724,7 +730,7 @@
@property
def essential(self):
- """Return True if the package is an essential part of the system."""
+ """Return ``True`` if the package is an essential part of the system."""
return self._pkg.essential
@DeprecatedProperty
@@ -836,7 +842,7 @@
def description(self):
"""Return the formatted long description.
- Return the formated long description according to the Debian policy
+ Return the formatted long description according to the Debian policy
(Chapter 5.6.13).
See http://www.debian.org/doc/debian-policy/ch-controlfields.html
for more information.
@@ -1152,12 +1158,12 @@
@property
def is_inst_broken(self):
- """Return True if the to-be-installed package is broken."""
+ """Return ``True`` if the to-be-installed package is broken."""
return self._pcache._depcache.is_inst_broken(self._pkg)
@property
def is_now_broken(self):
- """Return True if the installed package is broken."""
+ """Return ``True`` if the installed package is broken."""
return self._pcache._depcache.is_now_broken(self._pkg)
# depcache actions
Reply to: