Difference between revisions of "Portage API"

From Funtoo
Jump to navigation Jump to search
Line 55: Line 55:
<tr><td>{{c|minimum-all}}</td><td>Find the lowest match for the dependency, ignoring masks.</td><td>single string</td></tr>
<tr><td>{{c|minimum-all}}</td><td>Find the lowest match for the dependency, ignoring masks.</td><td>single string</td></tr>
<tr><td>{{c|minimum-visible}}</td><td>Find the lowest match for the dependency, respecting masks.</td><td>single string</td></tr>
<tr><td>{{c|minimum-visible}}</td><td>Find the lowest match for the dependency, respecting masks.</td><td>single string</td></tr>
{{TableEnd}}
=== Querying Package Metadata ===
Portage is designed to extract and cache a certain set of data from each ebuild, called metadata, and this metadata is queryable and used for dependency calculations, fetching sources, etc. Querying of metadata for a particular ebuild can be performed using the {{c|aux_get()}} DBAPI method:
{{console|body=
>>> ###p.aux_get("sys-apps/portage-2.3.8", ["EAPI", "SRC_URI"])
['5-progress', 'https://www.github.com/funtoo/portage-funtoo/tarball/funtoo-2.3.8 -> portage-funtoo-2.3.8.tar.gz']
}}
The parameters of the {{c|aux_get()}} method are, first, the name of a package in "catpkg-v" format, which is a reference to a specific version of a package in "category/packagename-version(-revision)" format. The second argument is a list or tuple of metadata to return. A list is returned containing the queried metadata in the order specified in the first argument. If necessary, Portage will evaluate the contents of the ebuild to extract and cache this metadata. For porttrees, the following metadata is available (and this may vary by EAPI):
{{TableStart}}
<tr><th>Metadata</th><th>Description</th></tr>
<tr><td>{{c|DEFINED_PHASES}}</td><td>String containing all phases (see [[Ebuild Functions]]) defined in the ebuild, delimited by spaces.</td></tr>
<tr><td>{{c|DEPEND}}</td><td>Build dependencies</td></tr>
<tr><td>{{c|EAPI}}</td><td>Ebuild API version</td></tr>
<tr><td>{{c|HDEPEND}}</td><td>Host Build Dependencies (EAPI 5-hdepend only)</td></tr>
<tr><td>{{c|INHERITED}}</td><td>A complete list of eclasses used by this ebuild, directly or indirectly (via eclasses inheriting other eclasses)</td></tr>
<tr><td>{{c|IUSE}}</td><td>{{c|IUSE}} variable from ebuild</td></tr>
<tr><td>{{c|KEYWORDS}}</td><td>{{c|KEYWORDS}} (masking) setting</td></tr>
<tr><td>{{c|LICENSE}}</td><td>{{c|LICENSE}} variable from ebuild</td></tr>
<tr><td>{{c|PDEPEND}}</td><td>{{c|PDEPEND}} variable from ebuild</td></tr>
<tr><td>{{c|PROPERTIES}}</td><td>{{c|PROPERTIES}} variable from ebuild</td></tr>
<tr><td>{{c|PROVIDE}}</td><td>{{c|PROVIDE}} variable from ebuild</td></tr>
<tr><td>{{c|RDEPEND}}</td><td>Runtime dependencies</td></tr>
<tr><td>{{c|REQUIRED_USE}}</td><td>{{c|REQUIRED_USE}} variable from ebuild</td></tr>
<tr><td>{{c|repository}}</td><td>Repository name ("gentoo" in main Gentoo or Funtoo Portage tree)</td></tr>
<tr><td>{{c|RESTRICT}}</td><td>{{c|RESTRICT}} variable from ebuild</td></tr>
<tr><td>{{c|SLOT}}</td><td>{{c|SLOT}} variable from ebuild</td></tr>
{{TableEnd}}
{{TableEnd}}

Revision as of 02:00, September 28, 2015

This page is the beginning of the missing documentation on the Portage Python API.

Introduction

Portage has always had a Python API; however, this API does not appear to be documented at all. This page represents an initial effort to document the API that is available for querying packages, etc.

Portage DBAPI

