busser-robot 0.1.3

data/vendor/robot/src/robot/testdoc.py

@@ -0,0 +1,303 @@
+#!/usr/bin/env python
+
+#  Copyright 2008-2015 Nokia Networks
+#  Copyright 2016-     Robot Framework Foundation
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+
+"""Module implementing the command line entry point for the `Testdoc` tool.
+
+This module can be executed from the command line using the following
+approaches::
+
+    python -m robot.testdoc
+    python path/to/robot/testdoc.py
+
+Instead of ``python`` it is possible to use also other Python interpreters.
+
+This module also provides :func:`testdoc` and :func:`testdoc_cli` functions
+that can be used programmatically. Other code is for internal usage.
+"""
+
+import os.path
+import sys
+import time
+
+# Allows running as a script. __name__ check needed with multiprocessing:
+# https://github.com/robotframework/robotframework/issues/1137
+if 'robot' not in sys.modules and __name__ == '__main__':
+    import pythonpathsetter
+
+from robot.conf import RobotSettings
+from robot.htmldata import HtmlFileWriter, ModelWriter, JsonWriter, TESTDOC
+from robot.parsing import disable_curdir_processing
+from robot.running import TestSuiteBuilder
+from robot.utils import (abspath, Application, file_writer, format_time,
+                         get_link_path, html_escape, html_format, is_string,
+                         secs_to_timestr, seq2str2, timestr_to_secs, unescape,
+                         IRONPYTHON)
+
+
+# http://ironpython.codeplex.com/workitem/31549
+if IRONPYTHON and sys.version_info < (2, 7, 2):
+    int = long
+
+
+USAGE = """robot.testdoc -- Robot Framework test data documentation tool
+
+Version:  <VERSION>
+
+Usage:  python -m robot.testdoc [options] data_sources output_file
+
+Testdoc generates a high level test documentation based on Robot Framework
+test data. Generated documentation includes name, documentation and other
+metadata of each test suite and test case, as well as the top-level keywords
+and their arguments.
+
+Options
+=======
+
+  -T --title title       Set the title of the generated documentation.
+                         Underscores in the title are converted to spaces.
+                         The default title is the name of the top level suite.
+  -N --name name         Override the name of the top level suite.
+  -D --doc document      Override the documentation of the top level suite.
+  -M --metadata name:value *  Set/override metadata of the top level suite.
+  -G --settag tag *      Set given tag(s) to all test cases.
+  -t --test name *       Include tests by name.
+  -s --suite name *      Include suites by name.
+  -i --include tag *     Include tests by tags.
+  -e --exclude tag *     Exclude tests by tags.
+  -A --argumentfile path *  Text file to read more arguments from. Use special
+                          path `STDIN` to read contents from the standard input
+                          stream. File can have both options and data sources
+                          one per line. Contents do not need to be escaped but
+                          spaces in the beginning and end of lines are removed.
+                          Empty lines and lines starting with a hash character
+                          (#) are ignored. New in Robot Framework 3.0.2.
+                          Example file:
+                          |  --name Example
+                          |  # This is a comment line
+                          |  my_tests.robot
+                          |  output.html
+                          Examples:
+                          --argumentfile argfile.txt --argumentfile STDIN
+  -h -? --help           Print this help.
+
+All options except --title have exactly same semantics as same options have
+when executing test cases.
+
+Execution
+=========
+
+Data can be given as a single file, directory, or as multiple files and
+directories. In all these cases, the last argument must be the file where
+to write the output. The output is always created in HTML format.
+
+Testdoc works with all interpreters supported by Robot Framework (Python,
+Jython and IronPython). It can be executed as an installed module like
+`python -m robot.testdoc` or as a script like `python path/robot/testdoc.py`.
+
+Examples:
+
+  python -m robot.testdoc my_test.html testdoc.html
+  jython -m robot.testdoc -N smoke_tests -i smoke path/to/my_tests smoke.html
+  ipy path/to/robot/testdoc.py first_suite.txt second_suite.txt output.html
+
+For more information about Testdoc and other built-in tools, see
+http://robotframework.org/robotframework/#built-in-tools.
+"""
+
+
+class TestDoc(Application):
+
+    def __init__(self):
+        Application.__init__(self, USAGE, arg_limits=(2,))
+
+    def main(self, datasources, title=None, **options):
+        outfile = abspath(datasources.pop())
+        suite = TestSuiteFactory(datasources, **options)
+        self._write_test_doc(suite, outfile, title)
+        self.console(outfile)
+
+    def _write_test_doc(self, suite, outfile, title):
+        with file_writer(outfile) as output:
+            model_writer = TestdocModelWriter(output, suite, title)
+            HtmlFileWriter(output, model_writer).write(TESTDOC)
+
+
+@disable_curdir_processing
+def TestSuiteFactory(datasources, **options):
+    settings = RobotSettings(options)
+    if is_string(datasources):
+        datasources = [datasources]
+    suite = TestSuiteBuilder().build(*datasources)
+    suite.configure(**settings.suite_config)
+    return suite
+
+
+class TestdocModelWriter(ModelWriter):
+
+    def __init__(self, output, suite, title=None):
+        self._output = output
+        self._output_path = getattr(output, 'name', None)
+        self._suite = suite
+        self._title = title.replace('_', ' ') if title else suite.name
+
+    def write(self, line):
+        self._output.write('<script type="text/javascript">\n')
+        self.write_data()
+        self._output.write('</script>\n')
+
+    def write_data(self):
+        model = {
+            'suite': JsonConverter(self._output_path).convert(self._suite),
+            'title': self._title,
+            'generated': int(time.time() * 1000)
+        }
+        JsonWriter(self._output).write_json('testdoc = ', model)
+
+
+class JsonConverter(object):
+
+    def __init__(self, output_path=None):
+        self._output_path = output_path
+
+    def convert(self, suite):
+        return self._convert_suite(suite)
+
+    def _convert_suite(self, suite):
+        return {
+            'source': suite.source or '',
+            'relativeSource': self._get_relative_source(suite.source),
+            'id': suite.id,
+            'name': self._escape(suite.name),
+            'fullName': self._escape(suite.longname),
+            'doc': self._html(suite.doc),
+            'metadata': [(self._escape(name), self._html(value))
+                         for name, value in suite.metadata.items()],
+            'numberOfTests': suite.test_count   ,
+            'suites': self._convert_suites(suite),
+            'tests': self._convert_tests(suite),
+            'keywords': list(self._convert_keywords(suite))
+        }
+
+    def _get_relative_source(self, source):
+        if not source or not self._output_path:
+            return ''
+        return get_link_path(source, os.path.dirname(self._output_path))
+
+    def _escape(self, item):
+        return html_escape(item)
+
+    def _html(self, item):
+        return html_format(unescape(item))
+
+    def _convert_suites(self, suite):
+        return [self._convert_suite(s) for s in suite.suites]
+
+    def _convert_tests(self, suite):
+        return [self._convert_test(t) for t in suite.tests]
+
+    def _convert_test(self, test):
+        return {
+            'name': self._escape(test.name),
+            'fullName': self._escape(test.longname),
+            'id': test.id,
+            'doc': self._html(test.doc),
+            'tags': [self._escape(t) for t in test.tags],
+            'timeout': self._get_timeout(test.timeout),
+            'keywords': list(self._convert_keywords(test))
+        }
+
+    def _convert_keywords(self, item):
+        for kw in getattr(item, 'keywords', []):
+            if kw.type == kw.SETUP_TYPE:
+                yield self._convert_keyword(kw, 'SETUP')
+            elif kw.type == kw.TEARDOWN_TYPE:
+                yield self._convert_keyword(kw, 'TEARDOWN')
+            elif kw.type == kw.FOR_LOOP_TYPE:
+                yield self._convert_for_loop(kw)
+            else:
+                yield self._convert_keyword(kw, 'KEYWORD')
+
+    def _convert_for_loop(self, kw):
+        return {
+            'name': self._escape(self._get_for_loop(kw)),
+            'arguments': '',
+            'type': 'FOR'
+        }
+
+    def _convert_keyword(self, kw, kw_type):
+        return {
+            'name': self._escape(self._get_kw_name(kw)),
+            'arguments': self._escape(', '.join(kw.args)),
+            'type': kw_type
+        }
+
+    def _get_kw_name(self, kw):
+        if kw.assign:
+            return '%s = %s' % (', '.join(a.rstrip('= ') for a in kw.assign), kw.name)
+        return kw.name
+
+    def _get_for_loop(self, kw):
+        joiner = ' %s ' % kw.flavor
+        return ', '.join(kw.variables) + joiner + seq2str2(kw.values)
+
+    def _get_timeout(self, timeout):
+        if timeout is None:
+            return ''
+        try:
+            tout = secs_to_timestr(timestr_to_secs(timeout.value))
+        except ValueError:
+            tout = timeout.value
+        if timeout.message:
+            tout += ' :: ' + timeout.message
+        return tout
+
+
+def testdoc_cli(arguments):
+    """Executes `Testdoc` similarly as from the command line.
+
+    :param arguments: command line arguments as a list of strings.
+
+    For programmatic usage the :func:`testdoc` function is typically better. It
+    has a better API for that and does not call :func:`sys.exit` like
+    this function.
+
+    Example::
+
+        from robot.testdoc import testdoc_cli
+
+        testdoc_cli(['--title', 'Test Plan', 'mytests', 'plan.html'])
+    """
+    TestDoc().execute_cli(arguments)
+
+
+def testdoc(*arguments, **options):
+    """Executes `Testdoc` programmatically.
+
+    Arguments and options have same semantics, and options have same names,
+    as arguments and options to Testdoc.
+
+    Example::
+
+        from robot.testdoc import testdoc
+
+        testdoc('mytests', 'plan.html', title='Test Plan')
+    """
+    TestDoc().execute(*arguments, **options)
+
+
+if __name__ == '__main__':
+    testdoc_cli(sys.argv[1:])

