aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorEugene Triguba <hello@eugenetriguba.com>2026-05-22 00:34:31 +0000
committerEugene Triguba <hello@eugenetriguba.com>2026-05-22 00:34:31 +0000
commit265ae71a7717062d1a108949c6ae920057063569 (patch)
tree6eef78570a5a1f7cb8428c15f628626d43600e60
parentAdd clean_nb (diff)
downloadnb-265ae71a7717062d1a108949c6ae920057063569.zip
Fix export annotations to use NotebookNode
-rw-r--r--nb/export.py38
-rw-r--r--nbs/export.ipynb311
2 files changed, 306 insertions, 43 deletions
diff --git a/nb/export.py b/nb/export.py
index c2a4748..e20053d 100644
--- a/nb/export.py
+++ b/nb/export.py
@@ -2,16 +2,21 @@
# cell: 96525ac4
import enum,pathlib,re
+from pathlib import Path
from typing import IO
import nbformat
+from nbformat import NotebookNode
+
+# cell: 29a65b22
+type PathOrFileLike = str|Path|IO[str]
# cell: 27202360
def read_nb(
- fp:str|IO[str], # a path or file-like object to read the notebook from
- v:int=4, # the notebook format major version to read the notebook as
-)->dict:
- "Read in a notebook as a dictionary."
+ fp:PathOrFileLike, # a path or file-like object to read the notebook from
+ v:int=4, # the notebook format major version to read the notebook as
+)->NotebookNode:
+ "Read in a notebook as a dictionary-like NotebookNode."
return nbformat.read(fp, as_version=v)
# cell: 1ee0d459
@@ -23,9 +28,9 @@ class CellType(enum.StrEnum):
# cell: 133ebd88
def filter_cells(
- nb:dict, # A notebook that has been read in via `read_nb`
- ct:CellType, # The cells to filter down to
-)->list[dict]:
+ nb:NotebookNode, # A notebook that has been read in via `read_nb`.
+ ct:CellType, # The cells to filter down to.
+)->list[NotebookNode]:
"Retrieve specific cell types from a notebook."
return list(filter(lambda c: c['cell_type'] == ct, nb['cells']))
@@ -59,12 +64,12 @@ def strip_directives(src:str|list[str])->str:
return "\n".join(filter(lambda l: not has_directive(l), src))
# cell: d1f32654
-def is_cell_exported(cell:dict)->bool:
+def is_cell_exported(cell:NotebookNode)->bool:
"Check whether the code cell should be exported."
return any(DIRECTIVE_EXPORT_RE.match(l) for l in cell['source'].splitlines())
# cell: ddc5c9e6
-def get_default_export(cells:list[dict])->str:
+def get_default_export(cells:list[NotebookNode])->str:
"Retrieve the `default_exp` directive argument from a list of cells."
matches = [
m.group('module')
@@ -78,10 +83,11 @@ def get_default_export(cells:list[dict])->str:
# cell: 9ce855f0
def find_cells_to_export(
- fp:str|IO[str], # a path or file-like object to read the notebook from
-)->tuple[str,list[dict]]: # returns the module name and list of cells to export
+ fp:PathOrFileLike|NotebookNode, # Where to read the notebook from.
+)->tuple[str,list[NotebookNode]]: # Returns the module name and list of cells to export.
"Find the code cells in an ipynb file to export out."
- code_cells = filter_cells(read_nb(fp), CellType.CODE)
+ if not isinstance(fp, NotebookNode): fp = read_nb(fp)
+ code_cells = filter_cells(fp, CellType.CODE)
module = get_default_export(code_cells)
cells = [
{**c, 'source': strip_directives(c['source'])}
@@ -113,15 +119,15 @@ def mk_py_mod_scaffold(
# cell: f3ab7819
def export_nb(
- fp:str|IO[str], # The notebook to export
- src_dir:str|pathlib.Path='.', # The source directory to export the Python module to.
+ fp:PathOrFileLike|NotebookNode, # The notebook to export.
+ src_dir:str|Path='.', # The source directory to export the Python module to.
):
"Export the exportable code cells to a Python file."
module, cells = find_cells_to_export(fp)
mk_py_mod_scaffold(module, src_dir)
- exp_path = (pathlib.Path(src_dir)/module).with_suffix('.py')
+ exp_path = (Path(src_dir)/module).with_suffix('.py')
src = '\n'.join(
['# AUTOGENERATED! DO NOT EDIT!\n'] +
list(map(lambda c: fmt_export_cell(c)['source'], cells))
)
- pathlib.Path(exp_path).write_text(src)
+ Path(exp_path).write_text(src)
diff --git a/nbs/export.ipynb b/nbs/export.ipynb
index f1618f2..3084d3e 100644
--- a/nbs/export.ipynb
+++ b/nbs/export.ipynb
@@ -19,9 +19,11 @@
"source": [
"#| export\n",
"import enum,pathlib,re\n",
+ "from pathlib import Path\n",
"from typing import IO\n",
"\n",
- "import nbformat"
+ "import nbformat\n",
+ "from nbformat import NotebookNode"
]
},
{
@@ -31,7 +33,7 @@
"metadata": {},
"outputs": [],
"source": [
- "import os,tempfile\n",
+ "import os,json,tempfile\n",
"from io import StringIO"
]
},
@@ -108,17 +110,28 @@
{
"cell_type": "code",
"execution_count": null,
+ "id": "29a65b22",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "#| export\n",
+ "type PathOrFileLike = str|Path|IO[str]"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
"id": "27202360",
"metadata": {},
"outputs": [],
"source": [
"#| export\n",
"def read_nb(\n",
- " fp:str|IO[str], # a path or file-like object to read the notebook from\n",
- " v:int=4, # the notebook format major version to read the notebook as\n",
- ")->dict:\n",
- " \"Read in a notebook as a dictionary.\"\n",
- " return nbformat.read(fp, as_version=v)"
+ " fp:PathOrFileLike, # Where to read the notebook from.\n",
+ " v:int=4, # The notebook format major version to read the notebook as.\n",
+ ")->NotebookNode:\n",
+ " \"Read in a notebook as a dictionary-like NotebookNode.\"\n",
+ " return nbformat.read(fp, as_version=v)\n"
]
},
{
@@ -128,8 +141,10 @@
"metadata": {},
"outputs": [],
"source": [
- "nb = read_nb('export.ipynb')\n",
- "assert list(nb.keys()) == ['cells', 'metadata', 'nbformat', 'nbformat_minor']"
+ "for fp in ['export.ipynb', Path('export.ipynb')]:\n",
+ " nb = read_nb(fp)\n",
+ " assert list(nb.keys()) == ['cells', 'metadata', 'nbformat', 'nbformat_minor']\n",
+ " assert type(nb) == NotebookNode"
]
},
{
@@ -187,9 +202,9 @@
"source": [
"#| export\n",
"def filter_cells(\n",
- " nb:dict, # A notebook that has been read in via `read_nb`\n",
- " ct:CellType, # The cells to filter down to\n",
- ")->list[dict]:\n",
+ " nb:NotebookNode, # A notebook that has been read in via `read_nb`.\n",
+ " ct:CellType, # The cells to filter down to.\n",
+ ")->list[NotebookNode]:\n",
" \"Retrieve specific cell types from a notebook.\"\n",
" return list(filter(lambda c: c['cell_type'] == ct, nb['cells']))"
]
@@ -589,7 +604,7 @@
"outputs": [],
"source": [
"#| export\n",
- "def is_cell_exported(cell:dict)->bool:\n",
+ "def is_cell_exported(cell:NotebookNode)->bool:\n",
" \"Check whether the code cell should be exported.\"\n",
" return any(DIRECTIVE_EXPORT_RE.match(l) for l in cell['source'].splitlines())"
]
@@ -616,7 +631,7 @@
"outputs": [],
"source": [
"#| export\n",
- "def get_default_export(cells:list[dict])->str:\n",
+ "def get_default_export(cells:list[NotebookNode])->str:\n",
" \"Retrieve the `default_exp` directive argument from a list of cells.\"\n",
" matches = [\n",
" m.group('module')\n",
@@ -656,10 +671,11 @@
"source": [
"#| export\n",
"def find_cells_to_export(\n",
- " fp:str|IO[str], # a path or file-like object to read the notebook from\n",
- ")->tuple[str,list[dict]]: # returns the module name and list of cells to export\n",
+ " fp:PathOrFileLike|NotebookNode, # Where to read the notebook from.\n",
+ ")->tuple[str,list[NotebookNode]]: # Returns the module name and list of cells to export.\n",
" \"Find the code cells in an ipynb file to export out.\"\n",
- " code_cells = filter_cells(read_nb(fp), CellType.CODE)\n",
+ " if not isinstance(fp, NotebookNode): fp = read_nb(fp)\n",
+ " code_cells = filter_cells(fp, CellType.CODE)\n",
" module = get_default_export(code_cells)\n",
" cells = [\n",
" {**c, 'source': strip_directives(c['source'])}\n",
@@ -671,6 +687,71 @@
},
{
"cell_type": "markdown",
+ "id": "aa285ef2",
+ "metadata": {},
+ "source": [
+ "If a notebook has a `default_exp` directive and exported cells, we should see those extracted out and the directive comments stripped out."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "ffaa9942",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "nb = nbformat.v4.new_notebook()\n",
+ "nb.cells = [\n",
+ " nbformat.v4.new_code_cell('#| default_exp: mymodule'),\n",
+ " nbformat.v4.new_code_cell('#| export\\ndef hello(): return \"hi\"'),\n",
+ "]\n",
+ "assert find_cells_to_export(nb) == ('mymodule', [{**nb.cells[1], 'source': 'def hello(): return \"hi\"'}])"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "85a57955",
+ "metadata": {},
+ "source": [
+ "Additionally, we can pass in a path to a notebook rather than an in-memory notebook. If no cell is exported, the cells to export will be empty."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "329abbe7",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "nb = nbformat.v4.new_notebook(cells=[nbformat.v4.new_code_cell('#| default_exp: mymodule')])\n",
+ "with tempfile.TemporaryDirectory() as tmp:\n",
+ " p = tmp/Path('test.ipynb')\n",
+ " p.write_text(json.dumps(nb))\n",
+ " assert find_cells_to_export(p) == ('mymodule', [])"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "9e1d96de",
+ "metadata": {},
+ "source": [
+ "An empty notebook should raise a `ValueError` because it doesn't have a `default_exp` directive."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "2c349b45",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "nb = nbformat.v4.new_notebook()\n",
+ "try: find_cells_to_export(nb); assert False\n",
+ "except ValueError: pass"
+ ]
+ },
+ {
+ "cell_type": "markdown",
"id": "66574d29",
"metadata": {},
"source": [
@@ -710,13 +791,13 @@
"source": [
"#| export\n",
"def mk_py_mod_scaffold(\n",
- " mod:str, # The Python module name or dotted path e.g. mod.mymod.file\n",
- " src_dir:str|pathlib.Path, # The Python package source code directory scaffold\n",
+ " mod:str, # The Python module name or dotted path e.g. mod.mymod.file\n",
+ " src_dir:str|Path, # The Python package source code directory scaffold\n",
"):\n",
" \"Create all intermediary __init__.py files and directories, if any, and the final .py file.\"\n",
" if not mod: raise ValueError('The module path cannot be empty')\n",
- " src_dir = pathlib.Path(src_dir)\n",
- " mod_file = (src_dir/pathlib.Path(*mod.split('.'))).with_suffix('.py')\n",
+ " src_dir = Path(src_dir)\n",
+ " mod_file = (src_dir/Path(*mod.split('.'))).with_suffix('.py')\n",
" mod_file.parent.mkdir(parents=True, exist_ok=True)\n",
" mod_file.touch()\n",
" pkg_dirs = list(mod_file.parents)\n",
@@ -759,7 +840,7 @@
"with tempfile.TemporaryDirectory() as tmp:\n",
" mk_py_mod_scaffold('mod.file', src_dir=tmp)\n",
" assert os.listdir(tmp) == ['__init__.py', 'mod']\n",
- " assert os.listdir(pathlib.Path(tmp)/'mod') == ['__init__.py', 'file.py']"
+ " assert os.listdir(Path(tmp)/'mod') == ['__init__.py', 'file.py']"
]
},
{
@@ -771,18 +852,18 @@
"source": [
"#| export\n",
"def export_nb(\n",
- " fp:str|IO[str], # The notebook to export\n",
- " src_dir:str|pathlib.Path='.', # The source directory to export the Python module to.\n",
+ " fp:PathOrFileLike|NotebookNode, # The notebook to export.\n",
+ " src_dir:str|Path='.', # The source directory to export the Python module to.\n",
"):\n",
" \"Export the exportable code cells to a Python file.\"\n",
" module, cells = find_cells_to_export(fp)\n",
" mk_py_mod_scaffold(module, src_dir)\n",
- " exp_path = (pathlib.Path(src_dir)/module).with_suffix('.py')\n",
+ " exp_path = (Path(src_dir)/module).with_suffix('.py')\n",
" src = '\\n'.join(\n",
" ['# AUTOGENERATED! DO NOT EDIT!\\n'] +\n",
" list(map(lambda c: fmt_export_cell(c)['source'], cells))\n",
" )\n",
- " pathlib.Path(exp_path).write_text(src)"
+ " Path(exp_path).write_text(src)"
]
},
{
@@ -824,7 +905,7 @@
"\"\"\"\n",
"with tempfile.TemporaryDirectory() as tmp:\n",
" export_nb(nb, src_dir=tmp)\n",
- " result = pathlib.Path(tmp, 'testmod.py').read_text()\n",
+ " result = Path(tmp, 'testmod.py').read_text()\n",
" assert result == src, result"
]
},
@@ -845,6 +926,182 @@
"source": [
"export_nb('export.ipynb', src_dir='../nb/')"
]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "59c195b3",
+ "metadata": {},
+ "source": [
+ "i don't understand how I'm somehow getting python files exported into the *same* directory sometimes. e.g. see 'export.py' in the same directory right now.\n",
+ "\n",
+ "##### 🤖Reply🤖<!-- SOLVEIT_SEPARATOR_7f3a9b2c -->\n",
+ "\n",
+ "The default value for `src_dir` in `export_nb` is `'.'`:\n",
+ "\n",
+ "```python\n",
+ "def export_nb(fp, src_dir='.'):\n",
+ "```\n",
+ "\n",
+ "So if you ever called `export_nb('export.ipynb')` without specifying `src_dir` (e.g. while testing in the REPL), it would drop `export.py` right into the current working directory — the same folder as the notebook.\n",
+ "\n",
+ "That's likely what happened. You can just delete the stray `export.py` file. You might also consider whether having `'.'` as the default is what you actually want, or if it'd be safer to make `src_dir` a required parameter (no default) so this can't happen accidentally."
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "6a271023",
+ "metadata": {},
+ "source": [
+ "But if you read export.py, it's clear that it isn't from export_nb because it has no cell comments.\n",
+ "\n",
+ "##### 🤖Reply🤖<!-- SOLVEIT_SEPARATOR_7f3a9b2c -->\n",
+ "\n",
+ "Good point — if there are no `# cell: ...` comments, then `export_nb` didn't create it. Let me take a look at the file to see what's actually in it.\n",
+ "\n",
+ "\n",
+ "<details class='tool-usage-details' markdown='1'>\n",
+ "<summary><code>view(path=&#x27;nb/nbs/export.py&#x27;)→&#x27;Error: File not found: /app/data/nb/nbs/…&#x27;</code></summary>\n",
+ "\n",
+ "```json\n",
+ "{\n",
+ " \"id\": \"toolu_0185u2rVBZJG6ics9LDHYvTi\",\n",
+ " \"call\": {\n",
+ " \"function\": \"view\",\n",
+ " \"arguments\": {\n",
+ " \"path\": \"nb/nbs/export.py\"\n",
+ " }\n",
+ " },\n",
+ " \"result\": \"Error: File not found: /app/data/nb/nbs/nb/nbs/export.py\"\n",
+ "}\n",
+ "```\n",
+ "\n",
+ "</details>\n",
+ "\n",
+ "Let me find the right path.\n",
+ "\n",
+ "\n",
+ "<details class='tool-usage-details' markdown='1'>\n",
+ "<summary><code>realpath(subpath=&#x27;/&#x27;)→&quot;{&#x27;path&#x27;: &#x27;/app/data&#x27;}&quot;</code></summary>\n",
+ "\n",
+ "```json\n",
+ "{\n",
+ " \"id\": \"toolu_01UXNtz4TuJLxzDXcQU5ygQ7\",\n",
+ " \"call\": {\n",
+ " \"function\": \"realpath\",\n",
+ " \"arguments\": {\n",
+ " \"subpath\": \"/\"\n",
+ " }\n",
+ " },\n",
+ " \"result\": \"{'path': '/app/data'}\"\n",
+ "}\n",
+ "```\n",
+ "\n",
+ "</details>\n",
+ "\n",
+ "The data root is `/app/data`. The dialog path is `nb/nbs/export`. Let me look for the file.\n",
+ "\n",
+ "\n",
+ "<details class='tool-usage-details' markdown='1'>\n",
+ "<summary><code>rg(argstr=&#x27;--files -g export.py /app/data/nb&#x27;)→&#x27;/app/data/nb/nb/export.py\\n/app/data/nb/n…&#x27;</code></summary>\n",
+ "\n",
+ "```json\n",
+ "{\n",
+ " \"id\": \"toolu_01FfH6PxdZYtbwAnoQR2NsQc\",\n",
+ " \"call\": {\n",
+ " \"function\": \"rg\",\n",
+ " \"arguments\": {\n",
+ " \"argstr\": \"--files -g export.py /app/data/nb\"\n",
+ " }\n",
+ " },\n",
+ " \"result\": \"/app/data/nb/nb/export.py\\n/app/data/nb/nbs/export.py\"\n",
+ "}\n",
+ "```\n",
+ "\n",
+ "</details>\n",
+ "\n",
+ "There are two `export.py` files — one at `nb/nb/export.py` and one at `nb/nbs/export.py`. Let me look at the one in the notebook's directory:\n",
+ "\n",
+ "\n",
+ "<details class='tool-usage-details' markdown='1'>\n",
+ "<summary><code>view(path=&#x27;/app/data/nb/nbs/export.py&#x27;)→&#x27;import enum,pathlib,re\\nfrom pathlib impo…&#x27;</code></summary>\n",
+ "\n",
+ "```json\n",
+ "{\n",
+ " \"id\": \"toolu_01NUNL9YfvjKLpiDqTNZ9L4t\",\n",
+ " \"call\": {\n",
+ " \"function\": \"view\",\n",
+ " \"arguments\": {\n",
+ " \"path\": \"/app/data/nb/nbs/export.py\"\n",
+ " }\n",
+ " },\n",
+ " \"result\": \"import enum,pathlib,re\\nfrom pathlib import Path\\nfrom typing import IO\\n\\nimport nbformat\\nfrom nbformat import NotebookNode\\ntype PathOrFileLike = str|Path|IO[str]\\ndef read_nb(\\n fp:PathOrFileLike, # Where to read the notebook from.\\n v:int=4, # The notebook format major version to read the notebook as.\\n)->NotebookNode:\\n \\\"Read in a notebook as a dictionary-like NotebookNode.\\\"\\n return nbformat.read(fp, as_version=v)\\n\\nclass CellType(enum.StrEnum):\\n \\\"Possible Jupyter notebook cell types.\\\"\\n CODE = 'code'\\n MD = 'markdown'\\n RAW = 'raw'\\ndef filter_cells(\\n nb:NotebookNode, # A notebook that has been read in via `read_nb`.\\n ct:CellType, # The cells to filter down to.\\n)->list[NotebookNode]:\\n \\\"Retrieve specific cell types from a notebook.\\\"\\n return list(filter(lambda c: c['cell_type'] == ct, nb['cells']))\\ndef _mk_directive_re(\\n name:str, # The name of the directive\\n arg_re:str|None=None, # A regex pattern to match an argument for the directive\\n)->re.Pattern:\\n \\\"Compile a regex to match a directive, optionally supporting an argument.\\\"\\n arg = rf':\\\\s*{arg_re}' if arg_re else ''\\n return re.compile(rf'^\\\\s*#\\\\|\\\\s*{name}{arg}\\\\s*$')\\nDIRECTIVE_DEFAULT_EXP_RE = _mk_directive_re('default_exp', arg_re=r'(?P<module>\\\\w+(\\\\.\\\\w+)*)')\\nDIRECTIVE_EXPORT_RE = _mk_directive_re('export')\\nDIRECTIVES = [DIRECTIVE_DEFAULT_EXP_RE, DIRECTIVE_EXPORT_RE]\\ndef has_directive(src:str)->bool:\\n \\\"Check whether a line or block of source code has a nb directive.\\\"\\n return any(any(r.match(l) for r in DIRECTIVES) for l in src.splitlines())\\ndef strip_directives(src:str|list[str])->str:\\n \\\"Remove all nb directives from the source code.\\\"\\n src = src if isinstance(src, list) else src.splitlines()\\n return \\\"\\\\n\\\".join(filter(lambda l: not has_directive(l), src))\\ndef is_cell_exported(cell:NotebookNode)->bool:\\n \\\"Check whether the code cell should be exported.\\\"\\n return any(DIRECTIVE_EXPORT_RE.match(l) for l in cell['source'].splitlines())\\ndef get_default_export(cells:list[NotebookNode])->str:\\n \\\"Retrieve the `default_exp` directive argument from a list of cells.\\\"\\n matches = [\\n m.group('module')\\n for c in cells\\n for l in c['source'].splitlines()\\n if c['cell_type'] == CellType.CODE and (m:=DIRECTIVE_DEFAULT_EXP_RE.match(l))\\n ]\\n if len(matches) > 1: raise ValueError('More than one default_exp directive')\\n if len(matches) == 0: raise ValueError('Missing default_exp directive')\\n return matches[0]\\ndef find_cells_to_export(\\n fp:PathOrFileLike|NotebookNode, # Where to read the notebook from.\\n)->tuple[str,list[NotebookNode]]: # Returns the module name and list of cells to export.\\n \\\"Find the code cells in an ipynb file to export out.\\\"\\n if not isinstance(fp, NotebookNode): fp = read_nb(fp)\\n code_cells = filter_cells(fp, CellType.CODE)\\n module = get_default_export(code_cells)\\n cells = [\\n {**c, 'source': strip_directives(c['source'])}\\n for c in code_cells\\n if is_cell_exported(c)\\n ]\\n return module, cells\\ndef fmt_export_cell(cell:dict)->dict:\\n \\\"Format a code cell's source with metadata to prepare for export.\\\"\\n cell['source'] = f'# cell: {cell[\\\"id\\\"]}\\\\n' + cell['source'] + '\\\\n'\\n return cell\\ndef mk_py_mod_scaffold(\\n mod:str, # The Python module name or dotted path e.g. mod.mymod.file\\n src_dir:str|Path, # The Python package source code directory scaffold\\n):\\n \\\"Create all intermediary __init__.py files and directories, if any, and the final .py file.\\\"\\n if not mod: raise ValueError('The module path cannot be empty')\\n src_dir = Path(src_dir)\\n mod_file = (src_dir/Path(*mod.split('.'))).with_suffix('.py')\\n mod_file.parent.mkdir(parents=True, exist_ok=True)\\n mod_file.touch()\\n pkg_dirs = list(mod_file.parents)\\n for p in pkg_dirs[:pkg_dirs.index(src_dir) + 1]:\\n (p / '__init__.py').touch()\\ndef export_nb(\\n fp:PathOrFileLike|NotebookNode, # The notebook to export.\\n src_dir:str|Path='.', # The source directory to export the Python module to.\\n):\\n \\\"Export the exportable code cells to a Python file.\\\"\\n module, cells = find_cells_to_export(fp)\\n mk_py_mod_scaffold(module, src_dir)\\n exp_path = (Path(src_dir)/module).with_suffix('.py')\\n src = '\\\\n'.join(\\n ['# AUTOGENERATED! DO NOT EDIT!\\\\n'] +\\n list(map(lambda c: fmt_export_cell(c)['source'], cells))\\n )\\n Path(exp_path).write_text(src)\"\n",
+ "}\n",
+ "```\n",
+ "\n",
+ "</details>\n",
+ "\n",
+ "Ah, now I see! This `export.py` is clearly **solveit's own export** — it's the concatenation of all your code cells that are marked as exported (with `is_exported` flag in solveit's message metadata), just joined together with no `# cell:` comments and no `# AUTOGENERATED` header.\n",
+ "\n",
+ "This is solveit's built-in export mechanism, which is separate from the `export_nb` function you're building. When you mark messages as \"exported\" in solveit (the toggle in the UI), solveit generates this file automatically. It happens to write to `export.py` because your dialog is named `export`.\n",
+ "\n",
+ "So you have two different export systems both targeting the same module name — solveit's built-in one writing to `nb/nbs/export.py`, and your `export_nb` writing to `nb/nb/export.py` (via `src_dir='../nb/'`)."
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "7afcff5b",
+ "metadata": {},
+ "source": [
+ "how can I turn off solveits? The tool I'm building also uses #| export markers.\n",
+ "\n",
+ "##### 🤖Reply🤖<!-- SOLVEIT_SEPARATOR_7f3a9b2c -->\n",
+ "\n",
+ "<details class='tool-usage-details' markdown='1'>\n",
+ "<summary><code>solveit_docs()→&#x27;⚠️ This content will be truncated in you…&#x27;</code></summary>\n",
+ "\n",
+ "```json\n",
+ "{\n",
+ " \"id\": \"toolu_01LSMhJdmQQkiAgpaXu2bNRG\",\n",
+ " \"call\": {\n",
+ " \"function\": \"solveit_docs\",\n",
+ " \"arguments\": {}\n",
+ " },\n",
+ " \"result\": \"<TRUNCATED>\\u2026ntent will be truncated in your next turn. Re-call this tool if you need it again.\\nIf the user wants more info, give them a link to https://gist.github.com/jph00/9e7b444aba5ecf6d14295ba2cee890c3.# Solveit Reference\\n\\n## What is Solveit?\\n\\nSolveit is a \\\"Dialog Engineering\\\" web application for interactive development. Unlike ChatGPT (pure chat) or Jupyter (pure code), Solveit combines three message types in one workspace: code execution, markdown notes, and AI prompts. Users build solutions incrementally\\u2014writing a few lines, understanding them, then continuing\\u2014rather than generating large code blocks.\\n\\nThe AI sees the full dialog context (code, outputs, notes, prompts) when responding -- but only those ABOVE the current message. Users can edit any message at any time, including AI responses\\u2014the dialog is a living document, not an append-only log.\\n\\nThe dialog is a running ipykernel instance. A \\\"dialog\\\" is like a \\\"Jupyter notebook\\\", and uses a compatible ipynb file format, but provides a superset of functionality (in particular, \\\"prompt messages\\\"). A \\\"message\\\" is like a \\\"Jupyter cell\\\", with additional attributes stored as ipynb cell metadata. Most standard jupyter functionality is supported (including cell magics like `%%js`, `%%html`, `%%bash`, and custom magics via `@line_magic`/`@cell_magic` decorators), except for ipywidgets. Cell magics can be async; if an async magic returns a FastHTML FT component, it's auto-converted to HTML.\\n\\n## Architecture\\n\\n- **Instance**: A persistent Linux container (virtual private server) with home dir at `/app/data`. Each user can have multiple instances. Instances have private URLs (for the solveit interface) and public URLs (for hosting apps on port 8000).\\n- **Dialog**: An `.ipynb` file containing messages. Each open dialog runs its own Python kernel (ipykernel). Dialogs can be organized into folders.\\n- **Kernel**: A running Python 3.12 interpreter maintaining state. Variables persist between code messages. Each dialog has its own isolated kernel. Kernels keep running when navigating away; must explicitly stop via UI or shutdown. Use `%load_ext autoreload` and `%autoreload 2` to auto-reload modules when files change. The current dialog name is available as `__dialog_name` in the kernel namespace and as the `__DIALOG_NAME` environment variable.\\n\\n### CRAFT and TEMPLATE Files\\n\\n**CRAFT.ipynb** files provide reusable AI context and auto-executed code for a folder:\\n- **Note/prompt messages** are prepended to the AI's context for all dialogs in that folder and subfolders\\n- **Code messages** are automatically executed in the kernel when opening a dialog\\n\\n\\n**CRAFT.css** and **CRAFT.js** files can be placed alongside `CRAFT.ipynb`. They follow the same parent-chain hierarchy and are injected as `<style>` and `<script type=\\\"module\\\">` tags when a dialog opens. Useful for custom theming or adding client-side behavior without touching the main app.\\n**TEMPLATE.ipynb** files serve as dialog templates\\u2014their cells are prepended to new dialogs created in that folder.\\n\\nBoth use path hierarchy: files from parent folders are included too, letting you build layered configurations (e.g., org-wide settings in root, project-specific in subfolders).\\n\\n### Optional CRAFTs (CRAFTs Folders)\\n\\nIn addition to `CRAFT.ipynb` files (which are always loaded), you can place notebooks in a `CRAFTs/` subfolder at any level of the folder hierarchy. These are **optional crafts** \\u2014 they are discovered but not automatically loaded.\\n\\nThe AI always sees optional crafts listed in its context on every prompt: only the first message and the file size are shown, wrapped in `<optional-craft-block>` tags. This gives the AI enough information to decide whether a particular optional craft is relevant to the current task. If so, the AI can call the `load_dialog` tool, which runs all its code cells in the kernel and returns the full contents.\\n\\nExample structure:\\n```\\nproject/\\n\\u251c\\u2500\\u2500 CRAFT.ipynb # Always loaded (required)\\n\\u251c\\u2500\\u2500 CRAFTs/\\n\\u2502 \\u251c\\u2500\\u2500 testing.ipynb # Optional \\u2014 AI loads on demand\\n\\u2502 \\u2514\\u2500\\u2500 advanced.ipynb # Optional \\u2014 AI loads on demand\\n\\u2514\\u2500\\u2500 my_dialog.ipynb\\n```\\n\\nOptional crafts loaded via `load_dialog` are automatically re-imported when the kernel restarts, so you don't need to re-load them manually after a restart. Solveit achieves this by scanning the dialog's prompt history for prior `load_dialog` calls and replaying them during startup.\\n\\n\\n### AUTORUN Folders\\n\\nPlace notebooks inside an `AUTORUN/` folder at the root of your instance to have them automatically opened and run on startup. Useful for persistent background processes (Discord bots, FastHTML apps, scheduled tasks). Dialogs in `AUTORUN/` folders are exempt from idle shutdown.\\n\\n## Message Types\\n\\n| Type | Purpose | Input | Output |\\n|------|---------|-------|--------|\\n| `code` | Python execution | Python source | ipynb-format output list (stream, execute_result, display_data, error) |\\n| `note` | Documentation | Markdown with optional attachments\\u2026</TRUNCATED>\"\n",
+ "}\n",
+ "```\n",
+ "\n",
+ "</details>\n",
+ "\n",
+ "\n",
+ "\n",
+ "\n",
+ "\n",
+ "From the solveit docs: when you press `e` on a code message, it sets `is_exported=True` in the message metadata and adds a `#| export` marker. When the dialog is saved, all messages with `is_exported=True` are combined into `{dialog_name}.py` automatically.\n",
+ "\n",
+ "So some of your code messages have the `is_exported` flag set in their solveit metadata. Since your dialog is named `export`, solveit generates `export.py` in the same folder.\n",
+ "\n",
+ "To fix it: select the messages that have the export flag on (they'll have a đź”– indicator) and press `e` to toggle it off. That will stop solveit from generating its own `export.py`, and your `export_nb` tool will be the only thing producing Python files."
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "d20c0005",
+ "metadata": {},
+ "source": [
+ "But will that remove the #| export marker I want in the cell source? I need it for my tool.\n",
+ "\n",
+ "##### 🤖Reply🤖<!-- SOLVEIT_SEPARATOR_7f3a9b2c -->\n",
+ "\n",
+ "Good concern. Yes, pressing `e` toggles *both* the `is_exported` metadata flag and the `#| export` text in the source together.\n",
+ "\n",
+ "But solveit's auto-export is driven by the **metadata flag**, not the source text. So you can keep the `#| export` text (for your tool) and just clear the metadata flag directly. I can do that for you — want me to find the messages with `is_exported` set and clear just the flag, leaving the source untouched?"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "110716b6",
+ "metadata": {},
+ "source": []
}
],
"metadata": {},