API Documentation — pyngrok 5.0.5 documentation
Description: A Python wrapper for ngrok that makes ngrok readily available from anywhere on the command line and via a convenient Python API.

# API Documentation

This part of the documentation covers the interfaces used to develop with `pyngrok`.

## Main `ngrok` Interface

class `pyngrok.ngrok.` `NgrokTunnel`(data, pyngrok_config, api_url)

  Bases: `object`

  An object containing information about a `ngrok` tunnel.

  Variables

    - data (dict) – The original tunnel data.

    - name (str) – The name of the tunnel.

    - proto (str) – A valid tunnel protocol.

    - uri (str) – The tunnel URI, a relative path that can be used to make requests to the `ngrok` web interface.

    - public_url (str) – The public `ngrok` URL.

    - config (dict) – The config for the tunnel.

    - metrics (dict) – Metrics for the tunnel.

    - pyngrok_config (PyngrokConfig) – The `pyngrok` configuration to use when interacting with the `ngrok`.

    - api_url (str) – The API URL for the `ngrok` web interface.

  `refresh_metrics`()

    Get the latest metrics for the tunnel and update the `metrics` variable.

`pyngrok.ngrok.` `api_request`(url, method='GET', data=None, params=None, timeout=4)

  Invoke an API request to the given URL, returning JSON data from the response.

  One use for this method is making requests to `ngrok` tunnels:

      from pyngrok import ngrok

      public_url = ngrok.connect()
      response = ngrok.api_request("{}/some-route".format(public_url),
                                   method="POST", data={"foo": "bar"})

  Another is making requests to the `ngrok` API itself:

      from pyngrok import ngrok

      api_url = ngrok.get_ngrok_process().api_url
      response = ngrok.api_request("{}/api/requests/http".format(api_url),
                                   params={"tunnel_name": "foo"})

  Parameters

    - url (str) – The request URL.

    - method (str, optional) – The HTTP method.

    - data (dict, optional) – The request body.

    - params (dict, optional) – The URL parameters.

    - timeout (float, optional) – The request timeout, in seconds.

  Returns

    The response from the request.

  Return type

    dict

`pyngrok.ngrok.` `connect`(addr=None, proto=None, name=None, pyngrok_config=None, **options)

  Establish a new `ngrok` tunnel for the given protocol to the given port, returning an object representing the connected tunnel.

  If a tunnel definition in ngrok’s config file matches the given `name`, it will be loaded and used to start the tunnel. When `name` is `None` and a “pyngrok-default” tunnel definition exists in `ngrok`’s config, it will be loaded and use. Any `kwargs` passed as `options` will override properties from the loaded tunnel definition.

  If `ngrok` is not installed at `PyngrokConfig`’s `ngrok_path`, calling this method will first download and install `ngrok`.

  If `ngrok` is not running, calling this method will first start a process with `PyngrokConfig`.

  Note

  `ngrok`’s default behavior for `http` when no additional properties are passed is to open two tunnels, one `http` and one `https`. This method will return a reference to the `http` tunnel in this case. If only a single tunnel is needed, pass `bind_tls=True`.

  Parameters

    - addr (str, optional) – The local port to which the tunnel will forward traffic, or a local directory or network address, defaults to “80”.

    - proto (str, optional) – The protocol to tunnel, defaults to “http”.

    - name (str, optional) – A friendly name for the tunnel, or the name of a ngrok tunnel definition to be used.

    - pyngrok_config (PyngrokConfig, optional) – A `pyngrok` configuration to use when interacting with the `ngrok` binary, overriding `get_default`.

    - options (dict, optional) – Remaining `kwargs` are passed as configuration for the ngrok tunnel.

  Returns

    The created `ngrok` tunnel.

  Return type

    NgrokTunnel

`pyngrok.ngrok.` `disconnect`(public_url, pyngrok_config=None)

  Disconnect the `ngrok` tunnel for the given URL, if open.

  Parameters

    - public_url (str) – The public URL of the tunnel to disconnect.

    - pyngrok_config (PyngrokConfig, optional) – A `pyngrok` configuration to use when interacting with the `ngrok` binary, overriding `get_default`.

