fixes #249

Author: jph00

README.md

@@ -51,7 +51,7 @@ For more details, including a link to the full documentation and source code, us
 doc(coll_repr)
 ```
 
-<img width="499" src="nbs/images/att_00000.png" align="left">
+<img width="499" src="nbs/images/att_00000.png" style="max-width: 499px">
 
 The documentation also contains links to any related functions or classes, which appear like this: `coll_repr` (in the notebook itself you will just see a word with back-ticks around it; the links are auto-generated in the documentation site). The documentation will generally show one or more examples of use, along with any background context necessary to understand them. As you'll see, the examples for each function and method are shown as tests, rather than example outputs, so let's start by explaining that. 
 

fastcore/_nbdev.py

@@ -158,6 +158,7 @@
          "Path.mk_write": "03_xtras.ipynb",
          "Path.ls": "03_xtras.ipynb",
          "Path.__repr__": "03_xtras.ipynb",
+         "autostart": "03_xtras.ipynb",
          "time_events": "03_xtras.ipynb",
          "stringfmt_names": "03_xtras.ipynb",
          "PartialFormatter": "03_xtras.ipynb",

fastcore/xtras.py

@@ -2,7 +2,7 @@
 
 __all__ = ['dict2obj', 'obj2dict', 'repr_dict', 'is_listy', 'shufflish', 'mapped', 'IterLen', 'ReindexCollection',
            'maybe_open', 'image_size', 'bunzip', 'join_path_file', 'loads', 'untar_dir', 'repo_details', 'run',
-           'open_file', 'save_pickle', 'load_pickle', 'time_events', 'stringfmt_names', 'PartialFormatter',
+           'open_file', 'save_pickle', 'load_pickle', 'autostart', 'time_events', 'stringfmt_names', 'PartialFormatter',
            'partial_format', 'utc2local', 'local2utc', 'trace', 'round_multiple', 'modified_env', 'ContextManagers',
            'str2bool', 'sort_by_run']
 
@@ -222,8 +222,19 @@ def __repr__(self:Path):
     return f"Path({self.as_posix()!r})"
 
 # Cell
+def autostart(g):
+    "Decorator that automatically starts a generator"
+    @functools.wraps(g)
+    def f():
+        r = g()
+        next(r)
+        return r
+    return f
+
+# Cell
+@autostart
 def time_events():
-    "A simple event timer implemented as a coroutine"
+    "An event timer implemented as a coroutine"
     start,events = default_timer(),0
     while True: events += (yield events,events/(default_timer()-start)) or 0
 
@@ -237,6 +248,7 @@ def stringfmt_names(s:str)->list:
 
 # Cell
 class PartialFormatter(string.Formatter):
+    "A `string.Formatter` that doesn't error on missing fields, and tracks missing fields and unused args"
     def __init__(self):
         self.missing = set()
         super().__init__()

nbs/03_xtras.ipynb

@@ -618,7 +618,7 @@
     {
      "data": {
       "text/plain": [
-       "['d', 'h', 'g', 'a', 'c', 'f', 'e', 'b']"
+       "['g', 'a', 'b', 'c', 'e', 'f', 'd', 'h']"
       ]
      },
      "execution_count": null,
@@ -1326,8 +1326,26 @@
    "outputs": [],
    "source": [
     "#export\n",
+    "def autostart(g):\n",
+    "    \"Decorator that automatically starts a generator\"\n",
+    "    @functools.wraps(g)\n",
+    "    def f():\n",
+    "        r = g()\n",
+    "        next(r)\n",
+    "        return r\n",
+    "    return f"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "#export\n",
+    "@autostart\n",
     "def time_events():\n",
-    "    \"A simple event timer implemented as a coroutine\"\n",
+    "    \"An event timer implemented as a coroutine\"\n",
     "    start,events = default_timer(),0\n",
     "    while True: events += (yield events,events/(default_timer()-start)) or 0"
    ]
@@ -1336,7 +1354,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "This is convenient for tracking the frequency of events. Call `send(None)` to start the timer, and then call `send(n)` any time you want to add `n` events to the counter. Pass the object to `next()` to get a tuple of the number of events and the frequency/second."
+    "This is convenient for tracking the frequency of events. Call `send(n)` any time you want to add `n` events to the counter. Pass the object to `next()` to get a tuple of the number of events and the frequency/second."
    ]
   },
   {
@@ -1348,18 +1366,18 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "# Events: 10, Freq/sec: 64.50\n"
+      "# Events: 10, Freq/sec: 80.30\n"
      ]
     }
    ],
    "source": [
     "# Random wait function for testing `time_events`\n",
     "def _randwait(): yield from (sleep(random.random()/30) for _ in range(10))\n",
     "\n",
-    "c = time_events()\n",
-    "c.send(None)                     # Start timer by sending `None`\n",
+    "c = time_events()                # Start timer\n",
     "for o in _randwait(): c.send(1)  # Send an event\n",
-    "events,freq = next(c)            # `next` returns counter values\n",
+    "events,freq = next(c)            # Return counter values\n",
+    "c.close()                        # Close when done\n",
     "print(f'# Events: {events}, Freq/sec: {freq:.02f}')"
    ]
   },
@@ -1403,6 +1421,7 @@
    "source": [
     "#export\n",
     "class PartialFormatter(string.Formatter):\n",
+    "    \"A `string.Formatter` that doesn't error on missing fields, and tracks missing fields and unused args\"\n",
     "    def __init__(self):\n",
     "        self.missing = set()\n",
     "        super().__init__()\n",
@@ -1417,6 +1436,32 @@
     "        self.xtra = filter_keys(kwargs, lambda o: o not in used)"
    ]
   },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/markdown": [
+       "<h4 id=\"PartialFormatter\" class=\"doc_header\"><code>class</code> <code>PartialFormatter</code><a href=\"\" class=\"source_link\" style=\"float:right\">[source]</a></h4>\n",
+       "\n",
+       "> <code>PartialFormatter</code>() :: `Formatter`\n",
+       "\n",
+       "A `string.Formatter` that doesn't error on missing fields, and tracks missing fields and unused args"
+      ],
+      "text/plain": [
+       "<IPython.core.display.Markdown object>"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    }
+   ],
+   "source": [
+    "show_doc(PartialFormatter, title_level=4)"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,