path: root/venv/lib/python3.8/site-packages/plotly/io/_orca.py

import atexit
import functools
import json
import os
import random
import socket
import subprocess
import sys
import threading
import time
import warnings
from contextlib import contextmanager
from copy import copy
from pathlib import Path
from shutil import which

import plotly
from plotly.files import PLOTLY_DIR, ensure_writable_plotly_dir
from plotly.io._utils import validate_coerce_fig_to_dict
from plotly.optional_imports import get_module

psutil = get_module("psutil")

# Valid image format constants
# ----------------------------
valid_formats = ("png", "jpeg", "webp", "svg", "pdf", "eps")
format_conversions = {fmt: fmt for fmt in valid_formats}
format_conversions.update({"jpg": "jpeg"})


# Utility functions
# -----------------
def raise_format_value_error(val):
    raise ValueError(
        """
Invalid value of type {typ} receive as an image format specification.
    Received value: {v}

An image format must be specified as one of the following string values:
    {valid_formats}""".format(
            typ=type(val), v=val, valid_formats=sorted(format_conversions.keys())
        )
    )


def validate_coerce_format(fmt):
    """
    Validate / coerce a user specified image format, and raise an informative
    exception if format is invalid.

    Parameters
    ----------
    fmt
        A value that may or may not be a valid image format string.

    Returns
    -------
    str or None
        A valid image format string as supported by orca. This may not
        be identical to the input image designation. For example,
        the resulting string will always be lower case and  'jpg' is
        converted to 'jpeg'.

        If the input format value is None, then no exception is raised and
        None is returned.

    Raises
    ------
    ValueError
        if the input `fmt` cannot be interpreted as a valid image format.
    """

    # Let None pass through
    if fmt is None:
        return None

    # Check format type
    if not isinstance(fmt, str) or not fmt:
        raise_format_value_error(fmt)

    # Make lower case
    fmt = fmt.lower()

    # Remove leading period, if any.
    # For example '.png' is accepted and converted to 'png'
    if fmt[0] == ".":
        fmt = fmt[1:]

    # Check string value
    if fmt not in format_conversions:
        raise_format_value_error(fmt)

    # Return converted string specification
    return format_conversions[fmt]


def find_open_port():
    """
    Use the socket module to find an open port.

    Returns
    -------
    int
        An open port
    """
    s = socket.socket()
    s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
    s.bind(("", 0))
    _, port = s.getsockname()
    s.close()

    return port


def retry(min_wait=5, max_wait=10, max_delay=60000):
    def decorator(func):
        @functools.wraps(func)
        def wrapper(*args, **kwargs):
            start_time = time.time()

            while True:
                try:
                    return func(*args, **kwargs)
                except Exception as e:
                    elapsed_time = time.time() - start_time
                    if elapsed_time * 1000 >= max_delay:
                        raise TimeoutError(
                            f"Retry limit of {max_delay} milliseconds reached."
                        ) from e

                    wait_time = random.uniform(min_wait, max_wait)
                    print(f"Retrying in {wait_time:.2f} seconds due to {e}...")
                    time.sleep(wait_time)

        return wrapper

    return decorator


