diff options
| author | Michael Vogt <michael.vogt@ubuntu.com> | 2009-01-13 17:22:27 +0100 |
|---|---|---|
| committer | Michael Vogt <michael.vogt@ubuntu.com> | 2009-01-13 17:22:27 +0100 |
| commit | 38d602dc83006c51dfe4ed594d691ea9b0679498 (patch) | |
| tree | b7aedfba82c44cad6c3012f879b5d6d7e8ad1425 /doc | |
| parent | 12cf58d12b969010f3d98b2974d72bbb950b775f (diff) | |
| parent | 614897f798d9f16591fbd29ebe2a6c5674102d2d (diff) | |
| download | python-apt-38d602dc83006c51dfe4ed594d691ea9b0679498.tar.gz | |
* apt/*.py:
- Almost complete cleanup of the code
- Remove inconsistent use of tabs and spaces (Closes: #505443)
- Improved documentation
* apt/debfile.py:
- Drop get*() methods, as they are deprecated and were
never in a stable release
- Make DscSrcPackage working
* apt/gtk/widgets.py:
- Fix the code and document the signals
* Introduce new documentation build with Sphinx
- Contains style Guide (Closes: #481562)
- debian/rules: Build the documentation here
- setup.py: Remove pydoc building and add new docs.
- debian/examples: Include examples from documentation
- debian/python-apt.docs:
+ Change html/ to build/doc/html.
+ Add build/doc/text for the text-only documentation
* setup.py:
- Only create build/data when building, not all the time
- Remove build/mo and build/data on clean -a
* debian/control:
- Remove the Conflicts on python2.3-apt, python2.4-apt, as
they are only needed for oldstable (sarge)
- Build-Depend on python-sphinx (>= 0.5)
* aptsources/distinfo.py:
- Allow @ in mirror urls (Closes: #478171) (LP: #223097)
* Merge Ben Finney's whitespace changes (Closes: #481563)
* Merge Ben Finney's do not use has_key() (Closes: #481878)
* Do not use deprecated form of raise statement (Closes: #494259)
* Add support for PkgRecords.SHA256Hash (Closes: #456113)
Diffstat (limited to 'doc')
50 files changed, 3021 insertions, 333 deletions
diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 00000000..327bba91 --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,79 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source + +.PHONY: help clean html web pickle htmlhelp latex changes linkcheck + +help: + @echo "Please use \`make <target>' where <target> is one of" + @echo " html to make standalone HTML files" + @echo " pickle to make pickle files" + @echo " json to make JSON files" + @echo " htmlhelp to make HTML files and a HTML help project" + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " changes to make an overview over all changed/added/deprecated items" + @echo " linkcheck to check all external links for integrity" + +clean: + -rm -rf build/* + +text: + mkdir -p build/text build/doctrees + $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) build/text + +html: + mkdir -p build/html build/doctrees + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) build/html + @echo + @echo "Build finished. The HTML pages are in build/html." + +pickle: + mkdir -p build/pickle build/doctrees + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) build/pickle + @echo + @echo "Build finished; now you can process the pickle files." + +web: pickle + +json: + mkdir -p build/json build/doctrees + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) build/json + @echo + @echo "Build finished; now you can process the JSON files." + +htmlhelp: + mkdir -p build/htmlhelp build/doctrees + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) build/htmlhelp + @echo + @echo "Build finished; now you can run HTML Help Workshop with the" \ + ".hhp project file in build/htmlhelp." + +latex: + mkdir -p build/latex build/doctrees + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) build/latex + @echo + @echo "Build finished; the LaTeX files are in build/latex." + @echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \ + "run these through (pdf)latex." + +changes: + mkdir -p build/changes build/doctrees + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) build/changes + @echo + @echo "The overview file is in build/changes." + +linkcheck: + mkdir -p build/linkcheck build/doctrees + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) build/linkcheck + @echo + @echo "Link check complete; look for any errors in the above output " \ + "or in build/linkcheck/output.txt." diff --git a/doc/examples/acquire.py b/doc/examples/acquire.py index eef6c1f7..58372961 100644 --- a/doc/examples/acquire.py +++ b/doc/examples/acquire.py @@ -4,15 +4,15 @@ import os import sys import tempfile + def get_file(fetcher, uri, destFile): - # get the file - af = apt_pkg.GetPkgAcqFile(fetcher, - uri=uri, - descr="sample descr", destFile=destFile) - res = fetcher.Run() - if res != fetcher.ResultContinue: - return False - return True + # get the file + af = apt_pkg.GetPkgAcqFile(fetcher, uri=uri, descr="sample descr", + destFile=destFile) + res = fetcher.Run() + if res != fetcher.ResultContinue: + return False + return True apt_pkg.init() @@ -27,12 +27,12 @@ recs = apt_pkg.GetPkgRecords(cache) list = apt_pkg.GetPkgSourceList() list.ReadMainList() -# show the amount fetch needed for a dist-upgrade +# show the amount fetch needed for a dist-upgrade depcache.Upgrade(True) progress = apt.progress.TextFetchProgress() fetcher = apt_pkg.GetAcquire(progress) pm = apt_pkg.GetPackageManager(depcache) -pm.GetArchives(fetcher,list,recs) +pm.GetArchives(fetcher, list, recs) print "%s (%s)" % (apt_pkg.SizeToStr(fetcher.FetchNeeded), fetcher.FetchNeeded) actiongroup = apt_pkg.GetPkgActionGroup(depcache) for pkg in cache.Packages: @@ -43,7 +43,7 @@ try: os.mkdir("/tmp/pyapt-test/partial") except OSError: pass -apt_pkg.Config.Set("Dir::Cache::archives","/tmp/pyapt-test") +apt_pkg.Config.Set("Dir::Cache::archives", "/tmp/pyapt-test") pkg = cache["3ddesktop"] depcache.MarkInstall(pkg) @@ -58,7 +58,7 @@ print fetcher get_file(fetcher, "ftp://ftp.debian.org/debian/dists/README", "/tmp/lala") -pm.GetArchives(fetcher,list,recs) +pm.GetArchives(fetcher, list, recs) for item in fetcher.Items: print item @@ -67,7 +67,7 @@ for item in fetcher.Items: if item.Complete == False: print "No error, still nothing downloaded (%s)" % item.ErrorText print - + res = fetcher.Run() print "fetcher.Run() returned: %s" % res @@ -75,6 +75,3 @@ print "fetcher.Run() returned: %s" % res print "now runing pm.DoInstall()" res = pm.DoInstall(1) print "pm.DoInstall() returned: %s"% res - - - diff --git a/doc/examples/action.py b/doc/examples/action.py index adf26539..9b9d7dd3 100644 --- a/doc/examples/action.py +++ b/doc/examples/action.py @@ -21,15 +21,6 @@ cache.Update(progress) print "Exiting" sys.exit(0) - - - - - - - - - iter = cache["base-config"] print "example package iter: %s" % iter @@ -45,7 +36,6 @@ depcache.Init(progress) #sys.exit() - # get a canidate version ver= depcache.GetCandidateVer(iter) print "Candidate version: %s " % ver @@ -66,7 +56,6 @@ depcache.MarkDelete(iter) print "DelCount: %s " % depcache.DelCount print "%s.MarkedDelete(): %s" % (iter.Name, depcache.MarkedDelete(iter)) - iter = cache["3dchess"] print "\nMarking '%s' for install" % iter.Name depcache.MarkInstall(iter) @@ -97,10 +86,10 @@ print "UsrSize: %s " % apt_pkg.SizeToStr(depcache.UsrSize) print "DebSize: %s " % apt_pkg.SizeToStr(depcache.DebSize) for pkg in cache.Packages: - if pkg.CurrentVer != None and not depcache.MarkedInstall(pkg) and depcache.IsUpgradable(pkg): + if pkg.CurrentVer is not None and not depcache.MarkedInstall(pkg) \ + and depcache.IsUpgradable(pkg): print "Upgrade didn't upgrade (kept): %s" % pkg.Name - print "\nPerforming DistUpgrade" depcache.Upgrade(True) print "Keep: %s " % depcache.KeepCount @@ -112,7 +101,7 @@ print "DebSize: %s " % apt_pkg.SizeToStr(depcache.DebSize) # overview about what would happen for pkg in cache.Packages: if depcache.MarkedInstall(pkg): - if pkg.CurrentVer != None: + if pkg.CurrentVer is not None: print "Marked upgrade: %s " % pkg.Name else: print "Marked install: %s" % pkg.Name diff --git a/doc/examples/all_deps.py b/doc/examples/all_deps.py index f4f1741c..992e98d8 100644 --- a/doc/examples/all_deps.py +++ b/doc/examples/all_deps.py @@ -1,34 +1,36 @@ -#!/usr/bin/env python
-
-import sys
-import apt
-
-
-def dependencies(cache, pkg, deps, key="Depends"):
- #print "pkg: %s (%s)" % (pkg.name, deps)
- candver = cache._depcache.GetCandidateVer(pkg._pkg)
- if candver == None:
- return deps
- dependslist = candver.DependsList
- if dependslist.has_key(key):
- for depVerList in dependslist[key]:
- for dep in depVerList:
- if cache.has_key(dep.TargetPkg.Name):
- if pkg.name != dep.TargetPkg.Name and not dep.TargetPkg.Name in deps:
- deps.add(dep.TargetPkg.Name)
- dependencies(cache, cache[dep.TargetPkg.Name], deps, key)
- return deps
-
-
-pkgname = sys.argv[1]
-c = apt.Cache()
-pkg = c[pkgname]
-
-deps = set()
-
-deps = dependencies(c,pkg, deps, "Depends")
-print " ".join(deps)
-
-preDeps = set()
-preDeps = dependencies(c,pkg, preDeps, "PreDepends")
-print " ".join(preDeps)
+#!/usr/bin/env python +import sys + +import apt + + +def dependencies(cache, pkg, deps, key="Depends"): + #print "pkg: %s (%s)" % (pkg.name, deps) + candver = cache._depcache.GetCandidateVer(pkg._pkg) + if candver is None: + return deps + dependslist = candver.DependsList + if key in dependslist: + for depVerList in dependslist[key]: + for dep in depVerList: + if dep.TargetPkg.Name in cache: + if pkg.name != dep.TargetPkg.Name and \ + not dep.TargetPkg.Name in deps: + deps.add(dep.TargetPkg.Name) + dependencies( + cache, cache[dep.TargetPkg.Name], deps, key) + return deps + + +pkgname = sys.argv[1] +c = apt.Cache() +pkg = c[pkgname] + +deps = set() + +deps = dependencies(c, pkg, deps, "Depends") +print " ".join(deps) + +preDeps = set() +preDeps = dependencies(c, pkg, preDeps, "PreDepends") +print " ".join(preDeps) diff --git a/doc/examples/build-deps.py b/doc/examples/build-deps.py index 65e35f3d..aeb5667c 100755 --- a/doc/examples/build-deps.py +++ b/doc/examples/build-deps.py @@ -3,20 +3,21 @@ import apt_pkg import sys -import sets # only needed for python2.3, python2.4 supports this naively + def get_source_pkg(pkg, records, depcache): - """ get the source package name of a given package """ - version = depcache.GetCandidateVer(pkg) - if not version: - return None - file, index = version.FileList.pop(0) - records.Lookup((file, index)) - if records.SourcePkg != "": - srcpkg = records.SourcePkg - else: - srcpkg = pkg.Name - return srcpkg + """ get the source package name of a given package """ + version = depcache.GetCandidateVer(pkg) + if not version: + return None + file, index = version.FileList.pop(0) + records.Lookup((file, index)) + if records.SourcePkg != "": + srcpkg = records.SourcePkg + else: + srcpkg = pkg.Name + return srcpkg + # main apt_pkg.init() @@ -28,45 +29,45 @@ srcrecords = apt_pkg.GetPkgSrcRecords() # base package that we use for build-depends calculation if len(sys.argv) < 2: - print "need a package name as argument" - sys.exit(1) + print "need a package name as argument" + sys.exit(1) try: - base = cache[sys.argv[1]] + base = cache[sys.argv[1]] except KeyError: - print "No package %s found" % sys.argv[1] - sys.exit(1) -all_build_depends = sets.Set() + print "No package %s found" % sys.argv[1] + sys.exit(1) +all_build_depends = set() # get the build depdends for the package itself srcpkg_name = get_source_pkg(base, records, depcache) print "srcpkg_name: %s " % srcpkg_name if not srcpkg_name: - print "Can't find source package for '%s'" % pkg.Name + print "Can't find source package for '%s'" % pkg.Name srcrec = srcrecords.Lookup(srcpkg_name) if srcrec: - print "Files:" - print srcrecords.Files - bd = srcrecords.BuildDepends - print "build-depends of the package: %s " % bd - for b in bd: - all_build_depends.add(b[0]) + print "Files:" + print srcrecords.Files + bd = srcrecords.BuildDepends + print "build-depends of the package: %s " % bd + for b in bd: + all_build_depends.add(b[0]) # calculate the build depends for all dependencies depends = depcache.GetCandidateVer(base).DependsList for dep in depends["Depends"]: # FIXME: do we need to consider PreDepends? - pkg = dep[0].TargetPkg - srcpkg_name = get_source_pkg(pkg, records, depcache) - if not srcpkg_name: - print "Can't find source package for '%s'" % pkg.Name - continue - srcrec = srcrecords.Lookup(srcpkg_name) - if srcrec: - #print srcrecords.Package - #print srcrecords.Binaries - bd = srcrecords.BuildDepends - #print "%s: %s " % (srcpkg_name, bd) - for b in bd: - all_build_depends.add(b[0]) - + pkg = dep[0].TargetPkg + srcpkg_name = get_source_pkg(pkg, records, depcache) + if not srcpkg_name: + print "Can't find source package for '%s'" % pkg.Name + continue + srcrec = srcrecords.Lookup(srcpkg_name) + if srcrec: + #print srcrecords.Package + #print srcrecords.Binaries + bd = srcrecords.BuildDepends + #print "%s: %s " % (srcpkg_name, bd) + for b in bd: + all_build_depends.add(b[0]) + print "\n".join(all_build_depends) diff --git a/doc/examples/cdrom.py b/doc/examples/cdrom.py index bf044d7c..743220a6 100644 --- a/doc/examples/cdrom.py +++ b/doc/examples/cdrom.py @@ -2,7 +2,8 @@ # example how to deal with the depcache import apt_pkg -import sys, os +import sys +import os import copy from progress import CdromProgress @@ -16,17 +17,11 @@ print cdrom progress = CdromProgress() -(res,ident) = cdrom.Ident(progress) +(res, ident) = cdrom.Ident(progress) print "ident result is: %s (%s) " % (res, ident) apt_pkg.Config.Set("APT::CDROM::Rename", "True") cdrom.Add(progress) - - print "Exiting" sys.exit(0) - - - - diff --git a/doc/examples/checkstate.py b/doc/examples/checkstate.py index 2986872f..3368d500 100755 --- a/doc/examples/checkstate.py +++ b/doc/examples/checkstate.py @@ -14,23 +14,23 @@ packages = cache.Packages uninstalled, updated, upgradable = {}, {}, {} for package in packages: - versions = package.VersionList - if not versions: - continue - version = versions[0] - for other_version in versions: - if apt_pkg.VersionCompare(version.VerStr, other_version.VerStr)<0: - version = other_version - if package.CurrentVer: - current = package.CurrentVer - if apt_pkg.VersionCompare(current.VerStr, version.VerStr)<0: - upgradable[package.Name] = version - break - else: - updated[package.Name] = current - else: - uninstalled[package.Name] = version + versions = package.VersionList + if not versions: + continue + version = versions[0] + for other_version in versions: + if apt_pkg.VersionCompare(version.VerStr, other_version.VerStr)<0: + version = other_version + if package.CurrentVer: + current = package.CurrentVer + if apt_pkg.VersionCompare(current.VerStr, version.VerStr)<0: + upgradable[package.Name] = version + break + else: + updated[package.Name] = current + else: + uninstalled[package.Name] = version for l in (uninstalled, updated, upgradable): - print l.items()[0] + print l.items()[0] diff --git a/doc/examples/config.py b/doc/examples/config.py index 24d90a0d..9d4e51fc 100755 --- a/doc/examples/config.py +++ b/doc/examples/config.py @@ -6,49 +6,53 @@ # config.py -no-h --no-help --help=no ; Turn off help # config.py -qqq -q=3 ; verbosity to 3 # config.py -c /etc/apt/apt.conf ; include that config file] -# config.py -o help=true ; Turn on help by giving a config file string +# config.py -o help=true ; Turn on help by giving a +# ; config file string # config.py -no-h -- -help ; Turn off help, specify the file '-help' # -c and -o are standard APT-program options. # This shows how to use the system for configuration and option control. # The other varient is for ISC object config files. See configisc.py. -import apt_pkg,sys,posixpath; +import apt_pkg +import sys +import posixpath # Create a new empty Configuration object - there is also the system global # configuration object apt_pkg.Config which is used interally by apt-pkg # routines to control unusual situations. I recommend using the sytem global # whenever possible.. -Cnf = apt_pkg.newConfiguration(); +Cnf = apt_pkg.newConfiguration() -print "Command line is",sys.argv +print "Command line is", sys.argv # Load the default configuration file, InitConfig() does this better.. -Cnf.Set("config-file","/etc/apt/apt.conf"); # or Cnf["config-file"] = ".."; +Cnf.Set("config-file", "/etc/apt/apt.conf") # or Cnf["config-file"] = ".." if posixpath.exists(Cnf.FindFile("config-file")): - apt_pkg.ReadConfigFile(Cnf,"/etc/apt/apt.conf"); + apt_pkg.ReadConfigFile(Cnf, "/etc/apt/apt.conf") # Merge the command line arguments into the configuration space -Arguments = [('h',"help","help"), - ('v',"version","version"), - ('q',"quiet","quiet","IntLevel"), - ('c',"config-file","","ConfigFile"), - ('o',"option","","ArbItem")] -print "FileNames",apt_pkg.ParseCommandLine(Cnf,Arguments,sys.argv); +Arguments = [('h', "help", "help"), + ('v', "version", "version"), + ('q', "quiet", "quiet", "IntLevel"), + ('c', "config-file", "", "ConfigFile"), + ('o', "option", "", "ArbItem")] +print "FileNames", apt_pkg.ParseCommandLine(Cnf, Arguments, sys.argv) -print "Quiet level selected is",Cnf.FindI("quiet",0); +print "Quiet level selected is", Cnf.FindI("quiet", 0) # Do some stuff with it -if Cnf.FindB("version",0) == 1: - print "Version selected - 1.1"; +if Cnf.FindB("version", 0) == 1: + print "Version selected - 1.1" -if Cnf.FindB("help",0) == 1: - print "python-apt",apt_pkg.Version,"compiled on",apt_pkg.Date,apt_pkg.Time; - print "Hi, I am the help text for this program"; - sys.exit(0); +if Cnf.FindB("help", 0) == 1: + print "python-apt", apt_pkg.Version, \ + "compiled on", apt_pkg.Date, apt_pkg.Time + print "Hi, I am the help text for this program" + sys.exit(0) -print "No help for you, try -h"; +print "No help for you, try -h" # Print the configuration space -print "The Configuration space looks like:"; +print "The Configuration space looks like:" for I in Cnf.keys(): - print "%s \"%s\";"%(I,Cnf[I]); + print "%s \"%s\";" % (I, Cnf[I]) diff --git a/doc/examples/configisc.py b/doc/examples/configisc.py index 1773a919..de8ec6be 100755 --- a/doc/examples/configisc.py +++ b/doc/examples/configisc.py @@ -8,32 +8,37 @@ # doc/examples/ftp-archive.conf # or a bind8 config file.. -import apt_pkg,sys,posixpath; +import apt_pkg +import sys +import posixpath -ConfigFile = apt_pkg.ParseCommandLine(apt_pkg.Config,[],sys.argv); +ConfigFile = apt_pkg.ParseCommandLine(apt_pkg.Config, [], sys.argv) if len(ConfigFile) != 1: - print "Must have exactly 1 file name"; - sys.exit(0); + print "Must have exactly 1 file name" + sys.exit(0) -Cnf = apt_pkg.newConfiguration(); -apt_pkg.ReadConfigFileISC(Cnf,ConfigFile[0]); +Cnf = apt_pkg.newConfiguration() +apt_pkg.ReadConfigFileISC(Cnf, ConfigFile[0]) # Print the configuration space -#print "The Configuration space looks like:"; +#print "The Configuration space looks like:" #for I in Cnf.keys(): -# print "%s \"%s\";"%(I,Cnf[I]); +# print "%s \"%s\";" % (I, Cnf[I]) # bind8 config file.. -if Cnf.has_key("Zone"): - print "Zones: ",Cnf.SubTree("zone").List(); - for I in Cnf.List("zone"): - SubCnf = Cnf.SubTree(I); - if SubCnf.Find("type") == "slave": - print "Masters for %s: %s"%(SubCnf.MyTag(),SubCnf.ValueList("masters")); +if Cnf.Exists("Zone"): + print "Zones: ", Cnf.SubTree("zone").List() + for I in Cnf.List("zone"): + SubCnf = Cnf.SubTree(I) + if SubCnf.Find("type") == "slave": + print "Masters for %s: %s" % ( + SubCnf.MyTag(), SubCnf.ValueList("masters")) else: - print "Tree definitions:"; - for I in Cnf.List("tree"): - SubCnf = Cnf.SubTree(I); - # This could use Find which would eliminate the possibility of exceptions. - print "Subtree %s with sections '%s' and architectures '%s'"%(SubCnf.MyTag(),SubCnf["Sections"],SubCnf["Architectures"]); + print "Tree definitions:" + for I in Cnf.List("tree"): + SubCnf = Cnf.SubTree(I) + # This could use Find which would eliminate the possibility of + # exceptions. + print "Subtree %s with sections '%s' and architectures '%s'" % ( + SubCnf.MyTag(), SubCnf["Sections"], SubCnf["Architectures"]) diff --git a/doc/examples/deb_inspect.py b/doc/examples/deb_inspect.py index 0befd2bb..cc0d04be 100755 --- a/doc/examples/deb_inspect.py +++ b/doc/examples/deb_inspect.py @@ -6,11 +6,11 @@ import apt_inst import sys import os.path -def Callback(What,Name,Link,Mode,UID,GID,Size,MTime,Major,Minor): + +def Callback(What, Name, Link, Mode, UID, GID, Size, MTime, Major, Minor): """ callback for debExtract """ - - print "%s '%s','%s',%u,%u,%u,%u,%u,%u,%u"\ - % (What,Name,Link,Mode,UID,GID,Size, MTime, Major, Minor); + print "%s '%s','%s',%u,%u,%u,%u,%u,%u,%u" \ + % (What, Name, Link, Mode, UID, GID, Size, MTime, Major, Minor) if __name__ == "__main__": @@ -39,9 +39,11 @@ if __name__ == "__main__": print "extracting archive" dir = "/tmp/deb" os.mkdir(dir) - apt_inst.debExtractArchive(open(file),dir) + apt_inst.debExtractArchive(open(file), dir) + def visit(arg, dirname, names): print "%s/" % dirname for file in names: print "\t%s" % file + os.path.walk(dir, visit, None) diff --git a/doc/examples/depcache.py b/doc/examples/depcache.py index 556c954b..790cc9d6 100644 --- a/doc/examples/depcache.py +++ b/doc/examples/depcache.py @@ -84,7 +84,8 @@ print "UsrSize: %s " % apt_pkg.SizeToStr(depcache.UsrSize) print "DebSize: %s " % apt_pkg.SizeToStr(depcache.DebSize) for pkg in cache.Packages: - if pkg.CurrentVer != None and not depcache.MarkedInstall(pkg) and depcache.IsUpgradable(pkg): + if pkg.CurrentVer is not None and not depcache.MarkedInstall(pkg) \ + and depcache.IsUpgradable(pkg): print "Upgrade didn't upgrade (kept): %s" % pkg.Name @@ -99,7 +100,7 @@ print "DebSize: %s " % apt_pkg.SizeToStr(depcache.DebSize) # overview about what would happen for pkg in cache.Packages: if depcache.MarkedInstall(pkg): - if pkg.CurrentVer != None: + if pkg.CurrentVer is not None: print "Marked upgrade: %s " % pkg.Name else: print "Marked install: %s" % pkg.Name diff --git a/doc/examples/dependant-pkgs.py b/doc/examples/dependant-pkgs.py index f36936a8..5fbbc76d 100755 --- a/doc/examples/dependant-pkgs.py +++ b/doc/examples/dependant-pkgs.py @@ -6,31 +6,31 @@ import sys pkgs = set() cache = apt.Cache() for pkg in cache: - candver = cache._depcache.GetCandidateVer(pkg._pkg) - if candver == None: - continue - dependslist = candver.DependsList - for dep in dependslist.keys(): - # get the list of each dependency object - for depVerList in dependslist[dep]: - for z in depVerList: - # get all TargetVersions of - # the dependency object - for tpkg in z.AllTargets(): - if sys.argv[1] == tpkg.ParentPkg.Name: - pkgs.add(pkg.name) + candver = cache._depcache.GetCandidateVer(pkg._pkg) + if candver is None: + continue + dependslist = candver.DependsList + for dep in dependslist.keys(): + # get the list of each dependency object + for depVerList in dependslist[dep]: + for z in depVerList: + # get all TargetVersions of + # the dependency object + for tpkg in z.AllTargets(): + if sys.argv[1] == tpkg.ParentPkg.Name: + pkgs.add(pkg.name) main = set() universe = set() for pkg in pkgs: - if "universe" in cache[pkg].section: - universe.add(cache[pkg].sourcePackageName) - else: - main.add(cache[pkg].sourcePackageName) + if "universe" in cache[pkg].section: + universe.add(cache[pkg].sourcePackageName) + else: + main.add(cache[pkg].sourcePackageName) -print "main:" +print "main:" print "\n".join(main) print -print "universe:" +print "universe:" print "\n".join(universe) diff --git a/doc/examples/desc.py b/doc/examples/desc.py index 87b9473b..f47517cf 100644 --- a/doc/examples/desc.py +++ b/doc/examples/desc.py @@ -3,7 +3,7 @@ import apt_pkg apt_pkg.init() -apt_pkg.Config.Set("APT::Acquire::Translation","de") +apt_pkg.Config.Set("APT::Acquire::Translation", "de") cache = apt_pkg.GetCache() depcache = apt_pkg.GetDepCache(cache) @@ -15,11 +15,10 @@ print cand desc = cand.TranslatedDescription print desc print desc.FileList -(f,index) = desc.FileList.pop(0) +(f, index) = desc.FileList.pop(0) records = apt_pkg.GetPkgRecords(cache) -records.Lookup((f,index)) +records.Lookup((f, index)) desc = records.LongDesc print len(desc) print desc - diff --git a/doc/examples/gui-inst.py b/doc/examples/gui-inst.py index feefd6ed..8138d922 100755 --- a/doc/examples/gui-inst.py +++ b/doc/examples/gui-inst.py @@ -1,20 +1,13 @@ #!/usr/bin/python # example how to install in a custom terminal widget # see also gnome bug: #169201 - -import apt -import apt_pkg -import sys, os, fcntl -import copy -import string -import fcntl - import pygtk pygtk.require('2.0') import gtk import apt.gtk.widgets + if __name__ == "__main__": win = gtk.Window() @@ -23,14 +16,12 @@ if __name__ == "__main__": win.add(progress) progress.show() win.show() - + cache = apt.cache.Cache(progress.open) if cache["2vcard"].isInstalled: cache["2vcard"].markDelete() else: cache["2vcard"].markInstall() progress.show_terminal(expanded=True) - cache.commit(progress.fetch, - progress.install) - + cache.commit(progress.fetch, progress.install) gtk.main() diff --git a/doc/examples/indexfile.py b/doc/examples/indexfile.py index d383fd61..22d0b635 100644 --- a/doc/examples/indexfile.py +++ b/doc/examples/indexfile.py @@ -10,7 +10,7 @@ cache = apt_pkg.GetCache() depcache = apt_pkg.GetDepCache(cache) pkg = cache["libimlib2"] cand = depcache.GetCandidateVer(pkg) -for (f,i) in cand.FileList: +for (f, i) in cand.FileList: index = sources.FindIndex(f) print index if index: diff --git a/doc/examples/inst.py b/doc/examples/inst.py index ff9d452c..a3a50356 100644 --- a/doc/examples/inst.py +++ b/doc/examples/inst.py @@ -2,27 +2,34 @@ # example how to deal with the depcache import apt -import sys, os +import sys +import os import copy import time from apt.progress import InstallProgress + class TextInstallProgress(InstallProgress): - def __init__(self): - apt.progress.InstallProgress.__init__(self) - self.last = 0.0 - def updateInterface(self): - InstallProgress.updateInterface(self) - if self.last >= self.percent: - return - sys.stdout.write("\r[%s] %s\n" %(self.percent, self.status)) - sys.stdout.flush() - self.last = self.percent - def conffile(self,current,new): - print "conffile prompt: %s %s" % (current,new) - def error(self, errorstr): - print "got dpkg error: '%s'" % errorstr + + def __init__(self): + apt.progress.InstallProgress.__init__(self) + self.last = 0.0 + + def updateInterface(self): + InstallProgress.updateInterface(self) + if self.last >= self.percent: + return + sys.stdout.write("\r[%s] %s\n" %(self.percent, self.status)) + sys.stdout.flush() + self.last = self.percent + + def conffile(self, current, new): + print "conffile prompt: %s %s" % (current, new) + + def error(self, errorstr): + print "got dpkg error: '%s'" % errorstr + cache = apt.Cache(apt.progress.OpTextProgress()) @@ -33,16 +40,12 @@ pkg = cache["3dchess"] # install or remove, the importend thing is to keep us busy :) if pkg.isInstalled: - print "Going to delete %s" % pkg.name - pkg.markDelete() + print "Going to delete %s" % pkg.name + pkg.markDelete() else: - print "Going to install %s" % pkg.name - pkg.markInstall() + print "Going to install %s" % pkg.name + pkg.markInstall() res = cache.commit(fprogress, iprogress) print res sys.exit(0) - - - - diff --git a/doc/examples/metaindex.py b/doc/examples/metaindex.py index 1bce0dba..f00a7e01 100644 --- a/doc/examples/metaindex.py +++ b/doc/examples/metaindex.py @@ -9,7 +9,7 @@ sources.ReadMainList() for metaindex in sources.List: print metaindex - print "URI: ",metaindex.URI - print "Dist: ",metaindex.Dist - print "IndexFiles: ","\n".join([str(i) for i in metaindex.IndexFiles]) + print "URI: ", metaindex.URI + print "Dist: ", metaindex.Dist + print "IndexFiles: ", "\n".join([str(i) for i in metaindex.IndexFiles]) print diff --git a/doc/examples/print_uris.py b/doc/examples/print_uris.py index c8a64223..3b678e83 100755 --- a/doc/examples/print_uris.py +++ b/doc/examples/print_uris.py @@ -12,11 +12,11 @@ upgradable = filter(lambda p: p.isUpgradable, cache) for pkg in upgradable: - pkg._lookupRecord(True) - path = apt_pkg.ParseSection(pkg._records.Record)["Filename"] - cand = pkg._depcache.GetCandidateVer(pkg._pkg) - for (packagefile,i) in cand.FileList: - indexfile = cache._list.FindIndex(packagefile) - if indexfile: - uri = indexfile.ArchiveURI(path) - print uri + pkg._lookupRecord(True) + path = apt_pkg.ParseSection(pkg._records.Record)["Filename"] + cand = pkg._depcache.GetCandidateVer(pkg._pkg) + for (packagefile, i) in cand.FileList: + indexfile = cache._list.FindIndex(packagefile) + if indexfile: + uri = indexfile.ArchiveURI(path) + print uri diff --git a/doc/examples/progress.py b/doc/examples/progress.py index 2723c382..83847598 100644 --- a/doc/examples/progress.py +++ b/doc/examples/progress.py @@ -1,10 +1,11 @@ -import apt -from apt import SizeToStr import sys import time -import string + +import apt + class TextProgress(apt.OpProgress): + def __init__(self): self.last=0.0 @@ -21,37 +22,47 @@ class TextProgress(apt.OpProgress): class TextFetchProgress(apt.FetchProgress): + def __init__(self): pass - + def start(self): pass - + def stop(self): pass - + def updateStatus(self, uri, descr, shortDescr, status): - print "UpdateStatus: '%s' '%s' '%s' '%i'" % (uri,descr,shortDescr, status) + print "UpdateStatus: '%s' '%s' '%s' '%i'" % ( + uri, descr, shortDescr, status) + def pulse(self): - print "Pulse: CPS: %s/s; Bytes: %s/%s; Item: %s/%s" % (SizeToStr(self.currentCPS), SizeToStr(self.currentBytes), SizeToStr(self.totalBytes), self.currentItems, self.totalItems) + print "Pulse: CPS: %s/s; Bytes: %s/%s; Item: %s/%s" % ( + apt.SizeToStr(self.currentCPS), SizeToStr(self.currentBytes), + apt.SizeToStr(self.totalBytes), self.currentItems, self.totalItems) return True def mediaChange(self, medium, drive): - print "Please insert medium %s in drive %s" % (medium, drive) - sys.stdin.readline() + print "Please insert medium %s in drive %s" % (medium, drive) + sys.stdin.readline() #return False class TextInstallProgress(apt.InstallProgress): + def __init__(self): apt.InstallProgress.__init__(self) pass + def startUpdate(self): print "StartUpdate" + def finishUpdate(self): print "FinishUpdate" + def statusChange(self, pkg, percent, status): print "[%s] %s: %s" % (percent, pkg, status) + def updateInterface(self): apt.InstallProgress.updateInterface(self) # usefull to e.g. redraw a GUI @@ -59,20 +70,25 @@ class TextInstallProgress(apt.InstallProgress): class TextCdromProgress(apt.CdromProgress): + def __init__(self): pass + # update is called regularly so that the gui can be redrawn + def update(self, text, step): # check if we actually have some text to display if text != "": print "Update: %s %s" % (string.strip(text), step) + def askCdromName(self): print "Please enter cd-name: ", cd_name = sys.stdin.readline() return (True, string.strip(cd_name)) + def changeCdrom(self): print "Please insert cdrom and press <ENTER>" - answer = sys.stdin.readline() + answer = sys.stdin.readline() return True diff --git a/doc/examples/recommends.py b/doc/examples/recommends.py index b1094aee..f0b3b1be 100755 --- a/doc/examples/recommends.py +++ b/doc/examples/recommends.py @@ -5,37 +5,35 @@ apt_pkg.init() cache = apt_pkg.GetCache() + class Wanted: - def __init__(self, name): - self.name = name - self.recommended = [] - self.suggested = [] + def __init__(self, name): + self.name = name + self.recommended = [] + self.suggested = [] + wanted = {} for package in cache.Packages: - current = package.CurrentVer - if not current: - continue - depends = current.DependsList - for (key, attr) in (('Suggests', 'suggested'), - ('Recommends', 'recommended')): - list = depends.get(key, []) - for dependency in list: - name = dependency[0].TargetPkg.Name - dep = cache[name] - if dep.CurrentVer: - continue - getattr(wanted.setdefault(name, Wanted(name)), - attr).append(package.Name) + current = package.CurrentVer + if not current: + continue + depends = current.DependsList + for (key, attr) in (('Suggests', 'suggested'), + ('Recommends', 'recommended')): + list = depends.get(key, []) + for dependency in list: + name = dependency[0].TargetPkg.Name + dep = cache[name] + if dep.CurrentVer: + continue + getattr(wanted.setdefault(name, Wanted(name)), + attr).append(package.Name) ks = wanted.keys() ks.sort() for want in ks: - print want, wanted[want].recommended, wanted[want].suggested - - - - + print want, wanted[want].recommended, wanted[want].suggested diff --git a/doc/examples/records.py b/doc/examples/records.py index ef04b555..a0fc8dc4 100755 --- a/doc/examples/records.py +++ b/doc/examples/records.py @@ -5,8 +5,9 @@ import apt cache = apt.Cache() for pkg in cache: - if not pkg.candidateRecord: - continue - if pkg.candidateRecord.has_key("Task"): - print "Pkg %s is part of '%s'" % (pkg.name, pkg.candidateRecord["Task"].split()) - #print pkg.candidateRecord + if not pkg.candidateRecord: + continue + if "Task" in pkg.candidateRecord: + print "Pkg %s is part of '%s'" % ( + pkg.name, pkg.candidateRecord["Task"].split()) + #print pkg.candidateRecord diff --git a/doc/examples/sources.py b/doc/examples/sources.py index b48c0ba5..49652982 100644 --- a/doc/examples/sources.py +++ b/doc/examples/sources.py @@ -10,6 +10,7 @@ apt_pkg.init() sources = apt_pkg.GetPkgSrcRecords() sources.Restart() while sources.Lookup('hello'): - print sources.Package, sources.Version, sources.Maintainer, sources.Section, `sources.Binaries` - print sources.Files - print sources.Index.ArchiveURI(sources.Files[0][2]) + print sources.Package, sources.Version, sources.Maintainer, \ + sources.Section, `sources.Binaries` + print sources.Files + print sources.Index.ArchiveURI(sources.Files[0][2]) diff --git a/doc/examples/tagfile.py b/doc/examples/tagfile.py index 653c0a71..4faf08ac 100755 --- a/doc/examples/tagfile.py +++ b/doc/examples/tagfile.py @@ -1,8 +1,8 @@ #!/usr/bin/env python import apt_pkg -Parse = apt_pkg.ParseTagFile(open("/var/lib/dpkg/status","r")); +Parse = apt_pkg.ParseTagFile(open("/var/lib/dpkg/status", "r")) while Parse.Step() == 1: - print Parse.Section.get("Package"); - print apt_pkg.ParseDepends(Parse.Section.get("Depends","")); + print Parse.Section.get("Package") + print apt_pkg.ParseDepends(Parse.Section.get("Depends", "")) diff --git a/doc/examples/update.py b/doc/examples/update.py index be7bb679..364fa1c9 100755 --- a/doc/examples/update.py +++ b/doc/examples/update.py @@ -9,5 +9,5 @@ if __name__ == "__main__": "touch /tmp/update-was-run") c = apt.Cache() res = c.update(apt.progress.TextFetchProgress()) - print "res: ",res + print "res: ", res assert(os.path.exists("/tmp/update-about-to-run")) diff --git a/doc/examples/versiontest.py b/doc/examples/versiontest.py index 95f887f2..fa13cc1c 100755 --- a/doc/examples/versiontest.py +++ b/doc/examples/versiontest.py @@ -1,36 +1,39 @@ #!/usr/bin/python # This is a simple clone of tests/versiontest.cc -import apt_pkg,sys,re,string; -apt_pkg.InitConfig(); -apt_pkg.InitSystem(); +import apt_pkg +import sys +import re -TestFile = apt_pkg.ParseCommandLine(apt_pkg.Config,[],sys.argv); +apt_pkg.InitConfig() +apt_pkg.InitSystem() + +TestFile = apt_pkg.ParseCommandLine(apt_pkg.Config, [], sys.argv) if len(TestFile) != 1: - print "Must have exactly 1 file name"; - sys.exit(0); + print "Must have exactly 1 file name" + sys.exit(0) -# Go over the file.. -List = open(TestFile[0],"r"); -CurLine = 0; +# Go over the file.. +List = open(TestFile[0], "r") +CurLine = 0 while(1): - Line = List.readline(); - CurLine = CurLine + 1; - if Line == "": - break; - Line = string.strip(Line); - if len(Line) == 0 or Line[0] == '#': - continue; - - Split = re.split("[ \n]",Line); + Line = List.readline() + CurLine = CurLine + 1 + if Line == "": + break + Line = Line.strip() + if len(Line) == 0 or Line[0] == '#': + continue + + Split = re.split("[ \n]", Line) - # Check forward - if apt_pkg.VersionCompare(Split[0],Split[1]) != int(Split[2]): - print "Comparision failed on line %u. '%s' ? '%s' %i != %i"%(CurLine, - Split[0],Split[1],apt_pkg.VersionCompare(Split[0],Split[1]), - int(Split[2])); - # Check reverse - if apt_pkg.VersionCompare(Split[1],Split[0]) != -1*int(Split[2]): - print "Comparision failed on line %u. '%s' ? '%s' %i != %i"%(CurLine, - Split[1],Split[0],apt_pkg.VersionCompare(Split[1],Split[0]), - -1*int(Split[2])); + # Check forward + if apt_pkg.VersionCompare(Split[0], Split[1]) != int(Split[2]): + print "Comparision failed on line %u. '%s' ? '%s' %i != %i" % (CurLine, + Split[0], Split[1], apt_pkg.VersionCompare(Split[0], Split[1]), + int(Split[2])) + # Check reverse + if apt_pkg.VersionCompare(Split[1], Split[0]) != -1 * int(Split[2]): + print "Comparision failed on line %u. '%s' ? '%s' %i != %i" % (CurLine, + Split[1], Split[0], apt_pkg.VersionCompare(Split[1], Split[0]), + -1 * int(Split[2])) diff --git a/doc/makefile b/doc/makefile deleted file mode 100644 index 7f9dff2b..00000000 --- a/doc/makefile +++ /dev/null @@ -1,13 +0,0 @@ -# -*- make -*- -BASE=.. -SUBDIR=doc - -# Bring in the default rules -include ../buildlib/defaults.mak - -# Examples -SOURCE = examples/config.py examples/configisc.py examples/tagfile.py \ - examples/versiontest.py examples/checkstate.py \ - examples/recommends.py -TO = $(DOC) -include $(COPY_H) diff --git a/doc/source/apt/cache.rst b/doc/source/apt/cache.rst new file mode 100644 index 00000000..d96cba97 --- /dev/null +++ b/doc/source/apt/cache.rst @@ -0,0 +1,78 @@ +:mod:`apt.cache` --- The Cache class +===================================== +.. automodule:: apt.cache + +The Cache class +--------------- + +.. autoclass:: Cache + :members: + :undoc-members: + + .. describe:: cache[pkgname] + + Return a :class:`Package()` for the package with the name *pkgname*. + +Example +^^^^^^^ + +The following example shows how to load the cache, update it, and upgrade +all the packages on the system:: + + import apt + import apt.progress + + # First of all, open the cache + cache = apt.Cache() + # Now, lets update the package list + cache.update() + # We need to re-open the cache because it needs to read the package list + cache.open(None) + # Now we can do the same as 'apt-get upgrade' does + cache.upgrade() + # or we can play 'apt-get dist-upgrade' + cache.upgrade(True) + # Q: Why does nothing happen? + # A: You forgot to call commit()! + cache.commit(apt.progress.TextFetchProgress(), + apt.progress.InstallProgress()) + + + +Working with Filters +-------------------- +.. autoclass:: Filter + :members: + :inherited-members: + :undoc-members: + +.. autoclass:: MarkedChangesFilter + :members: + :inherited-members: + :undoc-members: + +.. autoclass:: FilteredCache + :members: + :inherited-members: + :undoc-members: + + +Example +^^^^^^^ + +This is an example for a filtered cache, which only allows access to the +packages whose state has been changed, eg. packages marked for installation:: + + >>> from apt.cache import FilteredCache, Cache, MarkedChangesFilter + >>> cache = apt.Cache() + >>> changed = apt.FilteredCache(cache) + >>> changed.setFilter(MarkedChangesFilter()) + >>> print len(changed) == len(cache.GetChanges()) # Both need to have same length + True + + +Exceptions +---------- +.. autoexception:: FetchCancelledException +.. autoexception:: FetchFailedException +.. autoexception:: LockFailedException diff --git a/doc/source/apt/cdrom.rst b/doc/source/apt/cdrom.rst new file mode 100644 index 00000000..56381f14 --- /dev/null +++ b/doc/source/apt/cdrom.rst @@ -0,0 +1,7 @@ +:mod:`apt.cdrom` - Functionality like in apt-cdrom +==================================================== +.. automodule:: apt.cdrom + :members: + + + diff --git a/doc/source/apt/debfile.rst b/doc/source/apt/debfile.rst new file mode 100644 index 00000000..7133b5a8 --- /dev/null +++ b/doc/source/apt/debfile.rst @@ -0,0 +1,39 @@ +:mod:`apt.debfile` --- Classes related to debian package files +============================================================== +The :mod:`apt.debfile` provides classes to work with locally available +debian packages, or source packages. + +.. module:: apt.debfile + +Binary packages +---------------- +.. autoclass:: DebPackage + :members: + :inherited-members: + :undoc-members: + + The :class:`DebPackage` class is a class for working with '.deb' files, + also known as Debian packages. + + It provides methods and attributes to get a list of the files in the + package, to install the package and much more. + + If you specify *cache* it has to point to an :class:`apt.cache.Cache()` + object. + + .. versionchanged:: 0.7.9 + Introduce all new methods (everything except for :meth:`open()` and + :attr:`filelist`) + + +Source packages +---------------- +.. autoclass:: DscSrcPackage + :members: + :inherited-members: + :undoc-members: + + Provide functionality to work with locally available source packages, + especially with their '.dsc' file. + + .. versionadded:: 0.7.9 diff --git a/doc/source/apt/gtk.widgets.rst b/doc/source/apt/gtk.widgets.rst new file mode 100644 index 00000000..9fa84ead --- /dev/null +++ b/doc/source/apt/gtk.widgets.rst @@ -0,0 +1,29 @@ +:mod:`apt.gtk.widgets` --- GTK widgets +====================================== +.. automodule:: apt.gtk.widgets + + +GObject progress classes +------------------------- + +.. autoclass:: GDpkgInstallProgress + :members: + +.. autoclass:: GFetchProgress + :members: + +.. autoclass:: GInstallProgress + :members: + +.. autoclass:: GOpProgress + :members: + +GTK+ Class +---------- +.. autoclass:: GtkAptProgress + :members: + + +Example +------- +.. literalinclude:: ../examples/apt-gtk.py diff --git a/doc/source/apt/index.rst b/doc/source/apt/index.rst new file mode 100644 index 00000000..5047a0fd --- /dev/null +++ b/doc/source/apt/index.rst @@ -0,0 +1,58 @@ +:mod:`apt` --- Highlevel apt package +===================================== +The highlevel apt package provides a lot of functionality, all +with an easy-to-use interface. + +.. warning:: + The API of this package is not considered stable. Evenmore, it is considered + to change the naming conventions in future to lowercase_with_underscores. + + In case this happens, the API will still be kept compatible, with the old + functions provided as deprecated ones. + +.. automodule:: apt + :members: + + + + +.. toctree:: + :maxdepth: 2 + :glob: + + * + + +Classes exported in apt +------------------------ +These classes are defined in the submodules, but are also exported directly +in the package. + +.. class:: Cache + + Please see :class:`apt.cache.Cache` for documentation. + +.. class:: Cdrom + + Please see :class:`apt.cdrom.Cdrom` for documentation. + +.. class:: CdromProgress + + Please see :class:`apt.progress.CdromProgress` for documentation. + +.. class:: FetchProgress + + Please see :class:`apt.progress.FetchProgress` for documentation. + +.. class:: InstallProgress + + Please see :class:`apt.progress.InstallProgress` for documentation. + +.. class:: OpProgress + + Please see :class:`apt.progress.OpProgress` for documentation. + +.. class:: Package + + Please see :class:`apt.package.Package` for documentation. + diff --git a/doc/source/apt/package.rst b/doc/source/apt/package.rst new file mode 100644 index 00000000..1bd032ab --- /dev/null +++ b/doc/source/apt/package.rst @@ -0,0 +1,101 @@ +:mod:`apt.package` --- Classes for package handling +==================================================== + + +.. automodule:: apt.package + + +The Package class +----------------- +.. autoclass:: Package + :members: + + +Dependency Information +---------------------- +.. class:: BaseDependency + + The :class:`BaseDependency` class defines various attributes for accessing + the parts of a dependency. The attributes are as follows: + + .. attribute:: name + + The name of the dependency + + .. attribute:: relation + + The relation (>>,>=,==,<<,<=,) + + .. attribute:: version + + The version or None. + + .. attribute:: preDepend + + Boolean value whether this is a pre-dependency. + +.. class:: Dependency + + The dependency class represents a Or-Group of dependencies. It provides + an attribute to access the :class:`BaseDependency` object for the available + choices. + + .. attribute:: or_dependencies + + A list of :class:`BaseDependency` objects which could satisfy the + requirement of the Or-Group. + + +Origin Information +------------------- +.. class:: Origin + + The :class:`Origin` class provides access to the origin of the package. + It allows you to check the component, archive, the hostname, and even if + this package can be trusted. + + .. attribute:: archive + + The archive (eg. unstable) + + .. attribute:: component + + The component (eg. main) + + .. attribute:: label + + The Label, as set in the Release file + + .. attribute:: origin + + The Origin, as set in the Release file + + .. attribute:: site + + The hostname of the site. + + .. attribute:: trusted + + Boolean value whether this is trustworthy. An origin can be trusted, if + it provides a GPG-signed Release file and the GPG-key used is in the + keyring used by apt (see apt-key). + +Examples +--------- +.. code-block:: python + + import apt + + cache = apt.Cache() + pkg = cache['python-apt'] # Access the Package object for python-apt + print 'python-apt is trusted:', pkg.candidateOrigin.trusted + + # Mark python-apt for install + pkg.markInstall() + + print 'python-apt is marked for install:', pkg.markedInstall + + print 'python-apt is', pkg.summary #Python interface to libapt-pkg + + # Now, really install it + cache.commit() diff --git a/doc/source/apt/progress.rst b/doc/source/apt/progress.rst new file mode 100644 index 00000000..8989aa27 --- /dev/null +++ b/doc/source/apt/progress.rst @@ -0,0 +1,37 @@ +:mod:`apt.progress` --- Classes for progress reporting +====================================================== +.. automodule:: apt.progress + +.. warning:: + + This class is currently under re-organisation. Therefore, the API may + change soon. The old names will still be kept until it is safe to remove + them. + + + +Classes without output +---------------------- +.. autoclass:: FetchProgress + :members: +.. autoclass:: OpProgress + :members: +.. autoclass:: CdromProgress + :members: +.. autoclass:: DumbInstallProgress + :members: + +Implementing classes for text output +------------------------------------ +.. autoclass:: TextFetchProgress + :members: +.. autoclass:: OpTextProgress + :members: +.. autoclass:: InstallProgress + :members: +.. autoclass:: DpkgInstallProgress + :members: + + + + diff --git a/doc/source/apt_inst.rst b/doc/source/apt_inst.rst new file mode 100644 index 00000000..97705f61 --- /dev/null +++ b/doc/source/apt_inst.rst @@ -0,0 +1,96 @@ +:mod:`apt_inst` - Working with local Debian packages +==================================================== +.. module:: apt_inst + +The :mod:`apt_inst` extension provides access to functions for working with +locally available Debian packages (.deb files) and tar files. + + +Checking packages +------------------ +.. function:: arCheckMember(file, membername) + + Check if the member specified by the parameter *membername* exists in + the AR file referenced by the :class:`file` object *file*. + + +Listing contents +----------------- +.. function:: debExtract(file, func, chunk) + + Call the function referenced by *func* for each member of the tar file + *chunk* which is contained in the AR file referenced by the file object + *file*. + + An example would be:: + + debExtract(open("package.deb"), my_callback, "data.tar.gz") + + See :ref:`emulating-dpkg-contents` for a more detailed example. + +.. function:: tarExtract(file,func,comp) + + Call the function *func* for each member of the tar file *file*. + + *Comp* is a string determining the compressor used. Possible options are + "lzma", "bzip2" and "gzip". + + +Callback +^^^^^^^^^ +Both of these functions expect a callback with the signature +``(what, name, link, mode, uid, gid, size, mtime, major, minor)``. + +The parameter *what* describes the type of the member. It can be 'FILE', +'DIR', or 'HARDLINK'. + +The parameter *name* refers to the name of the member. In case of links, +*link* refers to the target of the link. + + +Extracting contents +------------------- + +.. function:: debExtractArchive(file, rootdir) + + Extract the archive referenced by the :class:`file` object *file* + into the directory specified by *rootdir*. + + See :ref:`emulating-dpkg-extract` for an example. + + .. warning:: + + If the directory given by *rootdir* does not exist, the package is + extracted into the current directory. + +.. function:: debExtractControl(file[, member='control']) + + Return the indicated file from the control tar. The default is 'control'. + + If you want to print the control file of a given package, you could do + something like:: + + print debExtractControl(open("package.deb")) + + :return: The contents of the file, as :class:`str`. + + +.. _emulating-dpkg-extract: + +Example: Emulating :program:`dpkg` :option:`--extract` +------------------------------------------------------- +Here is a code snippet which emulates dpkg -x. It can be run as +:program:`tool` :option:`pkg.deb` :option:`outdir`. + +.. literalinclude:: examples/dpkg-extract.py + + +.. _emulating-dpkg-contents: + +Example: Emulating :program:`dpkg` :option:`--contents` +------------------------------------------------------- +.. literalinclude:: examples/dpkg-contents.py + +Example: Emulating :program:`dpkg` :option:`--info` +---------------------------------------------------- +.. literalinclude:: examples/dpkg-info.py diff --git a/doc/source/apt_pkg/cache.rst b/doc/source/apt_pkg/cache.rst new file mode 100644 index 00000000..af67d82f --- /dev/null +++ b/doc/source/apt_pkg/cache.rst @@ -0,0 +1,1227 @@ +Classes in apt_pkg +================== + +.. todo:: + + This should be split and cleaned up a bit. + +:class:`Acquire` +---------------- +.. class:: Acquire + + .. method:: Run() + + Fetch all the items which have been added by + :func:`apt_pkg.GetPkgAcqFile`. + + .. method:: Shutdown + + Shut the fetcher down. + +:class:`PkgAcqFile` +------------------- +.. class:: PkgAcqFile + + This class provides no methods or attributes + +:class:`AcquireItem` +--------------------- + +.. class:: AcquireItem + + .. attribute:: ID + + The ID of the item. + + .. attribute:: Complete + + Is the item completely acquired? + + .. attribute:: Local + + Is the item a local file? + + .. attribute:: IsTrusted + + Can the file be trusted? + + .. attribute:: FileSize + + The size of the file, in bytes. + + .. attribute:: ErrorText + + The error message. For example, when a file does not exist on a http + server, this will contain a 404 error message. + + .. attribute:: DestFile + + The location the file is saved as. + + .. attribute:: DescURI + + The source location. + + **Status**: + + .. attribute:: Status + + Integer, representing the status of the item. + + .. attribute:: StatIdle + + Constant for comparing :attr:`AcquireItem.Status`. + + .. attribute:: StatFetching + + Constant for comparing :attr:`AcquireItem.Status` + + .. attribute:: StatDone + + Constant for comparing :attr:`AcquireItem.Status` + + .. attribute:: StatError + + Constant for comparing :attr:`AcquireItem.Status` + + .. attribute:: StatAuthError + + Constant for comparing :attr:`AcquireItem.Status` + +:class:`ActionGroup` +-------------------- + +.. class:: ActionGroup + + Normally, apt checkes the package cache after every modification for + packages which are automatically installed but on which no package depends + anymore (it collects the package garbage). + + Using ActionGroups you can turn this off and therefore make your code + much faster. + + Initialize it using :func:`apt_pkg.GetPkgActionGroup`, eg:: + + apt_pkg.GetPkgActionGroup(depcache) + + .. method:: release + + Release the ActionGroup. This will reactive the collection of package + garbage. + + +:class:`Configuration` +---------------------- + +.. class:: Configuration + + The Configuration objects store the configuration of apt. + + .. describe:: conf[key] + + Return the value of the option given key *key*. If it does not + exist, raise :exc:`KeyError`. + + .. describe:: conf[key] = value + + Set the option at *key* to *value*. + + .. method:: Find(key[, default='']) + + Return the value for the given key *key*. This is the same as + :meth:`Configuration.get`. + + If *key* does not exist, return *default*. + + .. method:: FindFile(key[, default='']) + + Return the filename hold by the configuration at *key*. This formats the + filename correctly and supports the Dir:: stuff in the configuration. + + If *key* does not exist, return *default*. + + .. method:: FindDir(key[, default='/']) + + Return the absolute path to the directory specified in *key*. A + trailing slash is appended. + + If *key* does not exist, return *default*. + + .. method:: FindI(key[, default=0]) + + Return the integer value stored at *key*. + + If *key* does not exist, return *default*. + + .. method:: FindB(key[, default=0]) + + Return the boolean value stored at *key*. This returns an integer, but + it should be treated like True/False. + + If *key* does not exist, return *default*. + + .. method:: Set(key, value) + + Set the value of *key* to *value*. + + .. method:: Exists(key) + + Check whether the key *key* exists in the configuration. + + .. method:: SubTree(key) + + Return a sub tree starting at *key*. The resulting object can be used + like this one. + + .. method:: List([key]) + + List all items at *key*. Normally, return the keys at the top level, + eg. APT, Dir, etc. + + Use *key* to specify a key of which the childs will be returned. + + .. method:: ValueList([key]) + + Same as :meth:`Configuration.List`, but this time for the values. + + .. method:: MyTag() + + Return the tag name of the current tree. Normally this is an empty + string, but for subtrees it is the key of the subtree. + + .. method:: Clear(key) + + Clear the configuration. Remove all values and keys at *key*. + + .. method:: keys([key]) + + Return all the keys, recursive. If *key* is specified, ... (FIXME) + + .. method:: has_key(key) + + Return whether the configuration contains the key *key*. + + .. method:: get(key[, default='']) + + This behaves just like :meth:`dict.get` and :meth:`Configuration.Find`, + it returns the value of key or if it does not exist, *default*. + + +:class:`pkgCache` +----------------- +.. class:: pkgCache + + The :class:`pkgCache` class prov + + .. describe:: cache[pkgname] + + Return the :class:`Package()` object for the package name given by + *pkgname*. + + .. method:: Close() + + Close the package cache. + + .. method:: Open([progress]) + + Open the package cache again. The parameter *progress* may be set to + an :class:`apt.progress.OpProgress()` object or `None`. + + .. method:: Update(progress, list) + + Update the package cache. + + The parameter *progress* points to an :class:`apt.progress.FetchProgress()` + object. + + The parameter *list* refers to an object as returned by + :func:`apt_pkg.GetPkgSourceList`. + + .. attribute:: DependsCount + + The total number of dependencies. + + .. attribute:: PackageCount + + The total number of packages available in the cache. + + .. attribute:: ProvidesCount + + The number of provided packages. + + .. attribute:: VerFileCount + + .. todo:: Seems to be some mixture of versions and pkgFile. + + .. attribute:: VersionCount + + The total number of package versions available in the cache. + + .. attribute:: PackageFileCount + + The total number of Packages files available (the Packages files + listing the packages). This is the same as the length of the list in + the attribute :attr:`FileList`. + + .. attribute:: FileList + + A list of :class:`PackageFile` objects. + + +:class:`PackageFile` +-------------------- +.. class:: PackageFile + + A :class:`PackageFile` represents a Packages file, eg. + /var/lib/dpkg/status. + + .. attribute:: Architecture + + The architecture of the package file. + + .. attribute:: Archive + + The archive (eg. unstable) + + .. attribute:: Component + + The component (eg. main) + + .. attribute:: FileName + + The name of the file. + + .. attribute:: ID + + The ID of the package. This is an integer which can be used to store + further information about the file [eg. as dictionary key]. + + .. attribute:: IndexType + + The sort of the index file. In normal cases, this is + 'Debian Package Index'. + + .. attribute:: Label + + The Label, as set in the Release file + + .. attribute:: NotAutomatic + + Whether packages from this list will be updated automatically. The + default for eg. example is 0 (aka false). + + .. attribute:: NotSource + + Whether the file has no source from which it can be updated. In such a + case, the value is 1; else 0. /var/lib/dpkg/status is 0 for example. + + Example:: + + for pkgfile in cache.FileList: + if pkgfile.NotSource: + print 'The file %s has no source.' % pkgfile.FileName + + .. attribute:: Origin + + The Origin, as set in the Release file + + .. attribute:: Site + + The hostname of the site. + + .. attribute:: Size + + The size of the file. + + .. attribute:: Version + + The version, as set in the release file (eg. "4.0" for "Etch") + + +Example +^^^^^^^ +.. literalinclude:: ../examples/cache-pkgfile.py + + +:class:`Package` +---------------- + +.. class:: Package + + The pkgCache::Package objects are an interface to package specific + features. + + + Attributes: + + .. attribute:: CurrentVer + + The version currently installed, or None. This returns a + :class:`Version` object. + + .. attribute:: ID + + The ID of the package. This can be used to store information about + the package. The ID is an int value. + + .. attribute:: Name + + This is the name of the package. + + .. attribute:: ProvidesList + + A list of packages providing this package. More detailed, this is a + list of tuples (str:pkgname, ????, :class:`Version`). + + If you want to check for check for virtual packages, the expression + ``pkg.ProvidesList and not pkg.VersionList`` helps you. It detects if + the package is provided by something else and is not available as a + real package. + + .. attribute:: RevDependsList + + An iterator of :class:`Dependency` objects for dependencies on this + package. + + .. attribute:: Section + + The section of the package, as specified in the record. The list of + possible sections is defined in the Policy. + + .. attribute:: VersionList + + A list of :class:`Version` objects for all versions available in the + cache. + + **States**: + + .. attribute:: SelectedState + + The state we want it to be, ie. if you mark a package for installation, + this is :attr:`apt_pkg.SelStateInstall`. + + See :ref:`SelStates` for a list of available states. + + .. attribute:: InstState + + The state the currently installed version is in. This is normally + :attr:`apt_pkg.InstStateOK`, unless the installation failed. + + See :ref:`InstStates` for a list of available states. + + .. attribute:: CurState + + The current state of the package (not installed, unpacked, installed, + etc). See :ref:`CurStates` for a list of available states. + + **Flags**: + + .. attribute:: Auto + + Whether the package was installed automatically as a dependency of + another package. (or marked otherwise as automatically installed) + + .. attribute:: Essential + + Whether the package is essential. + + .. attribute:: Important + + Whether the package is important. + +Example: +^^^^^^^^^ +.. literalinclude:: ../examples/cache-packages.py + + + +:class:`Version` +---------------- +.. class:: Version + + The version object contains all information related to a specific package + version. + + .. attribute:: VerStr + + The version, as a string. + + .. attribute:: Section + + The usual sections (eg. admin, net, etc.). Prefixed with the component + name for packages not in main (eg. non-free/admin). + + .. attribute:: Arch + + The architecture of the package, eg. amd64 or all. + + .. attribute:: FileList + + A list of (:class:`PackageFile`, int: index) tuples for all Package + files containing this version of the package. + + .. attribute:: DependsListStr + + A dictionary of dependencies. The key specifies the type of the + dependency ('Depends', 'Recommends', etc.). + + + The value is a list, containing items which refer to the or-groups of + dependencies. Each of these or-groups is itself a list, containing + tuples like ('pkgname', 'version', 'relation') for each or-choice. + + An example return value for a package with a 'Depends: python (>= 2.4)' + would be:: + + {'Depends': [ + [ + ('python', '2.4', '>=') + ] + ] + } + + The same for a dependency on A (>= 1) | B (>= 2):: + + {'Depends': [ + [ + ('A', '1', '>='), + ('B', '2', '>='), + ] + ] + } + + .. attribute:: DependsList + + This is basically the same as :attr:`Version.DependsListStr`, + but instead of the ('pkgname', 'version', 'relation') tuples, + it returns :class:`Dependency` objects, which can assist you with + useful functions. + + .. attribute:: ParentPkg + + The :class:`Package` object this version belongs to. + + .. attribute:: ProvidesList + + This returns a list of all packages provided by this version. Like + :attr:`Package.ProvidesList`, it returns a list of tuples + of the form ('virtualpkgname', ???, :class:`Version`), where as the + last item is the same as the object itself. + + .. attribute:: Size + + The size of the .deb file, in bytes. + + .. attribute:: InstalledSize + + The size of the package (in kilobytes), when unpacked on the disk. + + .. attribute:: Hash + + An integer hash value. + + .. attribute:: ID + + An integer id. + + .. attribute:: Priority + + The integer representation of the priority. This can be used to speed + up comparisons a lot, compared to :attr:`Version.PriorityStr`. + + The values are defined in the :mod:`apt_pkg` extension, see + :ref:`Priorities` for more information. + + .. attribute:: PriorityStr + + Return the priority of the package version, as a string, eg. + "optional". + + .. attribute:: Downloadable + + Whether this package can be downloaded from a remote site. + + .. attribute:: TranslatedDescription + + Return a :class:`Description` object. + + +:class:`Dependency` +------------------- +.. class:: Dependency + + Represent a dependency from one package to another one. + + .. method:: AllTargets + + A list of :class:`Version` objects which satisfy the dependency, + and do not conflict with already installed ones. + + From my experience, if you use this method to select the target + version, it is the best to select the last item unless any of the + other candidates is already installed. This leads to results being + very close to the normal package installation. + + .. method:: SmartTargetPkg + + Return a :class:`Version` object of a package which satisfies the + dependency and does not conflict with installed packages + (the 'natural target'). + + .. attribute:: TargetVer + + The target version of the dependency, as string. Empty string if the + dependency is not versioned. + + .. attribute:: TargetPkg + + The :class:`Package` object of the target package. + + .. attribute:: ParentVer + + The :class:`Version` object of the parent version, ie. the package + which declares the dependency. + + .. attribute:: ParentPkg + + The :class:`Package` object of the package which declares the + dependency. This is the same as using ParentVer.ParentPkg. + + .. attribute:: CompType + + The type of comparison (>=, ==, >>, <=), as string. + + .. attribute:: DepType + + The type of the dependency, as string, eg. "Depends". + + .. attribute:: ID + + The ID of the package, as integer. + +Example: Find all missing dependencies +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +With the help of Dependency.AllTargets(), you can easily find all packages with +broken dependencies: + +.. literalinclude:: ../examples/missing-deps.py + + +:class:`Description` +-------------------- +.. class:: Description + + Represent the description of the package. + + .. attribute:: LanguageCode + + The language code of the description + + .. attribute:: md5 + + The md5 hashsum of the description + + .. attribute:: FileList + + A list of tuples (:class:`PackageFile`, int: index). + + + +:class:`pkgDepCache` +-------------------- +.. class:: pkgDepCache + + The pkgDepCache object contains various methods to manipulate the cache, + to install packages, to remove them, and much more. + + .. method:: Commit(fprogress, iprogress) + + Apply all the changes made. + + The parameter *fprogress* has to be set to an instance of + apt.progress.FetchProgress or one of its subclasses. + + The parameter *iprogress* has to be set to an instance of + apt.progress.InstallProgress or one of its subclasses. + + .. method:: FixBroken() + + Try to fix all broken packages in the cache. + + .. method:: GetCandidateVer(pkg) + + Return the candidate version of the package, ie. the version that + would be installed normally. + + The parameter *pkg* refers to an :class:`Package` object, + available using the :class:`pkgCache`. + + This method returns a :class:`Version` object. + + .. method:: SetCandidateVer(pkg, version) + + The opposite of :meth:`pkgDepCache.GetCandidateVer`. Set the candidate + version of the :class:`Package` *pkg* to the :class:`Version` + *version*. + + + .. method:: Upgrade([distUpgrade=False]) + + Perform an upgrade. More detailed, this marks all the upgradable + packages for upgrade. You still need to call + :meth:`pkgDepCache.Commit` for the changes to apply. + + To perform a dist-upgrade, the optional parameter *distUpgrade* has + to be set to True. + + .. method:: FixBroken() + + Fix broken packages. + + .. method:: ReadPinFile() + + Read the policy, eg. /etc/apt/preferences. + + .. method:: MinimizeUpgrade() + + Go over the entire set of packages and try to keep each package marked + for upgrade. If a conflict is generated then the package is restored. + + .. todo:: + Explain better.. + + .. method:: MarkKeep(pkg) + + Mark the :class:`Package` *pkg* for keep. + + .. method:: MarkDelete(pkg[, purge]) + + Mark the :class:`Package` *pkg* for delete. If *purge* is True, + the configuration files will be removed as well. + + .. method:: MarkInstall(pkg[, autoInst=True[, fromUser=True]]) + + Mark the :class:`Package` *pkg* for install. + + If *autoInst* is ``True``, the dependencies of the package will be + installed as well. This is the default. + + If *fromUser* is ``True``, the package will be marked as manually + installed. This is the default. + + .. method:: SetReinstall(pkg) + + Set if the :class:`Package` *pkg* should be reinstalled. + + .. method:: IsUpgradable(pkg) + + Return ``1`` if the package is upgradable. + + The package can be upgraded by calling :meth:`pkgDepCache.MarkInstall`. + + .. method:: IsNowBroken(pkg) + + Return `1` if the package is broken now (including changes made, but + not committed). + + .. method:: IsInstBroken(pkg) + + Return ``1`` if the package is broken on the current install. This + takes changes which have not been committed not into effect. + + .. method:: IsGarbage(pkg) + + Return ``1`` if the package is garbage, ie. if it is automatically + installed and no longer referenced by other packages. + + .. method:: IsAutoInstalled(pkg) + + Return ``1`` if the package is automatically installed (eg. as the + dependency of another package). + + .. method:: MarkedInstall(pkg) + + Return ``1`` if the package is marked for install. + + .. method:: MarkedUpgrade(pkg) + + Return ``1`` if the package is marked for upgrade. + + .. method:: MarkedDelete(pkg) + + Return ``1`` if the package is marked for delete. + + .. method:: MarkedKeep(pkg) + + Return ``1`` if the package is marked for keep. + + .. method:: MarkedReinstall(pkg) + + Return ``1`` if the package should be installed. + + .. method:: MarkedDowngrade(pkg) + + Return ``1`` if the package should be downgraded. + + .. attribute:: KeepCount + + Integer, number of packages marked as keep + + .. attribute:: InstCount + + Integer, number of packages marked for installation. + + .. attribute:: DelCount + + Number of packages which should be removed. + + .. attribute:: BrokenCount + + Number of packages which are broken. + + .. attribute:: UsrSize + + The size required for the changes on the filesystem. If you install + packages, this is positive, if you remove them its negative. + + .. attribute:: DebSize + + The size of the packages which are needed for the changes to be + applied. + + +:class:`MetaIndex` +------------------ + +.. todo:: + + Complete them + +.. class:: MetaIndex + + .. attribute:: URI + .. attribute:: Dist + .. attribute:: IsTrusted + .. attribute:: IndexFiles + + +:class:`PackageIndexFile` +------------------------- + +.. class:: PackageIndexFile + + .. method:: ArchiveURI(path) + + Return the full url to path in the archive. + + .. attribute:: Label + + Return the Label. + + .. attribute:: Exists + + Return whether the file exists. + + .. attribute:: HasPackages + + Return whether the file has packages. + + .. attribute:: Size + + Size of the file + + .. attribute:: IsTrusted + + Whether we can trust the file. + + +:class:`PkgManager` +------------------- + +.. class:: PkgManager + + Class, as returned by :func:`apt_pkg.GetPackageManager`. + + .. method:: GetArchives(fetcher, list, records) + + Add all the selected packages to the :class:`Acquire()` object + *fetcher*. + + The parameter *list* refers to a :class:`PkgSourceList()` object, as + returned by :func:`apt_pkg.GetPkgSourceList`. + + The parameter *records* refers to a :class:`pkgRecords()` object, as + returned by :func:`apt_pkg.GetPkgRecords`. + + .. method:: DoInstall() + + Install the packages. + + .. method:: FixMissing + + Fix the installation if a package could not be downloaded. + + .. attribute:: ResultCompleted + + A constant for checking whether the the result is 'completed'. + + Compare it against the return value of :meth:`PkgManager.GetArchives` + or :meth:`PkgManager.DoInstall`. + + .. attribute:: ResultFailed + + A constant for checking whether the the result is 'failed'. + + Compare it against the return value of :meth:`PkgManager.GetArchives` + or :meth:`PkgManager.DoInstall`. + + .. attribute:: ResultIncomplete + + A constant for checking whether the the result is 'incomplete'. + + Compare it against the return value of :meth:`PkgManager.GetArchives` + or :meth:`PkgManager.DoInstall`. + +:class:`pkgRecords` +-------------------- + +.. class:: PkgRecords + + Provide access to the packages records. This provides very useful + attributes for fast (convient) access to some fields of the record. + + See :func:`apt_pkg.GetPkgRecords` for initialization. + + + .. method:: Lookup(verfile_iter) + + Change the actual package to the package given by the verfile_iter. + + The parameter *verfile_iter* refers to a tuple consisting + of (:class:`PackageFile()`, int: index), as returned by various + attributes, including :attr:`Version.FileList`. + + Example (shortened):: + + cand = depcache.GetCandidateVer(cache['python-apt']) + records.Lookup(cand.FileList[0]) + # Now you can access the record + print records.SourcePkg # == python-apt + + .. attribute:: FileName + + Return the field 'Filename' of the record. This is the path to the + package, relative to the base path of the archive. + + .. attribute:: MD5Hash + + Return the MD5 hashsum of the package This refers to the field + 'MD5Sum' in the raw record. + + .. attribute:: SHA1Hash + + Return the SHA1 hashsum of the package. This refers to the field 'SHA1' + in the raw record. + + .. attribute:: SHA256Hash + + Return the SHA256 hashsum of the package. This refers to the field + 'SHA256' in the raw record. + + .. versionadded:: 0.7.9 + + .. attribute:: SourcePkg + + Return the source package. + + .. attribute:: SourceVer + + Return the source version. + + .. attribute:: Maintainer + + Return the maintainer of the package. + + .. attribute:: ShortDesc + + Return the short description. This is the summary on the first line of + the 'Description' field. + + .. attribute:: LongDesc + + Return the long description. These are lines 2-END from the + 'Description' field. + + .. attribute:: Name + + Return the name of the package. This is the 'Package' field. + + .. attribute:: Homepage + + Return the Homepage. This is the 'Homepage' field. + + .. attribute:: Record + + Return the whole record as a string. If you want to access fields of + the record not available as an attribute, you can use + :func:`apt_pkg.ParseSection` to parse the record and access the field + name. + + Example:: + + section = apt_pkg.ParseSection(records.Record) + print section['SHA256'] + +:class:`PkgSrcRecords` +---------------------- + +.. class:: PkgSrcRecords + + This represents the entries in the Sources files, ie. the dsc files of + the source packages. + + .. note:: + + If the Lookup failed, because no package could be found, no error is + raised. Instead, the attributes listed below are simply not existing + anymore (same applies when no Lookup has been made, or when it has + been restarted). + + .. method:: Lookup(pkgname) + + Lookup the record for the package named *pkgname*. To access all + available records, you need to call it multiple times. + + Imagine a package P with two versions X, Y. The first ``Lookup(P)`` + would set the record to version X and the second ``Lookup(P)`` to + version Y. + + .. method:: Restart() + + Restart the lookup. + + Imagine a package P with two versions X, Y. The first ``Lookup(P)`` + would set the record to version X and the second ``Lookup(P)`` to + version Y. + + If you now call ``Restart()``, the internal position will be cleared. + Now you can call ``Lookup(P)`` again to move to X. + + .. attribute:: Package + + The name of the source package. + + .. attribute:: Version + + A string describing the version of the source package. + + .. attribute:: Maintainer + + A string describing the name of the maintainer. + + .. attribute:: Section + + A string describing the section. + + .. attribute:: Record + + The whole record, as a string. You can use :func:`apt_pkg.ParseSection` + if you need to parse it. + + You need to parse the record if you want to access fields not available + via the attributes, eg. 'Standards-Version' + + .. attribute:: Binaries + + Return a list of strings describing the package names of the binaries + created by the source package. This matches the 'Binary' field in the + raw record. + + .. attribute:: Index + + The index in the Sources files. + + .. attribute:: Files + + The list of files. This returns a list of tuples with the contents + ``(str: md5, int: size, str: path, str:type)``. + + .. attribute:: BuildDepends + + Return the list of Build dependencies, as + ``(str: package, str: version, int: op, int: type)``. + + .. table:: Values of *op* + + ===== ============================================= + Value Meaning + ===== ============================================= + 0x0 No Operation (no versioned build dependency) + 0x10 | (or) - this will be added to the other values + 0x1 <= (less than or equal) + 0x2 >= (greater than or equal) + 0x3 << (less than) + 0x4 >> (greater than) + 0x5 == (equal) + 0x6 != (not equal) + ===== ============================================= + + .. table:: Values of *type* + + ===== =================== + Value Meaning + ===== =================== + 0 Build-Depends + 1 Build-Depends-Indep + 2 Build-Conflicts + 3 Build-Conflicts-Indep + ===== =================== + + **Example**: In the following content, we will imagine a + build-dependency:: + + Build-Depends: A (>= 1) | B (>= 1), C + + This results in:: + + [('A', '1', 18, 0), # 18 = 16 + 2 = 0x10 + 0x2 + ('B', '1', 2, 0), + ('C', '', 0, 0)] + + This is **not** the same as returned by + :func:`apt_pkg.ParseSrcDepends`. + + +:class:`PkgSourceList` +----------------------- + +.. class:: PkgSourceList + + This is for :file:`/etc/apt/sources.list`. + + .. method:: FindIndex(pkgfile) + + Return a :class:`PackageIndexFile` object for the :class:`PackageFile` + *pkgfile*. + + .. method:: ReadMainList + + Read the main list. + + .. method:: GetIndexes(acq[, all]) + + Add the index files to the :class:`Acquire()` object *acq*. If *all* is + given and ``True``, all files are fetched. + + +:class:`ProblemResolver` +------------------------ +.. class:: ProblemResolver + + The problem resolver helps when there are problems in the package + selection. An example is a package which conflicts with another, already + installed package. + + .. method:: Protect(pkg) + + Protect the :class:`Package()` object given by the parameter *pkg*. + + .. todo:: + + Really document it. + + .. method:: InstallProtect() + + Protect all installed packages from being removed. + + .. method:: Remove(pkg) + + Remove the :class:`Package()` object given by the parameter *pkg*. + + .. todo:: + + Really document it. + + .. method:: Clear(pkg) + + Reset the :class:`Package()` *pkg* to the default state. + + .. todo:: + + Really document it. + + .. method:: Resolve() + + Try to resolve problems by installing and removing packages. + + .. method:: ResolveByKeep() + + Try to resolve problems only by using keep. + + +:class:`TagFile` +---------------- + +.. class:: TagFile + + An object which represents a typical debian control file. Can be used for + Packages, Sources, control, Release, etc. + + Use :func:`apt_pkg.ParseTagFile` to parse a file. + + .. method:: Step + + Step forward to the next section. This simply returns ``1`` if OK, and + ``0`` if there is no section + + .. method:: Offset + + Return the current offset (in bytes) from the beginning of the file. + + .. method:: Jump(offset) + + Jump back/forward to *offset*. Use ``Jump(0)`` to jump to the + beginning of the file again. + + .. attribute:: Section + + This is the current :class:`TagSection()` instance. + +:class:`TagSection` +------------------- + +.. class:: TagSection + + Represent a single section of a debian control file. + + .. describe:: section[key] + + Return the value of the field at *key*. If *key* is not available, + raise :exc:`KeyError`. + + .. method:: Bytes + + The number of bytes in the section. + + .. method:: Find(key, default='') + + Return the value of the field at the key *key* if available, + else return *default*. + + .. method:: FindFlag(key) + + Find a yes/no value for the key *key*. An example for such a + field is 'Essential'. + + .. method:: get(key, default='') + + Return the value of the field at the key *key* if available, else + return *default*. + + .. method:: has_key(key) + + Check whether the field with named by *key* exists. + + .. method:: keys() + + Return a list of keys in the section. diff --git a/doc/source/apt_pkg/index.rst b/doc/source/apt_pkg/index.rst new file mode 100644 index 00000000..1c5866a9 --- /dev/null +++ b/doc/source/apt_pkg/index.rst @@ -0,0 +1,261 @@ +:mod:`apt_pkg` --- The low-level bindings for apt-pkg +===================================================== +.. module:: apt_pkg + +The apt_pkg extensions provides a more low-level way to work with apt. It can +do everything apt can, and is written in C++. It has been in python-apt since +the beginning. + + +.. toctree:: + :maxdepth: 2 + :glob: + + * + + +Module Initialization +--------------------- + + +.. function:: initConfig + + Initialize the configuration of apt. This is needed for most operations. + +.. function:: initSystem + + Initialize the system. + +.. function:: init + + Deprecated function. Use initConfig() and initSystem() instead. + +Object initialization +---------------------- +.. function:: GetCache([progress]) + + Return a :class:`pkgCache` object. The optional parameter ``progress`` + specifies an instance of :class:`apt.progress.OpProgress()` which will + display the open progress. + +.. function:: GetCdrom() + + Return a Cdrom object with the following methods: + + .. method:: Cdrom.Ident(progress) + + Identify the cdrom. The parameter ``progress`` refers to an + :class:`apt.progress.CdromProgress()` object. + + .. method:: Cdrom.Add(progress) + + Add the cdrom to the sources.list file. The parameter ``progress`` + refers to an :class:`apt.progress.CdromProgress()` object. + + + +.. function:: GetDepCache(cache) + + Return a :class:`pkgDepCache` object. The parameter ``cache`` specifies an + instance of :class:`pkgCache` (see :func:`GetCache()`). + + +.. function:: GetPkgSourceList() + + Return a :class:`pkgSourceList` object. + + +The Acquire interface +---------------------- +.. function:: GetAcquire([progress]) + + Return an :class:`Acquire` object. This is a class which allows you + to fetch files, or archive contents. The parameter ``progress`` refers to + an :class:`apt.progress.FetchProgress()` object. + + Acquire items have multiple methods: + + .. method:: Acquire.Run() + + Fetch all the items which have been added by :func:`GetPkgAcqFile`. + + .. method:: Acquire.Shutdown() + + Shut the fetcher down. + + .. attribute:: Acquire.TotalNeeded + + The total amount of bytes needed (including those of files which are + already present) + + .. attribute:: Acquire.FetchNeeded + + The total amount of bytes which need to be fetched. + + .. attribute:: Acquire.PartialPresent + + Whether some files have been acquired already. (???) + + +.. function:: GetPkgAcqFile(aquire, uri[, md5, size, descr, shortDescr, destDir, destFile]) + + The parameter ``acquire`` refers to an :class:`Acquire()` object as returned + by :func:`GetAcquire`. The file will be added to the Acquire queue + automatically. + + The parameter ``uri`` refers to the location of the file, any protocol + of apt is supported. + + The parameter ``md5`` refers to the md5sum of the file. This can be used + for checking the file. + + The parameter ``size`` can be used to specify the size of the package, + which can then be used to calculate the progress and validate the download. + + The parameter ``descr`` is a descripition of the download. It may be + used to describe the item in the progress class. ``shortDescr`` is the + short form of it. + + You can use ``destDir`` to manipulate the directory where the file will + be saved in. Together with ``destFile`` you can specify the complete target + path. + + + +Hash functions +-------------- +The apt_pkg module also provides several hash functions. If you develop +applications with python-apt it is often easier to use these functions instead +of the ones provides in Python's :mod:`hashlib` module. + +.. function:: md5sum(object) + + Return the md5sum of the object. ``object`` may either be a string, in + which case the md5sum of the string is returned, or a :class:`file()` + object, in which case the md5sum of its contents is returned. + +.. function:: sha1sum(object) + + Return the sha1sum of the object. ``object`` may either be a string, in + which case the sha1sum of the string is returned, or a :class:`file()` + object, in which case the sha1sum of its contents is returned. + +.. function:: sha256sum(object) + + Return the sha256sum of the object. ``object`` may either be a string, in + which case the sha256sum of the string is returned, or a :class:`file()` + object, in which case the sha256sum of its contents is returned. + +Other functions +---------------- + +.. note:: + + This documentation is created automatically and should be rewritten. + +.. autofunction:: Base64Encode +.. autofunction:: CheckDep +.. autofunction:: CheckDomainList +.. autofunction:: DeQuoteString +.. autofunction:: GetLock +.. autofunction:: GetPackageManager +.. autofunction:: GetPkgActionGroup +.. autofunction:: GetPkgProblemResolver +.. autofunction:: GetPkgRecords +.. autofunction:: GetPkgSrcRecords +.. autofunction:: newConfiguration +.. autofunction:: ParseCommandLine +.. autofunction:: ParseDepends +.. autofunction:: ParseSection +.. autofunction:: ParseSrcDepends +.. autofunction:: ParseTagFile +.. autofunction:: PkgSystemLock +.. autofunction:: PkgSystemUnLock +.. autofunction:: QuoteString +.. autofunction:: ReadConfigFile +.. autofunction:: ReadConfigFileISC +.. autofunction:: RewriteSection +.. autofunction:: SizeToStr +.. autofunction:: StringToBool +.. autofunction:: StrToTime +.. autofunction:: TimeRFC1123 +.. autofunction:: TimeToStr +.. autofunction:: UpstreamVersion +.. autofunction:: URItoFileName +.. autofunction:: VersionCompare + + +Data +----- + +.. data:: Config + + An :class:`Configuration()` object with the default configuration. Actually, + this is a bit different object, but it is compatible. + +.. data:: RewritePackageOrder + +.. data:: RewriteSourceOrder + + +.. _CurStates: + +Package States +^^^^^^^^^^^^^^^ +.. data:: CurStateConfigFiles +.. data:: CurStateHalfConfigured +.. data:: CurStateHalfInstalled +.. data:: CurStateInstalled +.. data:: CurStateNotInstalled +.. data:: CurStateUnPacked + + + + +Dependency types +^^^^^^^^^^^^^^^^ +.. data:: DepConflicts +.. data:: DepDepends +.. data:: DepObsoletes +.. data:: DepPreDepends +.. data:: DepRecommends +.. data:: DepReplaces +.. data:: DepSuggests + +.. _InstStates: + +Installed states +^^^^^^^^^^^^^^^^^ +.. data:: InstStateHold +.. data:: InstStateHoldReInstReq +.. data:: InstStateOk +.. data:: InstStateReInstReq + +.. _Priorities: + +Priorities +^^^^^^^^^^ +.. data:: PriExtra +.. data:: PriImportant +.. data:: PriOptional +.. data:: PriRequired +.. data:: PriStandard + + +.. _SelStates: + +Select states +^^^^^^^^^^^^^^ +.. data:: SelStateDeInstall +.. data:: SelStateHold +.. data:: SelStateInstall +.. data:: SelStatePurge +.. data:: SelStateUnknown + + +Build information +^^^^^^^^^^^^^^^^^ +.. data:: Date +.. data:: LibVersion +.. data:: Time +.. data:: Version diff --git a/doc/source/aptsources/distinfo.rst b/doc/source/aptsources/distinfo.rst new file mode 100644 index 00000000..96f9445d --- /dev/null +++ b/doc/source/aptsources/distinfo.rst @@ -0,0 +1,10 @@ +:mod:`aptsources.distinfo` --- provide meta information for distro repositories +=============================================================================== + +.. automodule:: aptsources.distinfo + :members: + :undoc-members: + + .. note:: + + This part of the documentation is created automatically. diff --git a/doc/source/aptsources/distro.rst b/doc/source/aptsources/distro.rst new file mode 100644 index 00000000..06ca0fda --- /dev/null +++ b/doc/source/aptsources/distro.rst @@ -0,0 +1,10 @@ +:mod:`aptsources.distro` --- Distribution abstraction of the sources.list +=============================================================================== + +.. automodule:: aptsources.distro + :members: + :undoc-members: + + .. note:: + + This part of the documentation is created automatically. diff --git a/doc/source/aptsources/index.rst b/doc/source/aptsources/index.rst new file mode 100644 index 00000000..898fbf74 --- /dev/null +++ b/doc/source/aptsources/index.rst @@ -0,0 +1,10 @@ +:mod:`aptsources` --- Working with sources.list +===================================================== +.. automodule:: aptsources + +.. toctree:: + :maxdepth: 2 + :glob: + + * + diff --git a/doc/source/aptsources/sourceslist.rst b/doc/source/aptsources/sourceslist.rst new file mode 100644 index 00000000..509db3ce --- /dev/null +++ b/doc/source/aptsources/sourceslist.rst @@ -0,0 +1,10 @@ +:mod:`aptsources.sourceslist` --- Provide an abstraction of the sources.list +============================================================================ + +.. automodule:: aptsources.sourceslist + :members: + :undoc-members: + + .. note:: + + This part of the documentation is created automatically. diff --git a/doc/source/coding.rst b/doc/source/coding.rst new file mode 100644 index 00000000..1357ce14 --- /dev/null +++ b/doc/source/coding.rst @@ -0,0 +1,168 @@ +Coding for python-apt +====================== +Let's say you need a new feature, you can develop it, and you want to get it +included in python-apt. Then be sure to follow the following guidelines. + +Available branches +------------------- +First of all, let's talk a bit about the bzr branches of python-apt. In the +following parts, we will assume that you use bzr to create your changes and +submit them. + +**mvo:** http://people.ubuntu.com/~mvo/bzr/python-apt/mvo + This is Michael Vogt's branch. Most of the development of apt happens here, + as he is the lead maintainer of python-apt. + + This branch is also available from Launchpads super mirror, via + ``lp:python-apt``. Checkouts from Launchpad are generally faster and can + use the bzr protocoll. + + VCS-Browser: https://code.launchpad.net/~mvo/python-apt/python-apt--mvo + +**debian-sid:** http://bzr.debian.org/apt/python-apt/debian-sid + This is the official Debian branch of python-apt. All code which will be + uploaded to Debian is here. It is not as up-to-date as the mvo branch, + because this branch often gets updated just right before the release + happens. + + VCS-Browser: http://bzr.debian.org/loggerhead/apt/python-apt/debian-sid/changes + +**jak:** http://bzr.debian.org/users/jak/python-apt/jak + This is Julian Andres Klode's (the documentation author's) branch. This + is the place where cleanup and documentation updates happen. It is based + off debian-sid or mvo. + + VCS-Browser: http://bzr.debian.org/loggerhead/users/jak/python-apt/jak/changes + +**ubuntu:** ``lp:~ubuntu-core-dev/python-apt/ubuntu`` + This is the official Ubuntu development branch. The same notes apply as + for the debian-sid branch above. + + VCS-Browser: https://code.launchpad.net/~ubuntu-core-dev/python-apt/ubuntu + + +C++ Coding style +---------------- +When you work on the C++ code in the python/ directory, you should follow some +basic rules. + +The indentation of the code is a bit non-standard. We currently use 3 spaces +indentation for the C++ code. + +When you create new functions, you should follow some naming conventions. All +C++ functions are named according to the ``CamelCase`` convention. + +The resulting Python functions should be ``CamelCase`` as well in apt_pkg, or +``mixedCase`` in apt_inst. The same applies for variables, parameters, +attributes, etc. + +.. note:: + + This coding style guidelines are incomplete. If you have any questions + send an email to deity@lists.debian.org. + +.. note:: + + The coding style may be changed completely during the port to Python 3.0. + But this will not happen very soon. + + +Python Coding Style +------------------- +The coding style for all code written in python is :PEP:`8`. For modules added +from version 0.7.9 on, there are no exceptions. + +Modules introduced prior to 0.7.9 use mixedCase names for methods, functions +and variables. These names will be replaced by names conforming to :PEP:`8` +in a future release of python-apt. + +Therefore, try to reduce the introduction of the mixedName code to the absolute +minimum (sometimes you can also use shorter names). + +To prepare the port to Python 3.0, code should not use any functionality which +is deprecated as of Python 2.6. + +The has_key() functionality may be used only on TagSection objects; as they +provide no other way to do this. If someone is willing to adapt TagSection to +support ``key in mapping`` and ``iter(mapping)``, this would be great. + +.. note:: + + You can use the tool pep8.py from http://svn.browsershots.org/trunk/devtools/pep8/ + to validate your code. Please also run pylint, pychecker, and pyflakes and + fix all new **errors** they report (undefined names, etc.). + +Submitting your patch +--------------------- +First of all, the patch you create should be based against the debian-sid +branch of python-apt. + +Once you have made your change, check that it: + + * conforms to :PEP:`8` (checked with pep8.py). It should, at least not + introduce new errors. (and never have whitespace at end of line) + * produces no new errors in pychecker, pyflakes and pylint (unless you + can't fix them, but please tell so when requesting the merge, so it can + be fixed before hitting one of the main branches). + * does not change the behaviour of existing code in a non-compatible way. + +If your change follows all points of the checklist, you can commit it to your +repository. (You could commit it first, and check later, and then commit the +fixes, but commits should be logical and it makes no sense to have to commits +for one logical unit). + +Once you have made all your changes, you can run ``bzr send -o patch-name`` +to create a so called *merge-directive*, which contains your changes and +allows us to preserve the history of your changes. (But please replace patch-name +with something useful). + +Now report a bug against the python-apt package, attach the merge directive +you created in the previous step, and tag it with 'patch'. It might also be +a good idea to prefix the bug report with '[PATCH]'. + +If your patch introduces new functions, parameters, etc. , but does not update +the content of this documentation, please CC. jak@debian.org, and add a short +notice to the bug report. Also see `Documentation updates` + +Once your patch got merged, you can *pull* the branch into which it has been +merged into your local one. If you have made changes since you submitted your +patch, you may need to *merge* the branch instead. + +.. note:: + + If you plan to work on python-apt for a longer time, it may be a good + idea to publish your branch somewhere. Alioth (http://alioth.debian.org) + and Launchpad (https://launchpad.net) provide bzr hosting. You can also + use any webspace with ftp or sftp connection (for the upload). Then you do + not need to send *merge directives*, but you can point to your branch + instead. + + +Documentation updates +--------------------- +If you want to update the documentation, please follow the procedure as written +above. But please CC: jak@debian.org in the bug report. + +You can send your content in plain text, but reStructuredText is the preferred +format. I (Julian Andres Klode) will review your patch and will forward them to +Michael Vogt, for inclusion in his branch. On release, this will be merged into +the debian-sid branch. + + +Example patch session +---------------------- +In the following example, we edit a file, create a merge directive (an enhanced +patch), and report a wishlist bug with this patch against the python-apt +package:: + + user@pc:~$ bzr clone http://bzr.debian.org/apt/python-apt/debian-sid/ + user@pc:~$ cd debian-sid + user@pc:~/debian-sid$ editor FILES + user@pc:~/debian-sid$ pep8.py FILES # PEP 8 check, see above. + user@pc:~/debian-sid$ pylint -e FILES # Check with pylint + user@pc:~/debian-sid$ pyflakes FILES # Check with pyflakes + user@pc:~/debian-sid$ pychecker FILES # Check with pychecker + user@pc:~/debian-sid$ bzr commit + user@pc:~/debian-sid$ bzr send -o my-patch + user@pc:~/debian-sid$ reportbug --severity=wishlist --tag=patch --attach=my-patch python-apt + user@pc:~/debian-sid$ # Add --list-cc=jak@debian.org if you change docs. diff --git a/doc/source/conf.py b/doc/source/conf.py new file mode 100644 index 00000000..8f71e3e3 --- /dev/null +++ b/doc/source/conf.py @@ -0,0 +1,200 @@ +# -*- coding: utf-8 -*- +# +# python-apt documentation build configuration file, created by +# sphinx-quickstart on Wed Jan 7 17:04:36 2009. +# +# This file is execfile()d with the current directory set to its containing +# dir. +# +# The contents of this file are pickled, so don't put values in the namespace +# that aren't pickleable (module imports are okay, they're removed +# automatically). +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. +import os +import sys + +# If your extensions are in another directory, add it here. If the directory +# is relative to the documentation root, use os.path.abspath to make it +# absolute, like shown here. +sys.path.insert(0, os.path.abspath('..')) +sys.path.insert(0, os.path.abspath('../..')) +if os.path.exists("../../build"): + for dirname in os.listdir('../../build'): + sys.path.insert(0, os.path.abspath('../../build/' + dirname)) + +# General configuration +# --------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones. +extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', + 'sphinx.ext.intersphinx', 'sphinx.ext.todo'] +intersphinx_mapping = {'http://docs.python.org/': None} + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['.templates'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The encoding of source files. +#source_encoding = 'utf-8' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'python-apt' +copyright = u'2009, Julian Andres Klode <jak@debian.org>' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = '0.7' +# The full version, including alpha/beta/rc tags. +release = '0.7.9~exp2' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +#language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of documents that shouldn't be included in the build. +#unused_docs = [] + +# List of directories, relative to source directory, that shouldn't be searched +# for source files. +exclude_trees = [] + +# The reST default role (used for this markup: `text`) for all documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + + +# Options for HTML output +# ----------------------- + +# The style sheet to use for HTML and HTML Help pages. A file of that name +# must exist either in Sphinx' static/ path, or in one of the custom paths +# given in html_static_path. +html_style = 'default.css' + +# The name for this set of Sphinx documents. If None, it defaults to +# "<project> v<release> documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +#html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['.static'] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +#html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_use_modindex = True + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, the reST sources are included in the HTML build as _sources/<name>. +#html_copy_source = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a <link> tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = '' + +# Output file base name for HTML help builder. +htmlhelp_basename = 'python-aptdoc' + + +# Options for LaTeX output +# ------------------------ + +# The paper size ('letter' or 'a4'). +#latex_paper_size = 'letter' + +# The font size ('10pt', '11pt' or '12pt'). +#latex_font_size = '10pt' + +# Grouping the document tree into LaTeX files. List of tuples +# (source index, target name, title, author, document class [howto/manual]). +latex_documents = [ + ('index', 'python-apt.tex', ur'python-apt Documentation', + ur'Julian Andres Klode <jak@debian.org>', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# Additional stuff for the LaTeX preamble. +#latex_preamble = '' + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_use_modindex = True + +todo_include_todos = True diff --git a/doc/source/examples/apt-gtk.py b/doc/source/examples/apt-gtk.py new file mode 100644 index 00000000..c3bb09d5 --- /dev/null +++ b/doc/source/examples/apt-gtk.py @@ -0,0 +1,29 @@ +#!/usr/bin/python +"""Example for gtk widgets""" +import pygtk +pygtk.require("2.0") +import gtk + +import apt.gtk.widgets + + +def main(): + """Main function.""" + win = gtk.Window() + win.connect("destroy", gtk.main_quit) + progress = apt.gtk.widgets.GtkAptProgress() + win.set_title("GtkAptProgress Demo") + win.add(progress) + progress.show() + win.show() + cache = apt.cache.Cache(progress.open) + if cache["xterm"].isInstalled: + cache["xterm"].markDelete() + else: + cache["xterm"].markInstall() + progress.show_terminal(expanded=True) + cache.commit(progress.fetch, progress.install) + gtk.main() + +if __name__ == "__main__": + main() diff --git a/doc/source/examples/cache-packages.py b/doc/source/examples/cache-packages.py new file mode 100644 index 00000000..1abe7cf2 --- /dev/null +++ b/doc/source/examples/cache-packages.py @@ -0,0 +1,22 @@ +#!/usr/bin/python +"""Example for packages. Print all essential and important packages""" + +import apt_pkg + + +def main(): + """Main.""" + apt_pkg.InitConfig() + apt_pkg.InitSystem() + cache = apt_pkg.GetCache() + print "Essential packages:" + for pkg in cache.Packages: + if pkg.Essential: + print " ", pkg.Name + print "Important packages:" + for pkg in cache.Packages: + if pkg.Important: + print " ", pkg.Name + +if __name__ == "__main__": + main() diff --git a/doc/source/examples/cache-pkgfile.py b/doc/source/examples/cache-pkgfile.py new file mode 100644 index 00000000..f25975d3 --- /dev/null +++ b/doc/source/examples/cache-pkgfile.py @@ -0,0 +1,29 @@ +#!/usr/bin/python +import apt_pkg + + +def main(): + """Example for PackageFile()""" + apt_pkg.init() + cache = apt_pkg.GetCache() + for pkgfile in cache.FileList: + print 'Package-File:', pkgfile.FileName + print 'Index-Type:', pkgfile.IndexType # 'Debian Package Index' + if pkgfile.NotSource: + print 'Source: None' + else: + if pkgfile.Site: + # There is a source, and a site, print the site + print 'Source:', pkgfile.Site + else: + # It seems to be a local repository + print 'Source: Local package file' + if pkgfile.NotAutomatic: + # The system won't be updated automatically (eg. experimental) + print 'Automatic: No' + else: + print 'Automatic: Yes' + print + +if __name__ == '__main__': + main() diff --git a/doc/source/examples/dpkg-contents.py b/doc/source/examples/dpkg-contents.py new file mode 100644 index 00000000..99d1596f --- /dev/null +++ b/doc/source/examples/dpkg-contents.py @@ -0,0 +1,55 @@ +#!/usr/bin/python +"""Emulate dpkg --contents""" + +import grp +import pwd +import stat +import sys +import time + +import apt_inst + + +def format_mode(what, mode): + """Return the symbolic mode""" + s_mode = dict(DIR="d", HARDLINK="h", FILE="-").get(what) + s_mode += ((mode & stat.S_IRUSR) and "r" or "-") + s_mode += ((mode & stat.S_IWUSR) and "w" or "-") + s_mode += ((mode & stat.S_IXUSR) and (mode & stat.S_ISUID and "s" or "x") + or (mode & stat.S_ISUID and "S" or "-")) + s_mode += ((mode & stat.S_IRGRP) and "r" or "-") + s_mode += ((mode & stat.S_IWGRP) and "w" or "-") + s_mode += ((mode & stat.S_IXGRP) and (mode & stat.S_ISGID and "s" or "x") + or (mode & stat.S_ISGID and "S" or "-")) + s_mode += ((mode & stat.S_IROTH) and "r" or "-") + s_mode += ((mode & stat.S_IWOTH) and "w" or "-") + s_mode += ((mode & stat.S_IXOTH) and "x" or "-") + return s_mode + + +def callback(what, name, link, mode, uid, gid, size, mtime, major, minor): + """callback for debExtract""" + s_mode = format_mode(what, mode) + s_owner = "%s/%s" % (pwd.getpwuid(uid)[0], grp.getgrgid(gid)[0]) + s_size = "%9d" % size + s_time = time.strftime("%Y-%m-%d %H:%M", time.localtime(mtime)) + s_name = name.startswith(".") and name or ("./" + name) + if link: + s_name += " link to %s" % link + print s_mode, s_owner, s_size, s_time, s_name + + +def main(): + """Main function""" + if len(sys.argv) < 2: + print >> sys.stderr, "need filename argumnet" + sys.exit(1) + + fobj = open(sys.argv[1]) + try: + apt_inst.debExtract(fobj, callback, "data.tar.gz") + finally: + fobj.close() + +if __name__ == "__main__": + main() diff --git a/doc/source/examples/dpkg-extract.py b/doc/source/examples/dpkg-extract.py new file mode 100644 index 00000000..ced8652f --- /dev/null +++ b/doc/source/examples/dpkg-extract.py @@ -0,0 +1,25 @@ +#!/usr/bin/python +"""Emulate dpkg --extract package.deb outdir""" +import os +import sys + +import apt_inst + + +def main(): + """Main function.""" + if len(sys.argv) < 3: + print >> sys.stderr, "Usage:", __file__, "package.deb outdir" + sys.exit(1) + if not os.path.exists(sys.argv[2]): + print >> sys.stderr, "The directory %s does not exist" % sys.argv[2] + sys.exit(1) + + fobj = open(sys.argv[1]) + try: + apt_inst.debExtractArchive(fobj, sys.argv[2]) + finally: + fobj.close() + +if __name__ == "__main__": + main() diff --git a/doc/source/examples/dpkg-info.py b/doc/source/examples/dpkg-info.py new file mode 100644 index 00000000..ff98d8b1 --- /dev/null +++ b/doc/source/examples/dpkg-info.py @@ -0,0 +1,20 @@ +#!/usr/bin/python +"""Emulate dpkg --info package.deb control-file""" +import sys + +from apt_inst import debExtractControl + + +def main(): + """Main function.""" + if len(sys.argv) < 3: + print >> sys.stderr, 'Usage: tool file.deb control-file' + sys.exit(0) + fobj = open(sys.argv[1]) + try: + print debExtractControl(fobj, sys.argv[2]) + finally: + fobj.close() + +if __name__ == '__main__': + main() diff --git a/doc/source/examples/missing-deps.py b/doc/source/examples/missing-deps.py new file mode 100644 index 00000000..3ca16e45 --- /dev/null +++ b/doc/source/examples/missing-deps.py @@ -0,0 +1,52 @@ +#!/usr/bin/python +"""Check the archive for missing dependencies""" +import apt_pkg + + +def fmt_dep(dep): + """Format a Dependency object [of apt_pkg] as a string.""" + ret = dep.TargetPkg.Name + if dep.TargetVer: + ret += " (%s %s)" % (dep.CompType, dep.TargetVer) + return ret + + +def check_version(pkgver): + """Check the version of the package""" + missing = [] + + for or_group in pkgver.DependsList.get("Pre-Depends", []) + \ + pkgver.DependsList.get("Depends", []): + if not any(dep.AllTargets() for dep in or_group): + # If none of the or-choices can be satisfied, add it to missing + missing.append(or_group) + + if missing: + print "Package:", pkgver.ParentPkg.Name + print "Version:", pkgver.VerStr + print "Missing:", + print ", ".join(" | ".join(fmt_dep(dep) for dep in or_group) + for or_group in missing) + print + + +def main(): + """The main function.""" + apt_pkg.InitConfig() + apt_pkg.InitSystem() + + cache = apt_pkg.GetCache() + + for pkg in sorted(cache.Packages, key=lambda pkg: pkg.Name): + # pkg is from a list of packages, sorted by name. + for version in pkg.VersionList: + # Check every version + for pfile, _ in version.FileList: + if (pfile.Origin == "Debian" and pfile.Component == "main" and + pfile.Archive == "unstable"): + # We only want packages from Debian unstable main. + check_version(version) + break + +if __name__ == "__main__": + main() diff --git a/doc/source/index.rst b/doc/source/index.rst new file mode 100644 index 00000000..23ea4cca --- /dev/null +++ b/doc/source/index.rst @@ -0,0 +1,41 @@ +Welcome to python-apt's documentation! +====================================== + +.. note:: + + This documentation can not be considered complete at the moment. But it + provides better documentation than the documentation available through + pydoc. + +.. note:: + + + This documentation has been created by Sphinx, using reStructuredText files + written by Julian Andres Klode <jak@debian.org>, and in case of the apt + package, from the documentation shipped in the modules. + + +Contents: + +.. toctree:: + :maxdepth: 2 + + apt/index + apt_pkg/index + apt_inst + aptsources/index + coding + + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` + + +TODO +====== +.. todolist:: |