Re: Request for review: python-apt inline documentation
I'm saving time by not covering anything that Jonathan Nieder has
already commented on and not producing an actual patch for the
formatted pydoc output.
Julian Andres Klode wrote:
> The style of the attached documentation mostly
> follows what I've seen in Python:
>
> - 'name' for parameter names and attribute
> names and similar stuff; and also for
> strings.
As in, using singlequotes for verbatim strings? Odd that it isn't
used for actual class-names (within text) and so on.
> Help on module apt_pkg:
>
> NAME
> apt_pkg - Classes and functions wrapping the apt-pkg library.
>
> FILE
> /home/jak/Desktop/python-apt/debian-sid/apt_pkg.so
Does it matter that it's pointing into your home directory?
> DESCRIPTION
> The apt_pkg module provides several classes and functions for accessing
> the functionality provided by the apt-pkg library. It allows parsing of
> index files, configuration files, installation/removal of packages and
> much more
JN's rewrite is also a less confusingly constructed list.
> CLASSES
[...]
> class Acquire(__builtin__.object)
> | Acquire(progress: apt_pkg.AcquireProgress) -> Acquire()
> | Create a new Acquire object. The parameter 'progress' can be used to
Besides JN's comment on the missing content (what is an Acquire
object?), there's also no consistency in the form. Later classes
have descriptions that are full sentences from the start, and that's
what I would be inclined to standardise on for clarity; something
like:
This class can be used to create new Acquire objects, which
[extra content here].
[...]
> | total_needed
> | The amount of data that needs to fetched plus the amount of data
^be
> | which has already been fetched.
> |
> | workers
> | A list of all active workers as apt_pkg.AcquireWorker objects.
That is, it returns a list of items as objects, where each item is
an active worker? If that's what it means it's okay; if not, let me
know.
[...]
> class AcquireFile(AcquireItem)
> | AcquireFile(owner, uri[, md5, size, descr, short_descr, destdir,destfile])
> |
> | Represent a file to be fetched. The parameter 'owner' points to
I assume:
This class represents a file to be fetched.
[...]
> | The parameters 'md5' and 'size' are used to verify the resulting
> | file. The parameter 'size' is also to calculate the total amount
^used
> | of data to be fetched and is useful for resuming a interrupted
an
> | download.
[...]
> | error_text
> | If an error occured, a string describing the error; empty string
occurred,
> | otherwise
This spelling mistake occurs below too. Also, even more trivially,
should these all end in periods (full stops)?
[...]
> class AcquireItem(__builtin__.object)
> | Representation of an Acquire item. It is not possible to create
> | instances of this class, but it is possible to create instances
> | of the AcquireFile subclass.
Homogenising JN's suggestion into a full sentence this would be
This is an abstract class representing an item to be fetched
by an Acquire object. It is [...]
(Watch out for JN's "a item" typo.)
[...]
> class AcquireItemDesc(__builtin__.object)
> | Describe an AcquireItem. This class provides the description of the
> | item and the uri the item is fetched from. It is used in progress
> | classes to get the descriptions to display.
I don't see why that initial sentence fragment is there at all; the
following sentence seems to do all the work.
That "uri" should be "URI" in end-user-oriented docs, but here you
may be talking about a Python entity that's lowercase.
[...]
> class AcquireWorker(__builtin__.object)
> | Acquire workers represent exactly one subprocess used for fetching
> | files. This subprocess is created from the methods stored in
> | Dir::Bin::Methods.
Here the ambiguity about whether the start is going to be a noun
phrase, verb phrase or full sentence makes it easy to trip up and
read it as "[This class can] acquire workers represent - ouch!"
Each AcquireWorker represents exactly one subprocess used for
fetching files.
[...]
> class ActionGroup(__builtin__.object)
> | ActionGroup(depcache)
> |
> | Create a new ActionGroup() object. The parameter *depcache* refers to an
> | apt_pkg.DepCache() object.
This class creates a new ActionGroup() object.
> | ActionGroups disable certain cleanup actions, so modifying many packages
> | is much faster.
> |
> | ActionGroup() can also be used with the 'with' statement, but be aware
> | that the ActionGroup() is active as soon as it is created, and not just
> | when entering the context. This means you can write::
> |
> | with apt_pkg.ActionGroup(depcache):
> | depcache.markInstall(pkg)
> |
> | Once the block of the with statement is left, the action group is
'with'
> | automatically released from the cache.
[...]
> class Cache(__builtin__.object)
> | Cache([progress]) -> Cache() object.
> |
> | The cache provides access to the packages and other stuff.
This is the first one that already matches the format I've been
suggesting, but maybe "stuff" should be "data", or "files"?
(Uh-oh, I'm off past JN's comments already and I've barely made a
dent in the file.)
> | The optional parameter *progress* can be used to specify an
> | apt.progress.OpProgress() object (or similar) which displays
> | the opening progress. If not specified, the progress is
> | displayed in simple text form.
What's "the opening progress"? Do you mean "the progress of the
file-opening process"?
> | The cache can be used like a mapping of package names to Package
> | objects.
Is that just an analogy, or is it in fact such a mapping? If so,
you mean "can be used as".
[...]
> | update(...)
> | update(progress, sources: SourceList, pulse_interval: int) -> bool
> |
> | Update the index files used by the 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.
> |
> | The parameter 'progress' takes an apt.progress.base.AcquireProgress
> | object as its argument which will display the progress of fetching
> | the index files. [...]
Arguments are internal to the software, and don't display things. I
think what you mean is that the object does the displaying, so say:
The parameter 'progress' takes as its argument an
apt.progress.base.AcquireProgress object which will display the
progress of the process 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
at
> | pulse() method of the 'progress' object will be called.
[...]
> class Cdrom(__builtin__.object)
[...]
> | add(...)
> | add(progress: apt_pkg.CdromProgress) -> bool
> |
> | Add the given CD-ROM to the sources.list. Returns True on success, may
Pedantically, s/,/;/
[...]
> class Configuration(__builtin__.object)
> | Configuration()
> |
> | Configuration objects represent the configuration of apt. They map
APT
The system as a whole (as opposed to the individual package) is
named APT, upper-case (and this capitalisation is also used below).
[...]
> | clear(...)
> | clear(key: str)
> |
> | Unset the option at the given key and all sub options.
sub-options
Unless they're options for submarines you want a hyphen.
[...]
> | 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).
I don't quite follow what a subtree('APT') is, but I think I would
recommend:
default object, this is an empty string. Thus for example
for a subtree('APT') of such an object, it would be 'APT'.
> | set(...)
> | set(key: str, value: str)
> |
> | Set the given key to the given value. To set int or bool values,
> | encode them using str(value). One can then use find_i()/find_b()
> | to retrieve their value again.
This is probably a sufficiently lofty intellectual context for the
formal generic pronoun "one" to be okay, but I would have been more
likely to write:
encode them using str(value), and then use find_i()/find_b()
> |
> | subtree(...)
> | sub_tree(key: str) -> apt_pkg.Configuration
> |
> | Return a new apt_pkg.Configuration objects which starts at the
X
> | given option. Example:
> |
> | apttree = config.subtree('APT')
> | apttree['Install-Suggests'] = config['APT::Install-Suggests']
I don't understand what "starts at the given option" means here.
[...]
> class DepCache(__builtin__.object)
[...]
> | init(...)
> | init(progress: apt.progress.base.OpProgress)
> |
> | Initialize the depcache (done on construct automatically)
Meaning "done automatically at the method construction stage"?
[...]
> | is_garbage(...)
> | is_garbage(pkg: apt_pkg.Package) -> bool
> |
> | Check whether the package is garbage, i.e. whether it is automatically
> | installed and the reverse dependencies are not installed anymore.
(Otherwise known as (deb)orphans - I like "garbage" better.)
[...]
> | mark_keep(...)
> | mark_keep(pkg: apt_pkg.Package)
> |
> | Mark package for keep
Say:
Mark package to be kept.
[...]
> | set_reinstall(...)
> | set_reinstall(pkg: apt_pkg.Package, reinstall: bool)
> |
> | Set if the package should be reinstalled (reinstall = True or False).
Set whether [...]
[...]
> | usr_size
> | The amount of space required for installing/removing the packages,
> | i.e. the Installed-Size of all packages marked for installation
> | minus the Installed-Size of all packages for for removal.
XXX
[...]
> | dep_type
> | The type of the dependency, may be translated
;
[...]
> | parent_pkg
> | The apt_pkg.Package object of the package which depends.
^^^^^^^
> | parent_ver
> | The apt_pkg.Version object of the package which depends.
^^^^^^^
> | target_pkg
> | The apt_pkg.Package object of the package depended upon
> |
Intransitive "depends" normally means something else, but I suppose
in context this works.
[...]
> | md5
> | The MD5 hash of the description.
>
> class FileLock(__builtin__.object)
> | SystemLock(filename: str)
> |
> | Context manager for locking using a file. The lock is established
> | as soon as the method __enter__() is called. It is released when
> | __exit__() is called.
> |
> | This should be used via the 'with' statement, e.g.::
^^
Is double colon a reStructuredTextism? It crops up several times
below.
[...]
> class Hashes(__builtin__.object)
> | Hashes([object: (bytes, file)])
> |
> | Calculate hashes for the given object. It can be used to create all
> | supported hashes for a file.
> |
> | The parameter *object* can be a bytes (3.X) / str (2.X) object, or an
> | object providing the fileno() method or an integer describing a file
> | descriptor.
That should be 'object', and I'm not sure about the punctuation on
that slash. Without the parenthesised Python version numbers I
would definitely prefer "a bytes/str object", but with them things get
awkward. Could you say "a bytes (3.X) or str (2.X) object, or..."?
[...]
> class IndexRecords(__builtin__.object)
[...]
> | lookup(...)
> | lookup(key: str) -> (HashString, int)
> |
> | Lookup the filename given by 'key', return a tuple (hash, size),
> | whereas the first element 'hash' is an apt_pkg.HashString object
> | and the second element 'size' an int object.
Several very minor problems, starting with s/whereas/where/g:
Look up the filename given by 'key', returning a tuple (hash, size),
where the first element 'hash' is an apt_pkg.HashString object
and the second element 'size' is an int object.
The verb is two words, "look up" ("look it up"), the noun is one.
> class MetaIndex(__builtin__.object)
> | Represent a meta index, i.e. a Release file. This class provides
> | some information about those release files, e.g. whether they
> | are signed or not.
A "meta index" would be self-referential in the sense of a
postmodern parody index; this is just a higher-level index, a
"meta-index".
[...]
> class Package(__builtin__.object)
[...]
> | auto
> | Ignore it, it does nothing. You want to use
this
> | DepCache.is_auto_installed instead.
> |
> | current_state
> | The current state, can be compared against the constants
^which
> | CURSTATE_CONFIG_FILES, CURSTATE_HALF_CONFIGURED,
> | CURSTATE_HALF_INSTALLED, CURSTATE_INSTALLED, CURSTATE_NOT_INSTALLED,
> | CURSTATE_UNPACKED of the apt_pkg module.
[...]
> | important
> | Boolean value determining whether the package has the 'important'
> | flag set ('Important: yes' in the Packages file). Not used anymore.
That's "any more" (or shorter: "No longer used").
> | inst_state
> | The state of the install, can be compared against the constants
^which
> | INSTSTATE_HOLD, INSTSTATE_HOLD_REINSTREQ, INSTSTATE_OK,
> | INSTSTATE_REINSTREQ of the apt_pkg module.
> |
> | name
> | The name of the package.
> |
> | provides_list
> | A list of all packages providing this package. The list contains
> | tuples in the format (providesname, providesver, version)
> | whereas 'version' is an apt_pkg.Version object.
where
> |
> | rev_depends_list
> | An apt_pkg.DependencyList object of all reverse dependencies.
> |
> | section
> | The section of the package.
> |
> | selected_state
> | The state of the selection; can be compared against the constants
,^which
> | SELSTATE_DEINSTALL, SELSTATE_HOLD, SELSTATE_INSTALL, SELSTATE_PURGE,
> | SELSTATE_UNKNOWN of the apt_pkg module.
> |
> | version_list
> | A list of all apt_pkg.Version objects for this package.
>
> class PackageFile(__builtin__.object)
[...]
> | not_source
> | Whether there is no source this file comes from; i.e. whether packages
> | listed in this file can not be downloaded.
This could easily be misinterpreted as meaning "no sourcecode
available" (i.e. non-free). Clarify:
Whether this package file lacks an active (sources.list) source;
packages listed in such a file cannot be downloaded.
[...]
> | version
> | The version set in the release file (e.g. '5.0.X' for lenny, where X is
> | is a point release).
XX
Doubled "is".
[...]
> class PackageManager(__builtin__.object)
[...]
> | do_install(...)
> | do_install(status_fd: int) -> int
> |
> | Install the packages and return one of the class constants
> | RESULT_COMPLETED, RESULT_FAILED, RESULT_INCOMPLETE. The argument
> | status_fd can be used to specify a file descriptor where APT will
> | write status information on (see README.progress-reporting in the
> | apt source code for information what is written there).
Syntax glitches:
status_fd can be used to specify a file descriptor that APT will
write status information on (see README.progress-reporting in the
apt source code for information about what is written there).
[...]
> class Policy(__builtin__.object)
[...]
> | create_pin(...)
> | create_pin(type: str, pkg: str, data: str, priority: int)
> |
> | Create a pin for the policy. The parameter 'type' refers to one of the
> | following strings: 'Version', 'Release', 'Origin'. The argument 'pkg'
> | is the name of the package, the parameter 'data' refers to the value
> | e.g. unstable for type='Release' and the other possible options.
> | The parameter 'priority' gives the priority of the pin.
Punctuation pedantry:
Create a pin for the policy. The parameter 'type' refers to one of the
strings 'Version', 'Release', or 'Origin'. The argument 'pkg' is the
name of the package. The parameter 'data' refers to the value
(e.g. unstable for type='Release') and the other possible options.
The parameter 'priority' gives the priority of the pin.
[...]
> class SourceRecords(__builtin__.object)
[...]
> | lookup(...)
> | lookup(name: str) -> bool
> |
> | Lookup the source package with the given name. Each call moves
Look up
> | the position of the records parser forward. If there are no
> | records anymore, return None. If the lookup failed this way,
more records,
> | access to any of the attributes will result in an AttributeError.
[...]
> | build_depends
> | A dictionary describing the build-time dependencies of the package,
> | the format is the same as used for apt_pkg.Version.depends_list_str.
s/, the/. The/
[...]
> class TagFile(__builtin__.object)
> | TagFile(file)
> |
> | TagFile() objects provide access to debian control files, which consists
> | of multiple RFC822-like formatted sections.
Plural, "consist". And you mean "multiple sections in an
RFC822-like format":
> | To provide access to those sections, TagFile objects provide an iterator
these
> | which yields TagSection objects for each section.
> |
> | TagFile objects also provide another API which uses a shared TagSection
> | object in the 'section' member. The functions step() and jump() can be
> | used to navigate in the file; and offset() tells the current position.
within the file; offset() returns the current position.
[...]
> | jump(...)
> | jump(offset: int) -> bool
> |
> | Jump to the given offset, returns True on success. Note that jumping to
;
> | an offset is not very reliable, and the 'section' attribute does not
> | always point to the section one would expect it to.
No need for the formal generic pronoun "one", it's just
an offset is not very reliable, and the 'section' attribute may
point to an unexpected section.
[...]
> class TagSection(__builtin__.object)
> | TagSection(text: str)
> |
> | TagSection() objects provide methods to access rfc822-style formatted
> | header sections, like those in debian/control or Packages files.
Again "rfc822-style formatted" is a bit of a mess; say
TagSection() objects provide methods to access header sections in an
RFC822-like format, like those in debian/control or Packages files.
[...]
> | bytes(...)
> | bytes() -> int
> |
> | Return the number of bytes this section is large.
Return a section's size in bytes.
[...]
> | find_flag(...)
> | find_flag(name: str) -> int
> |
> | Return 1 if the value at the key is 'yes' or a similar value describing
> | a boolean true. If the field does not exist, or does not have such a
> | value, return 0.
if the key's value is 'yes'
> | find_raw(...)
> | find_raw(name: str[, default = None] -> str
> |
> | Same as find(), but returns the complete key : value field; instead of
> | just the value.
No space before colon in English. But presumably the output doesn't
have a colon in it anyway, so just say:
the complete key/value pair instead of
[...]
> class Version(__builtin__.object)
[...]
> | depends_list
> | A dictionary mapping dependency types to lists (A) of lists (B) of
> | apt_pkg.Dependency objects. The lists (B) represent or dependencies
> | like 'a || b'.
This is too much like a fancy data structure for me to be sure, but
I would suggest:
A dictionary mapping dependency types to lists of sublists of
apt_pkg.Dependency objects. The sublists represent sets of
alternative 'a || b' dependencies.
> | depends_list_str
> | Same as depends_list, except that the apt_pkg.Dependency objects
> | are 3-tuples of the form (name, version, operator); whereas operator
> | is one of '<', '<=', '=', '>=', '>'.
s/whereas/where/g
> | downloadable
> | Whether the version can be downloaded.
> |
> | file_list
> | A list of tuples (pf: apt_pkg.PackageFile, index: int) for the
> | PackageFile objects related to this package. The index can be used
> | to retrieve the record of this package version.
What's a "pf"?
[...]
> | priority
> | The priority of the package as an integer, can be compared against
> | the constants PRI_EXTRA, PRI_IMPORTANT, PRI_OPTIONAL, PRI_REQUIRED,
> | PRI_STANDARD of the apt_pkg module.
Run-on sentence. I think it can be fixed just by s/,/, which/.
[...]
> | provides_list
> | A list of all packages provides by this version. See
provided
> | Package.provides_list for a description of the format.
[...]
> FUNCTIONS
> base64_encode(...)
> base64_encode(value: bytes) -> str
>
> Encode the given bytestring using the Base64. The input may not
> contain '
s/using the Base64/into Base64/
Does it really mean that it chokes on ASCII 0x27?
> Check that the given requirement is fulfilled; i.e. that the version
> string given by 'pkg_ver' matches the version string 'dep_ver' under
> the condition specified by the operator 'dep_op' (<,<=,=,>=,>).
^^^^^^^^^^^
Pedantically speaking this should be "('<', '<=', '=', '>=', or '>')."
> This functions returns True if 'pkg_ver' matches 'dep_ver' under the
X
> condition 'dep_op'; e.g. this returns True:
>
> apt_pkg.check_dep('1', '<=', '2')
[...]
> dequote_string(...)
> dequote_string(string: str) -> str
>
> Dequote the given string by replacing all HTTP encoded values such
> as '%20' with their decoded value (e.g. ' ').
No need for "e.g." in that context - say "(in this case, ' ')."
> gettext(...)
> gettext(msg: str[, domain: str = 'python-apt']) -> str
>
> Translate the given string. Much Faster than Python's version and only
f
> does translations after setlocale() has been called.
Half fragment, half sentence. "This is much faster [...]"
> init(...)
> init()
>
> Short hand for doing init_config() and init_system(). When working
Shorthand
> with command line arguments, first call init_config() then parse
> the command line and finally call init_system().
(Shorthand is one word, commandline can still be two.)
[...]
> init_system(...)
> init_system()
>
> Construct the underlying system.
Everything down to the bottommost turtle or just the apt_pkg system?
[...]
> parse_commandline(...)
> parse_commandLine(config: Configuration, options: list, argv: list) -> list
>
> Parse the command line in 'argv' into the configuration space. The
> list 'options' contains a list of 3-tuples or 4-tuples in the form:
>
> (short_option: str, long_option: str, variable: str[, type: str])
>
> The element 'short_option' is one character, the 'long_option' element
> is the name of the long option, the element 'variable' the name of the
> configuration option the result will be stored in and type is one of
> 'HasArg', 'IntLevel', 'Boolean', 'InvBoolean', 'ConfigFile',
> 'ArbItem'. The default type is 'Boolean'. Read the online documentation
> and the tutorial therin about writing an apt-cdrom clone for more details.
^^^^^^
"Therein", but don't use the word.
[...]. Read the online documentation
and its tutorial on writing an apt-cdrom clone for more details.
By the way, is this online documentation (on upstream's wiki) or
online documentation (on my /usr partition)?
> parse_depends(...)
> parse_depends(s: str) -> list
>
> Parse the dependencies given by 's' and return a list of lists. Each of
> these lists represents one or more options for an or-dependency in the form
> of tuples ``(pkg, ver, comptype)``. In this tuple, the element 'pkg' is the
> name of the package, the element 'ver' the version [or '' if no version was
> requested. The element 'ver' is a comparison operator such as <,<=,=,>=,>.
One of those bizarre rST double-back-flip-quotes has seeped through
into the output, there's a stray "[", and that final list looks like
an exhaustive one, not a "such as".
Parse the dependencies given by 's' and return a list of lists. Each of
these lists represents one or more options for an 'or' dependency in the form
of '(pkg, ver, comptype)' tuples. The tuple element 'pkg' is the name of the
package; the element 'ver' is the version, or '' if no version was requested.
The element 'ver' is a comparison operator ('<', '<=', '=', '>=', or '>').
> parse_src_depends(...)
Ditto.
> quote_string(...)
> quote_string(string: str, repl: str) -> str
>
> Quote the string 'string' by encoding a standard set of characters
> plus the characters given 'repl' using their HTTP value, e.g.
> '%20' for ' '.
I think as well as using jargon this has a missing word or two. And
"quoting" is a misleading word anyway - it's standard URL-encoding.
What does "their HTTP value" mean? It makes me want to throw this
whole thing away and replace it with:
Escape the string 'string', replacing any character not allowed in a URL
with its ASCII value preceded by a percent sign (so for example ' '
becomes '%20').
[...]
> read_config_file(...)
> read_config_file(configuration: apt_pkg.Configuration, filename: str)
>
> Read the configuration file given by filename and set the options
> defined therein in the configuration object.
^^^^^^^
Spelled correctly this time (unless it's meant to be "theremin"),
but still an unhelpfully obscure word.
Read the configuration file 'filename' and set the appropriate
options in the configuration object.
[...]
> read_config_file_isc(...)
> read_config_file(configuration: apt_pkg.Configuration, filename: str)
>
> Read the configuration file given by filename and set the options
> defined therein in the configuration object.
How is this different from read_config_file()?
> rewrite_section(...)
> rewrite_section(section: TagSection, order: list, rewrite_list: list) -> str
>
> Rewrite the section given by 'section' using 'rewrite_list', and order the
> fields according to 'order'.
>
> The parameter 'order' is a list object containing the names of the fields
> in the order they should appear in the rewritten section.
> apt_pkg.REWRITE_PACKAGE_ORDER and apt_pkg.REWRITE_SOURCE_ORDER are two
> predefined lists for rewriting package and source sections, respectively
>
> The parameter 'rewrite_list' is a list of tuples of the form
> ``(tag, newvalue[, renamed_to])``, whereas 'tag' describes the field which
> should be changed, 'newvalue' the value which should be inserted or None
> to delete the field, and the optional renamed_to can be used to rename the
> field.
Unprocessed backticks, and s/whereas/where/g.
[...]
> str_to_time(...)
> str_to_time(rfc_time: str) -> int
>
> Convert the given RFC 1123 formatted string to an Unix timestamp.
X
Unix begins with a consonant sound.
> string_to_bool(...)
> string_to_bool(string: str) -> int
>
> Return 1 if the string is a value such as 'yes', 'true', '1';
> 0 if the string is a value such as 'no', 'false','0'; -1 if
^
> the string is not recognized.
Trivial missing space.
[...]
> uri_to_filename(...)
> uri_to_filename(uri: str) -> str
>
> Return a filename based on the given URI after replacing some
> parts not suited for filenames (e.g. '/').
What apart from slash does it mangle? And what does it replace them
with? How does this differ from quote_string()?
Hurrah, that's the end of apt_pkg! I might as well go straight on
into apt_inst.
> Help on module apt_inst:
>
> NAME
> apt_inst - Functions for working with AR,tar archives and .deb packages.
apt_inst - Functions for working with ar/tar archives and .deb packages.
> FILE
> /home/jak/Desktop/python-apt/debian-sid/apt_inst.so
???
[...]
> class ArArchive(__builtin__.object)
> | ArArchive(file: str/int/file)
> |
> | An ArArchive object represents an archive in the 4.4 BSD AR format,
> | which is used for e.g. deb packages.
I don't know of any reason for capitalising ar archives any
differently from tar ones - the AR isn't an acronym, it's just short
for "archive". Also, this isn't a random example, it's the whole
point:
An ArArchive object represents an archive in the 4.4 BSD ar format
used for deb packages.
> | The parameter 'file' may be a string specifying the path of a file, or
> | a file-like object providing the fileno() method. It may also be an int
> | specifying a file descriptor (returned by e.g. os.open()).
> | The recommended way is to pass in the path to the file.
Way what? Insert ^of using it
[...]
> | extract(...)
> | extract(name: str[, target: str]) -> bool
> |
> | Extract the member given by 'name' into the directory given
> | by 'target'. If the extraction failed, raise OSError. In case
fails
> | of success, return True if the file owner could be set or
> | False if this was not possible. If the requested member
> | does not exist, raise LookupError.
> |
> | extractall(...)
> | extractall([target: str]) -> bool
> |
> | Extract all into the directory given by 'target'. If the extraction
^archive contents
> | failed, raise an error. Otherwise, return True if the owner could
fails
> | be set or False if the owner could not be changed.
> |
> | extractdata(...)
> | extractdata(name: str) -> bytes
> |
> | Return the contents of the member, as a bytes object. Raise
> | LookupError if there is no ArMember with the given name.
> |
> | getmember(...)
> | getmember(name: str) -> ArMember
> |
> | Return a ArMember object for the member given by name. Raise
an 'name'
> | LookupError if there is no ArMember with the given name.
> |
> | getmembers(...)
> | getmembers() -> list
> |
> | Return a list of all members in the AR archive.
ar
> | getnames(...)
> | getnames() -> list
> |
> | Return a list of the names of all members in the AR archive.
ar
[...]
> class ArMember(__builtin__.object)
> | An ArMember object represents a single file within an AR archive. For
ar
> | Debian packages this can be e.g. control.tar.gz. This class provides
> | information about this file, such as the mode and size.
[...]
> | uid
> | The user id of the owner.
ID
>
> class DebFile(ArArchive)
> | DebFile(file: str/int/file)
> |
> | A DebFile object represents a file in the .deb package format.
> |
> | The parameter 'file' may be a string specifying the path of a file, or
> | a file-like object providing the fileno() method. It may also be an int
> | specifying a file descriptor (returned by e.g. os.open()).
> | The recommended way is to pass in the path to the file.
^of using it
> | It differs from ArArchive by providing the members 'control', 'data'
> | and 'version' for accessing the control.tar.gz,data.tar.{gz,bz2,lzma}
> | ,debian-binary members in the archive.
> |
[...]
> | extract(...)
[etc etc]
See above (or maybe they should just say that themselves).
[...]
> class TarFile(__builtin__.object)
[...]
> | go(...)
> | go(callback: callable[, member: str]) -> True
> |
> | Go through the archive and call the callable callback for each
~~~~ ~~~~ ~~~~
Repepetititive, but not a real problem.
> | member with 2 arguments. The first argument is the TarMember and
two
> | the second one is the data, as bytes.
> |
> | The optional parameter 'member' can be used to specify the member for
> | which call the callback. If not specified, it will be called for all
> | members. If specified and not found, LookupError will be raised.
"For which call the callback"? I assume it should be "for which the
callback calls" (whatever that means - I imagine it's clear to
Pythonists).
[...]
> class TarMember(__builtin__.object)
> | Represent a single member of a 'tar' archive.
This class representsa single member of a tar archive.
[...]
> | isdev(...)
> | Determine whether the member is a device (block,character or FIFO).
^
[...]
> | gid
> | The owner's group id
ID.
[...]
> | uid
> | The owner's user id.
ID.
All done! Now it's only a week's work to integrate all these
nitpicks into the originals...
--
JBR with qualifications in linguistics, experience as a Debian
sysadmin, and probably no clue about this particular package
Reply to: