Bug#597054: python-apt: improvements to the documentation
Package: python-apt
Version: 0.7.97.1
Severity: normal
Please find attached.
--
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-15 22:09:43 +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.
+ This class has all available packages in its dictionary.
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,7 +115,7 @@
callback()
def open(self, progress=None):
- """ Open the package cache, after that it can be used like
+ """ Open the package cache, after which it can be used like
a dictionary
"""
if progress is None:
@@ -173,8 +173,9 @@
yield self[pkgname]
raise StopIteration
- def has_key(self, key):
- return (key in self._set)
+ def has_key(self, pkgname):
+ "Return ``True`` if pkg `pkgname` is found in the cache."
+ return (pkgname in self._set)
def __contains__(self, key):
return (key in self._set)
@@ -183,10 +184,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:
@@ -202,9 +204,9 @@
def upgrade(self, dist_upgrade=False):
"""Upgrade all packages.
- If the parameter *dist_upgrade* is True, new dependencies will be
+ If the parameter *dist_upgrade* is ``True``, new dependencies will be
installed as well (and conflicting packages may be removed). The
- default value is False.
+ default value is ``False``.
"""
self.cache_pre_change()
self._depcache.upgrade(dist_upgrade)
@@ -220,7 +222,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 filessystem."""
return self._depcache.usr_size
@property
@@ -281,7 +283,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 +298,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 +330,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 be set to an instance of
+ :class:`apt.progress.FetchProgress` (default is
+ :class:`apt.progress.base.AcquireProgress()`)
+
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 +442,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):
@@ -461,20 +464,20 @@
self._callbacks[name].append(callback)
def actiongroup(self):
- """Return an ActionGroup() object for the current cache.
+ """Return an :class:`ActionGroup()` object for the current cache.
- Action groups can be used to speedup actions. The action group is
+ Action groups can be used to speed-up actions. The action group is
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,11 +486,11 @@
@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
- 'dpkg --configure -a' as root.
+ ``dpkg --configure -a`` as root.
"""
dpkg_status_dir = os.path.dirname(
apt_pkg.config.find_file("Dir::State::status"))
@@ -624,7 +627,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 'apt/cdrom.py'
--- apt/cdrom.py 2009-07-31 13:24:09 +0000
+++ apt/cdrom.py 2010-09-15 22:18:00 +0000
@@ -28,20 +28,16 @@
class Cdrom(apt_pkg.Cdrom):
- """Support for apt-cdrom like features.
-
- This class has several optional parameters for initialisation, which may
- be used to influence the behaviour of the object:
-
- The optional parameter `progress` is a CdromProgress() subclass, which will
- ask for the correct cdrom, etc. If not specified or None, a CdromProgress()
- object will be used.
-
- The optional parameter `mountpoint` may be used to specify an alternative
- mountpoint.
-
- If the optional parameter `nomount` is True, the cdroms will not be
- mounted. This is the default behaviour.
+ """Support for ``apt-cdrom``-like features.
+
+ All parameters for this class are optional:
+
+ * `progress` is a CdromProgress() subclass, which will ask for the
+ correct cdrom, etc. If not specified or None, a :class:`CdromProgress()`
+ object will be used.
+ * `mountpoint` may be used to specify an alternative mount point.
+ * If the `nomount` is True, the cdroms will not be mounted. This is
+ the default behaviour.
"""
def __init__(self, progress=None, mountpoint=None, nomount=True):
=== modified file 'apt/debfile.py'
--- apt/debfile.py 2010-09-07 12:02:50 +0000
+++ apt/debfile.py 2010-09-15 22:27:23 +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 package files."""
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 file (.deb)."""
# 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))
@@ -84,7 +84,7 @@
return files
def _is_or_group_satisfied(self, or_group):
- """Return True if at least one dependency of the or-group is satisfied.
+ """Return ``True`` if at least one dependency of the or-group is satisfied.
This method gets an 'or_group' and analyzes if at least one dependency
of this group is already satisfied.
@@ -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))
@@ -262,9 +262,9 @@
return []
def replaces_real_pkg(self, pkgname, oper, ver):
- """Return True if a given non-virtual package is replaced.
+ """Return ``True`` if a given non-virtual package is replaced.
- Return True if the deb packages replaces a real (not virtual)
+ Return ``True`` if the deb packages replaces a real (not virtual)
packages named (pkgname, oper, ver).
"""
self._dbg(3, "replaces_real_pkg() %s %s %s" % (pkgname, oper, ver))
@@ -287,7 +287,7 @@
"""Check if there are conflicts with existing or selected packages.
Check if the package conflicts with a existing or to be installed
- package. Return True if the pkg is OK.
+ package. Return ``True`` if the pkg is OK.
"""
res = True
for or_group in self.conflicts:
@@ -299,10 +299,10 @@
def check_breaks_existing_packages(self):
"""
- check if installing the package would break exsisting
- package on the system, e.g. system has:
+ Check if installing the package would break exsisting
+ package(s) on the system, e.g. system has:
smc depends on smc-data (= 1.4)
- and user tries to installs smc-data 1.6
+ and user tries to installs smc-data 1.6.
"""
# show progress information as this step may take some time
size = float(len(self._cache))
@@ -480,7 +480,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 +501,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 +549,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 +560,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 +647,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-15 20:48:55 +0000
@@ -208,6 +208,16 @@
class Version(object):
"""Representation of a package version.
+
+ One way to create an instance::
+
+ cache = apt.Cache()
+ pkg = cache["python-apt"]
+ pkgv = pkg.candidate
+
+ And another not-so-readable way::
+
+ pkgv = apt.Cache()["python-apt"].candidate
.. versionadded:: 0.7.9
"""
@@ -300,7 +310,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 +337,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.
@@ -724,7 +734,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 +846,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 +1162,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
=== 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
Reply to: