mirror of
https://salsa.debian.org/freeipa-team/freeipa.git
synced 2024-12-27 09:21:59 -06:00
f4ad749126
Iterate over all API commands and perform the following validation: * Every command must have documentation and it must be marked for international translation * Every module hosting a command must have documentation and it must be marked for international translation * Every module topic must be marked for international translation For every error found emit a diagnostic. Emit a summary of total errors found. Return error flag if errors found, zero otherwise.
393 lines
14 KiB
Python
Executable File
393 lines
14 KiB
Python
Executable File
#!/usr/bin/python
|
|
# Authors:
|
|
# Rob Crittenden <rcritten@redhat.com>
|
|
# John Dennis <jdennis@redhat.com>
|
|
#
|
|
# Copyright (C) 2011 Red Hat
|
|
# see file 'COPYING' for use and warranty information
|
|
#
|
|
# This program is free software; you can redistribute it and/or modify
|
|
# it under the terms of the GNU General Public License as published by
|
|
# the Free Software Foundation, either version 3 of the License, or
|
|
# (at your option) any later version.
|
|
#
|
|
# This program is distributed in the hope that it will be useful,
|
|
# but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
# GNU General Public License for more details.
|
|
#
|
|
# You should have received a copy of the GNU General Public License
|
|
# along with this program. If not, see <http://www.gnu.org/licenses/>.
|
|
|
|
# Test the API against a known-good API to ensure that changes aren't made
|
|
# lightly.
|
|
|
|
import sys
|
|
import os
|
|
import re
|
|
import inspect
|
|
from ipalib import *
|
|
from ipalib.text import Gettext, NGettext
|
|
|
|
API_FILE='API.txt'
|
|
|
|
API_FILE_DIFFERENCE = 1
|
|
API_NEW_COMMAND = 2
|
|
API_NO_FILE = 4
|
|
API_DOC_ERROR = 8
|
|
|
|
def parse_options():
|
|
from optparse import OptionParser
|
|
|
|
parser = OptionParser()
|
|
parser.add_option("--validate", dest="validate", action="store_true",
|
|
default=False, help="Validate the API vs the stored API")
|
|
|
|
parser.add_option("--no-validate-doc", dest="validate_doc", action="store_false",
|
|
default=True, help="Do not validate documentation")
|
|
|
|
options, args = parser.parse_args()
|
|
return options, args
|
|
|
|
def strip_doc(line):
|
|
"""
|
|
Remove the doc= part from the repr() of a Parameter.
|
|
"""
|
|
|
|
# this pattern allows up to 2 nested parentheses in doc part
|
|
newline = re.sub(r', doc=([^(,]+)(\([^()]*(\([^()]+\)[^()]*)?\))?', '', line)
|
|
|
|
return newline
|
|
|
|
def validate_doc():
|
|
"""
|
|
Iterate over all API commands and perform the following validation:
|
|
|
|
* Every command must have documentation
|
|
and it must be marked for international translation
|
|
|
|
* Every module hosting a command must have documentation
|
|
and it must be marked for international translation
|
|
|
|
* Every module topic must be marked for international translation
|
|
|
|
For every error found emit a diagnostic.
|
|
Emit a summary of total errors found.
|
|
|
|
Return error flag if errors found, zero otherwise.
|
|
"""
|
|
|
|
def is_i18n(obj):
|
|
'Helper utility to determine if object has been internationalized'
|
|
return isinstance(obj, (Gettext, NGettext))
|
|
|
|
# The return value
|
|
rval = 0
|
|
|
|
# Used to track if we've processed a module already
|
|
modules = {}
|
|
|
|
# Initialize error counters
|
|
n_missing_cmd_doc = 0
|
|
n_missing_cmd_i18n = 0
|
|
n_missing_mod_doc = 0
|
|
n_missing_mod_i18n = 0
|
|
|
|
# Iterate over every command
|
|
for cmd in api.Command():
|
|
cmd_class = cmd.__class__
|
|
|
|
# Skip commands marked as NO_CLI
|
|
if getattr(cmd, 'NO_CLI', False):
|
|
continue
|
|
|
|
# Have we processed this module yet?
|
|
if not modules.setdefault(cmd.module, 0):
|
|
# First time seeing this module, validate the module contents
|
|
mod = sys.modules[cmd.module]
|
|
|
|
# See if there is a module topic, if so validate it
|
|
topic = getattr(mod, 'topic', None)
|
|
if topic is not None:
|
|
if not is_i18n(topic[1]):
|
|
src_file = inspect.getsourcefile(cmd_class)
|
|
n_missing_mod_i18n += 1
|
|
print "%s: topic in module \"%s\" is not internationalized" % \
|
|
(src_file, cmd.module)
|
|
|
|
# Does the module have documentation?
|
|
if mod.__doc__ is None:
|
|
src_file = inspect.getsourcefile(mod)
|
|
n_missing_mod_doc += 1
|
|
print "%s: module \"%s\" has no doc" % \
|
|
(src_file, cmd.module)
|
|
# Yes the module has doc, but is it internationalized?
|
|
elif not is_i18n(mod.__doc__):
|
|
src_file = inspect.getsourcefile(cmd_class)
|
|
n_missing_mod_i18n += 1
|
|
print "%s: module \"%s\" doc is not internationalized" % \
|
|
(src_file, cmd.module)
|
|
|
|
# Increment the count of how many commands in this module
|
|
modules[cmd.module] = modules[cmd.module] + 1
|
|
|
|
# Does the command have documentation?
|
|
if cmd.__doc__ is None:
|
|
src_file = inspect.getsourcefile(cmd_class)
|
|
line_num = inspect.getsourcelines(cmd_class)[1]
|
|
n_missing_cmd_doc += 1
|
|
print "%s:%d command \"%s\" has no doc" % (src_file, line_num, cmd.name)
|
|
# Yes the command has doc, but is it internationalized?
|
|
elif not is_i18n(cmd.__doc__):
|
|
src_file = inspect.getsourcefile(cmd_class)
|
|
line_num = inspect.getsourcelines(cmd_class)[1]
|
|
n_missing_cmd_i18n += 1
|
|
print "%s:%d command \"%s\" doc is not internationalized" % (src_file, line_num, cmd.name)
|
|
|
|
# If any errors, emit summary information and adjust return value
|
|
if n_missing_cmd_doc > 0 or n_missing_cmd_i18n > 0:
|
|
rval = API_DOC_ERROR
|
|
print "%d commands without doc, %d commands whose doc is not i18n" % \
|
|
(n_missing_cmd_doc, n_missing_cmd_i18n)
|
|
|
|
if n_missing_mod_doc > 0 or n_missing_mod_i18n > 0:
|
|
rval = API_DOC_ERROR
|
|
print "%d modules without doc, %d modules whose doc is not i18n" % \
|
|
(n_missing_mod_doc, n_missing_mod_i18n)
|
|
|
|
return rval
|
|
|
|
def make_api():
|
|
"""
|
|
Write a new API file from the current tree.
|
|
"""
|
|
fd = open(API_FILE, 'w')
|
|
for cmd in api.Command():
|
|
fd.write('command: %s\n' % cmd.name)
|
|
fd.write('args: %d,%d,%d\n' % (len(cmd.args), len(cmd.options), len(cmd.output)))
|
|
for a in cmd.args():
|
|
fd.write('arg: %s\n' % strip_doc(repr(a)))
|
|
for o in cmd.options():
|
|
fd.write('option: %s\n' % strip_doc(repr(o)))
|
|
for o in cmd.output():
|
|
fd.write('output: %s\n' % strip_doc(repr(o)))
|
|
fd.close()
|
|
|
|
return 0
|
|
|
|
def find_name(line):
|
|
"""
|
|
Break apart a Param line and pull out the name. It would be nice if we
|
|
could just eval() the line but we wouldn't have defined any validators
|
|
or normalizers it may be using.
|
|
"""
|
|
m = re.match('^[a-zA-Z0-9]+\(\'([a-z][_a-z0-9?\*\+]*)\'.*', line)
|
|
if m:
|
|
name = m.group(1)
|
|
else:
|
|
print "Couldn't find name in: %s" % line
|
|
name = ''
|
|
return name
|
|
|
|
def _finalize_command_validation(cmd, found_args, expected_args,
|
|
found_options, expected_options,
|
|
found_output, expected_output):
|
|
passed = True
|
|
# Check the args of the previous command.
|
|
if len(found_args) != expected_args:
|
|
print 'Argument count in %s of %d doesn\'t match expected: %d' % (
|
|
cmd.name, len(found_args), expected_args)
|
|
passed = False
|
|
if len(found_options) != expected_options:
|
|
print 'Options count in %s of %d doesn\'t match expected: %d' % (
|
|
cmd.name, len(found_options), expected_options)
|
|
passed = False
|
|
if len(found_output) != expected_output:
|
|
print 'Output count in %s of %d doesn\'t match expected: %d' % (
|
|
cmd.name, len(found_output), expected_output)
|
|
passed = False
|
|
|
|
# Check if there is not a new arg/opt/output in previous command
|
|
for a in cmd.args():
|
|
if a.param_spec not in found_args:
|
|
print 'Argument %s of command %s in ipalib, not in API file:\n%s' % (
|
|
a.param_spec, cmd.name, strip_doc(repr(a)))
|
|
passed = False
|
|
for o in cmd.options():
|
|
if o.param_spec not in found_options:
|
|
print 'Option %s of command %s in ipalib, not in API file:\n%s' % (
|
|
o.param_spec, cmd.name, strip_doc(repr(o)))
|
|
passed = False
|
|
for o in cmd.output():
|
|
if o.name not in found_output:
|
|
print 'Output %s of command %s in ipalib, not in API file:\n%s' % (
|
|
o.name, cmd.name, strip_doc(repr(o)))
|
|
passed = False
|
|
|
|
return passed
|
|
|
|
def validate_api():
|
|
"""
|
|
Compare the API in the file to the one in ipalib.
|
|
|
|
Return a bitwise return code to identify the types of errors found, if
|
|
any.
|
|
"""
|
|
fd = open(API_FILE, 'r')
|
|
lines = fd.readlines()
|
|
fd.close()
|
|
|
|
rval = 0
|
|
|
|
expected_args = 0
|
|
expected_options = 0
|
|
expected_output = 0
|
|
found_args = []
|
|
found_options = []
|
|
found_output = []
|
|
|
|
# First run through the file and compare it to the API
|
|
existing_cmds = []
|
|
cmd = None
|
|
for line in lines:
|
|
line = line.strip()
|
|
if line.startswith('command:'):
|
|
if cmd:
|
|
if not _finalize_command_validation(cmd, found_args, expected_args,
|
|
found_options, expected_options,
|
|
found_output, expected_output):
|
|
rval |= API_FILE_DIFFERENCE
|
|
|
|
(arg, name) = line.split(': ', 1)
|
|
if name not in api.Command:
|
|
print "Command %s in API file, not in ipalib" % name
|
|
rval |= API_FILE_DIFFERENCE
|
|
cmd = None
|
|
else:
|
|
existing_cmds.append(name)
|
|
cmd = api.Command[name]
|
|
found_args = []
|
|
found_options = []
|
|
found_output = []
|
|
if line.startswith('args:') and cmd:
|
|
line = line.replace('args: ', '')
|
|
(expected_args, expected_options, expected_output) = line.split(',')
|
|
expected_args = int(expected_args)
|
|
expected_options = int(expected_options)
|
|
expected_output = int(expected_output)
|
|
if line.startswith('arg:') and cmd:
|
|
line = line.replace('arg: ', '')
|
|
found = False
|
|
arg = find_name(line)
|
|
for a in cmd.args():
|
|
if strip_doc(repr(a)) == line:
|
|
found = True
|
|
else:
|
|
if a.name == arg:
|
|
found = True
|
|
print 'Arg in %s doesn\'t match.\nGot %s\nExpected %s' % (
|
|
name, strip_doc(repr(a)), line)
|
|
rval |= API_FILE_DIFFERENCE
|
|
if found:
|
|
found_args.append(arg)
|
|
else:
|
|
arg = find_name(line)
|
|
print "Argument '%s' in command '%s' in API file not found" % (arg, name)
|
|
rval |= API_FILE_DIFFERENCE
|
|
if line.startswith('option:') and cmd:
|
|
line = line.replace('option: ', '')
|
|
found = False
|
|
option = find_name(line)
|
|
for o in cmd.options():
|
|
if strip_doc(repr(o)) == line:
|
|
found = True
|
|
else:
|
|
if o.name == option:
|
|
found = True
|
|
print 'Option in %s doesn\'t match. Got %s Expected %s' % (name, o, line)
|
|
rval |= API_FILE_DIFFERENCE
|
|
if found:
|
|
found_options.append(option)
|
|
else:
|
|
option = find_name(line)
|
|
print "Option '%s' in command '%s' in API file not found" % (option, name)
|
|
rval |= API_FILE_DIFFERENCE
|
|
if line.startswith('output:') and cmd:
|
|
line = line.replace('output: ', '')
|
|
found = False
|
|
output = find_name(line)
|
|
for o in cmd.output():
|
|
if strip_doc(repr(o)) == line:
|
|
found = True
|
|
else:
|
|
if o.name == output:
|
|
found = True
|
|
print 'Output in %s doesn\'t match. Got %s Expected %s' % (name, o, line)
|
|
rval |= API_FILE_DIFFERENCE
|
|
if found:
|
|
found_output.append(output)
|
|
else:
|
|
output = find_name(line)
|
|
print "Option '%s' in command '%s' in API file not found" % (output, name)
|
|
rval |= API_FILE_DIFFERENCE
|
|
|
|
if cmd:
|
|
if not _finalize_command_validation(cmd, found_args, expected_args,
|
|
found_options, expected_options,
|
|
found_output, expected_output):
|
|
rval |= API_FILE_DIFFERENCE
|
|
|
|
# Now look for new commands not in the current API
|
|
for cmd in api.Command():
|
|
if cmd.name not in existing_cmds:
|
|
print "Command %s in ipalib, not in API" % cmd.name
|
|
rval |= API_NEW_COMMAND
|
|
|
|
return rval
|
|
|
|
def main():
|
|
rval = 0
|
|
options, args = parse_options()
|
|
|
|
cfg = dict(
|
|
context='cli',
|
|
in_server=False,
|
|
debug=False,
|
|
verbose=0,
|
|
validate_api=True,
|
|
enable_ra=True,
|
|
mode='developer',
|
|
)
|
|
|
|
api.bootstrap(**cfg)
|
|
api.finalize()
|
|
|
|
if options.validate_doc:
|
|
rval |= validate_doc()
|
|
|
|
if options.validate:
|
|
if not os.path.exists(API_FILE):
|
|
print 'No %s to validate' % API_FILE
|
|
rval |= API_NO_FILE
|
|
else:
|
|
rval |= validate_api()
|
|
else:
|
|
print "Writing API to API.txt"
|
|
rval |= make_api()
|
|
|
|
if rval & API_FILE_DIFFERENCE:
|
|
print ''
|
|
print 'There are one or more changes to the API.\nEither undo the API changes or update API.txt and increment the major version in VERSION.'
|
|
|
|
if rval & API_NEW_COMMAND:
|
|
print ''
|
|
print 'There are one or more new commands defined.\nUpdate API.txt and increment the minor version in VERSION.'
|
|
|
|
if rval & API_DOC_ERROR:
|
|
print ''
|
|
print 'There are one or more documentation problems.\nYou must fix these before preceeding'
|
|
|
|
return rval
|
|
|
|
sys.exit(main())
|