PR#1025: Fix and reword some docstrings again - fm-orchestrator

fm-orchestrator

#1025 Fix and reword some docstrings again

Merged 5 years ago by mprahl. Opened 5 years ago by cqi.

cqi/fm-orchestrator docstring into master

Fix and reword some docstrings again

Chenxiong Qi • 5 years ago

2c58471

module_build_service/builder/KojiContentGenerator.py

file modified

-1

		`@@ -66,7 +66,6 @@`

		`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`
		`"""`

module_build_service/builder/KojiModuleBuilder.py

file modified

+30 -16

		`@@ -648,7 +648,7 @@`
		`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 @@`
		`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 @@`

		`@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 @@`
		`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 @@`

		`@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)`

module_build_service/mmd_resolver.py

file modified

+5 -1

		`@@ -61,7 +61,11 @@`

		`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.`
		`"""`

module_build_service/utils/general.py

file modified

+13 -9

		`@@ -95,16 +95,20 @@`


		`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-<hash>"`
		`+ """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-<hash>". 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)`

module_build_service/utils/submit.py

file modified

+10

		`@@ -206,6 +206,16 @@`


		`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(`

cqi commented 5 years ago

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 cqi@redhat.com

rebased onto 189fd6299d418ff02b48232bbbbd8e84960603ed

5 years ago