`pyngrok.ngrok.` `get_ngrok_process`(pyngrok_config=None)

  Get the current `ngrok` process for the given config’s `ngrok_path`.

  If `ngrok` is not installed at `PyngrokConfig`’s `ngrok_path`, calling this method will first download and install `ngrok`.

  If `ngrok` is not running, calling this method will first start a process with `PyngrokConfig`.

  Use `is_process_running` to check if a process is running without also implicitly installing and starting it.

  Parameters

    pyngrok_config (PyngrokConfig, optional) – A `pyngrok` configuration to use when interacting with the `ngrok` binary, overriding `get_default`.

  Returns

    The `ngrok` process.

  Return type

    NgrokProcess

`pyngrok.ngrok.` `get_tunnels`(pyngrok_config=None)

  Get a list of active `ngrok` tunnels for the given config’s `ngrok_path`.

  If `ngrok` is not installed at `PyngrokConfig`’s `ngrok_path`, calling this method will first download and install `ngrok`.

  If `ngrok` is not running, calling this method will first start a process with `PyngrokConfig`.

  Parameters

    pyngrok_config (PyngrokConfig, optional) – A `pyngrok` configuration to use when interacting with the `ngrok` binary, overriding `get_default`.

  Returns

    The active `ngrok` tunnels.

  Return type

    list[NgrokTunnel]

`pyngrok.ngrok.` `get_version`(pyngrok_config=None)

  Get a tuple with the `ngrok` and `pyngrok` versions.

  Parameters

    pyngrok_config (PyngrokConfig, optional) – A `pyngrok` configuration to use when interacting with the `ngrok` binary, overriding `get_default`.

  Returns

    A tuple of `(ngrok_version, pyngrok_version)`.

  Return type

    tuple

`pyngrok.ngrok.` `install_ngrok`(pyngrok_config=None)

  Download, install, and initialize `ngrok` for the given config. If `ngrok` and its default config is already installed, calling this method will do nothing.

  Parameters

    pyngrok_config (PyngrokConfig, optional) – A `pyngrok` configuration to use when interacting with the `ngrok` binary, overriding `get_default`.

`pyngrok.ngrok.` `kill`(pyngrok_config=None)

  Terminate the `ngrok` processes, if running, for the given config’s `ngrok_path`. This method will not block, it will just issue a kill request.

  Parameters

    pyngrok_config (PyngrokConfig, optional) – A `pyngrok` configuration to use when interacting with the `ngrok` binary, overriding `get_default`.

`pyngrok.ngrok.` `main`()

  Entry point for the package’s `console_scripts`. This initializes a call from the command line and invokes `run`.

  This method is meant for interacting with `ngrok` from the command line and is not necessarily compatible with non-blocking API methods. For that, use `ngrok`’s interface methods (like `connect`), or use `get_process`.

`pyngrok.ngrok.` `run`(args=None, pyngrok_config=None)

  Ensure `ngrok` is installed at the default path, then call `run_process`.

  This method is meant for interacting with `ngrok` from the command line and is not necessarily compatible with non-blocking API methods. For that, use `ngrok`’s interface methods (like `connect`), or use `get_process`.

  Parameters

    - args (list[str], optional) – Arguments to be passed to the `ngrok` process.

    - pyngrok_config (PyngrokConfig, optional) – A `pyngrok` configuration to use when interacting with the `ngrok` binary, overriding `get_default`.

`pyngrok.ngrok.` `set_auth_token`(token, pyngrok_config=None)

  Set the `ngrok` auth token in the config file, enabling authenticated features (for instance, more concurrent tunnels, custom subdomains, etc.).

  If `ngrok` is not installed at `PyngrokConfig`’s `ngrok_path`, calling this method will first download and install `ngrok`.

  Parameters

    - token (str) – The auth token to set.

    - pyngrok_config (PyngrokConfig, optional) – A `pyngrok` configuration to use when interacting with the `ngrok` binary, overriding `get_default`.

`pyngrok.ngrok.` `update`(pyngrok_config=None)

  Update `ngrok` for the given config’s `ngrok_path`, if an update is available.

  Parameters

    pyngrok_config (PyngrokConfig, optional) – A `pyngrok` configuration to use when interacting with the `ngrok` binary, overriding `get_default`.

  Returns

    The result from the `ngrok` update.

  Return type

    str

## Process Management

class `pyngrok.process.` `NgrokLog`(line)

  Bases: `object`

  An object containing a parsed log from the `ngrok` process.

  Variables

    - line (str) – The raw, unparsed log line.

    - t (str) – The log’s ISO 8601 timestamp.

    - lvl (str) – The log’s level.

    - msg (str) – The log’s message.

    - err (str) – The log’s error, if applicable.

    - addr (str) – The URL, if `obj` is “web”.

class `pyngrok.process.` `NgrokProcess`(proc, pyngrok_config)

  Bases: `object`

  An object containing information about the `ngrok` process.

  Variables

    - proc (subprocess.Popen) – The child process that is running `ngrok`.

    - pyngrok_config (PyngrokConfig) – The `pyngrok` configuration to use with `ngrok`.

    - api_url (str) – The API URL for the `ngrok` web interface.

    - logs (list[NgrokLog]) – A list of the most recent logs from `ngrok`, limited in size to `max_logs`.

    - startup_error (str) – If `ngrok` startup fails, this will be the log of the failure.

  `_log_line`(line)

    Parse, log, and emit (if `log_event_callback` in `PyngrokConfig` is registered) the given log line.

    Parameters

      line (str) – The line to be processed.

    Returns

      The parsed log.

    Return type

      NgrokLog

  `_log_startup_line`(line)

    Parse the given startup log line and use it to manage the startup state of the `ngrok` process.

    Parameters

      line (str) – The line to be parsed and logged.

    Returns

      The parsed log.

    Return type

      NgrokLog

  `healthy`()

    Check whether the `ngrok` process has finished starting up and is in a running, healthy state.

    Returns

      `True` if the `ngrok` process is started, running, and healthy.

    Return type

      bool

  `start_monitor_thread`()

    Start a thread that will monitor the `ngrok` process and its logs until it completes.

    If a monitor thread is already running, nothing will be done.

  `stop_monitor_thread`()

    Set the monitor thread to stop monitoring the `ngrok` process after the next log event. This will not necessarily terminate the thread immediately, as the thread may currently be idle, rather it sets a flag on the thread telling it to terminate the next time it wakes up.

    This has no impact on the `ngrok` process itself, only `pyngrok`’s monitor of the process and its logs.

`pyngrok.process.` `_start_process`(pyngrok_config, retries=0)

  Start a `ngrok` process with no tunnels. This will start the `ngrok` web interface, against which HTTP requests can be made to create, interact with, and destroy tunnels.

  Parameters

    - pyngrok_config (PyngrokConfig) – The `pyngrok` configuration to use when interacting with the `ngrok` binary.

    - retries (int, optional) – The retry attempt index, if `ngrok` fails to establish the tunnel.

  Returns

    The `ngrok` process.

  Return type

    NgrokProcess

`pyngrok.process.` `_validate_path`(ngrok_path)

  Validate the given path exists, is a `ngrok` binary, and is ready to be started, otherwise raise a relevant exception.

  Parameters

    ngrok_path (str) – The path to the `ngrok` binary.

`pyngrok.process.` `capture_run_process`(ngrok_path, args)

  Start a blocking `ngrok` process with the binary at the given path and the passed args. When the process returns, so will this method, and the captured output from the process along with it.

  This method is meant for invoking `ngrok` directly (for instance, from the command line) and is not necessarily compatible with non-blocking API methods. For that, use `get_process`.

  Parameters

    - ngrok_path (str) – The path to the `ngrok` binary.

    - args (list[str]) – The args to pass to `ngrok`.

  Returns

    The output from the process.

  Return type

    str

`pyngrok.process.` `get_process`(pyngrok_config)

  Get the current `ngrok` process for the given config’s `ngrok_path`.

  If `ngrok` is not running, calling this method will first start a process with `PyngrokConfig`.

  Parameters

    pyngrok_config (PyngrokConfig) – The `pyngrok` configuration to use when interacting with the `ngrok` binary.

  Returns

    The `ngrok` process.

  Return type

    NgrokProcess

`pyngrok.process.` `is_process_running`(ngrok_path)

  Check if the `ngrok` process is currently running.

  Parameters

    ngrok_path (str) – The path to the `ngrok` binary.

  Returns

    `True` if `ngrok` is running from the given path.

