cut new release for ngrok-api-python

README.md

@@ -1,39 +1,32 @@
-# Unstable
-
-This library is currently unstable. We know of rough edges
-and are working to bring it to parity with our other API client
-libraries. Please feel free to try it out and let us know if you find
-it useful!
-
 # ngrok API client library for Python
 
 This library wraps the [ngrok HTTP API](https://ngrok.com/docs/api) to make it
 easier to consume in Python.
 
 ## Installation
 
-This library is published on [PyPi](https://pypi.org/project/ngrok-api/)
+This library is published on [PyPi](https://pypi.org/project/ngrok-api/):
 
     pip install ngrok-api
 
 ## Documentation
 
-A quickstart guide and a full API reference are included in the [ngrok python API documentation](https://python-api.docs.ngrok.com)
+A quickstart guide and a full API reference are included in the [ngrok python API documentation](https://python-api.docs.ngrok.com).
 
 ## Quickstart
 
 Please consult the [documentation](https://python-api.docs.ngrok.com) for additional examples.
 
     import ngrok
 
-    # construct the api client
+    # Construct the API client
     client = ngrok.Client("<API KEY>")
 
-    # list all online tunnels
+    # List all online tunnels
     for t in client.tunnels.list():
         print(t)
 
-    # create an ip policy that allows traffic from some subnets
+    # Create an IP policy that allows traffic from some subnets
     policy = client.ip_policies.create()
     for cidr in ["24.0.0.0/8", "12.0.0.0/8"]:
         client.ip_policy_rules.create(cidr=cidr, ip_policy_id=policy.id, action="allow")

doc/source/client.rst

@@ -10,14 +10,14 @@ Client object:
     import ngrok
 
     # construct the api client
-    ng = ngrok.Client("<API KEY>")
+    client = ngrok.Client("<API KEY>")
 
     # list all ip policies
-    for policy in ng.ip_policies.list():
+    for policy in client.ip_policies.list():
         print(policy)
 
     # create an ngrok agent authtoken
-    cred = ng.credentials.create()
+    cred = client.credentials.create()
     print(cred)
 
 .. automodule:: ngrok

doc/source/errors.rst

@@ -21,9 +21,9 @@ raised. Ensure that you check for it first because it is a subclass of :class:`n
 .. code-block::
 
     try:
-        c.ip_policies.get(id)
+        client.ip_policies.get(id)
     except ngrok.NotFoundError as e:
-        c.ip_policies.create(action="deny")
+        client.ip_policies.create()
     except ngrok.Error as e:
         # something else happened
 
@@ -34,9 +34,9 @@ documentation for the `list of all ngrok error codes <https://ngrok.com/docs/err
 ::
 
     try:
-        c.ip_policies.create(action="something invalid")
+        client.edges.https.create(hostports=["url-without-port.ngrok.io"])
     except ngrok.Error as e:
-        if e.error_code == "ERR_NGROK_1410":
+        if e.error_code == "ERR_NGROK_7104":
             # handle a specific condition
         else:
             raise
@@ -49,7 +49,7 @@ at that point it is best to use a naked ``except`` block or to catch a ``Runtime
 ::
 
     try:
-        c.ip_policies.create(action="something invalid")
+        client.ip_policies.create()
     except RuntimeError:
         # an unexpected network error that you could retry
 

doc/source/index.rst

@@ -31,16 +31,16 @@ object. That's it!
     import ngrok
 
     # construct the api client
-    ng = ngrok.Client("<API KEY>")
+    client = ngrok.Client("<API KEY>")
 
     # list all online tunnels
-    for t in ng.tunnels():
+    for t in client.tunnels.list():
         print(t)
 
     # create an ip policy the allows traffic from some subnets
-    policy = ng.ip_policies.create(action="allow")
+    policy = client.ip_policies.create()
     for cidr in ["24.0.0.0/8", "12.0.0.0/8"]:
-        ng.ip_policy_rules.create(cidr=cidr, ip_policy_id=policy.id)
+        client.ip_policy_rules.create(cidr=cidr, ip_policy_id=policy.id, action="allow")
 
 
 Automatic Paging
@@ -55,11 +55,11 @@ pages for you.
 
     import ngrok
 
-    ng = ngrok.Client("<API KEY>")
+    client = ngrok.Client("<API KEY>")
 
     # list all ip policies, transparently fetching additional
     # pages for you if necessary
-    for p in ng.ip_policies.list():
+    for p in client.ip_policies.list():
         print(p)
 
 
@@ -70,15 +70,18 @@ Instance methods like ``update`` and ``delete`` can be invoked on an instance of
 API object itself as well as directly without needing to first fetch the object.
 
 ::
+    import ngrok
+
+    client = ngrok.Client("<API KEY>")
 
     # update the metadata of a credential
-    cred = ng.credentials.get("cr_1kYyunEyn6XHHlqyMBLrj5nxkoz")
+    cred = client.credentials.get("cr_1kYyunEyn6XHHlqyMBLrj5nxkoz")
     cred.update(metadata=json.dumps({
         "server_name": "giraffe-1",
     }))
 
     # or do it in single call
-    cred = ng.credentials.update("cr_1kYyunEyn6XHHlqyMBLrj5nxkoz", metadata=json.dumps({
+    cred = client.credentials.update("cr_1kYyunEyn6XHHlqyMBLrj5nxkoz", metadata=json.dumps({
         "server_name": "giraffe-1",
     }))
 
@@ -93,10 +96,11 @@ section on :ref:`errors <errors>` for additional details.
 
     import ngrok
 
-    ng = ngrok.Client("<API KEY>")
+    client = ngrok.Client("<API KEY>")
 
     try:
-        ng.ip_policies.create(action="not a valid action")
+        policy = client.ip_policies.create()
+        client.ip_policy_rules.create(cidr="24.0.0.0/8", ip_policy_id=policy.id, action="not a valid action")
     except ngrok.Error as e:
         print("http status code", e.http_status_code)
         print("ngrok error code", e.error_code)

docs/_modules/ngrok/client.html

@@ -220,7 +220,7 @@ <h1>Source code for ngrok.client</h1><div class="highlight"><pre>
     <span class="k">def</span> <span class="nf">credentials</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n">CredentialsClient</span><span class="p">:</span>
         <span class="sd">"""Tunnel Credentials are ngrok agent authtokens. They authorize the ngrok</span>
 <span class="sd">        agent to connect the ngrok service as your account. They are installed with</span>
-<span class="sd">        the ``ngrok authtoken`` command or by specifying it in the ``ngrok.yml``</span>
+<span class="sd">        the ``ngrok config add-authtoken`` command or by specifying it in the ``ngrok.yml``</span>
 <span class="sd">        configuration file with the ``authtoken`` property."""</span>
         <span class="k">return</span> <span class="n">CredentialsClient</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span>
 

docs/_modules/ngrok/services.html

@@ -1038,7 +1038,7 @@ <h1>Source code for ngrok.services</h1><div class="highlight"><pre>
 <div class="viewcode-block" id="CredentialsClient"><a class="viewcode-back" href="../../credentials.html#ngrok.services.CredentialsClient">[docs]</a><span class="k">class</span> <span class="nc">CredentialsClient</span><span class="p">(</span><span class="nb">object</span><span class="p">):</span>
     <span class="sd">"""Tunnel Credentials are ngrok agent authtokens. They authorize the ngrok</span>
 <span class="sd">    agent to connect the ngrok service as your account. They are installed with</span>
-<span class="sd">    the ``ngrok authtoken`` command or by specifying it in the ``ngrok.yml``</span>
+<span class="sd">    the ``ngrok config add-authtoken`` command or by specifying it in the ``ngrok.yml``</span>
 <span class="sd">    configuration file with the ``authtoken`` property."""</span>
 
     <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">client</span><span class="p">):</span>
@@ -3457,9 +3457,9 @@ <h1>Source code for ngrok.services</h1><div class="highlight"><pre>
         <span class="bp">self</span><span class="p">,</span>
         <span class="n">cidr</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span>
         <span class="n">ip_policy_id</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span>
+        <span class="n">action</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span>
         <span class="n">description</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s2">""</span><span class="p">,</span>
         <span class="n">metadata</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s2">""</span><span class="p">,</span>
-        <span class="n">action</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span>
     <span class="p">)</span> <span class="o">-&gt;</span> <span class="n">IPPolicyRule</span><span class="p">:</span>
         <span class="sd">"""Create a new IP policy rule attached to an IP Policy.</span>
 

docs/_sources/client.rst.txt

@@ -10,14 +10,14 @@ Client object:
     import ngrok
 
     # construct the api client
-    ng = ngrok.Client("<API KEY>")
+    client = ngrok.Client("<API KEY>")
 
     # list all ip policies
-    for policy in ng.ip_policies.list():
+    for policy in client.ip_policies.list():
         print(policy)
 
     # create an ngrok agent authtoken
-    cred = ng.credentials.create()
+    cred = client.credentials.create()
     print(cred)
 
 .. automodule:: ngrok

docs/_sources/errors.rst.txt

@@ -21,9 +21,9 @@ raised. Ensure that you check for it first because it is a subclass of :class:`n
 .. code-block::
 
     try:
-        c.ip_policies.get(id)
+        client.ip_policies.get(id)
     except ngrok.NotFoundError as e:
-        c.ip_policies.create(action="deny")
+        client.ip_policies.create()
     except ngrok.Error as e:
         # something else happened
 
@@ -34,9 +34,9 @@ documentation for the `list of all ngrok error codes <https://ngrok.com/docs/err
 ::
 
     try:
-        c.ip_policies.create(action="something invalid")
+        client.edges.https.create(hostports=["url-without-port.ngrok.io"])
     except ngrok.Error as e:
-        if e.error_code == "ERR_NGROK_1410":
+        if e.error_code == "ERR_NGROK_7104":
             # handle a specific condition
         else:
             raise
@@ -49,7 +49,7 @@ at that point it is best to use a naked ``except`` block or to catch a ``Runtime
 ::
 
     try:
-        c.ip_policies.create(action="something invalid")
+        client.ip_policies.create()
     except RuntimeError:
         # an unexpected network error that you could retry
 

docs/_sources/index.rst.txt

@@ -31,16 +31,16 @@ object. That's it!
     import ngrok
 
     # construct the api client
-    ng = ngrok.Client("<API KEY>")
+    client = ngrok.Client("<API KEY>")
 
     # list all online tunnels
-    for t in ng.tunnels():
+    for t in client.tunnels.list():
         print(t)
 
     # create an ip policy the allows traffic from some subnets
-    policy = ng.ip_policies.create(action="allow")
+    policy = client.ip_policies.create()
     for cidr in ["24.0.0.0/8", "12.0.0.0/8"]:
-        ng.ip_policy_rules.create(cidr=cidr, ip_policy_id=policy.id)
+        client.ip_policy_rules.create(cidr=cidr, ip_policy_id=policy.id, action="allow")
 
 
 Automatic Paging
@@ -55,11 +55,11 @@ pages for you.
 
     import ngrok
 
-    ng = ngrok.Client("<API KEY>")
+    client = ngrok.Client("<API KEY>")
 
     # list all ip policies, transparently fetching additional
     # pages for you if necessary
-    for p in ng.ip_policies.list():
+    for p in client.ip_policies.list():
         print(p)
 
 
@@ -70,15 +70,18 @@ Instance methods like ``update`` and ``delete`` can be invoked on an instance of
 API object itself as well as directly without needing to first fetch the object.
 
 ::
+    import ngrok
+
+    client = ngrok.Client("<API KEY>")
 
     # update the metadata of a credential
-    cred = ng.credentials.get("cr_1kYyunEyn6XHHlqyMBLrj5nxkoz")
+    cred = client.credentials.get("cr_1kYyunEyn6XHHlqyMBLrj5nxkoz")
     cred.update(metadata=json.dumps({
         "server_name": "giraffe-1",
     }))
 
     # or do it in single call
-    cred = ng.credentials.update("cr_1kYyunEyn6XHHlqyMBLrj5nxkoz", metadata=json.dumps({
+    cred = client.credentials.update("cr_1kYyunEyn6XHHlqyMBLrj5nxkoz", metadata=json.dumps({
         "server_name": "giraffe-1",
     }))
 
@@ -93,10 +96,11 @@ section on :ref:`errors <errors>` for additional details.
 
     import ngrok
 
-    ng = ngrok.Client("<API KEY>")
+    client = ngrok.Client("<API KEY>")
 
     try:
-        ng.ip_policies.create(action="not a valid action")
+        policy = client.ip_policies.create()
+        client.ip_policy_rules.create(cidr="24.0.0.0/8", ip_policy_id=policy.id, action="not a valid action")
     except ngrok.Error as e:
         print("http status code", e.http_status_code)
         print("ngrok error code", e.error_code)

docs/client.html

@@ -185,14 +185,14 @@ <h1>Client<a class="headerlink" href="#client" title="Permalink to this headline
 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">ngrok</span>
 
 <span class="c1"># construct the api client</span>
-<span class="n">ng</span> <span class="o">=</span> <span class="n">ngrok</span><span class="o">.</span><span class="n">Client</span><span class="p">(</span><span class="s2">"&lt;API KEY&gt;"</span><span class="p">)</span>
+<span class="n">client</span> <span class="o">=</span> <span class="n">ngrok</span><span class="o">.</span><span class="n">Client</span><span class="p">(</span><span class="s2">"&lt;API KEY&gt;"</span><span class="p">)</span>
 
 <span class="c1"># list all ip policies</span>
-<span class="k">for</span> <span class="n">policy</span> <span class="ow">in</span> <span class="n">ng</span><span class="o">.</span><span class="n">ip_policies</span><span class="o">.</span><span class="n">list</span><span class="p">():</span>
+<span class="k">for</span> <span class="n">policy</span> <span class="ow">in</span> <span class="n">client</span><span class="o">.</span><span class="n">ip_policies</span><span class="o">.</span><span class="n">list</span><span class="p">():</span>
     <span class="nb">print</span><span class="p">(</span><span class="n">policy</span><span class="p">)</span>
 
 <span class="c1"># create an ngrok agent authtoken</span>
-<span class="n">cred</span> <span class="o">=</span> <span class="n">ng</span><span class="o">.</span><span class="n">credentials</span><span class="o">.</span><span class="n">create</span><span class="p">()</span>
+<span class="n">cred</span> <span class="o">=</span> <span class="n">client</span><span class="o">.</span><span class="n">credentials</span><span class="o">.</span><span class="n">create</span><span class="p">()</span>
 <span class="nb">print</span><span class="p">(</span><span class="n">cred</span><span class="p">)</span>
 </pre></div>
 </div>
@@ -256,7 +256,7 @@ <h1>Client<a class="headerlink" href="#client" title="Permalink to this headline
 <em class="property"><span class="pre">property</span> </em><code class="sig-name descname"><span class="pre">credentials</span></code><a class="headerlink" href="#ngrok.Client.credentials" title="Permalink to this definition">¶</a></dt>
 <dd><p>Tunnel Credentials are ngrok agent authtokens. They authorize the ngrok
 agent to connect the ngrok service as your account. They are installed with
-the <code class="docutils literal notranslate"><span class="pre">ngrok</span> <span class="pre">authtoken</span></code> command or by specifying it in the <code class="docutils literal notranslate"><span class="pre">ngrok.yml</span></code>
+the <code class="docutils literal notranslate"><span class="pre">ngrok</span> <span class="pre">config</span> <span class="pre">add-authtoken</span></code> command or by specifying it in the <code class="docutils literal notranslate"><span class="pre">ngrok.yml</span></code>
 configuration file with the <code class="docutils literal notranslate"><span class="pre">authtoken</span></code> property.</p>
 <dl class="field-list simple">
 <dt class="field-odd">Return type</dt>

docs/credentials.html

@@ -186,7 +186,7 @@ <h1>Tunnel Credentials<a class="headerlink" href="#tunnel-credentials" title="Pe
 <em class="property"><span class="pre">class</span> </em><code class="sig-prename descclassname"><span class="pre">ngrok.services.</span></code><code class="sig-name descname"><span class="pre">CredentialsClient</span></code><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">client</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/ngrok/services.html#CredentialsClient"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#ngrok.services.CredentialsClient" title="Permalink to this definition">¶</a></dt>
 <dd><p>Tunnel Credentials are ngrok agent authtokens. They authorize the ngrok
 agent to connect the ngrok service as your account. They are installed with
-the <code class="docutils literal notranslate"><span class="pre">ngrok</span> <span class="pre">authtoken</span></code> command or by specifying it in the <code class="docutils literal notranslate"><span class="pre">ngrok.yml</span></code>
+the <code class="docutils literal notranslate"><span class="pre">ngrok</span> <span class="pre">config</span> <span class="pre">add-authtoken</span></code> command or by specifying it in the <code class="docutils literal notranslate"><span class="pre">ngrok.yml</span></code>
 configuration file with the <code class="docutils literal notranslate"><span class="pre">authtoken</span></code> property.</p>
 <dl class="py method">
 <dt id="ngrok.services.CredentialsClient.create">