#1025 Fix and reword some docstrings again
Merged a year ago by mprahl. Opened a year ago by cqi.
cqi/fm-orchestrator docstring  into  master

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

          """

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

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

          """

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

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

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

a year ago

rebased onto 2c58471

a year ago

Pull-Request has been merged by mprahl

a year ago