Make docstrings more consistent using format-webkitpy.

third_party/WebKit/Tools/Scripts/webkitpy/layout_tests/port/base.py

 # Copyright (C) 2010 Google Inc. All rights reserved.
 #
 # Redistribution and use in source and binary forms, with or without
 # modification, are permitted provided that the following conditions are
 # met:
 #
 #     * Redistributions of source code must retain the above copyright
 # notice, this list of conditions and the following disclaimer.
 #     * Redistributions in binary form must reproduce the above
 # copyright notice, this list of conditions and the following disclaimer
 # in the documentation and/or other materials provided with the
 # distribution.
 #     * Neither the Google name nor the names of its
 # contributors may be used to endorse or promote products derived from
 # this software without specific prior written permission.
 #
 # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 # "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 # LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
 # A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
 # OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 # SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 # LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 # DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 # THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 # (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
 """Abstract base class of Port-specific entry points for the layout tests
-test infrastructure (the Port and Driver classes)."""
+test infrastructure (the Port and Driver classes).
+"""
 
 import collections
 import cgi
 import difflib
 import errno
 import itertools
 import json
 import logging
 import os
 import operator
@@ skipping 259 matching lines @@
         return [self._filesystem.join(path, suite.name) for path in self.default_baseline_search_path()]
 
     def baseline_search_path(self):
         return (self.get_option('additional_platform_directory', []) +
                 self._flag_specific_baseline_search_path() +
                 self._compare_baseline() +
                 self.default_baseline_search_path())
 
     def default_baseline_search_path(self):
         """Return a list of absolute paths to directories to search under for
-        baselines. The directories are searched in order."""
+        baselines. The directories are searched in order.
+        """
         return map(self._webkit_baseline_path, self.FALLBACK_PATHS[self.version()])
 
     @memoized
     def _compare_baseline(self):
         factory = PortFactory(self.host)
         target_port = self.get_option('compare_port')
         if target_port:
             return factory.get(target_port).default_baseline_search_path()
         return []
 
@@ skipping 206 matching lines @@
                 err_str = "Image diff returned an exit code of %s. See http://crbug.com/278596" % exit_code
         except OSError as e:
             err_str = 'error running image diff: %s' % str(e)
         finally:
             self._filesystem.rmtree(str(tempdir))
 
         return (result, err_str or None)
 
     def diff_text(self, expected_text, actual_text, expected_filename, actual_filename):
         """Returns a string containing the diff of the two text strings
-        in 'unified diff' format."""
+        in 'unified diff' format.
+        """
 
         # The filenames show up in the diff output, make sure they're
         # raw bytes and not unicode, so that they don't trigger join()
         # trying to decode the input.
         def to_raw_bytes(string_value):
             if isinstance(string_value, unicode):
                 return string_value.encode('utf-8')
             return string_value
         expected_filename = to_raw_bytes(expected_filename)
         actual_filename = to_raw_bytes(actual_filename)
@@ skipping 13 matching lines @@
 
         return ''.join(diff_fixup(diff))
 
     def driver_name(self):
         if self.get_option('driver_name'):
             return self.get_option('driver_name')
         return self.CONTENT_SHELL_NAME
 
     def expected_baselines_by_extension(self, test_name):
         """Returns a dict mapping baseline suffix to relative path for each baseline in
-        a test. For reftests, it returns ".==" or ".!=" instead of the suffix."""
+        a test. For reftests, it returns ".==" or ".!=" instead of the suffix.
+        """
         # FIXME: The name similarity between this and expected_baselines() below, is unfortunate.
         # We should probably rename them both.
         baseline_dict = {}
         reference_files = self.reference_files(test_name)
         if reference_files:
             # FIXME: How should this handle more than one type of reftest?
             baseline_dict['.' + reference_files[0][0]] = self.relative_test_filename(reference_files[0][1])
 
         for extension in self.baseline_extensions():
             path = self.expected_filename(test_name, extension, return_default=False)
