DSPy: The framework for programming—not prompting—language models
Python
import gzip
import json
from pathlib import Path
import pytest
from docs.hooks import fetch_stats as stats_hook
from docs.scripts.zensical_build import (
add_missing_titles,
convert_notebooks,
generate_llms,
load_config,
nav_entries,
navigation_titles,
prepare_config,
redirect_maps,
remove_redirect_sources,
social_cards,
validate_output,
write_page_markdown,
write_redirects,
)
def test_zensical_configuration_is_native_and_keeps_build_compatibility_separate():
project = Path(__file__).parents[2] / "docs"
config = load_config(project / "mkdocs.yml")
build = load_config(project / "build.yml")
assert config["theme"]["variant"] == "classic"
assert "name" not in config["theme"]
assert [plugin if isinstance(plugin, str) else next(iter(plugin)) for plugin in config["plugins"]] == [
"search",
"minify",
"mkdocstrings",
"redirects",
]
assert "hooks" not in config
redirects = next(plugin["redirects"] for plugin in config["plugins"] if "redirects" in plugin)
assert redirects["redirect_maps"]["intro/index.md"] == "index.md"
assert "Tutorials - Notebooks" in build["llms"]["sections"]
def test_extracts_navigation_titles(tmp_path):
config = tmp_path / "mkdocs.yml"
config.write_text(
"nav:\n - Overview: index.md\n - Retrieval-Augmented Generation (RAG): tutorials/rag/index.md\n"
)
parsed = load_config(config)
assert navigation_titles(parsed) == {
"/": "DSPy",
"/tutorials/rag/": "Retrieval-Augmented Generation (RAG)",
}
def test_adds_navigation_title_only_when_a_page_has_no_heading(tmp_path):
docs = tmp_path / "docs"
(docs / "tutorials" / "classification").mkdir(parents=True)
missing = docs / "tutorials" / "classification" / "index.md"
missing.write_text("Page content\n")
existing = docs / "guide.md"
existing.write_text("# Existing\n")
config = tmp_path / "mkdocs.yml"
config.write_text("nav:\n - Classification: tutorials/classification/index.md\n - Guide: guide.md\n")
add_missing_titles(docs, nav_entries(load_config(config)["nav"]))
assert missing.read_text().startswith("# Classification\n\n")
assert existing.read_text() == "# Existing\n"
def test_notebook_conversion_preserves_python_pages(tmp_path):
nbformat = pytest.importorskip("nbformat")
notebook = nbformat.v4.new_notebook(cells=[nbformat.v4.new_markdown_cell("# Guide")])
nbformat.write(notebook, tmp_path / "guide.ipynb")
helper = tmp_path / "helper.py"
helper.write_text("VALUE = 1\n")
routes = convert_notebooks(tmp_path)
assert routes == {"guide/index.html", "helper/index.html"}
assert (tmp_path / "guide.md").exists()
assert helper.exists()
assert "```python\nVALUE = 1" in (tmp_path / "helper.md").read_text()
def test_llms_generation_uses_the_configured_inventory(tmp_path):
docs = tmp_path / "docs"
(docs / "guides").mkdir(parents=True)
(docs / "index.md").write_text("# DSPy\n")
(docs / "guides" / "first.md").write_text("# First Guide\n")
(docs / "excluded.md").write_text("# Excluded\n")
output = tmp_path / "llms.txt"
generate_llms(
docs,
output,
"https://dspy.ai/",
{
"markdown_description": "Description",
"sections": {
"Home": [{"index.md": "Overview"}],
"Guides": ["guides/**.md"],
},
},
)
result = output.read_text()
assert "Description" in result
assert "[DSPy](https://dspy.ai/index.md): Overview" in result
assert "[First Guide](https://dspy.ai/guides/first/index.md)" in result
assert "Excluded" not in result
def test_page_markdown_is_written_beside_rendered_pages(tmp_path):
for module in ("bs4", "markdownify", "mdformat"):
pytest.importorskip(module)
guide = tmp_path / "guides" / "first" / "index.html"
guide.parent.mkdir(parents=True)
guide.write_text(
"<html><body><nav>Navigation</nav><article>"
'<h1 id="first">First<a class="headerlink" href="#first">¶</a></h1>'
'<p>See <a href="../second/#setup">Second</a>, <a href="../../learn/">Learn</a>,'
' <a href="/learn#steps">Steps</a>, <a href="../../gone/">Gone</a>'
' and <a href="https://example.com/">elsewhere</a>.</p>'
"<div class=\"highlight\"><pre><code>print('hi')</code></pre></div>"
"</article></body></html>"
)
second = tmp_path / "guides" / "second" / "index.html"
second.parent.mkdir()
second.write_text("<article><h1>Second</h1></article>")
redirect = tmp_path / "learn" / "index.html"
redirect.parent.mkdir()
redirect.write_text('<meta http-equiv="refresh" content="0; url=../guides/first/">')
write_page_markdown(tmp_path, "https://dspy.ai/current/", {"learn/index.md": "guides/second.md"})
markdown = (tmp_path / "guides" / "first" / "index.md").read_text()
assert markdown.startswith("# First\n")
assert "Navigation" not in markdown
assert "¶" not in markdown
assert "[Second](https://dspy.ai/current/guides/second/index.md#setup)" in markdown
assert "[Learn](https://dspy.ai/current/guides/second/index.md)" in markdown
assert "[Steps](https://dspy.ai/current/guides/second/index.md#steps)" in markdown
assert "[Gone](https://dspy.ai/current/gone/)" in markdown
assert "[elsewhere](https://example.com/)" in markdown
assert "```\nprint('hi')\n```" in markdown
assert (tmp_path / "guides" / "second" / "index.md").read_text() == "# Second\n"
assert not (tmp_path / "learn" / "index.md").exists()
def test_public_stats_api_does_not_leak_cache_metadata(tmp_path, monkeypatch):
cache = tmp_path / "stats.json"
fetched = {"stars": "10k"}
monkeypatch.setattr(stats_hook, "CACHE_DIR", tmp_path)
monkeypatch.setattr(stats_hook, "CACHE_FILE", cache)
monkeypatch.setattr(stats_hook, "_fetch_all", lambda: fetched)
result = stats_hook.fetch_stats()
assert result == {"stars": "10k"}
assert fetched == {"stars": "10k"}
assert stats_hook.fetch_stats() == {"stars": "10k"}
assert set(json.loads(cache.read_text())) == {"stars", "_ts", "_cache_version"}
def test_prepared_config_exposes_stats_without_mutating_source():
source = {"extra": {"social": []}}
prepared = prepare_config(source, {"stars": "10k"})
assert prepared["extra"] == {"social": [], "stats": {"stars": "10k"}}
assert source == {"extra": {"social": []}}
def test_social_cards_replace_renderer_image_metadata(tmp_path):
image = pytest.importorskip("PIL.Image")
logo = tmp_path / "logo.png"
image.new("RGBA", (16, 16), "red").save(logo)
home = tmp_path / "index.html"
home.write_text(
"<html><head>"
'<meta content="https://renderer.example/og.png" property="og:image">'
'<meta name="twitter:image" content="https://renderer.example/twitter.png">'
"</head><body><article>Home</article></body></html>"
)
social_cards(tmp_path, "https://dspy.ai/current/", {"/": "DSPy"}, logo)
rendered = home.read_text()
card = "https://dspy.ai/current/assets/images/social-zensical/8a5edab282632443.png"
assert rendered.count('property="og:image"') == 1
assert rendered.count('name="twitter:image"') == 1
assert 'property="twitter:image"' not in rendered
assert rendered.count(f'content="{card}"') == 2
assert "renderer.example" not in rendered
def test_redirect_sources_are_removed_only_from_prepared_tree(tmp_path):
source = tmp_path / "learn" / "index.md"
source.parent.mkdir()
source.write_text("legacy content")
config = {"plugins": [{"redirects": {"redirect_maps": {"learn/index.md": "index.md"}}}]}
remove_redirect_sources(tmp_path, config)
assert not source.exists()
assert redirect_maps(config) == {"learn/index.md": "index.md"}
def test_redirects_preserve_relative_navigation_query_and_fragment(tmp_path):
write_redirects(
tmp_path,
{
"learn/index.md": "getting-started/first-program.md",
"api/old.md": "api/new/index.md",
},
)
learn = (tmp_path / "learn" / "index.html").read_text()
api = (tmp_path / "api" / "old" / "index.html").read_text()
assert 'location.replace("../getting-started/first-program/"+location.search+location.hash)' in learn
assert 'href="../getting-started/first-program/"' in learn
assert 'location.replace("../new/"+location.search+location.hash)' in api
def test_output_validation_covers_native_and_compatibility_features(tmp_path):
required = ("index.html", "api/index.html", "llms.txt", "sitemap.xml")
for relative in required:
path = tmp_path / relative
path.parent.mkdir(parents=True, exist_ok=True)
path.write_text('<article></article><meta property="og:image">')
(tmp_path / "search.json").write_text(json.dumps({"items": [{"location": "/"}]}))
with gzip.open(tmp_path / "sitemap.xml.gz", "wb") as compressed:
compressed.write((tmp_path / "sitemap.xml").read_bytes())
notebook = tmp_path / "tutorial" / "index.html"
notebook.parent.mkdir()
notebook.write_text("notebook")
redirect = tmp_path / "old" / "index.html"
redirect.parent.mkdir()
redirect.write_text("redirect")
cards = tmp_path / "assets" / "images" / "social-zensical"
cards.mkdir(parents=True)
(cards / "home.png").write_bytes(b"card")
(tmp_path / "llms.txt").write_text("- [Home](https://dspy.ai/current/index.md): Overview\n")
(tmp_path / "index.md").write_text("# Home\n")
site_url = "https://dspy.ai/current/"
validate_output(tmp_path, {"tutorial/index.html"}, {"old.md": "index.md"}, site_url)
(tmp_path / "index.md").unlink()
with pytest.raises(RuntimeError, match=r"missing required files: https://dspy.ai/current/index.md"):
validate_output(tmp_path, {"tutorial/index.html"}, {"old.md": "index.md"}, site_url)
(tmp_path / "index.md").write_text("# Home\n")
(tmp_path / "search.json").write_text(json.dumps({"items": []}))
with pytest.raises(RuntimeError, match="search index is empty"):
validate_output(tmp_path, {"tutorial/index.html"}, {"old.md": "index.md"}, site_url)