From 2c58471630dbd1f0708de559010fed20b1e9e359 Mon Sep 17 00:00:00 2001 From: Chenxiong Qi Date: Sep 26 2018 06:12:39 +0000 Subject: Fix and reword some docstrings again During I'm reading through the code base to learn MBS, I found out some typos and minor issues in some other docstrings, and I also found some docstrings with extra informative description could make it easier to understand the code. Signed-off-by: Chenxiong Qi --- diff --git a/module_build_service/builder/KojiContentGenerator.py b/module_build_service/builder/KojiContentGenerator.py index 7b303ae..c8a4307 100644 --- a/module_build_service/builder/KojiContentGenerator.py +++ b/module_build_service/builder/KojiContentGenerator.py @@ -66,7 +66,6 @@ class KojiContentGenerator(object): def __init__(self, module, config): """ - :param owner: a string representing who kicked off the builds :param module: module_build_service.models.ModuleBuild instance. :param config: module_build_service.config.Config instance """ diff --git a/module_build_service/builder/KojiModuleBuilder.py b/module_build_service/builder/KojiModuleBuilder.py index a406def..cfde17a 100644 --- a/module_build_service/builder/KojiModuleBuilder.py +++ b/module_build_service/builder/KojiModuleBuilder.py @@ -648,7 +648,7 @@ chmod 644 %buildroot/etc/rpm/macros.zz-modules Searches for a complete build of an artifact belonging to the module and sets the component_build in the MBS database to the found build. This usually returns nothing since these builds should *not* exist. - :param artifact_name: a ComponentBuild object + :param component_build: a ComponentBuild object :return: a list of msgs that MBS needs to process """ opts = {'latest': True, 'package': component_build.package, 'inherit': False} @@ -843,15 +843,19 @@ chmod 644 %buildroot/etc/rpm/macros.zz-modules self.koji_session.setInheritanceData(tag['id'], inheritance_data) @module_build_service.utils.validate_koji_tag('dest_tag') - def _koji_add_groups_to_tag(self, dest_tag, groups=None): - """ - :param build_tag_name - :param groups: A dict {'group' : [package, ...]} + def _koji_add_groups_to_tag(self, dest_tag, groups): + """Add groups to a tag as well as packages listed by group + + :param dest_tag: the tag groups will be added to. This argument could + be a string representing tag name, or a mapping containing tag info + which must have name at least. + :type dest_tag: str or dict + :param dict groups: A dict ``{'group' : [package, ...]}``. If one of + the groups has been added to the tag, the group is skipped. """ log.debug("Adding groups=%s to tag=%s" % (list(groups), dest_tag)) if groups and not isinstance(groups, dict): raise ValueError("Expected dict {'group' : [str(package1), ...]") - dest_tag = self._get_tag(dest_tag)['name'] existing_groups = dict([(p['name'], p['group_id']) for p @@ -874,12 +878,15 @@ chmod 644 %buildroot/etc/rpm/macros.zz-modules @module_build_service.utils.validate_koji_tag('tag_name') def _koji_create_tag(self, tag_name, arches=None, perm=None): - """ - :param tag_name: name of koji tag - :param arches: list of architectures for the tag - :param perm: permissions for the tag (used in lock-tag) + """Create a tag in Koji This call is safe to call multiple times. + + :param str tag_name: name of koji tag + :kwarg list arches: list of architectures for the tag + :kwarg str perm: permissions for the tag (used in lock-tag) + :return: a mapping containing raw tag info returned from Koji. + :rtype: dict """ log.debug("Ensuring existence of tag='%s'." % tag_name) @@ -936,7 +943,7 @@ chmod 644 %buildroot/etc/rpm/macros.zz-modules if not tags: tags = [self.module_tag, self.module_build_tag] - # This will help with potential resubmiting of failed builds + # This will help with potential resubmitting of failed builds pkglists = {} for tag in tags: pkglists[tag['id']] = dict([(p['package_name'], p['package_id']) @@ -971,14 +978,21 @@ chmod 644 %buildroot/etc/rpm/macros.zz-modules @module_build_service.utils.validate_koji_tag(['build_tag', 'dest_tag']) def _koji_add_target(self, name, build_tag, dest_tag): - """ - :param name: target name - :param build-tag: build_tag name - :param dest_tag: dest tag name + """Add build target if it doesn't exist or validate the existing one This call is safe to call multiple times. Raises SystemError() if the existing target doesn't match params. The reason not to touch existing target, is that we don't want to - accidentaly alter a target which was already used to build some artifacts. + accidentally alter a target which was already used to build some artifacts. + + :param str name: target name. + :param dict build_tag: build tag info, which must have name at least. + :param dict dest_tag: dest tag info, which must have name at least. + :return: a mapping containing raw build target info returned from Koji. + If a new build target is created, it is the new one. Otherwise, + existing build target is returned. + :rtype: dict + :raises SystemError: if existing build target does not have build_tag + name or dest_tag name. """ build_tag = self._get_tag(build_tag) dest_tag = self._get_tag(dest_tag) diff --git a/module_build_service/mmd_resolver.py b/module_build_service/mmd_resolver.py index dfb88bb..2b9673f 100644 --- a/module_build_service/mmd_resolver.py +++ b/module_build_service/mmd_resolver.py @@ -61,7 +61,11 @@ class MMDResolver(object): See the inline comments for more information. - :param list deps: List of dicts with dependency name as key and list of streams as value. + :param list deps: List of dicts with dependency name as key and list of + streams as value. Generally, it is just the return value from + ``Modulemd.Dependencies.get_requires`` or + ``Modulemd.Dependencies.get_buildrequires`` whose value is + converted from ``Modulemd.SimpleSet`` to list. :rtype: solv.Dep :return: solv.Dep instance with dependencies in form libsolv accepts. """ diff --git a/module_build_service/utils/general.py b/module_build_service/utils/general.py index bacca62..45d8321 100644 --- a/module_build_service/utils/general.py +++ b/module_build_service/utils/general.py @@ -95,16 +95,20 @@ def module_build_state_from_msg(msg): def generate_koji_tag(name, stream, version, context, max_length=256): - """ - Generate a koji tag from name, stream, version and context. - - :param name: a module's name - :param stream: a module's stream - :param version: a module's version - :param context: a module's context - :kwarg max_length: the maximum length the Koji tag can be before falling back to - the old format of "module-" + """Generate a koji tag for a module + + Generally, a module's koji tag is in format ``module-N-S-V-C``. However, if + it is longer than maximum length, old format ``module-hash`` is used. + + :param str name: a module's name + :param str stream: a module's stream + :param str version: a module's version + :param str context: a module's context + :kwarg int max_length: the maximum length the Koji tag can be before + falling back to the old format of "module-". Default is 256 + characters, which is the maximum length of a tag Koji accepts. :return: a Koji tag + :rtype: str """ nsvc_list = [name, stream, str(version), context] nsvc_tag = 'module-' + '-'.join(nsvc_list) diff --git a/module_build_service/utils/submit.py b/module_build_service/utils/submit.py index ac70440..34b2222 100644 --- a/module_build_service/utils/submit.py +++ b/module_build_service/utils/submit.py @@ -206,6 +206,16 @@ def format_mmd(mmd, scmurl, session=None): def validate_mmd(mmd): + """Validate module metadata + + If everything is ok, just keep quiet, otherwise error is raised for + specific problem. + + :param mmd: modulemd object representing module metadata. + :type mmd: Modulemd.Module + :raises Forbidden: if metadata contains module repository but it is not + allowed. + """ for modname, mod in mmd.get_module_components().items(): if mod.get_repository() and not conf.modules_allow_repository: raise Forbidden(