@@ skipping 107 matching lines @@
 
     def expected_audio(self, test_name):
         baseline_path = self.expected_filename(test_name, '.wav')
         if not self._filesystem.exists(baseline_path):
             return None
         return self._filesystem.read_binary_file(baseline_path)
 
     def expected_text(self, test_name):
         """Returns the text output we expect the test to produce, or None
         if we don't expect there to be any text output.
-        End-of-line characters are normalized to '\n'."""
+        End-of-line characters are normalized to '\n'.
+        """
         # FIXME: DRT output is actually utf-8, but since we don't decode the
         # output from DRT (instead treating it as a binary string), we read the
         # baselines as a binary string, too.
         baseline_path = self.expected_filename(test_name, '.txt')
         if not self._filesystem.exists(baseline_path):
             return None
         text = self._filesystem.read_binary_file(baseline_path)
         return text.replace("\r\n", "\n")
 
     def _get_reftest_list(self, test_name):
@@ skipping 250 matching lines @@
             if self._filesystem.isdir(category) and test_name.startswith(test_or_category):
                 return True
         return False
 
     def is_chromium(self):
         return True
 
     def name(self):
         """Returns a name that uniquely identifies this particular type of port
         (e.g., "mac-snowleopard" or "linux-trusty" and can be passed
-        to factory.get() to instantiate the port."""
+        to factory.get() to instantiate the port.
+        """
         return self._name
 
     def operating_system(self):
         # Subclasses should override this default implementation.
         return 'mac'
 
     def version(self):
         """Returns a string indicating the version of a given platform, e.g.
         'leopard' or 'win7'.
 
         This is used to help identify the exact port when parsing test
-        expectations, determining search paths, and logging information."""
+        expectations, determining search paths, and logging information.
+        """
         return self._version
 
     def architecture(self):
         return self._architecture
 
     def get_option(self, name, default_value=None):
         return getattr(self._options, name, default_value)
 
     def set_option_default(self, name, default_value):
         return self._options.ensure_value(name, default_value)
 
     @memoized
     def path_to_generic_test_expectations_file(self):
         return self._filesystem.join(self.layout_tests_dir(), 'TestExpectations')
 
     def relative_test_filename(self, filename):
         """Returns a test_name a relative unix-style path for a filename under the LayoutTests
-        directory. Ports may legitimately return abspaths here if no relpath makes sense."""
+        directory. Ports may legitimately return abspaths here if no relpath makes sense.
+        """
         # Ports that run on windows need to override this method to deal with
         # filenames with backslashes in them.
         if filename.startswith(self.layout_tests_dir()):
             return self.host.filesystem.relpath(filename, self.layout_tests_dir())
         else:
             return self.host.filesystem.abspath(filename)
 
     @memoized
     def abspath_for_test(self, test_name):
         """Returns the full path to the file for a given test name. This is the
-        inverse of relative_test_filename()."""
+        inverse of relative_test_filename().
+        """
         return self._filesystem.join(self.layout_tests_dir(), test_name)
 
     def results_directory(self):
         """Absolute path to the place to store the test results (uses --results-directory)."""
         if not self._results_directory:
             option_val = self.get_option('results_directory') or self.default_results_directory()
             self._results_directory = self._filesystem.abspath(option_val)
         return self._results_directory
 
     def bot_test_times_path(self):
@@ skipping 82 matching lines @@
                 clean_env[variable] = self.host.environ[variable]
 
         for string_variable in self.get_option('additional_env_var', []):
             [name, value] = string_variable.split('=', 1)
             clean_env[name] = value
 
         return clean_env
 
     def show_results_html_file(self, results_filename):
         """This routine should display the HTML file pointed at by
-        results_filename in a users' browser."""
+        results_filename in a users' browser.
+        """
         return self.host.user.open_url(abspath_to_uri(self.host.platform, results_filename))
 
     def create_driver(self, worker_number, no_timeout=False):
         """Return a newly created Driver subclass for starting/stopping the test driver."""
         return self._driver_class()(self, worker_number, pixel_tests=self.get_option('pixel_tests'), no_timeout=no_timeout)
 
     def start_helper(self):
         """If a port needs to reconfigure graphics settings or do other
         things to ensure a known test configuration, it should override this
-        method."""
+        method.
+        """
         helper_path = self._path_to_helper()
         if helper_path:
             _log.debug("Starting layout helper %s", helper_path)
             # Note: Not thread safe: http://bugs.python.org/issue2320
             self._helper = self._executive.popen([helper_path],
                                                  stdin=self._executive.PIPE, stdout=self._executive.PIPE, stderr=None)
             is_ready = self._helper.stdout.readline()
             if not is_ready.startswith('ready'):
                 _log.error("layout_test_helper failed to be ready")
 
     def requires_http_server(self):
         """Does the port require an HTTP server for running tests? This could
-        be the case when the tests aren't run on the host platform."""
+        be the case when the tests aren't run on the host platform.
+        """
         return False
 
     def start_http_server(self, additional_dirs, number_of_drivers):
         """Start a web server. Raise an error if it can't start or is already running.
 
-        Ports can stub this out if they don't need a web server to be running."""
+        Ports can stub this out if they don't need a web server to be running.
+        """
         assert not self._http_server, 'Already running an http server.'
 
         server = apache_http.ApacheHTTP(self, self.results_directory(),
                                         additional_dirs=additional_dirs,
                                         number_of_servers=(number_of_drivers * 4))
         server.start()
         self._http_server = server
 
     def start_websocket_server(self):
         """Start a web server. Raise an error if it can't start or is already running.
 
-        Ports can stub this out if they don't need a websocket server to be running."""
+        Ports can stub this out if they don't need a websocket server to be running.
+        """
         assert not self._websocket_server, 'Already running a websocket server.'
 
         server = pywebsocket.PyWebSocket(self, self.results_directory())
         server.start()
         self._websocket_server = server
 
     def is_wptserve_enabled(self):
         """Used as feature flag for WPT Serve feature."""
         return self._is_wptserve_enabled
 
     @staticmethod
     def is_wptserve_test(test):
         """Whether wptserve should be used for a given test if enabled."""
         return test.startswith("imported/wpt/")
 
     def should_use_wptserve(self, test):
         return self.is_wptserve_enabled() and self.is_wptserve_test(test)
 
     def start_wptserve(self):
         """Start a WPT web server. Raise an error if it can't start or is already running.
 
-        Ports can stub this out if they don't need a WPT web server to be running."""
+        Ports can stub this out if they don't need a WPT web server to be running.
+        """
         assert not self._wpt_server, 'Already running an http server.'
         assert self.is_wptserve_enabled(), 'Cannot start server if WPT is not enabled.'
 
         # We currently don't support any output mechanism for the WPT server.
         server = wptserve.WPTServe(self, self.results_directory())
         server.start()
         self._wpt_server = server
 
     def stop_wptserve(self):
         """Shut down the WPT server if it is running. Do nothing if it isn't."""
         if self._wpt_server:
             self._wpt_server.stop()
             self._wpt_server = None
 
     def http_server_supports_ipv6(self):
         # Apache < 2.4 on win32 does not support IPv6, nor does cygwin apache.
         if self.host.platform.is_cygwin() or self.host.platform.is_win():
             return False
         return True
 
     def stop_helper(self):
         """Shut down the test helper if it is running. Do nothing if
         it isn't, or it isn't available. If a port overrides start_helper()
-        it must override this routine as well."""
+        it must override this routine as well.
+        """
         if self._helper:
             _log.debug("Stopping layout test helper")
             try:
                 self._helper.stdin.write("x\n")
                 self._helper.stdin.close()
                 self._helper.wait()
             except IOError:
                 pass
             finally:
                 self._helper = None
@@ skipping 17 matching lines @@
     def test_configuration(self):
         """Returns the current TestConfiguration for the port."""
         if not self._test_configuration:
             self._test_configuration = TestConfiguration(self._version, self._architecture, self._options.configuration.lower())
         return self._test_configuration
 
     # FIXME: Belongs on a Platform object.
     @memoized
     def all_test_configurations(self):
         """Returns a list of TestConfiguration instances, representing all available
-        test configurations for this port."""
+        test configurations for this port.
+        """
         return self._generate_all_test_configurations()
 
     # FIXME: Belongs on a Platform object.
     def configuration_specifier_macros(self):
         """Ports may provide a way to abbreviate configuration specifiers to conveniently
         refer to them as one term or alias specific values to more generic ones. For example:
 
         (vista, win7) -> win # Abbreviate all Windows versions into one namesake.
         (precise, trusty) -> linux  # Change specific name of Linux distro to a more generic term.
 
         Returns a dictionary, each key representing a macro term ('win', for example),
-        and value being a list of valid configuration specifiers (such as ['vista', 'win7'])."""
+        and value being a list of valid configuration specifiers (such as ['vista', 'win7']).
+        """
         return self.CONFIGURATION_SPECIFIER_MACROS
 
     def _generate_all_test_configurations(self):
         """Returns a sequence of the TestConfigurations the port supports."""
         # By default, we assume we want to test every graphics type in
         # every configuration on every system.
         test_configurations = []
         for version, architecture in self.ALL_SYSTEMS:
             for build_type in self.ALL_BUILD_TYPES:
                 test_configurations.append(TestConfiguration(version, architecture, build_type))
@@ skipping 11 matching lines @@
         return [self._filesystem.join(self.layout_tests_dir(), 'flag-specific', flag.lstrip('-'))
                 for flag in self.get_option('additional_driver_flag', [])]
 
     def expectations_dict(self):
         """Returns an OrderedDict of name -> expectations strings.
         The names are expected to be (but not required to be) paths in the filesystem.
         If the name is a path, the file can be considered updatable for things like rebaselining,
         so don't use names that are paths if they're not paths.
         Generally speaking the ordering should be files in the filesystem in cascade order
         (TestExpectations followed by Skipped, if the port honors both formats),
-        then any built-in expectations (e.g., from compile-time exclusions), then --additional-expectations options."""
+        then any built-in expectations (e.g., from compile-time exclusions), then --additional-expectations options.
+        """
         # FIXME: rename this to test_expectations() once all the callers are updated to know about the ordered dict.
         expectations = collections.OrderedDict()
 
         for path in self.expectations_files():
             if self._filesystem.exists(path):
                 expectations[path] = self._filesystem.read_text_file(path)
 
         for path in self.get_option('additional_expectations', []):
             expanded_path = self._filesystem.expanduser(path)
             if self._filesystem.exists(expanded_path):
@@ skipping 66 matching lines @@
                 expected_filename]
 
     @staticmethod
     def _handle_wdiff_error(script_error):
         # Exit 1 means the files differed, any other exit code is an error.
         if script_error.exit_code != 1:
             raise script_error
 
     def _run_wdiff(self, actual_filename, expected_filename):
         """Runs wdiff and may throw exceptions.
-        This is mostly a hook for unit testing."""
+        This is mostly a hook for unit testing.
+        """
         # Diffs are treated as binary as they may include multiple files
         # with conflicting encodings.  Thus we do not decode the output.
         command = self._wdiff_command(actual_filename, expected_filename)
         wdiff = self._executive.run_command(command, decode_output=False,
                                             error_handler=self._handle_wdiff_error)
         return self._format_wdiff_output_as_html(wdiff)
 
     _wdiff_error_html = "Failed to run wdiff, see error log."
 
     def wdiff_text(self, actual_filename, expected_filename):
         """Returns a string of HTML indicating the word-level diff of the
         contents of the two filenames. Returns an empty string if word-level
