Documentation updates

aiocoap/transports/ws.py

@@ -49,6 +49,16 @@
   port plus 3000 (resulting in the abovementioned 8683 for 5683). If TLS server
   keys are given, the TLS server is launched on the next port after the HTTP
   server (typically 8684).
+
+Using on pyodide_
+-----------------
+
+When use  on pyodide_,
+instead of using the ``websockets`` module,
+a simplified client-only back-end is used,
+which utilizes the browser's WebSocket API.
+
+.. _pyodide: https://pyodide.org/
 """
 
 from __future__ import annotations

contrib/aiocoap-proxy.ipynb

@@ -26,7 +26,7 @@
   "cells": [
     {
       "cell_type": "code",
-      "source": "import micropip\nawait micropip.install(\"aiocoap\", pre=True)\nimport aiocoap\nctx = await aiocoap.Context.create_client_context()",
+      "source": "import micropip\nawait micropip.install(\"aiocoap\")\nimport aiocoap\nctx = await aiocoap.Context.create_client_context()",
       "metadata": {
         "trusted": true
       },
@@ -35,7 +35,7 @@
     },
     {
       "cell_type": "code",
-      "source": "req = aiocoap.Message(\n    code=aiocoap.GET,\n    proxy_scheme=\"coap\",\n    uri_host=\"coap.me\",\n    uri_path=[\"blåbærsyltetøy\"])\nreq.remote = aiocoap.message.UndecidedRemote(\"coaps+ws\", \"proxy.coap.amsuess.com\")\nprint((await ctx.request(req).response).payload.decode('utf8'))",
+      "source": "req = aiocoap.Message(\n    code=aiocoap.GET,\n    uri=\"coap://coap.me/blåbærsyltetøy\")\nreq.remote = aiocoap.message.UndecidedRemote(\"coaps+ws\", \"proxy.coap.amsuess.com\")\nreq.opt.proxy_scheme = 'coap'\nprint((await ctx.request(req).response).payload.decode('utf8'))",
       "metadata": {
         "trusted": true
       },
@@ -49,4 +49,4 @@
       ]
     }
   ]
-}
+}

contrib/aiocoap-server.ipynb

@@ -3,6 +3,39 @@
     "toc-showcode": false,
     "toc-autonumbering": false,
     "toc-showtags": false,
+    "widgets": {
+      "application/vnd.jupyter.widget-state+json": {
+        "version_major": 2,
+        "version_minor": 0,
+        "state": {
+          "5fb425d3185b4cce92be92c1375094d5": {
+            "model_name": "LayoutModel",
+            "model_module": "@jupyter-widgets/base",
+            "model_module_version": "2.0.0",
+            "state": {}
+          },
+          "63dd6a1378da41b7a73f6e3134b2fd04": {
+            "model_name": "SliderStyleModel",
+            "model_module": "@jupyter-widgets/controls",
+            "model_module_version": "2.0.0",
+            "state": {
+              "description_width": ""
+            }
+          },
+          "9d812769e6724f83ae4a6dc4839b77bd": {
+            "model_name": "FloatSliderModel",
+            "model_module": "@jupyter-widgets/controls",
+            "model_module_version": "2.0.0",
+            "state": {
+              "step": 0.1,
+              "behavior": "drag-tap",
+              "layout": "IPY_MODEL_5fb425d3185b4cce92be92c1375094d5",
+              "style": "IPY_MODEL_63dd6a1378da41b7a73f6e3134b2fd04"
+            }
+          }
+        }
+      }
+    },
     "language_info": {
       "codemirror_mode": {
         "name": "python",
@@ -26,7 +59,7 @@
   "cells": [
     {
       "cell_type": "code",
-      "source": "import micropip\nawait micropip.install(\"aiocoap[prettyprint]\", pre=True)\nimport aiocoap\nctx = await aiocoap.Context.create_client_context()",
+      "source": "import micropip\nawait micropip.install(\"aiocoap[prettyprint]\")\nimport aiocoap\nctx = await aiocoap.Context.create_client_context()",
       "metadata": {
         "trusted": true
       },
@@ -49,7 +82,7 @@
             "application/vnd.jupyter.widget-view+json": {
               "version_major": 2,
               "version_minor": 0,
-              "model_id": "437c71d0747f4f6690a93cd04b089c47"
+              "model_id": "9d812769e6724f83ae4a6dc4839b77bd"
             }
           },
           "metadata": {}
@@ -75,4 +108,4 @@
       "outputs": []
     }
   ]
-}
+}

contrib/aiocoap.ipynb

@@ -23,7 +23,7 @@
   "cells": [
     {
       "cell_type": "code",
-      "source": "import micropip\nawait micropip.install(\"aiocoap\", pre=True)\nimport aiocoap\nctx = await aiocoap.Context.create_client_context()",
+      "source": "import micropip\nawait micropip.install(\"aiocoap[prettyprint]\")\nimport aiocoap\nctx = await aiocoap.Context.create_client_context()",
       "metadata": {
         "trusted": true
       },
@@ -32,18 +32,22 @@
     },
     {
       "cell_type": "code",
-      "source": "req = aiocoap.Message(code=aiocoap.GET, uri=\"coaps+ws://rd.coap.amsuess.com/.well-known/core\")\nprint((await ctx.request(req).response).payload.decode('utf8'))",
+      "source": "req = aiocoap.Message(code=aiocoap.GET, uri=\"coaps+ws://rd.coap.amsuess.com/.well-known/core\")\nawait ctx.request(req).response",
       "metadata": {
         "trusted": true
       },
       "execution_count": 2,
       "outputs": [
         {
-          "name": "stdout",
-          "text": "</.well-known/core>;ct=\"40\",</.well-known/rd>,</rd>;ct=\"40\";rt=\"core.rd\",</endpoint-lookup/>;ct=\"40\";rt=\"core.rd-lookup-ep\";obs,</resource-lookup/>;ct=\"40\";rt=\"core.rd-lookup-res\";obs,<https://christian.amsuess.com/tools/aiocoap/#version-0.4.5.post0>;rel=\"impl-info\"\n",
-          "output_type": "stream"
+          "execution_count": 2,
+          "output_type": "execute_result",
+          "data": {
+            "text/plain": "<aiocoap.Message at 0x190e358: no mtype, 2.05 Content (no MID, token 0311) remote <WSRemote at 0x1e61de0, hostinfo rd.coap.amsuess.com, local localhost>, 1 option(s), 260 byte(s) payload>",
+            "text/html": "<details style=\"padding-left:1em\"><summary style=\"margin-left:-1em;display:list-item;\">Message with code <abbr title=\"Successful Response Code 2.05\">CONTENT</abbr>, remote &lt;WSRemote at 0x1e61de0, hostinfo rd.coap.amsuess.com, local localhost&gt;</summary>\n                <details><summary style=\"display:list-item\">1 option</summary><ol><li value=\"12\"><abbr title=\"option 12: elective, safe-to-forward, part of the cache key\">CONTENT_FORMAT</abbr>: <abbr title=\"Content format 40, named ContentFormat.LINKFORMAT\">application/link-format</abbr></ol></details><div><p style=\"color:gray;font-size:small;\">application/link-format content was re-formatted</p><pre><div class=\"highlight\"><pre><span></span><span class=\"p\">&lt;</span><span class=\"nl\">/.well-known/core</span><span class=\"p\">&gt;; </span><span class=\"na\">ct</span><span class=\"o\">=</span><span class=\"ss\">40</span><span class=\"p\">,</span>\n<span class=\"p\">&lt;</span><span class=\"nl\">/.well-known/rd</span><span class=\"p\">&gt;,</span>\n<span class=\"p\">&lt;</span><span class=\"nl\">/rd</span><span class=\"p\">&gt;; </span><span class=\"na\">ct</span><span class=\"o\">=</span><span class=\"ss\">40</span><span class=\"p\">; </span><span class=\"na\">rt</span><span class=\"o\">=</span><span class=\"ss\">core.rd</span><span class=\"p\">,</span>\n<span class=\"p\">&lt;</span><span class=\"nl\">/endpoint-lookup/</span><span class=\"p\">&gt;; </span><span class=\"na\">ct</span><span class=\"o\">=</span><span class=\"ss\">40</span><span class=\"p\">; </span><span class=\"na\">rt</span><span class=\"o\">=</span><span class=\"ss\">core.rd-lookup-ep</span><span class=\"p\">; </span><span class=\"na\">obs</span><span class=\"p\">,</span>\n<span class=\"p\">&lt;</span><span class=\"nl\">/resource-lookup/</span><span class=\"p\">&gt;; </span><span class=\"na\">ct</span><span class=\"o\">=</span><span class=\"ss\">40</span><span class=\"p\">; </span><span class=\"na\">rt</span><span class=\"o\">=</span><span class=\"ss\">core.rd-lookup-res</span><span class=\"p\">; </span><span class=\"na\">obs</span><span class=\"p\">,</span>\n<span class=\"p\">&lt;</span><span class=\"nl\">https://christian.amsuess.com/tools/aiocoap/#version-0.4.7</span><span class=\"p\">&gt;; </span><span class=\"na\">rel</span><span class=\"o\">=</span><span class=\"ss\">impl-info</span>\n</pre></div>\n</pre></div>"
+          },
+          "metadata": {}
         }
       ]
     }
   ]
-}
+}

doc/LICENSE.rst

@@ -2,3 +2,5 @@ LICENSE
 =======
 
 .. include:: ../LICENSES/MIT.txt
+
+Files in ``aiocoap/util/vendored/`` may have different (but compatible and OSI approved) licenses.

doc/faq.rst

@@ -27,8 +27,17 @@ while it is not clear where to better put them).
   (``add_reader`` for udp6, ``sockname`` extra for role reversal on simple6).
   It is known to work with uvloop_ and gbulb_.
 
+  When aiocoap is used with pyodide_
+  (that is, in a web browser, with a Python interpreter compiled through emscripten),
+  for example in a `Jupyter notebook`_,
+  the "regular" transports are not functional.
+  An alternative is provided transparently
+  in the :mod:`WebSockets transport<aiocoap.transports.ws>`.
+
 .. _uvloop: https://uvloop.readthedocs.io/
 .. _gbulb: https://github.com/nathan-hoad/gbulb
+.. _pyodide: https://pyodide.org/
+.. _`Jupyter notebook`: https://jupyter.org/try-jupyter/lab/
 
 * **How can a server be scaled up to use multiple cores?**
 
@@ -72,7 +81,7 @@ while it is not clear where to better put them).
 
 * **aiocoap fails to start if IPv6 is disabled system-wide.**
 
-  Yes. `Don't do that`__
+  Yes. `Don't do that.`__
   It is not a supported mode of operation with the default implementation.
 
   .. __: https://howtodisableipv6.com/

doc/news.rst

@@ -5,4 +5,4 @@ This summarizes the changes between released versions. For a complete change
 log, see the git history. For details on the changes, see the respective git
 commits indicated at the start of the entry.
 
-.. include:: ../NEWS
+.. include:: ../NEWS.rst

doc/tools.rst

@@ -57,6 +57,13 @@ These tools are currently present:
   discovered during a Resource Directory discovery process, but does not serve
   as the full resource directory itself and redirects the client there.
 
+* ``*.ipynb``: Jupyter notebooks
+  in which aiocoap is run in a web browser
+  and accesses the larger network through WebSockets.
+
+  These files can be uploaded to `a live version of Jupyter Lite`_.
+
 .. _gbulb: https://github.com/nathan-hoad/gbulb
 .. _Kivy: https://kivy.org/
 .. _`the asyncio pull request`: https://github.com/kivy/kivy/pull/5241
+.. _`a live version of Jupyter Lite`: https://jupyter.org/try-jupyter/lab/