# Orca configuration class
# ------------------------
class OrcaConfig(object):
    """
    Singleton object containing the current user defined configuration
    properties for orca.

    These parameters may optionally be saved to the user's ~/.plotly
    directory using the `save` method, in which case they are automatically
    restored in future sessions.
    """

    def __init__(self):
        # Initialize properties dict
        self._props = {}

        # Compute absolute path to the 'plotly/package_data/' directory
        root_dir = os.path.dirname(os.path.abspath(plotly.__file__))
        self.package_dir = os.path.join(root_dir, "package_data")

        # Load pre-existing configuration
        self.reload(warn=False)

        # Compute constants
        plotlyjs = os.path.join(self.package_dir, "plotly.min.js")
        self._constants = {
            "plotlyjs": plotlyjs,
            "config_file": os.path.join(PLOTLY_DIR, ".orca"),
        }

    def restore_defaults(self, reset_server=True):
        """
        Reset all orca configuration properties to their default values
        """
        self._props = {}

        if reset_server:
            # Server must restart before setting is active
            reset_status()

    def update(self, d={}, **kwargs):
        """
        Update one or more properties from a dict or from input keyword
        arguments.

        Parameters
        ----------
        d: dict
            Dictionary from property names to new property values.

        kwargs
            Named argument value pairs where the name is a configuration
            property name and the value is the new property value.

        Returns
        -------
        None

        Examples
        --------
        Update configuration properties using a dictionary

        >>> import plotly.io as pio
        >>> pio.orca.config.update({'timeout': 30, 'default_format': 'svg'})

        Update configuration properties using keyword arguments

        >>> pio.orca.config.update(timeout=30, default_format='svg'})
        """
        # Combine d and kwargs
        if not isinstance(d, dict):
            raise ValueError(
                """
The first argument to update must be a dict, \
but received value of type {typ}l
    Received value: {val}""".format(typ=type(d), val=d)
            )

        updates = copy(d)
        updates.update(kwargs)

        # Validate keys
        for k in updates:
            if k not in self._props:
                raise ValueError("Invalid property name: {k}".format(k=k))

        # Apply keys
        for k, v in updates.items():
            setattr(self, k, v)

    def reload(self, warn=True):
        """
        Reload orca settings from ~/.plotly/.orca, if any.

        Note: Settings are loaded automatically when plotly is imported.
        This method is only needed if the setting are changed by some outside
        process (e.g. a text editor) during an interactive session.

        Parameters
        ----------
        warn: bool
            If True, raise informative warnings if settings cannot be restored.
            If False, do not raise warnings if setting cannot be restored.

        Returns
        -------
        None
        """
        if os.path.exists(self.config_file):
            # ### Load file into a string ###
            try:
                with open(self.config_file, "r") as f:
                    orca_str = f.read()
            except Exception:
                if warn:
                    warnings.warn(
                        """\
Unable to read orca configuration file at {path}""".format(path=self.config_file)
                    )
                return

            # ### Parse as JSON ###
            try:
                orca_props = json.loads(orca_str)
            except ValueError:
                if warn:
                    warnings.warn(
                        """\
Orca configuration file at {path} is not valid JSON""".format(path=self.config_file)
                    )
                return

            # ### Update _props ###
            for k, v in orca_props.items():
                self._props[k] = v

        elif warn:
            warnings.warn(
                """\
Orca configuration file at {path} not found""".format(path=self.config_file)
            )

    def save(self):
        """
        Attempt to save current settings to disk, so that they are
        automatically restored for future sessions.

        This operation requires write access to the path returned by
        in the `config_file` property.

        Returns
        -------
        None
        """
        if ensure_writable_plotly_dir():
            with open(self.config_file, "w") as f:
                json.dump(self._props, f, indent=4)
        else:
            warnings.warn(
                """\
Failed to write orca configuration file at '{path}'""".format(path=self.config_file)
            )

    @property
    def server_url(self):
        """
        The server URL to use for an external orca server, or None if orca
        should be managed locally

        Overrides executable, port, timeout, mathjax, topojson,
        and mapbox_access_token

        Returns
        -------
        str or None
        """
        return self._props.get("server_url", None)

    @server_url.setter
    def server_url(self, val):
        if val is None:
            self._props.pop("server_url", None)
            return
        if not isinstance(val, str):
            raise ValueError(
                """
The server_url property must be a string, but received value of type {typ}.
    Received value: {val}""".format(typ=type(val), val=val)
            )

        if not val.startswith("http://") and not val.startswith("https://"):
            val = "http://" + val

        shutdown_server()
        self.executable = None
        self.port = None
        self.timeout = None
        self.mathjax = None
        self.topojson = None
        self.mapbox_access_token = None
        self._props["server_url"] = val

    @property
    def port(self):
        """
        The specific port to use to communicate with the orca server, or
        None if the port is to be chosen automatically.

        If an orca server is active, the port in use is stored in the
        plotly.io.orca.status.port property.

        Returns
        -------
        int or None
        """
        return self._props.get("port", None)

    @port.setter
    def port(self, val):
        if val is None:
            self._props.pop("port", None)
            return
        if not isinstance(val, int):
            raise ValueError(
                """
The port property must be an integer, but received value of type {typ}.
    Received value: {val}""".format(typ=type(val), val=val)
            )

        self._props["port"] = val

    @property
    def executable(self):
        """
        The name or full path of the orca executable.

         - If a name (e.g. 'orca'), then it should be the name of an orca
           executable on the PATH. The directories on the PATH can be
           displayed by running the following command:

           >>> import os
           >>> print(os.environ.get('PATH').replace(os.pathsep, os.linesep))

         - If a full path (e.g. '/path/to/orca'), then
           it should be the full path to an orca executable. In this case
           the executable does not need to reside on the PATH.

        If an orca server has been validated, then the full path to the
        validated orca executable is stored in the
        plotly.io.orca.status.executable property.

        Returns
        -------
        str
        """
        executable_list = self._props.get("executable_list", ["orca"])
        if executable_list is None:
            return None
        else:
            return " ".join(executable_list)

    @executable.setter
    def executable(self, val):
        if val is None:
            self._props.pop("executable", None)
        else:
            if not isinstance(val, str):
                raise ValueError(
                    """
The executable property must be a string, but received value of type {typ}.
    Received value: {val}""".format(typ=type(val), val=val)
                )
            if isinstance(val, str):
                val = [val]
            self._props["executable_list"] = val

        # Server and validation must restart before setting is active
        reset_status()

    @property
    def timeout(self):
        """
        The number of seconds of inactivity required before the orca server
        is shut down.

        For example, if timeout is set to 20, then the orca
        server will shutdown once is has not been used for at least
        20 seconds. If timeout is set to None, then the server will not be
        automatically shut down due to inactivity.

        Regardless of the value of timeout, a running orca server may be
        manually shut down like this:

        >>> import plotly.io as pio
        >>> pio.orca.shutdown_server()

        Returns
        -------
        int or float or None
        """
        return self._props.get("timeout", None)

    @timeout.setter
    def timeout(self, val):
        if val is None:
            self._props.pop("timeout", None)
        else:
            if not isinstance(val, (int, float)):
                raise ValueError(
                    """
The timeout property must be a number, but received value of type {typ}.
    Received value: {val}""".format(typ=type(val), val=val)
                )
            self._props["timeout"] = val

        # Server must restart before setting is active
        shutdown_server()

    @property
    def default_width(self):
        """
        The default width to use on image export. This value is only
        applied if no width value is supplied to the plotly.io
        to_image or write_image functions.

        Returns
        -------
        int or None
        """
        return self._props.get("default_width", None)

    @default_width.setter
    def default_width(self, val):
        if val is None:
            self._props.pop("default_width", None)
            return
        if not isinstance(val, int):
            raise ValueError(
                """
The default_width property must be an int, but received value of type {typ}.
    Received value: {val}""".format(typ=type(val), val=val)
            )
        self._props["default_width"] = val

    @property
    def default_height(self):
        """
        The default height to use on image export. This value is only
        applied if no height value is supplied to the plotly.io
        to_image or write_image functions.

        Returns
        -------
        int or None
        """
        return self._props.get("default_height", None)

    @default_height.setter
    def default_height(self, val):
        if val is None:
            self._props.pop("default_height", None)
            return
        if not isinstance(val, int):
            raise ValueError(
                """
The default_height property must be an int, but received value of type {typ}.
    Received value: {val}""".format(typ=type(val), val=val)
            )
        self._props["default_height"] = val

    @property
    def default_format(self):
        """
        The default image format to use on image export.

        Valid image formats strings are:
          - 'png'
          - 'jpg' or 'jpeg'
          - 'webp'
          - 'svg'
          - 'pdf'
          - 'eps' (Requires the poppler library to be installed)

        This value is only applied if no format value is supplied to the
        plotly.io to_image or write_image functions.

        Returns
        -------
        str or None
        """
        return self._props.get("default_format", "png")

    @default_format.setter
    def default_format(self, val):
        if val is None:
            self._props.pop("default_format", None)
            return

        val = validate_coerce_format(val)
        self._props["default_format"] = val

    @property
    def default_scale(self):
        """
        The default image scaling factor to use on image export.
        This value is only applied if no scale value is supplied to the
        plotly.io to_image or write_image functions.

        Returns
        -------
        int or None
        """
        return self._props.get("default_scale", 1)

    @default_scale.setter
    def default_scale(self, val):
        if val is None:
            self._props.pop("default_scale", None)
            return
        if not isinstance(val, (int, float)):
            raise ValueError(
                """
The default_scale property must be a number, but received value of type {typ}.
    Received value: {val}""".format(typ=type(val), val=val)
            )
        self._props["default_scale"] = val

    @property
    def topojson(self):
        """
        Path to the topojson files needed to render choropleth traces.

        If None, topojson files from the plot.ly CDN are used.

        Returns
        -------
        str
        """
        return self._props.get("topojson", None)

    @topojson.setter
    def topojson(self, val):
        if val is None:
            self._props.pop("topojson", None)
        else:
            if not isinstance(val, str):
                raise ValueError(
                    """
The topojson property must be a string, but received value of type {typ}.
    Received value: {val}""".format(typ=type(val), val=val)
                )
            self._props["topojson"] = val

        # Server must restart before setting is active
        shutdown_server()

    @property
    def mathjax(self):
        """
        Path to the MathJax bundle needed to render LaTeX characters

        Returns
        -------
        str
        """
        return self._props.get(
            "mathjax",
            "https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/MathJax.js",
        )

    @mathjax.setter
    def mathjax(self, val):
        if val is None:
            self._props.pop("mathjax", None)
        else:
            if not isinstance(val, str):
                raise ValueError(
                    """
The mathjax property must be a string, but received value of type {typ}.
    Received value: {val}""".format(typ=type(val), val=val)
                )
            self._props["mathjax"] = val

        # Server must restart before setting is active
        shutdown_server()

    @property
    def mapbox_access_token(self):
        """
        Mapbox access token required to render mapbox traces.

        Returns
        -------
        str
        """
        return self._props.get("mapbox_access_token", None)

    @mapbox_access_token.setter
    def mapbox_access_token(self, val):
        if val is None:
            self._props.pop("mapbox_access_token", None)
        else:
            if not isinstance(val, str):
                raise ValueError(
                    """
The mapbox_access_token property must be a string, \
but received value of type {typ}.
    Received value: {val}""".format(typ=type(val), val=val)
                )
            self._props["mapbox_access_token"] = val

        # Server must restart before setting is active
        shutdown_server()

    @property
    def use_xvfb(self):
        dflt = "auto"
        return self._props.get("use_xvfb", dflt)

    @use_xvfb.setter
    def use_xvfb(self, val):
        valid_vals = [True, False, "auto"]
        if val is None:
            self._props.pop("use_xvfb", None)
        else:
            if val not in valid_vals:
                raise ValueError(
                    """
The use_xvfb property must be one of {valid_vals}
    Received value of type {typ}: {val}""".format(
                        valid_vals=valid_vals, typ=type(val), val=repr(val)
                    )
                )

            self._props["use_xvfb"] = val

        # Server and validation must restart before setting is active
        reset_status()

    @property
    def plotlyjs(self):
        """
        The plotly.js bundle being used for image rendering.

        Returns
        -------
        str
        """
        return self._constants.get("plotlyjs", None)

    @property
    def config_file(self):
        """
        Path to orca configuration file

        Using the `plotly.io.config.save()` method will save the current
        configuration settings to this file. Settings in this file are
        restored at the beginning of each sessions.

        Returns
        -------
        str
        """
        return os.path.join(PLOTLY_DIR, ".orca")

    def __repr__(self):
        """
        Display a nice representation of the current orca configuration.
        """
        return """\
orca configuration
------------------
    server_url: {server_url}
    executable: {executable}
    port: {port}
    timeout: {timeout}
    default_width: {default_width}
    default_height: {default_height}
    default_scale: {default_scale}
    default_format: {default_format}
    mathjax: {mathjax}
    topojson: {topojson}
    mapbox_access_token: {mapbox_access_token}
    use_xvfb: {use_xvfb}

constants
---------
    plotlyjs: {plotlyjs}
    config_file: {config_file}

""".format(
            server_url=self.server_url,
            port=self.port,
            executable=self.executable,
            timeout=self.timeout,
            default_width=self.default_width,
            default_height=self.default_height,
            default_scale=self.default_scale,
            default_format=self.default_format,
            mathjax=self.mathjax,
            topojson=self.topojson,
            mapbox_access_token=self.mapbox_access_token,
            plotlyjs=self.plotlyjs,
            config_file=self.config_file,
            use_xvfb=self.use_xvfb,
        )


