appi 0.2.5

Why not portage?

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.

Examples

Atom

>>> 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'>}

Versioning Policy

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.

Contributing

See Contributing page.