commit: a9e7d0e7211b5f7816667e0ab9bb2c17653c890e
Author: Mike Frysinger <vapier <AT> gentoo <DOT> org>
AuthorDate: Thu Nov 13 22:51:01 2014 +0000
Commit: Mike Frysinger <vapier <AT> gentoo <DOT> org>
CommitDate: Thu Nov 13 22:51:01 2014 +0000
URL:
http://sources.gentoo.org/gitweb/?p=proj/gentoolkit.git;a=commit;h=a9e7d0e7
ekeyword: fill out documentation and tweak API
Basically clean things up for people using ekeyword as a module.
---
src/ekeyword/ekeyword.py | 73 +++++++++++++++++++++++++++++++++++++++++-------
1 file changed, 63 insertions(+), 10 deletions(-)
diff --git a/src/ekeyword/ekeyword.py b/src/ekeyword/ekeyword.py
index 080e04f..a35d58d 100755
--- a/src/ekeyword/ekeyword.py
+++ b/src/ekeyword/ekeyword.py
@@ -18,22 +18,22 @@ The ^ leader instructs ekeyword to remove the specified
arch.
Examples:
# Mark all existing arches in the ebuild as stable.
- $ ekeyword all foo-1.ebuild
+ $ %(prog)s all foo-1.ebuild
# Mark arm as stable and x86 as unstable.
- $ ekeyword arm ~x86 foo-1.ebuild
+ $ %(prog)s arm ~x86 foo-1.ebuild
# Mark hppa as unsupported (explicitly adds -hppa).
- $ ekeyword -hppa foo-1.ebuild
+ $ %(prog)s -hppa foo-1.ebuild
# Delete alpha keywords from all ebuilds.
- $ ekeyword ^alpha *.ebuild
+ $ %(prog)s ^alpha *.ebuild
# Mark sparc as stable for foo-1 and m68k as unstable for foo-2.
- $ ekeyword sparc foo-1.ebuild ~m68k foo-2.ebuild
+ $ %(prog)s sparc foo-1.ebuild ~m68k foo-2.ebuild
# Mark s390 as the same state as amd64.
- $ ekeyword s390=amd64 foo-1.ebuild
+ $ %(prog)s s390=amd64 foo-1.ebuild
"""
from __future__ import print_function
@@ -52,10 +52,20 @@ from portage.output import colorize, nocolor
VERSION = '1.0 awesome'
+# Operation object that describes how to perform a change.
+# Args:
+# op: The operation to perform when |ref_arch| is not set:
+# None: Mark |arch| stable
+# '-': Mark |arch| as not applicable (e.g. -foo)
+# '~': Mark |arch| as unstable (e.g. ~foo)
+# '^': Delete |arch| so it isn't listed at all
+# arch: The required arch to update
+# ref_arch: Set |arch| status to this arch (ignoring |op|)
Op = collections.namedtuple('Op', ('op', 'arch', 'ref_arch'))
def warning(msg):
+ """Write |msg| as a warning to stderr"""
print('warning: %s' % msg, file=sys.stderr)
@@ -69,7 +79,17 @@ def keyword_to_arch(keyword):
def sort_keywords(arches):
- """Sort |arches| list in the order developers expect"""
+ """Sort |arches| list in the order developers expect
+
+ This is vaguely defined because it is kind of vaguely defined once you
get
+ past the basic (Linux-only) keywords.
+
+ Args:
+ arches: An iterable of ARCH values.
+
+ Returns:
+ A sorted list of |arches|
+ """
keywords = []
# Globs always come first.
@@ -98,7 +118,16 @@ def sort_keywords(arches):
def diff_keywords(old_keywords, new_keywords, format='color-inline'):
- """Show pretty diff between list of keywords"""
+ """Show pretty diff between list of keywords
+
+ Args:
+ old_keywords: The old set of KEYWORDS
+ new_keywords: The new set of KEYWORDS
+ format: The diff style
+
+ Returns:
+ A string containing the diff output ready to shown to the user
+ """
def show_diff(s):
output = ''
@@ -257,7 +286,21 @@ def process_content(ebuild, data, ops, arch_status=None,
verbose=0,
def process_ebuild(ebuild, ops, arch_status=None, verbose=0, quiet=0,
dry_run=False, format='color-inline'):
- """Process |ops| for |ebuild|"""
+ """Process |ops| for |ebuild|
+
+ Args:
+ ebuild: The ebuild file to operate on & update in place
+ ops: An iterable of operations (Op objects) to perform on |ebuild|
+ arch_status: A dict mapping default arches to their stability; see the
+ load_profile_data function for more details
+ verbose: Be verbose; show various status messages
+ quiet: Be quiet; only show errors
+ dry_run: Do not make any changes to |ebuild|; show what would be done
+ format: The diff style
+
+ Returns:
+ Whether any updates were processed
+ """
with io.open(ebuild, encoding='utf8') as f:
updated, content = process_content(
ebuild, f, ops, arch_status=arch_status,
@@ -265,10 +308,20 @@ def process_ebuild(ebuild, ops, arch_status=None,
verbose=0, quiet=0,
if updated and not dry_run:
with io.open(ebuild, 'w', encoding='utf8') as f:
f.writelines(content)
+ return updated
def load_profile_data(portdir=None, repo='gentoo'):
- """Load the list of known arches from the tree"""
+ """Load the list of known arches from the tree
+
+ Args:
+ portdir: The repository to load all data from (and ignore |repo|)
+ repo: Look up this repository by name to locate profile data
+
+ Returns:
+ A dict mapping the keyword to its preferred state:
+ {'x86': 'stable', 'mips': 'dev', ...}
+ """
if portdir is None:
portdir =
portage.db['/']['vartree'].settings.repositories[repo].location