# Make config a singleton object
# ------------------------------
config = OrcaConfig()
del OrcaConfig


# Orca status class
# ------------------------
class OrcaStatus(object):
    """
    Class to store information about the current status of the orca server.
    """

    _props = {
        "state": "unvalidated",  # or 'validated' or 'running'
        "executable_list": None,
        "version": None,
        "pid": None,
        "port": None,
        "command": None,
    }

    @property
    def state(self):
        """
        A string representing the state of the orca server process

        One of:
          - unvalidated: The orca executable has not yet been searched for or
            tested to make sure its valid.
          - validated: The orca executable has been located and tested for
            validity, but it is not running.
          - running: The orca server process is currently running.
        """
        return self._props["state"]

    @property
    def executable(self):
        """
        If the `state` property is 'validated' or 'running', this property
        contains the full path to the orca executable.

        This path can be specified explicitly by setting the `executable`
        property of the `plotly.io.orca.config` object.

        This property will be None if the `state` is 'unvalidated'.
        """
        executable_list = self._props["executable_list"]
        if executable_list is None:
            return None
        else:
            return " ".join(executable_list)

    @property
    def version(self):
        """
        If the `state` property is 'validated' or 'running', this property
        contains the version of the validated orca executable.

        This property will be None if the `state` is 'unvalidated'.
        """
        return self._props["version"]

    @property
    def pid(self):
        """
        The process id of the orca server process, if any. This property
        will be None if the `state` is not 'running'.
        """
        return self._props["pid"]

    @property
    def port(self):
        """
        The port number that the orca server process is listening to, if any.
        This property will be None if the `state` is not 'running'.

        This port can be specified explicitly by setting the `port`
        property of the `plotly.io.orca.config` object.
        """
        return self._props["port"]

    @property
    def command(self):
        """
        The command arguments used to launch the running orca server, if any.
        This property will be None if the `state` is not 'running'.
        """
        return self._props["command"]

    def __repr__(self):
        """
        Display a nice representation of the current orca server status.
        """
        return """\
orca status
-----------
    state: {state}
    executable: {executable}
    version: {version}
    port: {port}
    pid: {pid}
    command: {command}

""".format(
            executable=self.executable,
            version=self.version,
            port=self.port,
            pid=self.pid,
            state=self.state,
            command=self.command,
        )


