mirror of
https://salsa.debian.org/freeipa-team/freeipa.git
synced 2024-12-23 07:33:27 -06:00
db13494045
Capture the server API rather than client API in API.txt. Client API may be affected by client-side plugins and thus may not correspond to what is transmitted over the wire. https://fedorahosted.org/freeipa/ticket/4739 Reviewed-By: David Kupka <dkupka@redhat.com>
501 lines
17 KiB
Python
Executable File
501 lines
17 KiB
Python
Executable File
#!/usr/bin/python2
|
|
# Authors:
|
|
# Rob Crittenden <rcritten@redhat.com>
|
|
# John Dennis <jdennis@redhat.com>
|
|
# Martin Kosek <mkosek@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.
|
|
|
|
from __future__ import print_function
|
|
|
|
import importlib
|
|
import sys
|
|
import os
|
|
import re
|
|
import inspect
|
|
import operator
|
|
from ipalib import api
|
|
from ipalib.parameters import Param
|
|
from ipalib.output import Output
|
|
from ipalib.text import Gettext, NGettext, ConcatenatedLazyText
|
|
from ipalib.capabilities import capabilities
|
|
|
|
API_FILE='API.txt'
|
|
|
|
API_FILE_DIFFERENCE = 1
|
|
API_NEW_COMMAND = 2
|
|
API_NO_FILE = 4
|
|
API_DOC_ERROR = 8
|
|
|
|
# attributes removed from Param.__kw dictionary
|
|
PARAM_IGNORED_KW_ATTRIBUTES = (
|
|
'attribute',
|
|
'cli_metavar',
|
|
'default_from',
|
|
'doc',
|
|
'exclude',
|
|
'exponential',
|
|
'flags',
|
|
'hint',
|
|
'include',
|
|
'label',
|
|
'length',
|
|
'maxlength',
|
|
'maxvalue',
|
|
'minlength',
|
|
'minvalue',
|
|
'noextrawhitespace',
|
|
'normalizer',
|
|
'numberclass',
|
|
'only_absolute',
|
|
'only_relative',
|
|
'pattern',
|
|
'pattern_errmsg',
|
|
'precision',
|
|
'primary_key',
|
|
'query',
|
|
'sortorder',
|
|
)
|
|
|
|
# attributes removed from Output object
|
|
OUTPUT_IGNORED_ATTRIBUTES = (
|
|
'doc',
|
|
'flags',
|
|
)
|
|
|
|
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 param_repr(p):
|
|
"""
|
|
Return parameter repr() for API.txt purposes.
|
|
|
|
Some Param attributes do not cause API incompatibility (e.g. doc,
|
|
label or callables) and should not be added to API.txt. These attributes
|
|
are removed from the parameter before repr() is called.
|
|
|
|
NOTE: since the parameter is not not deepcopy()'ed before attributes are
|
|
removed, the original parameter is changed in the process. This is OK
|
|
for ./makeapi since we don't need this attributes anyway (except for
|
|
validate_doc() which is, however, called before any param_repr() call).
|
|
"""
|
|
if isinstance(p, Output):
|
|
for attr in OUTPUT_IGNORED_ATTRIBUTES:
|
|
try:
|
|
object.__delattr__(p, attr)
|
|
except AttributeError:
|
|
pass
|
|
return repr(p)
|
|
elif isinstance(p, Param):
|
|
param_kw = p.__dict__['_Param__kw']
|
|
for attr in PARAM_IGNORED_KW_ATTRIBUTES:
|
|
try:
|
|
del param_kw[attr]
|
|
except KeyError:
|
|
pass
|
|
object.__setattr__(p, 'rules', {})
|
|
return repr(p)
|
|
else:
|
|
raise ValueError('Unsupported parameter type!')
|
|
|
|
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, ConcatenatedLazyText))
|
|
|
|
# The return value
|
|
rval = 0
|
|
|
|
# Used to track if we've processed a module already
|
|
topics = {}
|
|
|
|
# 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?
|
|
topic = cmd.topic
|
|
while topic is not None:
|
|
if not topics.setdefault(topic, 0):
|
|
# First time seeing this module, validate the module contents
|
|
doc = None
|
|
next_topic = None
|
|
|
|
for package in api.packages:
|
|
module = '%s.%s' % (package.__name__, topic)
|
|
try:
|
|
mod = sys.modules[module]
|
|
except KeyError:
|
|
try:
|
|
mod = importlib.import_module(module)
|
|
except ImportError:
|
|
continue
|
|
|
|
if mod.__doc__ is not None:
|
|
doc = mod.__doc__
|
|
|
|
# See if there is a module topic, if so validate it
|
|
try:
|
|
next_topic = mod.topic
|
|
except AttributeError:
|
|
pass
|
|
|
|
# Does the module have documentation?
|
|
if doc is None:
|
|
src_file = inspect.getsourcefile(mod)
|
|
n_missing_mod_doc += 1
|
|
print("%s: module \"%s\" has no doc" %
|
|
(src_file, module))
|
|
# Yes the module has doc, but is it internationalized?
|
|
elif not is_i18n(doc):
|
|
src_file = inspect.getsourcefile(cmd_class)
|
|
n_missing_mod_i18n += 1
|
|
print("%s: module \"%s\" doc is not internationalized" %
|
|
(src_file, module))
|
|
else:
|
|
next_topic = None
|
|
|
|
# Increment the count of how many commands in this module
|
|
topics[topic] = topics[topic] + 1
|
|
|
|
topic = next_topic
|
|
|
|
# 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' % param_repr(a))
|
|
for o in sorted(cmd.options(), key=operator.attrgetter('name')):
|
|
fd.write('option: %s\n' % param_repr(o))
|
|
for o in sorted(cmd.output(), key=operator.attrgetter('name')):
|
|
fd.write('output: %s\n' % param_repr(o))
|
|
for name, version in sorted(
|
|
capabilities.items(), key=operator.itemgetter(1, 0)):
|
|
fd.write('capability: %s %s\n' % (name, version))
|
|
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, param_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, param_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, param_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 = []
|
|
existing_capabilities = set()
|
|
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 param_repr(a) == line:
|
|
found = True
|
|
else:
|
|
if a.name == arg:
|
|
found = True
|
|
print('Arg in %s doesn\'t match.\nGot %s\nExpected %s' % (
|
|
name, param_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 param_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 param_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 line.startswith('capability:'):
|
|
cap, version = line.replace('capability: ', '').split(' ', 1)
|
|
existing_capabilities.add(cap)
|
|
try:
|
|
expected_version = str(capabilities[cap])
|
|
except KeyError:
|
|
print("Capability '%s' in API file not found" % cap)
|
|
rval |= API_FILE_DIFFERENCE
|
|
else:
|
|
if version != expected_version:
|
|
print((
|
|
"Capability '%s' in API file doesn't match. Got %s, "
|
|
"expected %s.") % (cap, version, expected_version))
|
|
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
|
|
|
|
for cap in capabilities:
|
|
if cap not in existing_capabilities:
|
|
print("Capability %s in ipalib, not in API" % cap)
|
|
rval |= API_FILE_DIFFERENCE
|
|
|
|
return rval
|
|
|
|
def main():
|
|
rval = 0
|
|
options, args = parse_options()
|
|
|
|
cfg = dict(
|
|
context='server',
|
|
in_server=True,
|
|
in_tree=True,
|
|
debug=False,
|
|
verbose=0,
|
|
validate_api=True,
|
|
enable_ra=True,
|
|
mode='developer',
|
|
plugins_on_demand=False,
|
|
)
|
|
|
|
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())
|