`pyngrok.process.` `kill_process`(ngrok_path)

  Terminate the `ngrok` processes, if running, for the given path. This method will not block, it will just issue a kill request.

  Parameters

    ngrok_path (str) – The path to the `ngrok` binary.

`pyngrok.process.` `run_process`(ngrok_path, args)

  Start a blocking `ngrok` process with the binary at the given path and the passed args.

  This method is meant for invoking `ngrok` directly (for instance, from the command line) and is not necessarily compatible with non-blocking API methods. For that, use `get_process`.

  Parameters

    - ngrok_path (str) – The path to the `ngrok` binary.

    - args (list[str]) – The args to pass to `ngrok`.

`pyngrok.process.` `set_auth_token`(pyngrok_config, token)

  Set the `ngrok` auth token in the config file, enabling authenticated features (for instance, more concurrent tunnels, custom subdomains, etc.).

  Parameters

    - pyngrok_config (PyngrokConfig) – The `pyngrok` configuration to use when interacting with the `ngrok` binary.

    - token (str) – The auth token to set.

## Configuration

class `pyngrok.conf.` `PyngrokConfig`(ngrok_path=None, config_path=None, auth_token=None, region=None, monitor_thread=True, log_event_callback=None, startup_timeout=15, max_logs=100, request_timeout=4, start_new_session=False, reconnect_session_retries=0)

  Bases: `object`

  An object containing `pyngrok`’s configuration for interacting with the `ngrok` binary. All values are optional when it is instantiated, and default values will be used for parameters not passed.

  Use `get_default` and `set_default` to interact with the default `pyngrok_config`, or pass another instance of this object as the `pyngrok_config` keyword arg to most methods in the `ngrok` module to override the default.

      from pyngrok import conf, ngrok

      # Here we update the entire default config
      pyngrok_config = conf.PyngrokConfig(ngrok_path="/usr/local/bin/ngrok")
      conf.set_default(pyngrok_config)

      # Here we update just one variable in the default config
      conf.get_default().ngrok_path = "/usr/local/bin/ngrok"

      # Here we leave the default config as-is and pass an override
      pyngrok_config = conf.PyngrokConfig(ngrok_path="/usr/local/bin/ngrok")
      ngrok.connect(pyngrok_config=pyngrok_config)

  Variables

    - ngrok_path (str) – The path to the `ngrok` binary, defaults to the value in conf.DEFAULT_NGROK_PATH

    - config_path (str) – The path to the `ngrok` config, defaults to `None` and `ngrok` manages it.

    - auth_token (str) – An authtoken to pass to commands (overrides what is in the config).

    - region (str) – The region in which `ngrok` should start.

    - monitor_thread (bool) – Whether `ngrok` should continue to be monitored (for logs, etc.) after it startup is complete.

    - log_event_callback (types.FunctionType) – A callback that will be invoked each time `ngrok` emits a log. `monitor_thread` must be set to `True` or the function will stop being called after `ngrok` finishes starting.

    - startup_timeout (int) – The max number of seconds to wait for `ngrok` to start before timing out.

    - max_logs (int) – The max number of logs to store in `NgrokProcess`’s `logs` variable.

    - request_timeout (float) – The max timeout when making requests to `ngrok`’s API.

    - start_new_session (bool) – Passed to `subprocess.Popen` when launching `ngrok`. (Python 3 and POSIX only)

    - reconnect_session_retries (int) – The max number of times to retry establishing a new session with `ngrok` if the connection fails on startup.

`pyngrok.conf.` `get_default`()

  Get the default config to be used with methods in the `ngrok` module. To override the default individually, the `pyngrok_config` keyword arg can also be passed to most of these methods, or set a new default config with `set_default`.

  Returns

    The default `pyngrok_config`.

  Return type

    PyngrokConfig

`pyngrok.conf.` `set_default`(pyngrok_config)

  Set a new default config to be used with methods in the `ngrok` module. To override the default individually, the `pyngrok_config` keyword arg can also be passed to most of these methods.

  Parameters

    pyngrok_config (PyngrokConfig) – The new `pyngrok_config` to be used by default.