# Make status a singleton object
# ------------------------------
status = OrcaStatus()
del OrcaStatus


@contextmanager
def orca_env():
    """
    Context manager to clear and restore environment variables that are
    problematic for orca to function properly

    NODE_OPTIONS: When this variable is set, orca <v1.2 will have a
    segmentation fault due to an electron bug.
    See: https://github.com/electron/electron/issues/12695

    ELECTRON_RUN_AS_NODE: When this environment variable is set the call
    to orca is transformed into a call to nodejs.
    See https://github.com/plotly/orca/issues/149#issuecomment-443506732
    """
    clear_env_vars = ["NODE_OPTIONS", "ELECTRON_RUN_AS_NODE", "LD_PRELOAD"]
    orig_env_vars = {}

    try:
        # Clear and save
        orig_env_vars.update(
            {var: os.environ.pop(var) for var in clear_env_vars if var in os.environ}
        )
        yield
    finally:
        # Restore
        for var, val in orig_env_vars.items():
            os.environ[var] = val


# Public orca server interaction functions
# ----------------------------------------
def validate_executable():
    """
    Attempt to find and validate the orca executable specified by the
    `plotly.io.orca.config.executable` property.

    If the `plotly.io.orca.status.state` property is 'validated' or 'running'
    then this function does nothing.

    How it works:
      - First, it searches the system PATH for an executable that matches the
      name or path specified in the `plotly.io.orca.config.executable`
      property.
      - Then it runs the executable with the `--help` flag to make sure
      it's the plotly orca executable
      - Then it runs the executable with the `--version` flag to check the
      orca version.

    If all of these steps are successful then the `status.state` property
    is set to 'validated' and the `status.executable` and `status.version`
    properties are populated

    Returns
    -------
    None
    """
    # Check state
    # -----------
    if status.state != "unvalidated":
        # Nothing more to do
        return

    # Initialize error messages
    # -------------------------
    install_location_instructions = """\
If you haven't installed orca yet, you can do so using conda as follows:

    $ conda install -c plotly plotly-orca

Alternatively, see other installation methods in the orca project README at
https://github.com/plotly/orca

After installation is complete, no further configuration should be needed.

If you have installed orca, then for some reason plotly.py was unable to
locate it. In this case, set the `plotly.io.orca.config.executable`
property to the full path of your orca executable. For example:

    >>> plotly.io.orca.config.executable = '/path/to/orca'

After updating this executable property, try the export operation again.
If it is successful then you may want to save this configuration so that it
will be applied automatically in future sessions. You can do this as follows:

    >>> plotly.io.orca.config.save()

If you're still having trouble, feel free to ask for help on the forums at
https://community.plot.ly/c/api/python
"""

    # Try to find an executable
    # -------------------------
    # Search for executable name or path in config.executable
    executable = which(config.executable)
    path = os.environ.get("PATH", os.defpath)
    formatted_path = path.replace(os.pathsep, "\n    ")

    if executable is None:
        raise ValueError(
            """
The orca executable is required to export figures as static images,
but it could not be found on the system path.

Searched for executable '{executable}' on the following path:
    {formatted_path}

{instructions}""".format(
                executable=config.executable,
                formatted_path=formatted_path,
                instructions=install_location_instructions,
            )
        )

    # Check if we should run with Xvfb
    # --------------------------------
    xvfb_args = [
        "--auto-servernum",
        "--server-args",
        "-screen 0 640x480x24 +extension RANDR +extension GLX",
        executable,
    ]

    if config.use_xvfb:
        # Use xvfb
        xvfb_run_executable = which("xvfb-run")
        if not xvfb_run_executable:
            raise ValueError(
                """
The plotly.io.orca.config.use_xvfb property is set to True, but the
xvfb-run executable could not be found on the system path.

Searched for the executable 'xvfb-run' on the following path:
    {formatted_path}""".format(formatted_path=formatted_path)
            )

        executable_list = [xvfb_run_executable] + xvfb_args
    elif (
        config.use_xvfb == "auto"
        and sys.platform.startswith("linux")
        and not os.environ.get("DISPLAY")
        and which("xvfb-run")
    ):
        # use_xvfb is 'auto', we're on linux without a display server,
        # and xvfb-run is available. Use it.
        xvfb_run_executable = which("xvfb-run")
        executable_list = [xvfb_run_executable] + xvfb_args
    else:
        # Do not use xvfb
        executable_list = [executable]

    # Run executable with --help and see if it's our orca
    # ---------------------------------------------------
    invalid_executable_msg = """
The orca executable is required in order to export figures as static images,
but the executable that was found at '{executable}'
does not seem to be a valid plotly orca executable. Please refer to the end of
this message for details on what went wrong.

{instructions}""".format(
        executable=executable, instructions=install_location_instructions
    )

    # ### Run with Popen so we get access to stdout and stderr
    with orca_env():
        p = subprocess.Popen(
            executable_list + ["--help"], stdout=subprocess.PIPE, stderr=subprocess.PIPE
        )

        help_result, help_error = p.communicate()

    if p.returncode != 0:
        err_msg = (
            invalid_executable_msg
            + """
Here is the error that was returned by the command
    $ {executable} --help

[Return code: {returncode}]
{err_msg}
""".format(
                executable=" ".join(executable_list),
                err_msg=help_error.decode("utf-8"),
                returncode=p.returncode,
            )
        )

        # Check for Linux without X installed.
        if sys.platform.startswith("linux") and not os.environ.get("DISPLAY"):
            err_msg += """\
Note: When used on Linux, orca requires an X11 display server, but none was
detected. Please install Xvfb and configure plotly.py to run orca using Xvfb
as follows:

    >>> import plotly.io as pio
    >>> pio.orca.config.use_xvfb = True

You can save this configuration for use in future sessions as follows:

    >>> pio.orca.config.save()

See https://www.x.org/releases/X11R7.6/doc/man/man1/Xvfb.1.xhtml
for more info on Xvfb
"""
        raise ValueError(err_msg)

    if not help_result:
        raise ValueError(
            invalid_executable_msg
            + """
The error encountered is that no output was returned by the command
    $ {executable} --help
""".format(executable=" ".join(executable_list))
        )

    if "Plotly's image-exporting utilities" not in help_result.decode("utf-8"):
        raise ValueError(
            invalid_executable_msg
            + """
The error encountered is that unexpected output was returned by the command
    $ {executable} --help

{help_result}
""".format(executable=" ".join(executable_list), help_result=help_result)
        )

    # Get orca version
    # ----------------
    # ### Run with Popen so we get access to stdout and stderr
    with orca_env():
        p = subprocess.Popen(
            executable_list + ["--version"],
            stdout=subprocess.PIPE,
            stderr=subprocess.PIPE,
        )

        version_result, version_error = p.communicate()

    if p.returncode != 0:
        raise ValueError(
            invalid_executable_msg
            + """
An error occurred while trying to get the version of the orca executable.
Here is the command that plotly.py ran to request the version
    $ {executable} --version

This command returned the following error:

[Return code: {returncode}]
{err_msg}
        """.format(
                executable=" ".join(executable_list),
                err_msg=version_error.decode("utf-8"),
                returncode=p.returncode,
            )
        )

    if not version_result:
        raise ValueError(
            invalid_executable_msg
            + """
The error encountered is that no version was reported by the orca executable.
Here is the command that plotly.py ran to request the version:

    $ {executable} --version
""".format(executable=" ".join(executable_list))
        )
    else:
        version_result = version_result.decode()

    status._props["executable_list"] = executable_list
    status._props["version"] = version_result.strip()
    status._props["state"] = "validated"


