Metadata-Version: 2.1
Name: pyngrok
Version: 1.3.7
Summary: A Python wrapper for Ngrok.
Home-page: https://github.com/alexdlaird/pyngrok
Author: Alex Laird
Author-email: contact@alexlaird.com
License: MIT
Download-URL: https://github.com/alexdlaird/pyngrok/archive/1.3.7.tar.gz
Description: # pyngrok - a Python wrapper for ngrok
        
        [![PyPI version](https://badge.fury.io/py/pyngrok.svg)](https://badge.fury.io/py/pyngrok)
        [![image](https://img.shields.io/pypi/pyversions/pyngrok.svg)](https://pypi.org/project/pyngrok/)
        [![image](https://img.shields.io/pypi/implementation/pyngrok.svg)](https://pypi.org/project/pyngrok/)
        [![codecov](https://codecov.io/gh/alexdlaird/pyngrok/branch/master/graph/badge.svg)](https://codecov.io/gh/alexdlaird/pyngrok)
        [![Build Status](https://travis-ci.org/alexdlaird/pyngrok.svg?branch=master)](https://travis-ci.org/alexdlaird/pyngrok)
        
        `pyngrok` is a Python wrapper for [ngrok](https://ngrok.com/) that manages its own binary and puts
        it on our path, making `ngrok` readily available from anywhere on the command line and via a
        convenient Python API.
        
        ## install
        
        `pyngrok` is available on [PyPI](https://pypi.org/project/pyngrok/) and can be installed
        using `pip`.
        
        ```sh
        pip install pyngrok
        ```
        
        That's it! `pyngrok` is now available [as a package to our Python projects](#open-a-tunnel),
        and `ngrok` is now available [from the command line](#command-line-usage).
        
        ## open a tunnel
        
        To open a tunnel, use the `connect()` method, which returns the public URL generated by `ngrok`.
        
        ```python
        from pyngrok import ngrok
        
        # Open a tunnel on the default port 80
        public_url = ngrok.connect()
        ```
        
        The `connect()` method can also take an `options` parameter, which allows us to pass additional
        options that are [supported by ngrok](https://ngrok.com/docs#tunnel-definitions).
        
        ## get active tunnels
        
        It can be useful to ask the `ngrok` client what tunnels are currently open. This can be
        accomplished with the `get_tunnels()` method, which returns a list of `NgrokTunnel` objects.
        
        ```python
        from pyngrok import ngrok
        
        tunnels = ngrok.get_tunnels()
        # A public ngrok URL that tunnels to port 80 (ex. http://<public_sub>.ngrok.io)
        public_url = tunnels[0].public_url
        ```
        
        ## closing a tunnel
        
        All open tunnels will automatically be closed when the Python process terminates, but we can
        also close them manually.
        
        ```python
        from pyngrok import ngrok
        
        public_url = "http://<public_sub>.ngrok.io"
        
        ngrok.disconnect(public_url)
        ```
        
        ## the ngrok process
        
        Opening a tunnel will start the `ngrok` process. This process will remain alive, and the tunnels
        open, until `ngrok.kill()` is invoked, or until the Python process terminates.
        
        If we are building a short-lived app, for instance a CLI, we may want to block on the `ngrok`
        process so tunnels stay open until the user intervenes. We can do that by accessing the `NgrokProcess`.
        
        ```python
        from pyngrok import ngrok
        
        ngrok_process = ngrok.get_ngrok_process()
        # Block until CTRL-C or some other terminating event
        ngrok_process.process.wait()
        ```
        
        The `NgrokProcess` also contains an `api_url` variable, usually initialized to
        `http://127.0.0.1:4040`, from which we can access the [ngrok client API](https://ngrok.com/docs#client-api).
        
        If some feature we need is not available in this package, the client API is accessible to us via the
        `api_request()` method. Additionally, the `NgrokTunnel` objects expose a `uri` variable, which contains
        the relative path used to manipulate that resource against the client API. This package also gives us
        access to `ngrok` from the command line, [as shown below](#command-line-usage).
        
        ## other useful configuration
        
        ### authtoken
        
        Running `ngrok` with an auth token enables additional features available on our account (for
        instance, the ability to open more tunnels concurrently). We can obtain our auth token from
        the [ngrok dashboard](https://dashboard.ngrok.com) and install it like this:
        
        ```python
        from pyngrok import ngrok
        
        ngrok.set_auth_token("<NGROK_AUTH_TOKEN>")
        
        # Once an auth token is set, we are able to open multiple tunnels at the same time
        ngrok.connect()
        ngrok.connect(8000)
        ```
        
        This will set the auth token in the config file. We can also set it in a one-off fashion by
        setting it for [the "auth" key](https://ngrok.com/docs#tunnel-definitions) of the `options` parameter
        passed to `connect()`.
        
        ### config file
        
        The default [`ngrok` config file](https://ngrok.com/docs#config) lives in the home
        directory's `.ngrok2` folder. We can change this in one of two ways. Either pass the
        `config_path` parameter to methods:
        
        ```python
        from pyngrok import ngrok
        
        CONFIG_PATH = "/opt/ngrok/config.yml"
        
        ngrok.connect(config_path=CONFIG_PATH)
        ```
        
        or override the `DEFAULT_CONFIG_PATH` variable:
        
        ```python
        from pyngrok import ngrok
        
        ngrok.DEFAULT_CONFIG_PATH = "/opt/ngrok/config.yml"
        
        ngrok.set_auth_token("<NGROK_AUTH_TOKEN>")
        ```
        
        ### binary path
        
        The `pyngrok` package manages its own `ngrok` binary. However, we can use our `ngrok` binary if we
        want in one of two ways.  Either pass the `ngrok_path` parameter to methods:
        
        ```python
        from pyngrok import ngrok
        
        NGROK_PATH = "/usr/local/bin/ngrok"
        
        ngrok.get_tunnels(ngrok_path=NGROK_PATH)
        ```
        
        or override the `DEFAULT_NGROK_PATH` variable:
        
        ```python
        from pyngrok import ngrok
        
        ngrok.DEFAULT_NGROK_PATH = "/usr/local/bin/ngrok"
        
        ngrok.connect()
        ```
        
        ## command line usage
        
        This package puts the default `ngrok` binary on our path, so all features of `ngrok` are also
        available on the command line.
        
        ```sh
        ngrok http 80
        ```
        
        For details on how to fully leverage command line usage, see [ngrok's official documentation](https://ngrok.com/docs).
        
        ## contributing
        
        If you find issues, [report them on GitHub](https://github.com/alexdlaird/pyngrok/issues). Pull
        requests for fixes and features are also warmly welcomed.
        
Keywords: ngrok,tunnel,tunneling,webhook,localhost
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Development Status :: 5 - Production/Stable
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX
Classifier: Operating System :: Unix
Requires-Python: >=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*
Description-Content-Type: text/markdown
