Metadata-Version: 2.4
Name: pyngrok
Version: 9.1.0
Summary: The complete ngrok agent for Python: programmatic tunnels for ingress, inspection, webhooks, demos, and APIs
Author-email: Alex Laird <contact@alexlaird.com>
Maintainer-email: Alex Laird <contact@alexlaird.com>
License-Expression: MIT
Project-URL: Changelog, https://github.com/alexdlaird/pyngrok/blob/main/CHANGELOG.md
Project-URL: Documentation, https://pyngrok.readthedocs.io
Project-URL: Sponsor, https://github.com/sponsors/alexdlaird
Project-URL: Source Code, https://github.com/alexdlaird/pyngrok
Keywords: tunnel,webhook,reverse-proxy,ngrok,localhost,ingress,tunneling,mcp
Classifier: Development Status :: 6 - Mature
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: OS Independent
Classifier: Operating System :: POSIX
Classifier: Operating System :: POSIX :: BSD :: FreeBSD
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: Unix
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Topic :: Internet :: Proxy Servers
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Networking
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyYAML>=6.0.3
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: coverage[toml]; extra == "dev"
Requires-Dist: psutil; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Requires-Dist: flake8-pyproject; extra == "dev"
Requires-Dist: pep8-naming; extra == "dev"
Provides-Extra: docs
Requires-Dist: Sphinx; extra == "docs"
Requires-Dist: sphinx-notfound-page; extra == "docs"
Requires-Dist: sphinx_autodoc_typehints; extra == "docs"
Requires-Dist: sphinx-substitution-extensions; extra == "docs"
Requires-Dist: sphinx-sitemap; extra == "docs"
Requires-Dist: sphinxext-opengraph; extra == "docs"
Requires-Dist: furo; extra == "docs"
Requires-Dist: mypy; extra == "docs"
Requires-Dist: types-PyYAML; extra == "docs"
Dynamic: license-file

<p align="center"><img alt="pyngrok - The complete ngrok agent for Python: programmatic tunnels for ingress, inspection, webhooks, demos, and APIs" src="https://pyngrok.readthedocs.io/en/stable/_images/logo.png" /></p>