def reset_status():
    """
    Shutdown the running orca server, if any, and reset the orca status
    to unvalidated.

    This command is only needed if the desired orca executable is changed
    during an interactive session.

    Returns
    -------
    None
    """
    shutdown_server()
    status._props["executable_list"] = None
    status._props["version"] = None
    status._props["state"] = "unvalidated"


# Initialze process control variables
# -----------------------------------
orca_lock = threading.Lock()
orca_state = {"proc": None, "shutdown_timer": None}


# Shutdown
# --------
# The @atexit.register annotation ensures that the shutdown function is
# is run when the Python process is terminated
@atexit.register
def cleanup():
    shutdown_server()


def shutdown_server():
    """
    Shutdown the running orca server process, if any

    Returns
    -------
    None
    """
    # Use double-check locking to make sure the properties of orca_state
    # are updated consistently across threads.
    if orca_state["proc"] is not None:
        with orca_lock:
            if orca_state["proc"] is not None:
                # We use psutil to kill all child processes of the main orca
                # process. This prevents any zombie processes from being
                # left over, and it saves us from needing to write
                # OS-specific process management code here.

                parent = psutil.Process(orca_state["proc"].pid)
                for child in parent.children(recursive=True):
                    try:
                        child.terminate()
                    except Exception:
                        # We tried, move on
                        pass

                try:
                    # Kill parent process
                    orca_state["proc"].terminate()

                    # Wait for the process to shutdown
                    orca_state["proc"].wait()
                except Exception:
                    # We tried, move on
                    pass

                # Update our internal process management state
                orca_state["proc"] = None

                if orca_state["shutdown_timer"] is not None:
                    orca_state["shutdown_timer"].cancel()
                    orca_state["shutdown_timer"] = None

                orca_state["port"] = None

                # Update orca.status so the user has an accurate view
                # of the state of the orca server
                status._props["state"] = "validated"
                status._props["pid"] = None
                status._props["port"] = None
                status._props["command"] = None