-        diffing isn't available."""
+        diffing isn't available.
+        """
         if not self.wdiff_available():
             return ""
         try:
             # It's possible to raise a ScriptError we pass wdiff invalid paths.
             return self._run_wdiff(actual_filename, expected_filename)
         except OSError as e:
             if e.errno in [errno.ENOENT, errno.EACCES, errno.ECHILD]:
                 # Silently ignore cases where wdiff is missing.
                 self._wdiff_available = False
                 return ""
@@ skipping 43 matching lines @@
         This is needed only by ports that use the apache_http_server module.
         """
         raise NotImplementedError('Port.path_to_apache')
 
     def path_to_apache_config_file(self):
         """Returns the full path to the apache configuration file.
 
         If the WEBKIT_HTTP_SERVER_CONF_PATH environment variable is set, its
         contents will be used instead.
 
-        This is needed only by ports that use the apache_http_server module."""
+        This is needed only by ports that use the apache_http_server module.
+        """
         config_file_from_env = self.host.environ.get('WEBKIT_HTTP_SERVER_CONF_PATH')
         if config_file_from_env:
             if not self._filesystem.exists(config_file_from_env):
                 raise IOError('%s was not found on the system' % config_file_from_env)
             return config_file_from_env
 
         config_file_name = self._apache_config_file_name_for_platform()
         return self._filesystem.join(self.layout_tests_dir(), 'http', 'conf', config_file_name)
 
     #
@@ skipping 25 matching lines @@
 
     def _path_to_webcore_library(self):
         """Returns the full path to a built copy of WebCore."""
         return None
 
     def _path_to_helper(self):
         """Returns the full path to the layout_test_helper binary, which
         is used to help configure the system for the test run, or None
         if no helper is needed.
 
