#!/usr/bin/env python3 """Parse README.md and generate a static HTML site for awesome-quant. Can run in two modes: 1. With projects.csv (produced by parse.py) — includes stars, last commit, etc. 2. Without CSV — parses README.md directly for a quick local preview. """ import csv import html import re import sys from pathlib import Path def slugify(text: str) -> str: """Convert text to lowercase hyphen-separated slug.""" text = text.lower().strip() text = re.sub(r"[&/]+", "-", text) text = re.sub(r"[^\w\s-]", "", text) text = re.sub(r"[\s_]+", "-", text) text = re.sub(r"-+", "-", text) return text.strip("-") def parse_readme(path: str) -> list[dict]: """Parse README.md and return a list of project entries (no API data).""" entries = [] current_language = "" current_category = "" re_h2 = re.compile(r"^## (.+)$") re_h3 = re.compile(r"^### (.+)$") re_entry = re.compile(r"^\s*- \[(.+?)\]\((.+?)\) - (.+)$") re_github = re.compile(r"\[GitHub\]\((https://github\.com/[\w-]+/[-\w\.]+)\)") skip_sections = {"Languages"} # Strip markdown badge images before parsing re_badge = re.compile(r"\s*!\[[^\]]*\]\([^)]*\)\s*") with open(path, "r", encoding="utf-8") as f: for line in f: line = re_badge.sub(" ", line).rstrip("\n") m = re_h2.match(line) if m: current_language = m.group(1).strip() current_category = "" continue m = re_h3.match(line) if m: current_category = m.group(1).strip() continue if current_language in skip_sections: continue m = re_entry.match(line) if m: name = m.group(1).strip() url = m.group(2).strip() desc = m.group(3).strip() github_url = "" gh_match = re_github.search(desc) if gh_match: github_url = gh_match.group(1) desc = re_github.sub("", desc).rstrip(". ").rstrip() + "." elif "github.com" in url: github_url = url repo = "" if github_url: repo_match = re.match( r"https://github\.com/([\w-]+/[-\w\.]+)", github_url ) if repo_match: repo = repo_match.group(1) is_cran = "cran.r-project.org" in url is_pypi = "pypi.org" in url or "pypi.python.org" in url is_commercial = current_language == "Commercial & Proprietary Services" category = current_category or current_language section_slug = slugify(category) entries.append( { "project": name, "language": current_language, "category": category, "section_slug": section_slug, "url": url, "description": desc, "github": bool(github_url), "cran": is_cran, "pypi": is_pypi, "commercial": is_commercial, "github_url": github_url, "repo": repo, "stars": 0, "last_commit": "", } ) return entries def load_csv(path: str) -> list[dict]: """Load projects from CSV produced by parse.py.""" entries = [] with open(path, "r", encoding="utf-8") as f: reader = csv.DictReader(f) for row in reader: # Normalize booleans for key in ("github", "cran", "pypi", "commercial"): row[key] = row.get(key, "").lower() in ("true", "1", "yes") # Normalize numbers row["stars"] = int(float(row.get("stars", 0) or 0)) # Extract github_url and repo from CSV data repo = row.get("repo", "") row["github_url"] = f"https://github.com/{repo}" if repo else "" # Clean description: strip [GitHub](url) if present desc = row.get("description", "") desc = re.sub( r"\s*\[GitHub\]\(https://github\.com/[\w-]+/[-\w\.]+\)\s*", "", desc, ) desc = desc.rstrip(". ").rstrip() if desc and not desc.endswith("."): desc += "." row["description"] = desc entries.append(row) return entries def format_stars(n: int) -> str: """Format star count for display.""" if n >= 1000: return f"{n / 1000:.1f}k".replace(".0k", "k") return str(n) if n > 0 else "" def build_tags_html(e: dict) -> str: """Build tag pills for an entry.""" esc = html.escape tags = [] # Language tag lang = e.get("language", "") if lang and lang != "Commercial & Proprietary Services" and lang != "Related Lists": lang_slug = slugify(lang) tags.append( f'' ) # Section tag section_slug = e.get("section_slug", "") category = e.get("category", "") if section_slug and section_slug != slugify(lang): tags.append( f'' ) # Source tags if e.get("github"): tags.append( '' ) if e.get("cran"): tags.append( '' ) if e.get("pypi"): tags.append( '' ) if e.get("commercial"): tags.append( '' ) return "\n ".join(tags) def generate_html(entries: list[dict]) -> str: """Generate the full HTML page from project entries.""" languages = sorted( set( e["language"] for e in entries if e.get("language") and e["language"] != "Languages" ) ) # Build table rows rows = [] for i, e in enumerate(entries, 1): esc = html.escape name = esc(e["project"]) url = esc(e["url"]) desc = esc(e["description"]) language = esc(e.get("language", "")) category = esc(e.get("category", "")) github_url = esc(e.get("github_url", "")) repo = esc(e.get("repo", "")) stars = int(e.get("stars", 0) or 0) last_commit = e.get("last_commit", "") or "" is_github = e.get("github", False) is_cran = e.get("cran", False) is_pypi = e.get("pypi", False) is_commercial = e.get("commercial", False) # Stars display stars_html = ( f'' f'' f" {format_stars(stars)}" if stars > 0 else "" ) # Last update display last_update_html = ( f'{esc(last_commit)}' if last_commit and last_commit != "error" else "" ) # Source flags for data attributes sources = [] if is_github: sources.append("github") if is_cran: sources.append("cran") if is_pypi: sources.append("pypi") if is_commercial: sources.append("commercial") sources_attr = esc(" ".join(sources)) tags_html = build_tags_html(e) rows.append( f""" {i} {name} {category} {stars_html} {last_update_html} {tags_html} ›

{desc}

{url} {f'{github_url}' if github_url and github_url != url else ''}
""" ) total = len(entries) total_stars = sum(int(e.get("stars", 0) or 0) for e in entries) return f""" Awesome Quant Skip to content

Awesome Quant

A curated list of insanely awesome libraries, packages and resources for Quants.

Maintained by Wilson Freitas

{total} projects {len(languages)} languages {format_stars(total_stars)} total stars
Browse the List
/
{chr(10).join(rows)}
# Project Stars Last Update Tags

Know a great project?

Contribute to the list by opening a pull request on GitHub.

Contribute on GitHub
""" def main(): root = Path(__file__).resolve().parent.parent readme = root / "README.md" csv_path = root / "site" / "projects.csv" output = root / "site" / "index.html" # Prefer CSV if it exists (has stars, last commit from API) if csv_path.exists(): print(f"Loading from {csv_path}") entries = load_csv(str(csv_path)) elif readme.exists(): print(f"Parsing {readme} (no CSV — stars/dates will be empty)") entries = parse_readme(str(readme)) else: print(f"ERROR: neither {csv_path} nor {readme} found", file=sys.stderr) sys.exit(1) print(f"Loaded {len(entries)} projects") html_content = generate_html(entries) output.write_text(html_content, encoding="utf-8") print(f"Generated {output}") if __name__ == "__main__": main()