The API that exists in Portage to query this is called the DBAPI, and the "porttree" -- What is typically stored in Template:P, and querying the porttree is what we will examine here, using the interactive python interpreter.

w520 drobbins # python
Python 3.3.5 (default, Sep 21 2015, 23:01:43) 
[GCC 4.9.3] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> portage.root
'/'
>>> import portage
>>> p = portage.db[portage.root]["porttree"].dbapi
>>>

p now contains a reference to the DBAPI associated with the Portage tree associated with the system installed at portage.root, which is typically /usr/portage. We can now perform various queries using this variable.

>>> p.cp_list("sys-apps/portage")
['sys-apps/portage-2.3.6-r9', 'sys-apps/portage-2.3.8']

Above, cp_list takes what is called a "catpkg", which is a reference to a particular ebuild in a repository in "category/packagename" format. We can also get lists of specific available packages, using other functions:

>>> p.match("sys-apps/portage")
['sys-apps/portage-2.3.6-r9', 'sys-apps/portage-2.3.8']
>>> p.match("=sys-apps/portage-2*")
['sys-apps/portage-2.3.6-r9', 'sys-apps/portage-2.3.8']

While at first the match() method looks no different than the cp_list() method, you can see that it accepts any valid dependency atom, which is any individual dependency reference to a particular package. The match() method is actually a shortcut for the more sophisticated xmatch() method -- it matches all visible (non-masked) packages that satisfy the dependency.

Using xmatch(), more sophisticated matching can be performed:

>>> p.xmatch("match-visible", "=sys-apps/portage-2*")
['sys-apps/portage-2.3.6-r9', 'sys-apps/portage-2.3.8']

As you can see, xmatch() with the "match_visible" gives us the identical results as match(). In fact, match() is a shortcut for this particular xmatch() call. However, xmatch() has other matching methods, detailed below:

match modeDescriptionReturn Type
bestmatch-visibleFind the best (highest) visible (unmasked) match for the dependency.single string
match-allFind all matches, masked or unmasked.list of strings
match-visibleFind all visible (unmasked) matches for the dependency.list of strings
minimum-allFind the lowest match for the dependency, ignoring masks.single string
minimum-visibleFind the lowest match for the dependency, respecting masks.single string

Querying Package Metadata

Portage is designed to extract and cache a certain set of data from each ebuild, called metadata, and this metadata is queryable and used for dependency calculations, fetching sources, etc. Querying of metadata for a particular ebuild can be performed using the aux_get() DBAPI method:

>>> ###p.aux_get("sys-apps/portage-2.3.8", ["EAPI", "SRC_URI"])
['5-progress', 'https://www.github.com/funtoo/portage-funtoo/tarball/funtoo-2.3.8 -> portage-funtoo-2.3.8.tar.gz']

The parameters of the aux_get() method are, first, the name of a package in "catpkg-v" format, which is a reference to a specific version of a package in "category/packagename-version(-revision)" format. The second argument is a list or tuple of metadata to return. A list is returned containing the queried metadata in the order specified in the first argument. If necessary, Portage will evaluate the contents of the ebuild to extract and cache this metadata. For porttrees, the following metadata is available (and this may vary by EAPI):

MetadataDescription
DEFINED_PHASESString containing all phases (see Ebuild Functions) defined in the ebuild, delimited by spaces.
DEPENDBuild dependencies
EAPIEbuild API version
HDEPENDHost Build Dependencies (EAPI 5-hdepend only)
INHERITEDA complete list of eclasses used by this ebuild, directly or indirectly (via eclasses inheriting other eclasses)
IUSEIUSE variable from ebuild
KEYWORDSKEYWORDS (masking) setting
LICENSELICENSE variable from ebuild
PDEPENDPDEPEND variable from ebuild
PROPERTIESPROPERTIES variable from ebuild
PROVIDEPROVIDE variable from ebuild
RDEPENDRuntime dependencies
REQUIRED_USEREQUIRED_USE variable from ebuild
repositoryRepository name ("gentoo" in main Gentoo or Funtoo Portage tree)
RESTRICTRESTRICT variable from ebuild
SLOTSLOT variable from ebuild