Re: Request for review: python-apt inline documentation
Hi again,
Picking up where I left off.
Julian Andres Klode wrote:
> class ActionGroup(__builtin__.object)
> | ActionGroup(depcache)
> |
> | Create a new ActionGroup() object. The parameter *depcache* refers to an
> | apt_pkg.DepCache() object.
> |
> | ActionGroups disable certain cleanup actions, so modifying many packages
> | is much faster.
Maybe:
An ActionGroup object represents a collection of actions (package
installations, removals, etc) to be performed as a group. Until the
ActionGroup is released, there is no guarantee that the cache is in
a sane state.
Thus if you are making many changes to the list of installed packages,
using an ActionGroup can make this much faster. Currently the only
effect is to delay discovery of unneeded packages that were marked
as automatically installed.
[...]
> | release(...)
> | release()
End the scope of this action group. If this is the only action
group bound to the cache, this will cause any deferred cleanup actions
to be performed.
[...]
> class Cache(__builtin__.object)
> | Cache([progress]) -> Cache() object.
> |
> | The cache provides access to the packages and other stuff.
The APT cache file contains a hash table mapping names of binary
packages to their metadata. A Cache object is the in-core representation
of the same. It provides access to APT’s idea of the list of available
packages.
> | The optional parameter *progress* can be used to specify an
> | apt.progress.OpProgress() object (or similar) which displays
> | the opening progress.
... which may report progress while opening the status file.
The distinction between progress of the initial read and of later
access is a useful one --- good.
> | If not specified, the progress is
> | displayed in simple text form.
To standard output, I guess. Incorporating JBR’s suggestion:
If this parameter is not supplied, the progress of the file-opening
process will be reported in simple, human-readable text to standard
output.
> | The cache can be used like a mapping of package names to Package
> | objects.
same language tweak as JBR: s/like a mapping of/as a mapping from/
> | update(...)
> | update(progress, sources: SourceList, pulse_interval: int) -> bool
> |
> | Update the index files used by the cache.
Maybe:
Fetch updated index files for the repositories tracked by this cache.
> | A call to this method
> | does not affect the current Cache object, instead a new one
> | should be created in order to use the changed index files.
Nice.
same punctuation tweak as JBR: s/, instead a new one/; instead, a new one/
> | The parameter 'progress' takes an apt.progress.base.AcquireProgress
> | object as its argument which will display the progress of fetching
> | the index files. The parameter 'sources' takes an apt_pkg.SourceList
> | object which lists the sources. The parameter 'progress' takes an
> | integer describing the interval (in microseconds) in which the
> | pulse() method of the 'progress' object will be called.
What’s the difference between apt_pkg.AcquireProgress (as used by Acquire) and
apt.progress.base.AcquireProgress?
The phrasing here is odd (the parameter does not itself take an argument).
The parameter 'progress' can be used to specify an apt_pkg.AcquireProgress()
object, which will report progress information while the index files are
being fetched. The parameter 'sources', if provided, is an
apt_pkg.SourcesList object listing the remote repositories to be used.
The 'progress' parameter indicates how long (in microseconds) to wait between
calls to the pulse() method of the 'progress' object. The default is ...
> | depends_count
> | The number of apt_pkg.Dependency objects stored in the cache.
Maybe, to avoid having to track down the cross-reference:
Number of inter-package dependencies (apt_pkg.Dependency objects)
described in the cache.
What is the expected use for this value? Displaying progress while
iterating as below?
for pkg in cache.packages:
for ver in pkg.version_list:
for deps in ver.depends_list:
for dep in deps:
for alternative in dep:
...
> | file_list
> | A list of apt_pkg.PackageFile objects stored in the cache.
I am guessing these correspond to Packages and Sources files. Or just
Packages files, maybe.
> | package_count
> | The number of apt_pkg.Package objects stored in the cache.
Is this faster to access than len(cache.packages)?
> | package_file_count
> | The number of apt_pkg.PackageFile objects stored in the cache.
Similarly: when would I use this instead of len(cache.file_list)?
> | packages
> | A list of apt_pkg.Package objects stored in the cache.
One for each binary package.
> | provides_count
> | The number of provided packages.
Maybe:
Number of Provides relations described in the cache.
> | ver_file_count
> | The number of (Version, PackageFile) relations.
> |
> | version_count
> | The number of apt_pkg.Version objects stored in the cache.
When would these differ?
> class Cdrom(__builtin__.object)
> | Cdrom()
> |
> | Cdrom objects can be used to identify Debian installation media and to
> | add them to /etc/apt/sources.list.
Interesting.
[...]
> | ident(...)
> | ident(progress: apt_pkg.CdromProgress) -> str
> |
> | Try to identify the CD-ROM and if successful return the identity as a
> | string. Otherwise, return None or raise an error.
Does identity here mean something like the following:
Debian GNU/Linux testing _Squeeze_ - Official Snapshot i386 CD Binary-1 20091221-04:49
or like the following:
CD::e8cd5822376dda70c78c0f8af2a5f8d1-2
Either way, it might make sense to call it a CDROM ID, like the apt-cdrom(1)
manpage does (but with an adjective like "descriptive" or "hexadecimal").
> class Configuration(__builtin__.object)
[...]
> | The most important object is apt_pkg.config
> | which points to the global configuration object. Additional objects
> | can be created, but this is normally not needed.
Probably:
The most important Configuration object ... Other top-level Configuration
objects can be created, but there is usually no reason to.
If I understood correctly, how would one create another top-level
configuration object?
> | clear(...)
> | clear(key: str)
> |
> | Unset the option at the given key and all sub options.
As JBR mentioned, this is a little confusing.
Remove the specified option and all sub-options.
This only affects the configuration of the current process, right?
> | find_b(...)
> | find_i(key: str[, default: bool = False]) -> bool
> |
> | Same as find, but only for boolean values.
I’d drop the "only". What happens if a nonboolean value is encountered?
I guess that is more of a question for apt.conf(5), but I couldn’t find
the answer there.
> | find_file(...)
> | find_file(key: str[, default: str = '']) -> str
> |
> | Same as find(), but for filenames. In the APT configuration, there
> | is a special section Dir:: for storing filenames. find_file() locates
> | the given key and then goes up and prepends the directory names to the
> | return value, e.g. for:
punctuation. s/, e.g. for:/. For example, for/
> |
> | apt_pkg.config['Dir'] = 'a'
> | apt_pkg.config['Dir::D'] = 'b'
> | apt_pkg.config['Dir::D::F'] = 'c'
> |
> | find_file('Dir::D::F') returns 'a/b/c'.
[...]
> | find_i(...)
> | find_i(key: str[, default: int = 0]) -> int
> |
> | Same as find, but only for integer values.
I’d omit the "only".
[...]
> | list(...)
> | list([root: str]) -> list
> |
> | Return a list of all items at the given root.
In the example
apt_pkg.config['Dir'] = 'a'
apt_pkg.config['Dir::D'] = 'b'
apt_pkg.config['Dir::D::F'] = 'c'
if root='Dir', would this return ['Dir::D']?
I guess an example would be useful regardless of the answer.
> | my_tag(...)
> | my_tag() -> str
> |
> | Return the tag of the root of this Configuration object. For the
> | default object, this is an empty string. For a subtree('APT') of
> | such an object, it would be 'APT' (given as an example).
Return the name of the root for this configuration object. For
apt_pkg.config, this is ''. For
apt_pkg.config.subtree('APT').subtree('Get'), this is 'APT::Get'.
[...]
> | subtree(...)
> | sub_tree(key: str) -> apt_pkg.Configuration
> |
> | Return a new apt_pkg.Configuration objects which starts at the
> | given option.
... object with the given option as its root.
> | Example:
Nice.
Okay, that’s all for now. Sorry for the slow progress.
Regards,
Jonathan
Reply to: