marimo-dev 0.1.0__tar.gz

marimo_dev-0.1.0/PKG-INFO

@@ -0,0 +1,74 @@
+Metadata-Version: 2.3
+Name: marimo-dev
+Version: 0.1.0
+Summary: Build and publish python packages from marimo notebooks
+Author: Deufel
+Author-email: Deufel <MDeufel13@gmail.com>
+License: MIT
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# m_dev
+
+A literate programming build system that converts Marimo notebooks into distributable Python packages.
+
+## What it does
+
+Write code in numbered notebook files in a `notebooks/` directory. Mark functions and classes for export by making them purely functional with references from the setup cell—Marimo detects these automatically. Run `md build` to generate a proper Python package with `__init__.py`, module files, and `llms.txt` API documentation.
+
+## Project structure
+
+```
+my-project/
+├── pyproject.toml
+├── notebooks/
+│   ├── 00_core.py
+│   ├── 01_read.py
+│   ├── 02_pkg.py
+│   ├── 03_docs.py
+│   └── 04_build.py
+└── src/
+    └── my_package/
+        ├── __init__.py
+        ├── core.py
+        ├── read.py
+        └── ...
+```
+
+## How it works
+
+The build system parses notebooks via AST, extracts decorated exports (`@app.function`, `@app.class_definition`), and writes clean module files. It reads metadata from `pyproject.toml` and generates `__init__.py` with proper imports and `__all__` exports.
+
+The `llms.txt` file contains function signatures with inline documentation extracted from comments, formatted for LLM consumption. This provides a compact API reference.
+
+## CLI usage
+
+```bash
+md build              # build package from notebooks/
+md publish            # publish to PyPI
+md publish --test     # publish to Test PyPI
+```
+
+## Requirements
+
+- Python 3.10+
+- Marimo for notebook management
+- uv for dependency management
+- pyproject.toml with project metadata
+
+Marimo manages your `pyproject.toml` through its package tab, making dependencies visible and easy to update.
+
+## Install
+
+```bash
+uv add m-dev --index testpypi=https://test.pypi.org/simple --index pypi=https://pypi.org/simple --index-strategy unsafe-best-match
+```
+
+## Module structure
+
+- `core.py` - Data model: `Kind`, `Param`, `Node`
+- `read.py` - Parse notebooks, extract exports, scan project
+- `pkg.py` - Write module files and `__init__.py`
+- `docs.py` - Generate signatures and `llms.txt`
+- `build.py` - Orchestrate the build
+- `cli.py` - Command-line interface

marimo_dev-0.1.0/README.md

@@ -0,0 +1,64 @@
+# m_dev
+
+A literate programming build system that converts Marimo notebooks into distributable Python packages.
+
+## What it does
+
+Write code in numbered notebook files in a `notebooks/` directory. Mark functions and classes for export by making them purely functional with references from the setup cell—Marimo detects these automatically. Run `md build` to generate a proper Python package with `__init__.py`, module files, and `llms.txt` API documentation.
+
+## Project structure
+
+```
+my-project/
+├── pyproject.toml
+├── notebooks/
+│   ├── 00_core.py
+│   ├── 01_read.py
+│   ├── 02_pkg.py
+│   ├── 03_docs.py
+│   └── 04_build.py
+└── src/
+    └── my_package/
+        ├── __init__.py
+        ├── core.py
+        ├── read.py
+        └── ...
+```
+
+## How it works
+
+The build system parses notebooks via AST, extracts decorated exports (`@app.function`, `@app.class_definition`), and writes clean module files. It reads metadata from `pyproject.toml` and generates `__init__.py` with proper imports and `__all__` exports.
+
+The `llms.txt` file contains function signatures with inline documentation extracted from comments, formatted for LLM consumption. This provides a compact API reference.
+
+## CLI usage
+
+```bash
+md build              # build package from notebooks/
+md publish            # publish to PyPI
+md publish --test     # publish to Test PyPI
+```
+
+## Requirements
+
+- Python 3.10+
+- Marimo for notebook management
+- uv for dependency management
+- pyproject.toml with project metadata
+
+Marimo manages your `pyproject.toml` through its package tab, making dependencies visible and easy to update.
+
+## Install
+
+```bash
+uv add m-dev --index testpypi=https://test.pypi.org/simple --index pypi=https://pypi.org/simple --index-strategy unsafe-best-match
+```
+
+## Module structure
+
+- `core.py` - Data model: `Kind`, `Param`, `Node`
+- `read.py` - Parse notebooks, extract exports, scan project
+- `pkg.py` - Write module files and `__init__.py`
+- `docs.py` - Generate signatures and `llms.txt`
+- `build.py` - Orchestrate the build
+- `cli.py` - Command-line interface

marimo_dev-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["uv_build>=0.9.15,<0.10.0"]
+build-backend = "uv_build"
+
+[project]
+name = "marimo-dev"
+version = "0.1.0"
+description = "Build and publish python packages from marimo notebooks"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = []
+
+[project.license]
+text = "MIT"
+
+[[project.authors]]
+name = "Deufel"
+email = "MDeufel13@gmail.com"
+
+[project.scripts]
+md = "m_dev.cli:main"
+
+
+[tool.marimo.runtime]
+   pythonpath = ["src"] 
+
+# Remove this when ready to upload this is a saftey net for not accidentally uploading
+# classifiers = ["Private :: Do Not Upload"]
+
+# Development packages
+[dependency-groups]
+dev = ["anthropic>=0.72.0", "marimo[mcp]>=0.18.4" , "pytest>=8.4.2"]
+
+
+# Not sure that this is required... 
+[tool.uv]
+default-groups = ["dev"]
+
+
+
+

marimo_dev-0.1.0/src/marimo_dev/__init__.py

@@ -0,0 +1,39 @@
+"""Build and publish python packages from marimo notebooks"""
+__version__ = '0.1.0'
+__author__ = 'Deufel'
+from .core import Kind, Param, Node
+from .read import inline_doc, parse_params, parse_class_params, parse_ret, src_with_decs, is_export, parse_import, parse_const, parse_export, parse_node, parse_file, read_meta, nb_name, scan
+from .pkg import clean, write, write_mod, write_init
+from .docs import cls_sig, fn_sig, sig, write_llms
+from .build import publish
+from .cli import init, main
+__all__ = [
+    "Kind",
+    "Node",
+    "Param",
+    "clean",
+    "cls_sig",
+    "fn_sig",
+    "init",
+    "inline_doc",
+    "is_export",
+    "main",
+    "nb_name",
+    "parse_class_params",
+    "parse_const",
+    "parse_export",
+    "parse_file",
+    "parse_import",
+    "parse_node",
+    "parse_params",
+    "parse_ret",
+    "publish",
+    "read_meta",
+    "scan",
+    "sig",
+    "src_with_decs",
+    "write",
+    "write_init",
+    "write_llms",
+    "write_mod",
+]

marimo_dev-0.1.0/src/marimo_dev/build.py

@@ -0,0 +1,33 @@
+from m_dev.core import Kind, Param, Node
+from m_dev.read import scan
+from m_dev.pkg import write_mod, write_init
+from m_dev.docs import write_llms
+from pathlib import Path
+import ast
+
+def publish(
+    test:bool=True, # Use Test PyPI if True, real PyPI if False
+):
+    "Build and publish package to PyPI. Looks for ~/.pypirc for credentials, otherwise prompts."
+    import subprocess, configparser, shutil
+    from pathlib import Path
+
+    shutil.rmtree('dist', ignore_errors=True)
+    print("Building package...")
+    subprocess.run(['uv', 'build'], check=True)
+
+    pypirc, cmd = Path.home() / '.pypirc', ['uv', 'publish']
+    section = 'testpypi' if test else 'pypi'
+
+    if test: cmd.extend(['--publish-url', 'https://test.pypi.org/legacy/'])
+    else: cmd.extend(['--publish-url', 'https://upload.pypi.org/legacy/'])
+
+    if pypirc.exists():
+        config = configparser.ConfigParser()
+        config.read(pypirc)
+        if section in config:
+            username, password = config[section].get('username', '__token__'), config[section].get('password', '')
+            cmd.extend(['--username', username, '--password', password])
+
+    print(f"Publishing to {'Test ' if test else ''}PyPI...")
+    subprocess.run(cmd, check=True)

marimo_dev-0.1.0/src/marimo_dev/cli.py

@@ -0,0 +1,36 @@
+from m_dev.build import build
+import sys, subprocess
+from pathlib import Path
+
+def init(
+    name:str=None, # project name (defaults to current directory name)
+):
+    "Initialize a new m-dev project with notebooks dir and pyproject.toml."
+    cmd = ['uv', 'init', '--bare', '--no-readme', '--no-pin-python', '--vcs', 'none']
+    if name: cmd.append(name)
+    subprocess.run(cmd, check=True)
+    Path('notebooks').mkdir(exist_ok=True)
+    p = Path('pyproject.toml')
+    content = p.read_text()
+    additions = '''
+[tool.marimo.runtime]
+pythonpath = ["src"]
+
+[build-system]
+requires = ["uv_build>=0.9.15,<0.10.0"]
+build-backend = "uv_build"
+'''
+    if '[build-system]' not in content: p.write_text(content.rstrip() + '\n' + additions)
+
+def main():
+    if len(sys.argv) < 2: print("Usage: md [init|build|publish]"); sys.exit(1)
+    cmd = sys.argv[1]
+    if cmd == 'init': init(sys.argv[2] if len(sys.argv) > 2 else None)
+    elif cmd == 'build':
+        from m_dev.build import build
+        print(f"Built package at: {build()}")
+    elif cmd == 'publish':
+        test = '--test' in sys.argv or '-t' in sys.argv
+        from m_dev.publish import publish
+        publish(test=test)
+    else: print(f"Unknown command: {cmd}"); sys.exit(1)

marimo_dev-0.1.0/src/marimo_dev/core.py

@@ -0,0 +1,27 @@
+import ast, re, tomllib, json
+from pathlib import Path
+from enum import Enum
+from dataclasses import dataclass, field
+
+class Kind(Enum):
+    "Types of nodes in parsed code"
+    IMP='import'    # Import statement
+    CONST='const'   # Constant definition
+    EXP='export'    # Exported function or class
+
+@dataclass
+class Param:
+    name: str                # parameter name
+    anno: str|None = None    # type annotation
+    default: str|None = None # default value
+    doc: str = ''            # inline documentation
+
+@dataclass 
+class Node:
+    "A parsed code node representing an import, constant, or exported function/class."
+    kind: Kind       # type of node (import/const/export)
+    name: str        # identifier name
+    src: str         # source code
+    doc: str = ''    # docstring text
+    params: list[Param] = field(default_factory=list)    # function/class parameters
+    ret: tuple[str,str]|None = None                      # return type annotation and doc

marimo_dev-0.1.0/src/marimo_dev/docs.py

@@ -0,0 +1,44 @@
+from m_dev.core import Kind, Param, Node
+from pathlib import Path
+import ast
+
+def cls_sig(
+    n:Node,           # the node to generate signature for
+    dataclass=False,  # whether to include @dataclass decorator
+)->str:               # formatted class signature
+    "Generate a class signature string."
+    header = f"@dataclass\nclass {n.name}:" if dataclass else f"class {n.name}:"
+    lines = [header]
+    if n.doc: lines.append(f'    """{n.doc}"""')
+    lines.extend(f"    {p.name}{f': {p.anno}' if p.anno else ''}{f' = {p.default}' if p.default else ''}" for p in n.params)
+    return '\n'.join(lines)
+
+def fn_sig(
+    n:Node,         # the node to generate signature for
+    is_async=False, # whether function is async
+)->str:             # formatted function signature
+    "Generate a function signature string."
+    ps = ', '.join(f"{p.name}{f': {p.anno}' if p.anno else ''}{f'={p.default}' if p.default else ''}" for p in n.params)
+    ret = f" -> {n.ret[0]}" if n.ret else ""
+    s = f"{'async def' if is_async else 'def'} {n.name}({ps}){ret}:"
+    return f"{s}\n    \"\"\"{n.doc}\"\"\"" if n.doc else s
+
+def sig(
+    n:Node, # the node to generate signature for
+)->str:     # formatted signature string
+    "Generate a signature string for a class or function node."
+    src = n.src.lstrip()
+    if src.startswith('@dataclass'): return cls_sig(n, dataclass=True)
+    if src.startswith('class '): return cls_sig(n)
+    return fn_sig(n, is_async=src.startswith('async def'))
+
+def write_llms(
+    meta:dict,    # project metadata from pyproject.toml
+    nodes:list,   # list of Node objects to document
+    out='docs',   # output directory path
+):
+    "Write API signatures to llms.txt file for LLM consumption."
+    sigs = '\n\n'.join(sig(n) for n in nodes if not n.name.startswith('__'))
+    content = f"# {meta['name']}\n\n> {meta['desc']}\n\nVersion: {meta['version']}\n\n## API\n\n```python\n{sigs}\n```"
+    Path(out).mkdir(exist_ok=True)
+    (Path(out)/'llms.txt').write_text(content)

marimo_dev-0.1.0/src/marimo_dev/pkg.py

@@ -0,0 +1,41 @@
+from m_dev.core import Kind, Param, Node
+from pathlib import Path
+import ast
+
+def clean(
+    src:str, # source code to clean
+)->str:      # cleaned source code
+    "Remove decorator lines from source code."
+    return '\n'.join(l for l in src.splitlines() if not l.strip().startswith(('@app.function', '@app.class_definition')))
+
+def write(
+    p:str,      # path to write to
+    *parts:str, # content parts to join with blank lines
+):
+    "Write parts to file, filtering None values and joining with blank lines."
+    Path(p).write_text('\n\n'.join(filter(None, parts)) + '\n')
+
+def write_mod(
+    path,           # output file path
+    nodes:list,     # list of Node objects to write
+):
+    "Write module file with imports, constants, and exports."
+    g = {k: [n for n in nodes if n.kind == k] for k in Kind}
+    parts = ['\n'.join(n.src for n in g[Kind.IMP]), '\n'.join(n.src for n in g[Kind.CONST]), '\n\n'.join(clean(n.src) for n in g[Kind.EXP])]
+    write(path, *parts)
+
+def write_init(
+    path:str|Path, # path to write __init__.py file
+    meta:dict,     # metadata dict with desc, version, author
+    mods:list,     # list of (name, nodes) tuples
+):
+    "Generate and write __init__.py file with metadata and exports."
+    lines = [f'"""{meta["desc"]}"""', f"__version__ = '{meta['version']}'"]
+    if meta['author']: lines.append(f"__author__ = '{meta['author'].split('<')[0].strip()}'")
+    exports = []
+    for name, nodes in mods:
+        if name.startswith('00_'): continue
+        pub = [n.name for n in nodes if n.kind == Kind.EXP and not n.name.startswith('__')]
+        if pub: lines.append(f"from .{name} import {', '.join(pub)}"); exports.extend(pub)
+    if exports: lines.append('__all__ = [\n' + '\n'.join(f'    "{n}",' for n in sorted(exports)) + '\n]')
+    write(path, '\n'.join(lines))

marimo_dev-0.1.0/src/marimo_dev/read.py

@@ -0,0 +1,125 @@
+from m_dev.core import Kind, Param, Node
+from pathlib import Path
+import ast, re, tomllib
+
+def inline_doc(
+    ls:list[str], # source code lines
+    ln:int,       # line number to search
+    name:str,     # identifier name to match before comment
+)->str:           # extracted inline comment or empty string
+    "Extract inline comment following an identifier on a source line."
+    if 0 < ln <= len(ls) and (m := re.search(rf'\b{re.escape(name)}\b.*?#\s*(.+)', ls[ln-1])): return m.group(1).strip()
+    return ''
+
+def parse_params(
+    fn,            # function node to extract parameters from
+    ls,            # source lines for inline doc extraction
+)->list[Param]:    # list of parameter objects
+    "Extract parameters from a function node with inline documentation."
+    if not hasattr(fn, 'args'): return []
+    args, defs = fn.args.args, fn.args.defaults
+    pad = [None] * (len(args) - len(defs))
+    return [Param(a.arg, ast.unparse(a.annotation) if a.annotation else None, ast.unparse(d) if d else None, inline_doc(ls, a.lineno, a.arg)) for a, d in zip(args, pad + defs) if a.arg not in ('self', 'cls')]
+
+def parse_class_params(
+    n:ast.ClassDef, # class node to extract params from
+    ls:list,        # source lines for inline doc
+)->list[Param]:     # list of class attribute parameters
+    "Extract annotated class attributes as parameters."
+    return [Param(t.id, ast.unparse(a.annotation) if a.annotation else None, None, inline_doc(ls, a.lineno, t.id))
+            for a in n.body if isinstance(a, ast.AnnAssign) and isinstance((t := a.target), ast.Name)]
+
+def parse_ret(
+    fn,  # function node to parse return annotation from
+    ls,  # source code lines
+)->tuple[str,str]|None:  # tuple of (return type, inline doc) or None
+    "Extract return type annotation and inline documentation from function node."
+    if not fn.returns or isinstance(fn.returns, ast.Constant): return None
+    return (ast.unparse(fn.returns), inline_doc(ls, fn.returns.lineno, '->') if hasattr(fn.returns, 'lineno') else '')
+
+def src_with_decs(
+    n,   # AST node with potential decorators
+    ls,  # source code lines
+)->str:  # source code including decorators
+    "Extract source code including decorators from AST node."
+    start = n.decorator_list[0].lineno - 1 if n.decorator_list else n.lineno - 1
+    return '\n'.join(ls[start:n.end_lineno])
+
+def is_export(
+    d,   # decorator node to check
+)->bool: # whether decorator marks node for export
+    "Check if decorator marks a node for export."
+    return ast.unparse(d.func if isinstance(d, ast.Call) else d) in {'app.function', 'app.class_definition'}
+
+def parse_import(
+    n:ast.AST, # AST node to check
+    ls:list,   # source lines (unused but kept for consistent interface)
+)->Node|None:  # Node if import statement, else None
+    "Extract import node from AST."
+    if isinstance(n, (ast.Import, ast.ImportFrom)): return Node(Kind.IMP, '', ast.unparse(n))
+
+def parse_const(
+    n:ast.AST, # AST node to check
+    ls:list,   # source lines (unused)
+)->Node|None:  # Node if constant assignment, else None
+    "Extract constant definition (dunder-prefixed, non-dunder-suffixed)."
+    if not isinstance(n, ast.Assign): return None
+    for t in n.targets:
+        if isinstance(t, ast.Name) and t.id.startswith('__') and not t.id.endswith('__'): return Node(Kind.CONST, t.id, ast.unparse(n))
+
+def parse_export(
+    n:ast.AST, # AST node to check
+    ls:list,   # source lines for inline doc and decorators
+)->Node|None:  # Node if exported function/class, else None
+    "Extract exported function or class decorated with @app.function or @app.class_definition."
+    if not isinstance(n, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)): return None
+    if not any(is_export(d) for d in n.decorator_list) or n.name.startswith('test_'): return None
+    doc, src = ast.get_docstring(n) or '', src_with_decs(n, ls)
+    if isinstance(n, ast.ClassDef): return Node(Kind.EXP, n.name, src, doc, parse_class_params(n, ls), None)
+    return Node(Kind.EXP, n.name, src, doc, parse_params(n, ls), parse_ret(n, ls))
+
+def parse_node(
+    n:ast.AST, # AST node to parse
+    src:str,   # full source code text
+):             # yields Node objects for imports, constants, and exports
+    "Extract importable nodes from an AST node."
+    ls = src.splitlines()
+    if isinstance(n, ast.With):
+        for s in n.body:
+            if (node := parse_import(s, ls)): yield node
+            if (node := parse_const(s, ls)): yield node
+    if (node := parse_export(n, ls)): yield node
+
+def parse_file(
+    p:str|Path, # path to Python file to parse
+)->list[Node]:  # list of parsed nodes from the file
+    "Parse a Python file and extract all nodes."
+    src = Path(p).read_text()
+    return [node for n in ast.parse(src).body for node in parse_node(n, src)]
+
+def read_meta(
+    root='.', # project root directory containing pyproject.toml
+)->dict:      # metadata dict with name, version, desc, license, author
+    "Read project metadata from pyproject.toml."
+    with open(Path(root)/'pyproject.toml', 'rb') as f: p = tomllib.load(f).get('project', {})
+    a = (p.get('authors') or [{}])[0]
+    author = f"{a.get('name','')} <{a.get('email','')}>".strip(' <>') if isinstance(a, dict) else str(a)
+    lic = p.get('license', {})
+    return dict(name=p.get('name',''), version=p.get('version','0.0.0'), desc=p.get('description',''), license=lic.get('text','') if isinstance(lic, dict) else lic, author=author)
+
+def nb_name(
+    f:Path,   # file path to extract notebook name from
+)->str|None:  # cleaned notebook name or None if should be skipped
+    "Extract notebook name from file path, skipping hidden, test, and XX_ prefixed files."
+    if f.name.startswith('.') or f.stem.startswith('XX_'): return None
+    name = re.sub(r'^\d+_', '', f.stem)
+    return None if name.startswith('test') else name
+
+def scan(
+    nbs='notebooks', # directory containing notebook .py files
+    root='.',        # root directory containing pyproject.toml
+):                   # tuple of (meta dict, list of (name, nodes) tuples)
+    "Scan notebooks directory and extract metadata and module definitions."
+    meta = read_meta(root)
+    mods = [(name, parse_file(f)) for f in sorted(Path(nbs).glob('*.py')) if (name := nb_name(f))]
+    return meta, mods