data/vendor/robot/src/robot/tidy.py

@@ -0,0 +1,330 @@
+#!/usr/bin/env python
+
+#  Copyright 2008-2015 Nokia Networks
+#  Copyright 2016-     Robot Framework Foundation
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+
+"""Module implementing the command line entry point for the `Tidy` tool.
+
+This module can be executed from the command line using the following
+approaches::
+
+    python -m robot.tidy
+    python path/to/robot/tidy.py
+
+Instead of ``python`` it is possible to use also other Python interpreters.
+
+This module also provides :class:`Tidy` class and :func:`tidy_cli` function
+that can be used programmatically. Other code is for internal usage.
+"""
+
+import os
+import sys
+
+# Allows running as a script. __name__ check needed with multiprocessing:
+# https://github.com/robotframework/robotframework/issues/1137
+if 'robot' not in sys.modules and __name__ == '__main__':
+    import pythonpathsetter
+
+from robot.errors import DataError
+from robot.parsing import (ResourceFile, TestDataDirectory, TestCaseFile,
+                           disable_curdir_processing)
+from robot.utils import Application, binary_file_writer, file_writer, PY2
+
+
+USAGE = """robot.tidy -- Robot Framework test data clean-up tool
+
+Version:  <VERSION>
+
+Usage:  python -m robot.tidy [options] inputfile
+   or:  python -m robot.tidy [options] inputfile [outputfile]
+   or:  python -m robot.tidy --inplace [options] inputfile [more input files]
+   or:  python -m robot.tidy --recursive [options] directory
+
+Tidy tool can be used to clean up and change format of Robot Framework test
+data files. The output is written into the standard output stream by default,
+but an optional output file can be given starting from Robot Framework 2.7.5.
+Files can also be modified in-place using --inplace or --recursive options.
+
+Options
+=======
+
+ -i --inplace    Tidy given file(s) so that original file(s) are overwritten
+                 (or removed, if the format is changed). When this option is
+                 used, it is possible to give multiple input files.
+                 Examples:
+                   python -m robot.tidy --inplace tests.html
+                   python -m robot.tidy --inplace --format txt *.html
+ -r --recursive  Process given directory recursively. Files in the directory
+                 are processed in-place similarly as when --inplace option
+                 is used.
+ -f --format txt|html|tsv|robot
+                 Output file format. If omitted, the format of the input
+                 file is used.
+ -p --usepipes   Use pipe (`|`) as a cell separator in the txt format.
+ -s --spacecount number
+                 The number of spaces between cells in the txt format.
+                 New in Robot Framework 2.7.3.
+ -l --lineseparator native|windows|unix
+                 Line separator to use in outputs. The default is 'native'.
+                 native:  use operating system's native line separators
+                 windows: use Windows line separators (CRLF)
+                 unix:    use Unix line separators (LF)
+                 New in Robot Framework 2.7.6.
+ -h -? --help    Show this help.
+
+Cleaning up the test data
+=========================
+
+Test case files created with HTML editors or written by hand can be normalized
+using Tidy. Tidy always writes consistent headers, consistent order for
+settings, and consistent amount of whitespace between cells and tables.
+
+Examples:
+  python -m robot.tidy messed_up_tests.html cleaned_tests.html
+  python -m robot.tidy --inplace tests.txt
+
+Changing the test data format
+=============================
+
+Robot Framework supports test data in HTML, TSV and TXT formats, and Tidy
+makes changing between the formats trivial. Input format is always determined
+based on the extension of the input file. Output format is got from the
+extension of the output file, when used, and can also be set using the --format
+option.
+
+Examples:
+  python -m robot.tidy tests.html tests.tsv
+  python -m robot.tidy --format tsv --inplace tests.html
+  python -m robot.tidy --format txt --recursive mytests
+
+Output encoding
+===============
+
+All output files are written using UTF-8 encoding. Outputs written to the
+console use the current console encoding.
+
+Alternative execution
+=====================
+
+In the above examples Tidy is used only with Python, but it works also with
+Jython and IronPython. Above it is executed as an installed module, but it
+can also be run as a script like `python path/robot/tidy.py`.
+
+For more information about Tidy and other built-in tools, see
+http://robotframework.org/robotframework/#built-in-tools.
+"""
+
+
+class Tidy(object):
+    """Programmatic API for the `Tidy` tool.
+
+    Arguments accepted when creating an instance have same semantics as
+    Tidy command line options with same names.
+    """
+
+    def __init__(self, format='txt', use_pipes=False,
+                 space_count=4, line_separator=os.linesep):
+        self._options = dict(format=format,
+                             pipe_separated=use_pipes,
+                             txt_separating_spaces=space_count,
+                             line_separator=line_separator)
+
+    def file(self, path, output=None):
+        """Tidy a file.
+
+        :param path: Path of the input file.
+        :param output: Path of the output file. If not given, output is
+            returned.
+
+        Use :func:`inplace` to tidy files in-place.
+        """
+        data = self._parse_data(path)
+        with self._get_writer(path, output) as writer:
+            self._save_file(data, writer)
+            if not output:
+                return writer.getvalue().replace('\r\n', '\n')
+
+    def _get_writer(self, inpath, outpath):
+        if PY2 and self._is_tsv(inpath):
+            return binary_file_writer(outpath)
+        return file_writer(outpath, newline=self._options['line_separator'])
+
+    def _is_tsv(self, path):
+        format = self._options['format'] or os.path.splitext(path)[1][1:]
+        return format.upper() == 'TSV'
+
+    def inplace(self, *paths):
+        """Tidy file(s) in-place.
+
+        :param paths: Paths of the files to to process.
+        """
+        for path in paths:
+            self._save_file(self._parse_data(path))
+
+    def directory(self, path):
+        """Tidy a directory.
+
+        :param path: Path of the directory to process.
+
+        All files in a directory, recursively, are processed in-place.
+        """
+        self._save_directory(self._parse_data(path))
+
+    @disable_curdir_processing
+    def _parse_data(self, path):
+        if os.path.isdir(path):
+            return TestDataDirectory(source=path).populate()
+        if self._is_init_file(path):
+            path = os.path.dirname(path)
+            return TestDataDirectory(source=path).populate(recurse=False)
+        try:
+            return TestCaseFile(source=path).populate()
+        except DataError:
+            try:
+                return ResourceFile(source=path).populate()
+            except DataError:
+                raise DataError("Invalid data source '%s'." % path)
+
+    def _is_init_file(self, path):
+        return os.path.splitext(os.path.basename(path))[0].lower() == '__init__'
+
+    def _save_file(self, data, output=None):
+        source = data.initfile if self._is_directory(data) else data.source
+        if source and not output:
+            os.remove(source)
+        data.save(output=output, **self._options)
+
+    def _save_directory(self, data):
+        if not self._is_directory(data):
+            self._save_file(data)
+            return
+        if data.initfile:
+            self._save_file(data)
+        for child in data.children:
+            self._save_directory(child)
+
+    def _is_directory(self, data):
+        return hasattr(data, 'initfile')
+
+
+class TidyCommandLine(Application):
+    """Command line interface for the `Tidy` tool.
+
+    Typically :func:`tidy_cli` is a better suited for command line style
+    usage and :class:`Tidy` for other programmatic usage.
+    """
+
+    def __init__(self):
+        Application.__init__(self, USAGE, arg_limits=(1,))
+
+    def main(self, arguments, recursive=False, inplace=False, format='txt',
+             usepipes=False, spacecount=4, lineseparator=os.linesep):
+        tidy = Tidy(format=format, use_pipes=usepipes,
+                    space_count=spacecount, line_separator=lineseparator)
+        if recursive:
+            tidy.directory(arguments[0])
+        elif inplace:
+            tidy.inplace(*arguments)
+        else:
+            output = tidy.file(*arguments)
+            self.console(output)
+
+    def validate(self, opts, args):
+        validator = ArgumentValidator()
+        opts['recursive'], opts['inplace'] \
+            = validator.mode_and_arguments(args, **opts)
+        opts['format'] = validator.format(args, **opts)
+        opts['lineseparator'] = validator.line_sep(**opts)
+        if not opts['spacecount']:
+            opts.pop('spacecount')
+        else:
+            opts['spacecount'] = validator.spacecount(opts['spacecount'])
+        return opts, args
+
+
+class ArgumentValidator(object):
+
+    def mode_and_arguments(self, args, recursive, inplace, **others):
+        recursive, inplace = bool(recursive), bool(inplace)
+        validators = {(True, True): self._recursive_and_inplace_together,
+                      (True, False): self._recursive_mode_arguments,
+                      (False, True): self._inplace_mode_arguments,
+                      (False, False): self._default_mode_arguments}
+        validator = validators[(recursive, inplace)]
+        validator(args)
+        return recursive, inplace
+
+    def _recursive_and_inplace_together(self, args):
+        raise DataError('--recursive and --inplace can not be used together.')
+
+    def _recursive_mode_arguments(self, args):
+        if len(args) != 1:
+            raise DataError('--recursive requires exactly one argument.')
+        if not os.path.isdir(args[0]):
+            raise DataError('--recursive requires input to be a directory.')
+
+    def _inplace_mode_arguments(self, args):
+        if not all(os.path.isfile(path) for path in args):
+            raise DataError('--inplace requires inputs to be files.')
+
+    def _default_mode_arguments(self, args):
+        if len(args) not in (1, 2):
+            raise DataError('Default mode requires 1 or 2 arguments.')
+        if not os.path.isfile(args[0]):
+            raise DataError('Default mode requires input to be a file.')
+
+    def format(self, args, format, inplace, recursive, **others):
+        if not format:
+            if inplace or recursive or len(args) < 2:
+                return None
+            format = os.path.splitext(args[1])[1][1:]
+        format = format.upper()
+        if format not in ('TXT', 'TSV', 'HTML', 'ROBOT'):
+            raise DataError("Invalid format '%s'." % format)
+        return format
+
+    def line_sep(self, lineseparator, **others):
+        values = {'native': os.linesep, 'windows': '\r\n', 'unix': '\n'}
+        try:
+            return values[(lineseparator or 'native').lower()]
+        except KeyError:
+            raise DataError("Invalid line separator '%s'." % lineseparator)
+
+    def spacecount(self, spacecount):
+        try:
+            spacecount = int(spacecount)
+            if spacecount < 2:
+                raise ValueError
+        except ValueError:
+            raise DataError('--spacecount must be an integer greater than 1.')
+        return spacecount
+
+
+def tidy_cli(arguments):
+    """Executes `Tidy` similarly as from the command line.
+
+    :param arguments: Command line arguments as a list of strings.
+
+    Example::
+
+        from robot.tidy import tidy_cli
+
+        tidy_cli(['--format', 'txt', 'tests.html'])
+    """
+    TidyCommandLine().execute_cli(arguments)
+
+
+if __name__ == '__main__':
+    tidy_cli(sys.argv[1:])