-        This is likely only used by start/stop_helper()."""
+        This is likely only used by start/stop_helper().
+        """
         return None
 
     def _path_to_image_diff(self):
         """Returns the full path to the image_diff binary, or None if it is not available.
 
-        This is likely used only by diff_image()"""
+        This is likely used only by diff_image()
+        """
         return self._build_path('image_diff')
 
     @memoized
     def _path_to_wdiff(self):
         """Returns the full path to the wdiff binary, or None if it is not available.
 
-        This is likely used only by wdiff_text()"""
+        This is likely used only by wdiff_text()
+        """
         for path in ("/usr/bin/wdiff", "/usr/bin/dwdiff"):
             if self._filesystem.exists(path):
                 return path
         return None
 
     def _webkit_baseline_path(self, platform):
         """Return the  full path to the top of the baseline tree for a
-        given platform."""
+        given platform.
+        """
         return self._filesystem.join(self.layout_tests_dir(), 'platform', platform)
 
     def _driver_class(self):
         """Returns the port's driver implementation."""
         return driver.Driver
 
     def output_contains_sanitizer_messages(self, output):
         if not output:
             return None
         if 'AddressSanitizer' in output:
@@ skipping 262 matching lines @@
 
     def __init__(self, base, args, reference_args=None):
         self.name = base
         self.base = base
         self.args = args
         self.reference_args = args if reference_args is None else reference_args
         self.tests = set()
 
     def __repr__(self):
         return "PhysicalTestSuite('%s', '%s', %s, %s)" % (self.name, self.base, self.args, self.reference_args)