## `ngrok` Installer

`pyngrok.installer.` `_download_file`(url, retries=0, **kwargs)

  Download a file to a temporary path and emit a status to stdout (if possible) as the download progresses.

  Parameters

    - url (str) – The URL to download.

    - retries (int, optional) – The retry attempt index, if download fails.

    - kwargs (dict, optional) – Remaining `kwargs` will be passed to `urllib.request.urlopen`.

  Returns

    The path to the downloaded temporary file.

  Return type

    str

`pyngrok.installer.` `_install_ngrok_zip`(ngrok_path, zip_path)

  Extract the `ngrok` zip file to the given path.

  Parameters

    - ngrok_path (str) – The path where `ngrok` will be installed.

    - zip_path (str) – The path to the `ngrok` zip file to be extracted.

`pyngrok.installer.` `get_ngrok_bin`()

  Get the `ngrok` executable for the current system.

  Returns

    The name of the `ngrok` executable.

  Return type

    str

`pyngrok.installer.` `get_ngrok_config`(config_path, use_cache=True)

  Get the `ngrok` config from the given path.

  Parameters

    - config_path (str) – The `ngrok` config path to read.

    - use_cache (bool) – Use the cached version of the cache (if populated).

  Returns

    The `ngrok` config.

  Return type

    dict

`pyngrok.installer.` `install_default_config`(config_path, data=None)

  Install the given data to the `ngrok` config. If a config is not already present for the given path, create one. Before saving new data to the default config, validate that they are compatible with `pyngrok`.

  Parameters

    - config_path (str) – The path to where the `ngrok` config should be installed.

    - data (dict, optional) – A dictionary of things to added to the default config.

`pyngrok.installer.` `install_ngrok`(ngrok_path, **kwargs)

  Download and install the latest `ngrok` for the current system, overwriting any existing contents at the given path.

  Parameters

    - ngrok_path (str) – The path to where the `ngrok` binary will be downloaded.

    - kwargs (dict, optional) – Remaining `kwargs` will be passed to `_download_file`.

`pyngrok.installer.` `validate_config`(data)

  Validate that the given dict of config items are valid for `ngrok` and `pyngrok`.

  Parameters

    data (dict) – A dictionary of things to be validated as config items.

## Exceptions

exception `pyngrok.exception.` `PyngrokError`

  Bases: `Exception`

  Raised when a general `pyngrok` error has occurred.

exception `pyngrok.exception.` `PyngrokNgrokError`(error, ngrok_logs=None, ngrok_error=None)

  Bases: `pyngrok.exception.PyngrokError`

  Raised when an error occurs interacting directly with the `ngrok` binary.

  Variables

    - error (str) – A description of the error being thrown.

    - ngrok_logs (list[NgrokLog]) – The `ngrok` logs, which may be useful for debugging the error.

    - ngrok_error (str) – The error that caused the `ngrok` process to fail.

exception `pyngrok.exception.` `PyngrokNgrokHTTPError`(error, url, status_code, message, headers, body)

  Bases: `pyngrok.exception.PyngrokNgrokError`

  Raised when an error occurs making a request to the `ngrok` web interface. The `body` contains the error response received from `ngrok`.

  Variables

    - error (str) – A description of the error being thrown.

    - url (str) – The request URL that failed.

    - status_code (int) – The response status code from `ngrok`.

    - message (str) – The response message from `ngrok`.

    - headers (dict[str, str]) – The request headers sent to `ngrok`.

    - body (str) – The response body from `ngrok`.

exception `pyngrok.exception.` `PyngrokNgrokInstallError`

  Bases: `pyngrok.exception.PyngrokError`

  Raised when an error has occurred while downloading and installing the `ngrok` binary.

exception `pyngrok.exception.` `PyngrokNgrokURLError`(error, reason)

  Bases: `pyngrok.exception.PyngrokNgrokError`

  Raised when an error occurs when trying to initiate an API request.

  Variables

    - error (str) – A description of the error being thrown.

    - reason (str) – The reason for the URL error.

exception `pyngrok.exception.` `PyngrokSecurityError`

  Bases: `pyngrok.exception.PyngrokError`

  Raised when a `pyngrok` security error has occurred.