# Launch or get server
def ensure_server():
    """
    Start an orca server if none is running. If a server is already running,
    then reset the timeout countdown

    Returns
    -------
    None
    """

    # Validate psutil
    if psutil is None:
        raise ValueError(
            """\
Image generation requires the psutil package.

Install using pip:
    $ pip install psutil

Install using conda:
    $ conda install psutil
"""
        )

    # Validate requests
    if not get_module("requests"):
        raise ValueError(
            """\
Image generation requires the requests package.

Install using pip:
    $ pip install requests

Install using conda:
    $ conda install requests
"""
        )

    if not config.server_url:
        # Validate orca executable only if server_url is not provided
        if status.state == "unvalidated":
            validate_executable()
        # Acquire lock to make sure that we keep the properties of orca_state
        # consistent across threads
        with orca_lock:
            # Cancel the current shutdown timer, if any
            if orca_state["shutdown_timer"] is not None:
                orca_state["shutdown_timer"].cancel()

            # Start a new server process if none is active
            if orca_state["proc"] is None:
                # Determine server port
                if config.port is None:
                    orca_state["port"] = find_open_port()
                else:
                    orca_state["port"] = config.port

                # Build orca command list
                cmd_list = status._props["executable_list"] + [
                    "serve",
                    "-p",
                    str(orca_state["port"]),
                    "--plotly",
                    config.plotlyjs,
                    "--graph-only",
                ]

                if config.topojson:
                    cmd_list.extend(["--topojson", config.topojson])

                if config.mathjax:
                    cmd_list.extend(["--mathjax", config.mathjax])

                if config.mapbox_access_token:
                    cmd_list.extend(
                        ["--mapbox-access-token", config.mapbox_access_token]
                    )

                # Create subprocess that launches the orca server on the
                # specified port.
                DEVNULL = open(os.devnull, "wb")
                with orca_env():
                    stderr = DEVNULL if "CI" in os.environ else None  # fix for CI
                    orca_state["proc"] = subprocess.Popen(
                        cmd_list, stdout=DEVNULL, stderr=stderr
                    )

                # Update orca.status so the user has an accurate view
                # of the state of the orca server
                status._props["state"] = "running"
                status._props["pid"] = orca_state["proc"].pid
                status._props["port"] = orca_state["port"]
                status._props["command"] = cmd_list

            # Create new shutdown timer if a timeout was specified
            if config.timeout is not None:
                t = threading.Timer(config.timeout, shutdown_server)
                # Make it a daemon thread so that exit won't wait for timer to
                # complete
                t.daemon = True
                t.start()
                orca_state["shutdown_timer"] = t


