Merge pull request OpenAssetIO#81 from feltech/work/OpenAssetIO-1257-pathToUrlWindowsMaxPath

[Docs] Long Windows paths in FilePathUrlConverter notebook

Author: feltech

examples/file_path_url_converter.ipynb

@@ -33,8 +33,8 @@
    "metadata": {
     "collapsed": false,
     "ExecuteTime": {
-     "end_time": "2024-02-19T15:10:35.668132096Z",
-     "start_time": "2024-02-19T15:10:35.661355780Z"
+     "end_time": "2024-02-22T14:42:41.840621313Z",
+     "start_time": "2024-02-22T14:42:41.826582123Z"
     }
    },
    "outputs": [],
@@ -74,8 +74,8 @@
    "metadata": {
     "collapsed": false,
     "ExecuteTime": {
-     "end_time": "2024-02-19T15:10:35.750564608Z",
-     "start_time": "2024-02-19T15:10:35.669692678Z"
+     "end_time": "2024-02-22T14:42:41.874028812Z",
+     "start_time": "2024-02-22T14:42:41.830823958Z"
     }
    },
    "outputs": [
@@ -115,8 +115,8 @@
    "metadata": {
     "collapsed": false,
     "ExecuteTime": {
-     "end_time": "2024-02-19T15:10:35.751558242Z",
-     "start_time": "2024-02-19T15:10:35.746229492Z"
+     "end_time": "2024-02-22T14:42:41.905474515Z",
+     "start_time": "2024-02-22T14:42:41.852589101Z"
     }
    },
    "outputs": [
@@ -152,8 +152,8 @@
    "metadata": {
     "collapsed": false,
     "ExecuteTime": {
-     "end_time": "2024-02-19T15:10:35.752221829Z",
-     "start_time": "2024-02-19T15:10:35.746760363Z"
+     "end_time": "2024-02-22T14:42:41.906036777Z",
+     "start_time": "2024-02-22T14:42:41.875777447Z"
     }
    },
    "outputs": [
@@ -227,8 +227,8 @@
    "metadata": {
     "collapsed": false,
     "ExecuteTime": {
-     "end_time": "2024-02-19T15:10:35.752788470Z",
-     "start_time": "2024-02-19T15:10:35.747166792Z"
+     "end_time": "2024-02-22T14:42:41.906495146Z",
+     "start_time": "2024-02-22T14:42:41.875950983Z"
     }
    },
    "outputs": [
@@ -267,8 +267,8 @@
    "metadata": {
     "collapsed": false,
     "ExecuteTime": {
-     "end_time": "2024-02-19T15:10:35.753369976Z",
-     "start_time": "2024-02-19T15:10:35.747539701Z"
+     "end_time": "2024-02-22T14:42:41.969747703Z",
+     "start_time": "2024-02-22T14:42:41.876084914Z"
     }
    },
    "outputs": [
@@ -324,8 +324,8 @@
    "metadata": {
     "collapsed": false,
     "ExecuteTime": {
-     "end_time": "2024-02-19T15:10:35.754178890Z",
-     "start_time": "2024-02-19T15:10:35.748805566Z"
+     "end_time": "2024-02-22T14:42:41.970263505Z",
+     "start_time": "2024-02-22T14:42:41.905686849Z"
     }
    },
    "outputs": [
@@ -371,9 +371,46 @@
     "collapsed": false
    },
    "source": [
-    "Note that information is lost when converting to a `file` URL, i.e.whether the path was originally a device path or not. This can have implications for device paths that cannot be normalised, e.g. going beyond the `MAX_PATH` limit. Addressing this is the subject of future work."
+    "Note that information is lost when converting to a `file` URL, i.e. whether the path was originally a device path or not. This can have implications for device paths that cannot be normalised by the Windows API. \n",
+    "\n",
+    "As a special case, paths that exceed the Windows `MAX_PATH` limit will be automatically converted to non-normalised device paths (i.e. prefixed with `\\\\?\\`):"
    ]
   },
+  {
+   "cell_type": "code",
+   "outputs": [
+    {
+     "data": {
+      "text/markdown": "> **Result:**\n> - `Long drive path: \\\\?\\C:\\w\\012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234`\n> - `Long share path: \\\\?\\UNC\\host\\share\\0123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456`"
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    }
+   ],
+   "source": [
+    "long_drive_path = converter.pathFromUrl(\n",
+    "    \"file:///C:/w/0123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890\"\n",
+    "    \"12345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234\",\n",
+    "    PathType.kWindows)\n",
+    "\n",
+    "long_unc_path = converter.pathFromUrl(\n",
+    "    \"file://host/share/\"\n",
+    "    \"01234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890\"\n",
+    "    \"12345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456\",\n",
+    "    PathType.kWindows)\n",
+    "\n",
+    "display_result((f\"Long drive path: {long_drive_path}\", f\"Long share path: {long_unc_path}\"))"
+   ],
+   "metadata": {
+    "collapsed": false,
+    "ExecuteTime": {
+     "end_time": "2024-02-22T14:42:41.970844973Z",
+     "start_time": "2024-02-22T14:42:41.905879463Z"
+    }
+   },
+   "id": "6646fff173b8364e",
+   "execution_count": 8
+  },
   {
    "cell_type": "markdown",
    "id": "eb41ffc96d1228d9",
@@ -398,13 +435,13 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 8,
+   "execution_count": 9,
    "id": "23bd55feb9d6f65b",
    "metadata": {
     "collapsed": false,
     "ExecuteTime": {
-     "end_time": "2024-02-19T15:10:35.755287822Z",
-     "start_time": "2024-02-19T15:10:35.749198579Z"
+     "end_time": "2024-02-22T14:42:41.972347420Z",
+     "start_time": "2024-02-22T14:42:41.948777138Z"
     }
    },
    "outputs": [