robotframework 6.1rc1__zip → 7.0__zip

{robotframework-6.1rc1 → robotframework-7.0}/src/robot/libdocpkg/model.py

@@ -97,9 +97,9 @@ class LibraryDoc:
         formatter = DocFormatter(self.keywords, self.type_docs, self.doc, self.doc_format)
         self._doc = formatter.html(self.doc, intro=True)
         for item in self.inits + self.keywords:
-            # If 'shortdoc' is not set, it is generated automatically based on 'doc'
+            # If 'short_doc' is not set, it is generated automatically based on 'doc'
             # when accessed. Generate and set it to avoid HTML format affecting it.
-            item.shortdoc = item.shortdoc
+            item.short_doc = item.short_doc
             item.doc = formatter.html(item.doc)
         for type_doc in self.type_docs:
             # Standard docs are always in ROBOT format ...
@@ -113,7 +113,7 @@ class LibraryDoc:
 
     def to_dictionary(self, include_private=False, theme=None):
         data = {
-            'specversion': 2,
+            'specversion': 3,
             'name': self.name,
             'doc': self.doc,
             'version': self.version,
@@ -127,22 +127,12 @@ class LibraryDoc:
             'inits': [init.to_dictionary() for init in self.inits],
             'keywords': [kw.to_dictionary() for kw in self.keywords
                          if include_private or not kw.private],
-            # 'dataTypes' was deprecated in RF 5, 'typedoc' should be used instead.
-            'dataTypes': self._get_data_types(self.type_docs),
             'typedocs': [t.to_dictionary() for t in sorted(self.type_docs)]
         }
         if theme:
             data['theme'] = theme.lower()
         return data
 
-    def _get_data_types(self, types):
-        enums = sorted(t for t in types if t.type == 'Enum')
-        typed_dicts = sorted(t for t in types if t.type == 'TypedDict')
-        return {
-            'enums': [t.to_dictionary(legacy=True) for t in enums],
-            'typedDicts': [t.to_dictionary(legacy=True) for t in typed_dicts]
-        }
-
     def to_json(self, indent=None, include_private=True, theme=None):
         data = self.to_dictionary(include_private, theme)
         return json.dumps(data, indent=indent)
@@ -151,12 +141,12 @@ class LibraryDoc:
 class KeywordDoc(Sortable):
     """Documentation for a single keyword or an initializer."""
 