@retry(min_wait=5, max_wait=10, max_delay=60000)
def request_image_with_retrying(**kwargs):
    """
    Helper method to perform an image request to a running orca server process
    with retrying logic.
    """
    from requests import post
    from plotly.io.json import to_json_plotly

    if config.server_url:
        server_url = config.server_url
    else:
        server_url = "http://{hostname}:{port}".format(
            hostname="localhost", port=orca_state["port"]
        )

    request_params = {k: v for k, v in kwargs.items() if v is not None}
    json_str = to_json_plotly(request_params)
    response = post(server_url + "/", data=json_str)

    if response.status_code == 522:
        # On "522: client socket timeout", return server and keep trying
        shutdown_server()
        ensure_server()
        raise OSError("522: client socket timeout")

    return response


def to_image(fig, format=None, width=None, height=None, scale=None, validate=True):
    """
    Convert a figure to a static image bytes string

    Parameters
    ----------
    fig:
        Figure object or dict representing a figure

    format: str or None
        The desired image format. One of
          - 'png'
          - 'jpg' or 'jpeg'
          - 'webp'
          - 'svg'
          - 'pdf'
          - 'eps' (Requires the poppler library to be installed)

        If not specified, will default to `plotly.io.config.default_format`

    width: int or None
        The width of the exported image in layout pixels. If the `scale`
        property is 1.0, this will also be the width of the exported image
        in physical pixels.

        If not specified, will default to `plotly.io.config.default_width`

    height: int or None
        The height of the exported image in layout pixels. If the `scale`
        property is 1.0, this will also be the height of the exported image
        in physical pixels.

        If not specified, will default to `plotly.io.config.default_height`

    scale: int or float or None
        The scale factor to use when exporting the figure. A scale factor
        larger than 1.0 will increase the image resolution with respect
        to the figure's layout pixel dimensions. Whereas as scale factor of
        less than 1.0 will decrease the image resolution.

        If not specified, will default to `plotly.io.config.default_scale`

    validate: bool
        True if the figure should be validated before being converted to
        an image, False otherwise.

    Returns
    -------
    bytes
        The image data
    """
    # Make sure orca sever is running
    # -------------------------------
    ensure_server()

    # Handle defaults
    # ---------------
    # Apply configuration defaults to unspecified arguments
    if format is None:
        format = config.default_format

    format = validate_coerce_format(format)

    if scale is None:
        scale = config.default_scale

    if width is None:
        width = config.default_width

    if height is None:
        height = config.default_height

    # Validate figure
    # ---------------
    fig_dict = validate_coerce_fig_to_dict(fig, validate)

    # Request image from server
    # -------------------------
    try:
        response = request_image_with_retrying(
            figure=fig_dict, format=format, scale=scale, width=width, height=height
        )
    except OSError:
        # Get current status string
        status_str = repr(status)

        if config.server_url:
            raise ValueError(
                """
Plotly.py was unable to communicate with the orca server at {server_url}

Please check that the server is running and accessible.
""".format(server_url=config.server_url)
            )

        else:
            # Check if the orca server process exists
            pid_exists = psutil.pid_exists(status.pid)

            # Raise error message based on whether the server process existed
            if pid_exists:
                raise ValueError(
                    """
For some reason plotly.py was unable to communicate with the
local orca server process, even though the server process seems to be running.

Please review the process and connection information below:

{info}
""".format(info=status_str)
                )
            else:
                # Reset the status so that if the user tries again, we'll try to
                # start the server again
                reset_status()
                raise ValueError(
                    """
For some reason the orca server process is no longer running.

Please review the process and connection information below:

{info}
plotly.py will attempt to start the local server process again the next time
an image export operation is performed.
""".format(info=status_str)
                )

    # Check response
    # --------------
    if response.status_code == 200:
        # All good
        return response.content
    else:
        # ### Something went wrong ###
        err_message = """
The image request was rejected by the orca conversion utility
with the following error:
   {status}: {msg}
""".format(status=response.status_code, msg=response.content.decode("utf-8"))

        # ### Try to be helpful ###
        # Status codes from /src/component/plotly-graph/constants.js in the
        # orca code base.
        # statusMsg: {
        #     400: 'invalid or malformed request syntax',
        #     522: client socket timeout
        #     525: 'plotly.js error',
        #     526: 'plotly.js version 1.11.0 or up required',
        #     530: 'image conversion error'
        # }
        if response.status_code == 400 and isinstance(fig, dict) and not validate:
            err_message += """
Try setting the `validate` argument to True to check for errors in the
figure specification"""
        elif response.status_code == 525:
            any_mapbox = any(
                [
                    trace.get("type", None) == "scattermapbox"
                    for trace in fig_dict.get("data", [])
                ]
            )
            if any_mapbox and config.mapbox_access_token is None:
                err_message += """
Exporting scattermapbox traces requires a mapbox access token.
Create a token in your mapbox account and then set it using:

>>> plotly.io.orca.config.mapbox_access_token = 'pk.abc...'

If you would like this token to be applied automatically in
future sessions, then save your orca configuration as follows:

>>> plotly.io.orca.config.save()
"""
        elif response.status_code == 530 and format == "eps":
            err_message += """
Exporting to EPS format requires the poppler library.  You can install
poppler on MacOS or Linux with:

    $ conda install poppler

Or, you can install it on MacOS using homebrew with:

    $ brew install poppler

Or, you can install it on Linux using your distribution's package manager to
install the 'poppler-utils' package.

Unfortunately, we don't yet know of an easy way to install poppler on Windows.
"""
        raise ValueError(err_message)