[![Version](https://img.shields.io/pypi/v/pyngrok)](https://pypi.org/project/pyngrok)
[![PyPI - Downloads](https://img.shields.io/pypi/dm/pyngrok)](https://pypistats.org/packages/pyngrok)
[![Python Versions](https://img.shields.io/pypi/pyversions/pyngrok.svg)](https://pypi.org/project/pyngrok)
[![Coverage](https://img.shields.io/codecov/c/github/alexdlaird/pyngrok)](https://codecov.io/gh/alexdlaird/pyngrok)
[![Build](https://img.shields.io/github/actions/workflow/status/alexdlaird/pyngrok/build.yml)](https://github.com/alexdlaird/pyngrok/actions/workflows/build.yml)
[![Code Quality](https://app.codacy.com/project/badge/Grade/b055cf6e3f1745098fab86a2923730b3)](https://app.codacy.com/gh/alexdlaird/pyngrok/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)
[![Docs](https://img.shields.io/readthedocs/pyngrok)](https://pyngrok.readthedocs.io/en/stable)
[![GitHub License](https://img.shields.io/github/license/alexdlaird/pyngrok)](https://github.com/alexdlaird/pyngrok/blob/main/LICENSE)

`pyngrok` gives Python the complete [`ngrok` agent](https://ngrok.com/docs/gateway/agent), with programmatic tunnels for
ingress, inspection, webhooks, demos, and APIs. [`ngrok`](https://ngrok.com) is a reverse proxy that opens secure
tunnels from public URLs to localhost, and because `pyngrok` runs the real agent, you get everything it offers, from
traffic policies and OAuth to its web inspector and request replay, all callable from Python.

## Installation

`pyngrok` is available on [PyPI](https://pypi.org/project/pyngrok/) and can be installed
using `pip`:

```sh
pip install pyngrok
```

or `conda`:

```sh
conda install -c conda-forge pyngrok
```

That's it! `pyngrok` is now available as a package to your Python projects, and `ngrok` is now available from
the command line.

## Basic Usage

### Open a Tunnel

To open a tunnel, use the [`connect`](https://pyngrok.readthedocs.io/en/stable/api.html#pyngrok.ngrok.connect) method,
which returns a [`NgrokTunnel`](https://pyngrok.readthedocs.io/en/stable/api.html#pyngrok.ngrok.NgrokTunnel), and this
returned object has a reference to the public URL generated by `ngrok` in its [`public_url`](https://pyngrok.readthedocs.io/en/stable/api.html#pyngrok.ngrok.NgrokTunnel.public_url)
attribute.

```python
from pyngrok import ngrok

# Open a HTTP tunnel on the default port 80
# <NgrokTunnel: "https://<public_sub>.ngrok.io" -> "http://localhost:80">
http_tunnel = ngrok.connect()

# Open a SSH tunnel
# <NgrokTunnel: "tcp://0.tcp.ngrok.io:12345" -> "localhost:22">
ssh_tunnel = ngrok.connect("22", "tcp")

# Open a named tunnel from the config file
named_tunnel = ngrok.connect(name="my-config-file-tunnel")

# Open an Internal Endpoint that's load balanced
# <NgrokTunnel: "https://some-endpoint.internal" -> "http://localhost:9000">
internal_endpoint = ngrok.connect(addr="9000",
                                  url="https://some-endpoint.internal",
                                  pooling_enabled=True)
```

The [`connect`](https://pyngrok.readthedocs.io/en/stable/api.html#pyngrok.ngrok.connect) method takes `kwargs` as well,
which allows
you to pass additional tunnel configurations that are supported by `ngrok` (or the `name` of a tunnel defined in
`ngrok`'s config file), [as documented here](https://pyngrok.readthedocs.io/en/stable/#tunnel-configurations).

> **Note:** `pyngrok` unifies `ngrok`'s "tunnel" (v2) and "endpoint" (v3) concepts behind a single API: `connect()`
> returns an `NgrokTunnel` and handles the differences for you through the `config_version` you set. All `ngrok` 
> features are available to you through this. For v3-specific Endpoints,
> see [Using v3 Endpoints](https://pyngrok.readthedocs.io/en/stable/#using-v3-endpoints).

### `ngrok`'s API

The [`api`](https://pyngrok.readthedocs.io/en/stable/api.html#pyngrok.ngrok.api) method allows you to use the local
`ngrok` agent to make requests against [the `ngrok` API](https://ngrok.com/docs/agent/cli-api/), if you
have [set an API key](https://pyngrok.readthedocs.io/en/stable/#setting-the-authtoken-or-api-key).
For example, here's how you would reserve a `ngrok` domain, then create a Cloud Endpoint with an associated traffic
policy:

```python
from pyngrok import ngrok

domain = "some-domain.ngrok.dev"
ngrok.api("reserved-domains", "create",
          "--domain", domain)
ngrok.api("endpoints", "create",
          "--bindings", "public",
          "--url", f"https://{domain}",
          "--traffic-policy-file", "policy.yml")
```

### Command Line Usage

This package puts the default `ngrok` binary on your path, so all features of `ngrok` are
available on the command line.

```sh
ngrok http 80
```

For details on how to fully leverage `ngrok` from the command line,
see [`ngrok`'s official documentation](https://ngrok.com/docs/agent/cli/).

## Documentation

For more advanced usage, `pyngrok`'s official documentation is available
on [Read the Docs](https://pyngrok.readthedocs.io).

### Integration Examples

- [Flask](https://pyngrok.readthedocs.io/en/stable/integrations.html#flask)
- [Django](https://pyngrok.readthedocs.io/en/stable/integrations.html#django)
- [MCP Servers](https://pyngrok.readthedocs.io/en/stable/mcp.html)
- [Docker](https://pyngrok.readthedocs.io/en/stable/integrations.html#docker)
- [Google Colab](https://pyngrok.readthedocs.io/en/stable/integrations.html#google-colaboratory)
- [End-to-End Testing](https://pyngrok.readthedocs.io/en/stable/integrations.html#end-to-end-testing)

## Contributing

If you would like to get involved, be sure to review
the [Contribution Guide](https://github.com/alexdlaird/pyngrok/blob/main/CONTRIBUTING.rst).

Want to contribute financially? If you've found `pyngrok` useful, [sponsorship](https://github.com/sponsors/alexdlaird)
would also be greatly appreciated!