-    def __init__(self, name='', args=None, doc='', shortdoc='', tags=(), private=False,
+    def __init__(self, name='', args=None, doc='', short_doc='', tags=(), private=False,
                  deprecated=False, source=None, lineno=-1, parent=None):
         self.name = name
-        self.args = args or ArgumentSpec()
+        self.args = args if args is not None else ArgumentSpec()
         self.doc = doc
-        self._shortdoc = shortdoc
+        self._short_doc = short_doc
         self.tags = Tags(tags)
         self.private = private
         self.deprecated = deprecated
@@ -167,19 +157,19 @@ class KeywordDoc(Sortable):
         self.type_docs = {arg.name: {} for arg in self.args}
 
     @property
-    def shortdoc(self):
-        return self._shortdoc or self._doc_to_shortdoc()
+    def short_doc(self):
+        return self._short_doc or self._doc_to_short_doc()
 
-    def _doc_to_shortdoc(self):
+    def _doc_to_short_doc(self):
         if self.parent and self.parent.doc_format == 'HTML':
-            doc = HtmlToText().get_shortdoc_from_html(self.doc)
+            doc = HtmlToText().get_short_doc_from_html(self.doc)
         else:
             doc = self.doc
         return ' '.join(getshortdoc(doc).splitlines())
 
-    @shortdoc.setter
-    def shortdoc(self, shortdoc):
-        self._shortdoc = shortdoc
+    @short_doc.setter
+    def short_doc(self, short_doc):
+        self._short_doc = short_doc
 
     @property
     def _sort_key(self):
@@ -189,8 +179,9 @@ class KeywordDoc(Sortable):
         data = {
             'name': self.name,
             'args': [self._arg_to_dict(arg) for arg in self.args],
+            'returnType': self._return_to_dict(self.args.return_type),
             'doc': self.doc,
-            'shortdoc': self.shortdoc,
+            'shortdoc': self.short_doc,
             'tags': list(self.tags),
             'source': str(self.source) if self.source else None,
             'lineno': self.lineno
@@ -206,18 +197,20 @@ class KeywordDoc(Sortable):
         return {
             'name': arg.name,
             'type': self._type_to_dict(arg.type, type_docs),
-            'types': arg.types_reprs,
-            'typedocs': type_docs,
             'defaultValue': arg.default_repr,
             'kind': arg.kind,
             'required': arg.required,
             'repr': str(arg)
         }
 
-    def _type_to_dict(self, type: TypeInfo, type_docs: dict):
+    def _return_to_dict(self, return_type):
+        type_docs = self.type_docs.get('return', {})
+        return self._type_to_dict(return_type, type_docs)
+
+    def _type_to_dict(self, type: 'TypeInfo|None', type_docs: dict):
         if not type:
             return None
         return {'name': type.name,
                 'typedoc': type_docs.get(type.name),
-                'nested': [self._type_to_dict(t, type_docs) for t in type.nested],
+                'nested': [self._type_to_dict(t, type_docs) for t in type.nested or ()],
                 'union': type.is_union}

{robotframework-6.1rc1 → robotframework-7.0}/src/robot/libdocpkg/robotbuilder.py

@@ -18,8 +18,8 @@ import sys
 import re
 
 from robot.errors import DataError
-from robot.running import (ArgInfo, ResourceFileBuilder, TestLibrary, TestSuiteBuilder,
-                           TypeInfo, UserLibrary, UserErrorHandler)
+from robot.running import (ArgumentSpec, ResourceFileBuilder, TestLibrary,
+                           TestSuiteBuilder, TypeInfo)
 from robot.utils import is_string, split_tags_from_doc, unescape
 from robot.variables import search_variable
 
@@ -32,11 +32,11 @@ class LibraryDocBuilder:
 
     def build(self, library):
         name, args = self._split_library_name_and_args(library)
-        lib = TestLibrary(name, args)
+        lib = TestLibrary.from_name(name, args=args)
         libdoc = LibraryDoc(name=lib.name,
                             doc=self._get_doc(lib),
                             version=lib.version,
-                            scope=str(lib.scope),
+                            scope=lib.scope.name,
                             doc_format=lib.doc_format,
                             source=lib.source,
                             lineno=lib.lineno)
@@ -61,29 +61,36 @@ class LibraryDocBuilder:
         return lib.doc or f"Documentation for library ``{lib.name}``."
 
     def _get_initializers(self, lib):
-        if lib.init.arguments.maxargs:
+        if lib.init.args:
             return [KeywordDocBuilder().build_keyword(lib.init)]
         return []
 
     def _get_type_docs(self, keywords, custom_converters):
-        type_docs = {}
+        all_type_docs = {}
         for kw in keywords:
-            for arg in kw.args:
-                kw.type_docs[arg.name] = {}
-                for type_info in self._yield_type_info(arg.type):
-                    type_doc = TypeDoc.for_type(type_info.type, custom_converters)
-                    if type_doc:
-                        kw.type_docs[arg.name][type_info.name] = type_doc.name
-                        type_docs.setdefault(type_doc, set()).add(kw.name)
-        for type_doc, usages in type_docs.items():
+            for name, type_info in self._yield_names_and_infos(kw.args):
+                type_docs = kw.type_docs.setdefault(name, {})
+                type_doc = TypeDoc.for_type(type_info, custom_converters)
+                if type_doc:
+                    type_docs[type_info.name] = type_doc.name
+                    all_type_docs.setdefault(type_doc, set()).add(kw.name)
+        for type_doc, usages in all_type_docs.items():
             type_doc.usages = sorted(usages, key=str.lower)
-        return set(type_docs)
+        return set(all_type_docs)
 
-    def _yield_type_info(self, info: TypeInfo):
+    def _yield_names_and_infos(self, args: ArgumentSpec):
+        for arg in args:
+            for type_info in self._yield_infos(arg.type):
+                yield arg.name, type_info
+        if args.return_type:
+            for type_info in self._yield_infos(args.return_type):
+                yield 'return', type_info
+
+    def _yield_infos(self, info: TypeInfo):
         if not info.is_union:
             yield info
-        for nested in info.nested:
-            yield from self._yield_type_info(nested)
+        for nested in info.nested or ():
+            yield from self._yield_infos(nested)
 
 
 class ResourceDocBuilder:
@@ -91,19 +98,18 @@ class ResourceDocBuilder:
 
     def build(self, path):
         path = self._find_resource_file(path)
-        res, name = self._import_resource(path)
+        resource, name = self._import_resource(path)
         libdoc = LibraryDoc(name=name,
-                            doc=self._get_doc(res, name),
+                            doc=self._get_doc(resource, name),
                             type=self.type,
                             scope='GLOBAL',
-                            source=res.source,
+                            source=resource.source,
                             lineno=1)
-        libdoc.keywords = KeywordDocBuilder(resource=True).build_keywords(res)
+        libdoc.keywords = KeywordDocBuilder(resource=True).build_keywords(resource)
         return libdoc
 
     def _import_resource(self, path):
-        model = ResourceFileBuilder(process_curdir=False).build(path)
-        resource = UserLibrary(model)
+        resource = ResourceFileBuilder(process_curdir=False).build(path)
         return resource, resource.name
 
     def _find_resource_file(self, path):
@@ -128,10 +134,11 @@ class SuiteDocBuilder(ResourceDocBuilder):
         builder = TestSuiteBuilder(process_curdir=False)
         if os.path.basename(path).lower() == '__init__.robot':
             path = os.path.dirname(path)
-            builder.included_suites = ()
             builder.allow_empty_suite = True
+            # Hack to disable parsing nested files.
+            builder.included_files = ('-no-files-included-',)
         suite = builder.build(path)
-        return UserLibrary(suite.resource), suite.name
+        return suite.resource, suite.name
 
     def _get_doc(self, resource, name):
         return f"Documentation for keywords in suite ``{name}``."
@@ -142,15 +149,19 @@ class KeywordDocBuilder:
     def __init__(self, resource=False):
         self._resource = resource
 
-    def build_keywords(self, lib):
-        return [self.build_keyword(kw) for kw in lib.handlers]
+    def build_keywords(self, owner):
+        return [self.build_keyword(kw) for kw in owner.keywords]
 
     def build_keyword(self, kw):
         doc, tags = self._get_doc_and_tags(kw)
+        if kw.error:
+            doc = f'*Creating keyword failed:* {kw.error}'
         if not self._resource:
-            self._escape_strings_in_defaults(kw.arguments.defaults)
+            self._escape_strings_in_defaults(kw.args.defaults)
+        if kw.args.embedded:
+            self._remove_embedded(kw.args)
         return KeywordDoc(name=kw.name,
-                          args=kw.arguments,
+                          args=kw.args,
                           doc=doc,
                           tags=tags,
                           private=tags.robot('private'),
@@ -182,6 +193,14 @@ class KeywordDocBuilder:
         return doc, kw.tags + tags
 
     def _get_doc(self, kw):
-        if self._resource and not isinstance(kw, UserErrorHandler):
+        if self._resource:
             return unescape(kw.doc)
         return kw.doc
+
+    def _remove_embedded(self, spec: ArgumentSpec):
+        embedded = len(spec.embedded)
+        pos_only = len(spec.positional_only)
+        spec.positional_only = spec.positional_only[embedded:]
+        if embedded > pos_only:
+            spec.positional_or_named = spec.positional_or_named[embedded-pos_only:]
+        spec.embedded = ()

{robotframework-6.1rc1 → robotframework-7.0}/src/robot/libdocpkg/standardtypes.py

@@ -16,7 +16,7 @@
 from datetime import date, datetime, timedelta
 from decimal import Decimal
 from pathlib import Path
-from typing import Any
+from typing import Any, Literal
 
 
 STANDARD_TYPE_DOCS = {
@@ -180,6 +180,14 @@ If the type has nested types like ``frozenset[int]``, items are converted
 to those types automatically. This in new in Robot Framework 6.0.
 
 Examples: ``{1, 2, 3, 42}``, ``set()`` (an empty set)
+''',
+    Literal: '''\
+Only specified values are accepted. Values can be strings,
+integers, bytes, Booleans, enums and None, and used arguments
+are converted using the value type specific conversion logic.
+
+Strings are case, space, underscore and hyphen insensitive,
+but exact matches have precedence over normalized matches.
 '''
 }
 

{robotframework-6.1rc1 → robotframework-7.0}/src/robot/libdocpkg/xmlbuilder.py

@@ -16,7 +16,7 @@
 import os.path
 
 from robot.errors import DataError
-from robot.running import ArgInfo
+from robot.running import ArgInfo, TypeInfo
 from robot.utils import ET, ETSource
 
 from .datatypes import EnumMember, TypedDictItem, TypeDoc
@@ -52,9 +52,9 @@ class XmlDocBuilder:
         if root.tag != 'keywordspec':
             raise DataError(f"Invalid spec file '{path}'.")
         version = root.get('specversion')
-        if version not in ('3', '4', '5'):
+        if version not in ('3', '4', '5', '6'):
             raise DataError(f"Invalid spec file version '{version}'. "
-                            f"Supported versions are 3, 4 and 5.")
+                            f"Supported versions are 3, 4, 5, and 6.")
         return root
 
     def _create_keywords(self, spec, path, lib_source):
@@ -63,32 +63,38 @@ class XmlDocBuilder:
     def _create_keyword(self, elem, lib_source):
         kw = KeywordDoc(name=elem.get('name', ''),
                         doc=elem.find('doc').text or '',
-                        shortdoc=elem.find('shortdoc').text or '',
+                        short_doc=elem.find('shortdoc').text or '',
                         tags=[t.text for t in elem.findall('tags/tag')],
                         private=elem.get('private', 'false') == 'true',
                         deprecated=elem.get('deprecated', 'false') == 'true',
                         source=elem.get('source') or lib_source,
                         lineno=int(elem.get('lineno', -1)))
         self._create_arguments(elem, kw)
+        self._add_return_type(elem.find('returntype'), kw)
         return kw
 
     def _create_arguments(self, elem, kw: KeywordDoc):
         spec = kw.args
-        setters = {
-            ArgInfo.POSITIONAL_ONLY: spec.positional_only.append,
-            ArgInfo.POSITIONAL_ONLY_MARKER: lambda value: None,
-            ArgInfo.POSITIONAL_OR_NAMED: spec.positional_or_named.append,
-            ArgInfo.VAR_POSITIONAL: lambda value: setattr(spec, 'var_positional', value),
-            ArgInfo.NAMED_ONLY_MARKER: lambda value: None,
-            ArgInfo.NAMED_ONLY: spec.named_only.append,
-            ArgInfo.VAR_NAMED: lambda value: setattr(spec, 'var_named', value),
-        }
+        spec = kw.args
+        positional_only = []
+        positional_or_named = []
+        named_only = []
         for arg in elem.findall('arguments/arg'):
             name_elem = arg.find('name')
             if name_elem is None:
                 continue
             name = name_elem.text
-            setters[arg.get('kind')](name)
+            kind = arg.get('kind')
+            if kind == ArgInfo.POSITIONAL_ONLY:
+                positional_only.append(name)
+            elif kind == ArgInfo.POSITIONAL_OR_NAMED:
+                positional_or_named.append(name)
+            elif kind == ArgInfo.VAR_POSITIONAL:
+                spec.var_positional = name
+            elif kind == ArgInfo.NAMED_ONLY:
+                named_only.append(name)
+            elif kind == ArgInfo.VAR_NAMED:
+                spec.var_named = name
             default_elem = arg.find('default')
             if default_elem is not None:
                 spec.defaults[name] = default_elem.text or ''
@@ -97,20 +103,23 @@ class XmlDocBuilder:
             type_docs = {}
             type_elems = arg.findall('type')
             if len(type_elems) == 1 and 'name' in type_elems[0].attrib:
-                type_info = self._parse_modern_type_info(type_elems[0], type_docs)
+                type_info = self._parse_type_info(type_elems[0], type_docs)
             else:
                 type_info = self._parse_legacy_type_info(type_elems, type_docs)
             if type_info:
                 spec.types[name] = type_info
             kw.type_docs[name] = type_docs
+        spec.positional_only = positional_only
+        spec.positional_or_named = positional_or_named
+        spec.named_only = named_only
 
-    def _parse_modern_type_info(self, type_elem, type_docs):
+    def _parse_type_info(self, type_elem, type_docs):
         name = type_elem.get('name')
         if type_elem.get('typedoc'):
             type_docs[name] = type_elem.get('typedoc')
-        nested = tuple(self._parse_modern_type_info(child, type_docs)
-                       for child in type_elem.findall('type'))
-        return {'name': name, 'nested': nested}
+        nested = [self._parse_type_info(child, type_docs)
+                  for child in type_elem.findall('type')]
+        return TypeInfo(name, None, nested=nested or None)
 
     def _parse_legacy_type_info(self, type_elems, type_docs):
         types = []
@@ -119,7 +128,13 @@ class XmlDocBuilder:
             types.append(name)
             if elem.get('typedoc'):
                 type_docs[name] = elem.get('typedoc')
-        return types
+        return TypeInfo.from_sequence(types) if types else None
+
+    def _add_return_type(self, elem, kw):
+        if elem is not None:
+            type_docs = {}
+            kw.args.return_type = self._parse_type_info(elem, type_docs)
+            kw.type_docs['return'] = type_docs
 
     def _parse_type_docs(self, spec):
         for elem in spec.findall('typedocs/type'):

{robotframework-6.1rc1 → robotframework-7.0}/src/robot/libdocpkg/xmlwriter.py

@@ -14,7 +14,7 @@
 #  limitations under the License.
 
 from robot.running import TypeInfo
-from robot.utils import XmlWriter
+from robot.utils import NOT_SET, XmlWriter
 
 from .output import get_generation_time
 
@@ -26,9 +26,6 @@ class LibdocXmlWriter:
         self._write_start(libdoc, writer)
         self._write_keywords('inits', 'init', libdoc.inits, libdoc.source, writer)
         self._write_keywords('keywords', 'kw', libdoc.keywords, libdoc.source, writer)
-        # Write deprecated '<datatypes>' element.
-        self._write_data_types(libdoc.type_docs, writer)
-        # Write new '<types>' element.
         self._write_type_docs(libdoc.type_docs, writer)
         self._write_end(writer)
 
@@ -38,7 +35,7 @@ class LibdocXmlWriter:
                  'format': libdoc.doc_format,
                  'scope': libdoc.scope,
                  'generated': get_generation_time(),
-                 'specversion': '5'}
+                 'specversion': '6'}
         self._add_source_info(attrs, libdoc)
         writer.start('keywordspec', attrs)
         writer.element('version', libdoc.version)
@@ -57,8 +54,9 @@ class LibdocXmlWriter:
             attrs = self._get_start_attrs(kw, lib_source)
             writer.start(kw_type, attrs)
             self._write_arguments(kw, writer)
+            self._write_return_type(kw, writer)
             writer.element('doc', kw.doc)
-            writer.element('shortdoc', kw.shortdoc)
+            writer.element('shortdoc', kw.short_doc)
             if kw_type == 'kw' and kw.tags:
                 self._write_tags(kw.tags, writer)
             writer.end(kw_type)
@@ -80,24 +78,29 @@ class LibdocXmlWriter:
                 writer.element('name', arg.name)
             if arg.type:
                 self._write_type_info(arg.type, kw.type_docs[arg.name], writer)
-            if arg.default is not arg.NOTSET:
+            if arg.default is not NOT_SET:
                 writer.element('default', arg.default_repr)
             writer.end('arg')
         writer.end('arguments')
 
-    def _write_type_info(self, type_info: TypeInfo, type_docs: dict, writer, top=True):
+    def _write_type_info(self, type_info: TypeInfo, type_docs: dict, writer, element='type'):
         attrs = {'name': type_info.name}
         if type_info.is_union:
             attrs['union'] = 'true'
         if type_info.name in type_docs:
             attrs['typedoc'] = type_docs[type_info.name]
-        # Writing content, and omitting newlines, is backwards compatibility with
-        # specs created using RF < 6.1. TODO: Remove in RF 7.
-        writer.start('type', attrs, newline=False)
-        writer.content(str(type_info))
-        for nested in type_info.nested:
-            self._write_type_info(nested, type_docs, writer, top=False)
-        writer.end('type', newline=top)
+        if type_info.nested:
+            writer.start(element, attrs)
+            for nested in type_info.nested:
+                self._write_type_info(nested, type_docs, writer)
+            writer.end(element)
+        else:
+            writer.element(element, attrs=attrs)
+
+    def _write_return_type(self, kw, writer):
+        if kw.args.return_type:
+            self._write_type_info(kw.args.return_type, kw.type_docs['return'], writer,
+                                  element='returntype')
 
     def _get_start_attrs(self, kw, lib_source):
         attrs = {'name': kw.name}
@@ -108,29 +111,6 @@ class LibdocXmlWriter:
         self._add_source_info(attrs, kw, lib_source)
         return attrs
 
-    # Write legacy 'datatypes'. TODO: Remove in RF 7.
-    def _write_data_types(self, types, writer):
-        enums = sorted(t for t in types if t.type == 'Enum')
-        typed_dicts = sorted(t for t in types if t.type == 'TypedDict')
-        writer.start('datatypes')
-        if enums:
-            writer.start('enums')
-            for enum in enums:
-                writer.start('enum', {'name': enum.name})
-                writer.element('doc', enum.doc)
-                self._write_enum_members(enum, writer)
-                writer.end('enum')
-            writer.end('enums')
-        if typed_dicts:
-            writer.start('typeddicts')
-            for typ_dict in typed_dicts:
-                writer.start('typeddict', {'name': typ_dict.name})
-                writer.element('doc', typ_dict.doc)
-                self._write_typed_dict_items(typ_dict, writer)
-                writer.end('typeddict')
-            writer.end('typeddicts')
-        writer.end('datatypes')
-
     def _write_type_docs(self, type_docs, writer):
         writer.start('typedocs')
         for doc in sorted(type_docs):