def write_image(
    fig, file, format=None, scale=None, width=None, height=None, validate=True
):
    """
    Convert a figure to a static image and write it to a file or writeable
    object

    Parameters
    ----------
    fig:
        Figure object or dict representing a figure

    file: str or writeable
        A string representing a local file path or a writeable object
        (e.g. a pathlib.Path object or an open file descriptor)

    format: str or None
        The desired image format. One of
          - 'png'
          - 'jpg' or 'jpeg'
          - 'webp'
          - 'svg'
          - 'pdf'
          - 'eps' (Requires the poppler library to be installed)

        If not specified and `file` is a string then this will default to the
        file extension. If not specified and `file` is not a string then this
        will default to `plotly.io.config.default_format`

    width: int or None
        The width of the exported image in layout pixels. If the `scale`
        property is 1.0, this will also be the width of the exported image
        in physical pixels.

        If not specified, will default to `plotly.io.config.default_width`

    height: int or None
        The height of the exported image in layout pixels. If the `scale`
        property is 1.0, this will also be the height of the exported image
        in physical pixels.

        If not specified, will default to `plotly.io.config.default_height`

    scale: int or float or None
        The scale factor to use when exporting the figure. A scale factor
        larger than 1.0 will increase the image resolution with respect
        to the figure's layout pixel dimensions. Whereas as scale factor of
        less than 1.0 will decrease the image resolution.

        If not specified, will default to `plotly.io.config.default_scale`

    validate: bool
        True if the figure should be validated before being converted to
        an image, False otherwise.

    Returns
    -------
    None
    """

    # Try to cast `file` as a pathlib object `path`.
    # ----------------------------------------------
    if isinstance(file, str):
        # Use the standard Path constructor to make a pathlib object.
        path = Path(file)
    elif isinstance(file, Path):
        # `file` is already a Path object.
        path = file
    else:
        # We could not make a Path object out of file. Either `file` is an open file
        # descriptor with a `write()` method or it's an invalid object.
        path = None

    # Infer format if not specified
    # -----------------------------
    if path is not None and format is None:
        ext = path.suffix
        if ext:
            format = ext.lstrip(".")
        else:
            raise ValueError(
                """
Cannot infer image type from output path '{file}'.
Please add a file extension or specify the type using the format parameter.
For example:

    >>> import plotly.io as pio
    >>> pio.write_image(fig, file_path, format='png')
""".format(file=file)
            )

    # Request image
    # -------------
    # Do this first so we don't create a file if image conversion fails
    img_data = to_image(
        fig, format=format, scale=scale, width=width, height=height, validate=validate
    )

    # Open file
    # ---------
    if path is None:
        # We previously failed to make sense of `file` as a pathlib object.
        # Attempt to write to `file` as an open file descriptor.
        try:
            file.write(img_data)
            return
        except AttributeError:
            pass
        raise ValueError(
            """
The 'file' argument '{file}' is not a string, pathlib.Path object, or file descriptor.
""".format(file=file)
        )
    else:
        # We previously succeeded in interpreting `file` as a pathlib object.
        # Now we can use `write_bytes()`.
        path.write_bytes(img_data)