Another Portage Python Interface
Mainly, I was having hard time understanding the python portage
module. I found the code
somewhat obscure and lacking documentation. So I decided to start an alternative, bringing my
approach of how I would like the API to be.
So was born appi
. It is still at an early stage, but I hope someday it will have enough
features to enable portage-based distributions newcomers to use it and improve it.
>>> from appi import QueryAtom
>>> a = QueryAtom('portage')
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
File "/home/tony/Workspace/Funtoo/appi/appi/atom.py", line 76, in __init__
atom_string, code='missing_category')
appi.atom.AtomError: portage may be ambiguous, please specify the category.
>>> a = QueryAtom('portage', strict=False)
>>> a.list_matching_ebuilds()
{<Ebuild: 'sys-apps/portage-2.4.1-r1::gentoo'>, <Ebuild: 'sys-apps/portage-2.4.3-r1::gentoo'>}
>>> a
<QueryAtom: 'portage'>
>>> b = QueryAtom('>=sys-apps/portage-2.4.2')
>>> b
<QueryAtom: '>=sys-apps/portage-2.4.2'>
>>> b.list_matching_ebuilds()
{<Ebuild: 'sys-apps/portage-2.4.3-r1::gentoo'>}
>>> # Considering a second repository named "sapher" containing qtile ebuilds
...
>>> QueryAtom('=x11-wm/qtile-9999').list_matching_ebuilds()
{<Ebuild: 'x11-wm/qtile-9999::gentoo'>, <Ebuild: 'x11-wm/qtile-9999::sapher'>}
We use the following version format: M.m.p
- M is the major version
- m is the minor version
- p is the patch version
We may also package pre-releases (postfixed with _preN
, where N is the pre-release version)
and release candidates (postfixed with _rcN
, where N is the release candidate version).
Starting from version 1.0.0, a major version bump means:
- Global refactoring of the code base
- Removal of features deprecated in the previous releases
A minor version bump means:
- New features
- Existing features improvement
- Features deprecation (raising warnings) which will be removed in the next major version
A patch version bump means:
- Bug fixes
- Security fixes
Thus, backward compatibility is maintained across minor versions, but broken at each major version bump. However:
- Major version bumps should be very rare
- If you pay attention to the few deprecation warnings that may appear across minor version bumps, and fix them along the way, upgrading to a new major version will require no work at all.
- Support and patches will still be provided for the last two minor versions before the curent version.
- Starting from version 2.0.0, the main module will be named
appiM
where M is the major version number (eg.appi2
,appi3
, ...). This will allow old software not using the latest major version to stay available along with newer software using the latest major version.
Before version 1.0.0, any minor version bump may break backward compatibility.
See Contributing page.