Document 'auto' utility

CHANGELOG.md

@@ -1,6 +1,9 @@
 # 0.2 (2019-03-30)
 
+- Added an option to automatically resave files after loading.
+- Added an option to automatically reload files after saving.
 - Added registration system for custom class converters.
+- Added initial support for file inference via `auto(filename)`.
 
 # 0.1 (2019-01-13)
 

docs/utilities.md

@@ -0,0 +1,42 @@
+# `auto`
+
+Given an arbitrary file, this library can attempt to map its structure into a Python object synchronized back to that file. For example, a YAML file named `sample.yml` containing the following:
+
+```yaml
+names:
+- Alice
+- Bob
+numbers:
+- 1
+- 2
+```
+
+can be loaded into an object:
+
+```python
+>>> from datafiles import auto
+>>> sample = auto('sample.yml')
+>>> sample.names
+['Alice', 'Bob']
+```
+
+where modified attributes:
+
+```python
+>>> sample.numbers.append(3)
+```
+
+are automatically reflected in the file:
+
+```
+#!text hl_lines="9"
+$ cat sample.yml
+
+names:
+- Alice
+- Bob
+numbers:
+- 1
+- 2
+- 3
+```

mkdocs.yml

@@ -21,6 +21,7 @@ nav:
   - Extensions: types/extensions.md
   - Containers: types/containers.md
   - Custom Types: types/custom.md
+- Utilities: utilities.md
 - About:
   - Release Notes: about/changelog.md
   - Contributing: about/contributing.md

notebooks/file_inference.ipynb

@@ -1,9 +1,118 @@
 {
  "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Simple"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 1,
    "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Overwriting files/sample.yml\n"
+     ]
+    }
+   ],
+   "source": [
+    "%%writefile files/sample.yml\n",
+    "\n",
+    "names:\n",
+    "- Alice\n",
+    "- Bob\n",
+    "numbers:\n",
+    "- 1\n",
+    "- 2"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stderr",
+     "output_type": "stream",
+     "text": [
+      "INFO: datafiles.managers: Loading 'sample' object from 'files/sample.yml'\n"
+     ]
+    },
+    {
+     "data": {
+      "text/plain": [
+       "['Alice', 'Bob']"
+      ]
+     },
+     "execution_count": 2,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "from datafiles import auto\n",
+    "sample = auto('files/sample.yml')\n",
+    "sample.names"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stderr",
+     "output_type": "stream",
+     "text": [
+      "INFO: datafiles.managers: Saving 'sample' object to 'files/sample.yml'\n"
+     ]
+    }
+   ],
+   "source": [
+    "sample.numbers.append(3)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "names:\n",
+      "- Alice\n",
+      "- Bob\n",
+      "numbers:\n",
+      "- 1\n",
+      "- 2\n",
+      "- 3\n"
+     ]
+    }
+   ],
+   "source": [
+    "%%sh\n",
+    "\n",
+    "cat files/sample.yml"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Complex"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 5,
+   "metadata": {},
    "outputs": [
     {
      "name": "stdout",
@@ -55,7 +164,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 2,
+   "execution_count": 6,
    "metadata": {},
    "outputs": [
     {
@@ -74,7 +183,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 3,
+   "execution_count": 7,
    "metadata": {},
    "outputs": [
     {
@@ -91,7 +200,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 4,
+   "execution_count": 8,
    "metadata": {},
    "outputs": [
     {