Update documentation after fsspec rewrite (#30)

Updated documentation, including example notebooks.

Added `CerealReader` and `CerealWriter` protocols to public API (to help
with typing).

Author: NowanIlfideme

README.md

@@ -10,24 +10,29 @@ brings many changes and improvements, including a
 
 This package, `pydantic-cereal`, is a small extension package that enables users to serialize Pydantic
 models with "arbitrary" (non-JSON-fiendly) types to "arbitrary" file-system-like locations.
-It uses [`fsspec`](https://filesystem-spec.readthedocs.io/en/latest/) and
-[`universal_pathlib`](https://pypi.org/project/universal-pathlib/) to support generic file systems.
+It uses [`fsspec`](https://filesystem-spec.readthedocs.io/en/latest/) to support generic file systems.
 Writing a custom writer (serializer) and reader (loader) with `fsspec` URIs is quite straightforward.
+You can also use [`universal-pathlib`](https://pypi.org/project/universal-pathlib/)'s
+`UPath` with `pydantic-cereal`.
 
-See the [full documentation here](https://pydantic-cereal.readthedocs.io/).
+📘 See the [full documentation here](https://pydantic-cereal.readthedocs.io/). 📘
 
 ## Usage Example
 
-For most uses, you only need the `Cereal` class and `fsspec` or `upath`.
+See the [minimal pure-Python example](./docs/examples/minimal.ipynb) to learn how to wrap your own type.
+Below is a preview of this example.
 
 ```python
-from upath import UPath  # based on `fsspec`, used for `pathlib.Path`-like interface
+from fsspec import AbstractFileSystem
 from pydantic import BaseModel, ConfigDict
+
 from pydantic_cereal import Cereal
 
 cereal = Cereal()  # This is a global variable
 
 
+# Create and "register" a custom type
+
 class MyType(object):
     """My custom type, which isn't a Pydantic model."""
 
@@ -38,29 +43,24 @@ class MyType(object):
         return f"MyType({self.value})"
 
 
-# Create reader and writer from an fsspec URI
-
-def my_reader(uri: str) -> MyType:
+def my_reader(fs: AbstractFileSystem, path: str) -> MyType:
     """Read a MyType from an fsspec URI."""
-    return MyType(value=UPath(uri).read_text())
+    return MyType(value=fs.read_text(path))  # type: ignore
 
 
-def my_writer(obj: MyType, uri: str) -> None:
+def my_writer(obj: MyType, fs: AbstractFileSystem, path: str) -> None:
     """Write a MyType object to an fsspec URI."""
-    UPath(uri).write_text(obj.value)
-
+    fs.write_text(path, obj.value)
 
-# "Register" this type with pydantic-cereal
 MyWrappedType = cereal.wrap_type(MyType, reader=my_reader, writer=my_writer)
-# NOTE: Your type isn't modified, we just apply `Annotated` with a custom serializer and validator
 
 
-# Use the wrapped type as the fields of your Pydantic model
+# Use type within Pydantic model
 
 class MyModel(BaseModel):
     """My custom Pydantic model."""
 
-    model_config = ConfigDict(arbitrary_types_allowed=True)  # Pydantic configuration
+    config = ConfigDict(arbitrary_types_allowed=True)  # Pydantic configuration
     fld: MyWrappedType
 
 
@@ -76,5 +76,4 @@ assert isinstance(obj, MyModel)
 assert isinstance(obj.fld, MyType)
 ```
 
-For more detailed discussion, see the [minimal pure-Python example](./docs/examples/minimal.ipynb) or
-the [Pandas dataframe example](./docs/examples/pandas.ipynb)
+For wrapping 3rd-party libraries, see the [Pandas dataframe example](./docs/examples/pandas.ipynb).

docs/examples/minimal.ipynb

@@ -21,10 +21,9 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "\"\"\"Minimal imports.\"\"\"\n",
+    "\"\"\"Minimal imports to get started.\"\"\"\n",
     "\n",
-    "from typing import NewType\n",
-    "from upath import UPath\n",
+    "from fsspec import AbstractFileSystem\n",
     "from pydantic import BaseModel, ConfigDict\n",
     "from pydantic_cereal import Cereal\n",
     "\n",
@@ -35,7 +34,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "We have a custom type `MyType`, in this case it's just an alias for `str`:"
+    "We have a custom type `MyType`, in this case it's just an wrapper for a `str`:"
    ]
   },
   {
@@ -44,15 +43,29 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "MyType = NewType(\"MyType\", str)  # actually `str`, but type checker has special semantics "
+    "class MyType(object):\n",
+    "    \"\"\"My custom type, which isn't a Pydantic model.\"\"\"\n",
+    "\n",
+    "    def __init__(self, value: str):\n",
+    "        \"\"\"Initialize the object.\"\"\"\n",
+    "        self.value = str(value)\n",
+    "\n",
+    "    def __repr__(self) -> str:\n",
+    "        \"\"\"Represent the string.\"\"\"\n",
+    "        return f\"MyType({self.value})\"\n",
+    "\n",
+    "    def __str__(self) -> str:\n",
+    "        \"\"\"Return the internal string.\"\"\"\n",
+    "        return str(self.value)"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
     "We must add reader and writer classes for it. \n",
-    "These must accept [`fsspec`](https://filesystem-spec.readthedocs.io/en/latest/) URIs as inputs.\n",
+    "These must accept [`fsspec`](https://filesystem-spec.readthedocs.io/en/latest/) file system\n",
+    "and path (within that filesystem) as inputs.\n",
     "We can register these with our `cereal` object by creating a wrapped (`Annotated`) type."
    ]
   },
@@ -62,13 +75,20 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "def my_reader(uri: str) -> MyType:\n",
-    "    \"\"\"Read the object from an fsspec URI.\"\"\"\n",
-    "    return MyType(UPath(uri).read_text())\n",
+    "def my_reader(fs: AbstractFileSystem, path: str) -> MyType:\n",
+    "    \"\"\"Read a MyType from an fsspec URI.\"\"\"\n",
+    "    res = fs.read_text(path)\n",
+    "    if isinstance(res, bytes):\n",
+    "        res = res.decode(\"utf8\")\n",
+    "    else:\n",
+    "        res = str(res)\n",
+    "    return MyType(value=res)\n",
+    "\n",
+    "\n",
+    "def my_writer(obj: MyType, fs: AbstractFileSystem, path: str) -> None:\n",
+    "    \"\"\"Write a MyType object to an fsspec URI.\"\"\"\n",
+    "    fs.write_text(path, obj.value)\n",
     "\n",
-    "def my_writer(obj: MyType, uri: str) -> None:\n",
-    "    \"\"\"Write the object to an fsspec URI.\"\"\"\n",
-    "    UPath(uri).write_text(obj)\n",
     "\n",
     "MyWrappedType = cereal.wrap_type(MyType, reader=my_reader, writer=my_writer)"
    ]
@@ -145,7 +165,7 @@
     {
      "data": {
       "text/plain": [
-       "MemoryPath('memory://example_model/')"
+       "'/example_model'"
       ]
      },
      "execution_count": 7,
@@ -172,7 +192,7 @@
     {
      "data": {
       "text/plain": [
-       "'my_field'"
+       "MyType(my_field)"
       ]
      },
      "execution_count": 8,
@@ -201,7 +221,7 @@
     {
      "data": {
       "text/plain": [
-       "'my_field'"
+       "MyType(my_field)"
       ]
      },
      "execution_count": 9,
@@ -224,22 +244,40 @@
    "cell_type": "code",
    "execution_count": 10,
    "metadata": {},
+   "outputs": [],
+   "source": [
+    "from fsspec.implementations.memory import MemoryFileSystem  # noqa"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 11,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "fs = MemoryFileSystem()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 12,
+   "metadata": {},
    "outputs": [
     {
      "data": {
       "text/plain": [
-       "[MemoryPath('memory://example_model/51c07fc879fa403993ba780d9ff29b52'),\n",
-       " MemoryPath('memory://example_model/model.json'),\n",
-       " MemoryPath('memory://example_model/model.schema.json')]"
+       "['/example_model/9048f517f71f434aad4a5481f3b2b3d4',\n",
+       " '/example_model/model.json',\n",
+       " '/example_model/model.schema.json']"
       ]
      },
-     "execution_count": 10,
+     "execution_count": 12,
      "metadata": {},
      "output_type": "execute_result"
     }
    ],
    "source": [
-    "list(UPath(\"memory://example_model\").glob(\"*\"))"
+    "fs.glob(\"example_model/*\")"
    ]
   },
   {

docs/examples/pandas.ipynb

@@ -104,7 +104,7 @@
     {
      "data": {
       "text/plain": [
-       "MemoryPath('memory://example_model/')"
+       "'/example_model'"
       ]
      },
      "execution_count": 5,
@@ -273,24 +273,35 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 8,
+   "execution_count": 9,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from fsspec.implementations.memory import MemoryFileSystem  # noqa\n",
+    "\n",
+    "fs = MemoryFileSystem()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 10,
    "metadata": {},
    "outputs": [
     {
      "data": {
       "text/plain": [
-       "[MemoryPath('memory://example_model/example_model'),\n",
-       " MemoryPath('memory://example_model/model.json'),\n",
-       " MemoryPath('memory://example_model/model.schema.json')]"
+       "['/example_model/3f084fb6b6024e8da54fb231e655c8ea',\n",
+       " '/example_model/model.json',\n",
+       " '/example_model/model.schema.json']"
       ]
      },
-     "execution_count": 8,
+     "execution_count": 10,
      "metadata": {},
      "output_type": "execute_result"
     }
    ],
    "source": [
-    "list(UPath(\"memory://example_model\").glob(\"*\"))"
+    "fs.glob(\"example_model/*\")"
    ]
   },
   {