DEV Community: German Yamil

Python subprocess.run() Deep Dive: Isolation, Timeouts, and Captured Output

German Yamil — Mon, 04 May 2026 21:52:49 +0000

Python subprocess.run() Deep Dive: Isolation, Timeouts, and Captured Output

subprocess.run() is one of those functions you think you understand until you actually need it to do something precise.

Here's everything it does — from basic execution to full sandboxing — with working examples for each pattern.

🎁 Free: AI Publishing Checklist — 7 steps in Python · Full pipeline: germy5.gumroad.com/l/xhxkzz (pay what you want, min $9.99)

The signature

subprocess.run(
    args,                    # command as list or string
    *,
    stdin=None,
    input=None,
    capture_output=False,    # shorthand for stdout=PIPE, stderr=PIPE
    stdout=None,
    stderr=None,
    shell=False,
    cwd=None,                # working directory for the subprocess
    timeout=None,            # seconds before TimeoutExpired is raised
    check=False,             # raise CalledProcessError on non-zero exit
    encoding=None,
    errors=None,
    env=None,                # environment variables dict
    text=False,              # alias for encoding='utf-8'
    **kwargs
) -> CompletedProcess

Pattern 1: Capture stdout and stderr separately

import subprocess

result = subprocess.run(
    ["python3", "-c", "import sys; print('out'); print('err', file=sys.stderr)"],
    stdout=subprocess.PIPE,
    stderr=subprocess.PIPE,
    text=True,
)

print(f"stdout: {result.stdout!r}")   # 'out\n'
print(f"stderr: {result.stderr!r}")   # 'err\n'
print(f"exit:   {result.returncode}") # 0

Use capture_output=True as shorthand for stdout=PIPE, stderr=PIPE:

result = subprocess.run(
    ["python3", "-c", "print('hello')"],
    capture_output=True,
    text=True,
)
print(result.stdout)  # 'hello\n'

When to use: Any time you need to inspect the output programmatically rather than let it print to the terminal.

Pattern 2: Timeout enforcement

import subprocess

def run_with_timeout(cmd: list, timeout_seconds: int = 30) -> subprocess.CompletedProcess:
    try:
        return subprocess.run(
            cmd,
            capture_output=True,
            text=True,
            timeout=timeout_seconds,
        )
    except subprocess.TimeoutExpired as e:
        print(f"Command timed out after {timeout_seconds}s")
        print(f"Partial stdout: {e.stdout}")
        raise

# This will time out:
try:
    run_with_timeout(
        ["python3", "-c", "import time; time.sleep(100)"],
        timeout_seconds=2,
    )
except subprocess.TimeoutExpired:
    print("Caught timeout — subprocess killed")

When to use: Any time you're running untrusted or user-supplied code. Without a timeout, an infinite loop hangs your process forever.

Pattern 3: Directory isolation with cwd

import subprocess, tempfile, os

def run_isolated(script_content: str, timeout: int = 30) -> subprocess.CompletedProcess:
    """Run a script in a fresh temp directory — no access to parent dir."""
    with tempfile.TemporaryDirectory() as tmpdir:
        script_path = os.path.join(tmpdir, "script.py")
        with open(script_path, "w") as f:
            f.write(script_content)

        return subprocess.run(
            ["python3", script_path],
            capture_output=True,
            text=True,
            timeout=timeout,
            cwd=tmpdir,         # subprocess starts in the temp dir
        )

# Script that tries to read a parent directory file — will fail cleanly
result = run_isolated("""
import os
try:
    files = os.listdir('..')
    print(f"Parent dir: {files[:3]}")
except PermissionError:
    print("No access to parent")

# But can write/read within its own dir
with open('output.txt', 'w') as f:
    f.write('hello')
print(f"Created file: {os.path.exists('output.txt')}")
""")
print(result.stdout)
# Created file: True  (but the temp dir is deleted when context exits)

When to use: Running generated or untrusted code where you want a clean working directory and no accidental access to your project files.

Pattern 4: Environment variable injection

import subprocess, os

def run_with_env(cmd: list, extra_env: dict) -> subprocess.CompletedProcess:
    """Run with a modified environment — inherits current env, adds/overrides keys."""
    env = os.environ.copy()
    env.update(extra_env)
    return subprocess.run(cmd, capture_output=True, text=True, env=env)

result = run_with_env(
    ["python3", "-c", "import os; print(os.environ.get('MY_VAR', 'not set'))"],
    {"MY_VAR": "injected_value"},
)
print(result.stdout)  # injected_value

For a completely clean environment (no inherited vars):

result = subprocess.run(
    ["python3", "-c", "import os; print(len(os.environ))"],
    capture_output=True,
    text=True,
    env={"PATH": "/usr/bin:/bin"},  # minimal env only
)
# Output: 1

Pattern 5: check=True for fail-fast pipelines

import subprocess

def run_checked(cmd: list) -> str:
    """Run command, raise immediately on non-zero exit."""
    result = subprocess.run(
        cmd,
        capture_output=True,
        text=True,
        check=True,   # raises CalledProcessError on non-zero exit
    )
    return result.stdout

try:
    output = run_checked(["python3", "-c", "exit(1)"])
except subprocess.CalledProcessError as e:
    print(f"Command failed with exit code {e.returncode}")
    print(f"stderr: {e.stderr}")

When to use: In pipelines where a failure at any step should stop the whole chain. Equivalent to set -e in bash.

Pattern 6: stdin piping

import subprocess

result = subprocess.run(
    ["python3", "-c", "import sys; data = sys.stdin.read(); print(data.upper())"],
    input="hello from stdin\n",
    capture_output=True,
    text=True,
)
print(result.stdout)  # HELLO FROM STDIN

Pipe one process's output to another:

p1 = subprocess.run(
    ["python3", "-c", "print('line1\\nline2\\nline3')"],
    capture_output=True, text=True,
)
p2 = subprocess.run(
    ["python3", "-c", "import sys; [print(l.upper()) for l in sys.stdin]"],
    input=p1.stdout,
    capture_output=True, text=True,
)
print(p2.stdout)
# LINE1
# LINE2
# LINE3

Full validation harness

This is what I use in the ebook pipeline — all patterns combined:

import subprocess, tempfile, os
from dataclasses import dataclass

@dataclass
class ValidationResult:
    """Result of running a script through the validation harness."""
    passed: bool
    exit_code: int
    stdout: str
    stderr: str
    timed_out: bool = False

    def __bool__(self):
        return self.passed

def validate_script(
    code: str,
    timeout: int = 30,
    extra_env: dict = None,
) -> ValidationResult:
    """
    Run a Python script in complete isolation and return structured results.

    Args:
        code: Python source code to run
        timeout: Maximum execution time in seconds
        extra_env: Additional environment variables to inject

    Returns:
        ValidationResult with pass/fail and captured output
    """
    env = {"PATH": os.environ.get("PATH", "/usr/bin:/bin")}
    if extra_env:
        env.update(extra_env)

    with tempfile.TemporaryDirectory() as tmpdir:
        script_path = os.path.join(tmpdir, "test.py")
        with open(script_path, "w", encoding="utf-8") as f:
            f.write(code)

        try:
            result = subprocess.run(
                ["python3", script_path],
                capture_output=True,
                text=True,
                timeout=timeout,
                cwd=tmpdir,
                env=env,
            )
            return ValidationResult(
                passed=(result.returncode == 0),
                exit_code=result.returncode,
                stdout=result.stdout,
                stderr=result.stderr,
            )
        except subprocess.TimeoutExpired:
            return ValidationResult(
                passed=False,
                exit_code=-1,
                stdout="",
                stderr=f"Timed out after {timeout}s",
                timed_out=True,
            )

# Usage
code = '''
def greet(name: str) -> str:
    """Return a greeting string."""
    return f"Hello, {name}!"

if __name__ == "__main__":
    print(greet("world"))
'''

result = validate_script(code)
if result:
    print(f"✅ Passed — stdout: {result.stdout.strip()}")
else:
    print(f"❌ Failed — stderr: {result.stderr}")

CompletedProcess reference

result = subprocess.run(["echo", "hello"], capture_output=True, text=True)

result.args        # ['echo', 'hello']
result.returncode  # 0
result.stdout      # 'hello\n'
result.stderr      # ''
result.check_returncode()  # raises CalledProcessError if non-zero

This validation harness (and the full two-gate system using ast.parse() + subprocess.run()) is included in: germy5.gumroad.com/l/xhxkzz — pay what you want, min $9.99.

I'm Using Python to Automate My Own Marketing — Here's Every Script

German Yamil — Mon, 04 May 2026 14:13:23 +0000

I'm Using Python to Automate My Own Marketing — Here's Every Script

I built a pipeline that writes and publishes technical ebooks automatically.

Then I realized: why am I manually marketing it?

So I automated the marketing too. Here's every script I wrote to run a full content operation without logging into any dashboard.

🎁 Free: AI Publishing Checklist — 7 steps in Python · Full pipeline: germy5.gumroad.com/l/xhxkzz (pay what you want, min $9.99)

The stack: 4 APIs, 2 crons, 0 dashboards

Task	Tool	Script
Publish articles	Dev.to API	`publish_devto.py`
Auto-publish queue	Dev.to API + cron	`auto_publish_queue.py`
Update article tags	Dev.to API	inline script
Add CTAs to articles	Dev.to API	inline script
Generate cover images	Pillow	`make_covers.py`
Upload images	Imgur API	inline script
Attach covers to articles	Dev.to API	inline script
RSS ping	xmlrpc	`daily_ping.py`
Update product pricing	Gumroad API	inline script
Update product copy	Gumroad API	inline script
Track analytics	Dev.to API	`check_stats.py`

No Buffer. No Hootsuite. No Notion. Pure Python.

Script 1: Auto-publish queue

The core script. Publishes one article per day from a JSON queue, called by cron at 10am.

#!/usr/bin/env python3
"""
Publishes one article from publish_queue.json to Dev.to.
Cron: 0 10 * * * python3 auto_publish_queue.py
"""
import os, re, json, requests
from datetime import date

QUEUE_FILE = "publish_queue.json"
TOKEN = os.environ["DEVTO_TOKEN"]

def load_queue():
    with open(QUEUE_FILE) as f:
        return json.load(f)

def save_queue(q):
    with open(QUEUE_FILE, "w") as f:
        json.dump(q, f, indent=2)

def parse_frontmatter(content):
    match = re.match(r'^---\n(.*?)\n---\n', content, re.DOTALL)
    fm = {}
    for line in match.group(1).splitlines():
        if line.startswith('tags: '):
            fm['tags'] = [t.strip() for t in line[6:].split(',')]
        elif ': ' in line:
            k, _, v = line.partition(': ')
            fm[k.strip()] = v.strip().strip('"')
    return fm

def publish(filepath):
    with open(filepath) as f:
        content = f.read()
    fm = parse_frontmatter(content)
    headers = {"api-key": TOKEN, "Content-Type": "application/json"}
    payload = {"article": {
        "title": fm["title"],
        "body_markdown": content,
        "published": True,
        "tags": fm.get("tags", []),
        "description": fm.get("description", ""),
    }}
    resp = requests.post("https://dev.to/api/articles", headers=headers, json=payload)
    resp.raise_for_status()
    return resp.json()

q = load_queue()
if not q["pending"]:
    print("Queue empty")
    exit(0)

item = q["pending"][0]
result = publish(item["filename"])
url = f"https://dev.to{result['path']}"
print(f"✅ Published: {url}")

q["pending"].pop(0)
q["published"].append({
    "filename": item["filename"],
    "title": item["title"],
    "date": str(date.today()),
    "url": url,
    "id": result["id"],
})
save_queue(q)

Script 2: Bulk tag update

When I discovered #career gets 3-5x more views than #automation, I needed to update 6 articles immediately.

import requests, re, time

TOKEN = os.environ["DEVTO_TOKEN"]
HEADERS = {"api-key": TOKEN, "Content-Type": "application/json"}

# {article_id: new_tag_list}
UPDATES = {
    3507086: ["python", "tutorial", "career", "productivity"],
    3487145: ["python", "productivity", "career", "selfpublishing"],
    3511931: ["python", "career", "productivity", "selfpublishing"],
}

for article_id, new_tags in UPDATES.items():
    # Get current body
    r = requests.get(f"https://dev.to/api/articles/{article_id}", headers=HEADERS)
    body = r.json()["body_markdown"]

    # Replace tags line in frontmatter
    tags_str = ", ".join(new_tags)
    new_body = re.sub(r'^tags:.*$', f'tags: {tags_str}', body, flags=re.MULTILINE)

    # Update
    resp = requests.put(f"https://dev.to/api/articles/{article_id}",
        headers=HEADERS, json={"article": {"body_markdown": new_body}})

    print(f"✅ {article_id}: {resp.json().get('tag_list')}")
    time.sleep(1.5)

Key insight: Dev.to ignores the tags field in PUT requests — it only reads tags from the frontmatter inside body_markdown. You have to update the markdown, not the metadata field.

Script 3: Bulk CTA injection

I added a dual CTA (free + paid) to all 22 articles in one run.

CTA_BLOCK = """
---
> **🎁 Free:** [AI Publishing Checklist](https://germy5.gumroad.com/l/vlvhld) \
· **Full pipeline:** [germy5.gumroad.com/l/xhxkzz](https://germy5.gumroad.com/l/xhxkzz) (min $9.99)
---

"""

def insert_cta(body: str, cta: str) -> str:
    lines = body.split('\n')
    # Find end of frontmatter
    fm_end = 0
    if lines[0].strip() == '---':
        for i in range(1, len(lines)):
            if lines[i].strip() == '---':
                fm_end = i + 1
                break

    # Find after 2nd paragraph break
    blank_count = 0
    insert_at = fm_end + 2
    for i in range(fm_end, min(fm_end + 50, len(lines))):
        if lines[i].strip() == '':
            blank_count += 1
            if blank_count >= 2:
                insert_at = i + 1
                break

    new_lines = lines[:insert_at] + cta.split('\n') + lines[insert_at:]
    return '\n'.join(new_lines)

Script 4: Cover image generation

Articles with cover images get 2-3x more clicks in the Dev.to feed. I generate them with Pillow.

from PIL import Image, ImageDraw, ImageFont
import textwrap

def make_cover(title: str, subtitle: str, output_path: str, accent: str = "#6366f1"):
    W, H = 1000, 420
    img = Image.new("RGB", (W, H), "#0f172a")
    draw = ImageDraw.Draw(img)

    # Left accent stripe
    for x in range(10):
        draw.rectangle([x, 0, x+1, H], fill=accent)

    # Top-right accent bar
    draw.rectangle([W-220, 0, W, 6], fill=accent)

    # Load fonts
    try:
        ft = ImageFont.truetype("/System/Library/Fonts/Helvetica.ttc", 38)
        fs = ImageFont.truetype("/System/Library/Fonts/Helvetica.ttc", 18)
        fb = ImageFont.truetype("/System/Library/Fonts/Helvetica.ttc", 13)
    except:
        ft = fs = fb = ImageFont.load_default()

    # Tag line
    draw.text((40, 30), "dev.to · #python · #automation", fill="#94a3b8", font=fb)

    # Title
    y = 90
    for line in textwrap.wrap(title, 36)[:3]:
        draw.text((40, y), line, fill="#f8fafc", font=ft)
        y += 52

    # Subtitle
    y += 8
    for line in textwrap.wrap(subtitle, 60)[:2]:
        draw.text((40, y), line, fill="#94a3b8", font=fs)
        y += 28

    # Footer
    draw.rectangle([0, H-48, W, H], fill="#1e293b")
    draw.text((40, H-32), "germy5.gumroad.com/l/xhxkzz", fill="#94a3b8", font=fb)

    img.save(output_path, "PNG")
    return output_path

Script 5: Imgur upload + Dev.to attachment

import base64, requests

def upload_cover(img_path: str, article_id: int):
    # Upload to Imgur (anonymous — no auth needed)
    with open(img_path, "rb") as f:
        b64 = base64.b64encode(f.read()).decode()

    r = requests.post("https://api.imgur.com/3/image",
        headers={"Authorization": "Client-ID YOUR_CLIENT_ID"},
        data={"image": b64, "type": "base64"})
    img_url = r.json()["data"]["link"]

    # Attach to Dev.to article
    headers = {"api-key": DEVTO_TOKEN, "Content-Type": "application/json"}
    requests.put(f"https://dev.to/api/articles/{article_id}",
        headers=headers,
        json={"article": {"main_image": img_url}})

    return img_url

Script 6: RSS ping (daily cron, 9am)

#!/usr/bin/env python3
"""Ping RSS aggregators to request re-indexing."""
import xmlrpc.client
from datetime import datetime

FEED_URL = "https://dev.to/feed/german_yamil_e021eef8710d"

services = [
    "http://rpc.pingomatic.com/",
    "http://ping.blogs.yandex.ru/RPC2",
    "http://rpc.weblogs.com/RPC2",
]

for service in services:
    try:
        server = xmlrpc.client.ServerProxy(service)
        server.weblogUpdates.ping("AI Publishing Pipeline", FEED_URL)
    except:
        pass

print(f"{datetime.now():%Y-%m-%d %H:%M} — Pings sent to {len(services)} services")

Cron entry:

0 9 * * * python3 /path/to/daily_ping.py >> ping.log 2>&1
0 10 * * * python3 /path/to/auto_publish_queue.py >> queue.log 2>&1

Stats script

import requests

TOKEN = os.environ["DEVTO_TOKEN"]
headers = {"api-key": TOKEN}

arts = requests.get("https://dev.to/api/articles/me", headers=headers).json()

total_views = sum(a["page_views_count"] for a in arts)
total_reactions = sum(a["positive_reactions_count"] for a in arts)

print(f"Articles: {len(arts)}")
print(f"Views:    {total_views}")
print(f"Reactions:{total_reactions}")

for a in sorted(arts, key=lambda x: x["page_views_count"], reverse=True)[:5]:
    print(f"  [{a['page_views_count']:3d}v] {a['title'][:60]}")

What this replaces

Before Python scripts: would need Buffer ($18/mo), a content calendar tool ($12/mo), analytics dashboard ($20/mo), and 2-3 hours/week of manual posting.

After: $0 in SaaS tools, cron handles posting, a single Python script handles analytics.

The whole marketing stack is 6 scripts, ~300 lines of Python, and 2 cron jobs.

The ebook pipeline that makes the product worth marketing: germy5.gumroad.com/l/xhxkzz — pay what you want, min $9.99.

The Exact Prompts I Use to Generate Technical Ebook Chapters with Claude

German Yamil — Mon, 04 May 2026 14:04:16 +0000

The Exact Prompts I Use to Generate Technical Ebook Chapters with Claude

Prompt engineering for ebook generation is not about being clever. It's about setting up constraints that make bad outputs impossible.

Here are the exact prompts I use — system message, user message structure, and the four constraints that produce runnable, consistent, technical content at chapter scale.

🎁 Free: AI Publishing Checklist — 7 steps in Python · Full pipeline: germy5.gumroad.com/l/xhxkzz (pay what you want, min $9.99)

System Prompt

You are a technical author producing chapters for a Python programming book.

Your writing is direct, first-person, and code-forward. Every claim is demonstrated with a working code example. You never use marketing language or hedging phrases.

HARD CONSTRAINTS — these cannot be overridden by the user message:
1. Every code block must use only Python stdlib unless the chapter topic is specifically about a named third-party library
2. All variable names, function names, and inline comments must be in English
3. Every function must have a docstring
4. The chapter must end with a code example that a reader can run immediately in a clean Python environment

OUTPUT FORMAT:
- Start with the chapter title as H1
- Use H2 for major sections (3–5 sections per chapter)
- Use H3 for subsections only when necessary
- Code blocks must use triple backticks with language tag: ```

python
- Do not include a table of contents
- Do not include a conclusion section — end on the final code example

User Message Template


python
CHAPTER_PROMPT = """
Chapter {number}: {title}

Learning objective: {learning_objective}

Target length: {word_target} words (±15% is acceptable)

Style guide:
- Voice: {voice}
- Audience: {audience}
- Avoid: {avoid_list}

{notes_section}

Write this chapter now. Include:
1. An opening that states the problem this chapter solves (2–3 paragraphs, no fluff)
2. The core technical concept with a minimal working example
3. The full implementation with edge cases handled
4. A failure scenario and how to handle it
5. A closing runnable script that demonstrates everything covered

The final code block must produce visible output when run with: python3 script.py
"""

Building the prompt in code


python
import anthropic

client = anthropic.Anthropic()

def generate_chapter(chapter: dict, style_guide: dict) -> str:
    notes_section = ""
    if chapter.get("notes"):
        notes_section = f"Additional notes for this chapter:\n{chapter['notes']}"

    avoid_list = ", ".join(style_guide.get("avoid", []))

    user_message = CHAPTER_PROMPT.format(
        number=chapter["number"],
        title=chapter["title"],
        learning_objective=chapter["learning_objective"],
        word_target=chapter["word_target"],
        voice=style_guide.get("voice", "direct, technical"),
        audience=style_guide.get("audience", "experienced Python developers"),
        avoid_list=avoid_list or "passive voice, marketing language",
        notes_section=notes_section,
    )

    response = client.messages.create(
        model="claude-opus-4-5",
        max_tokens=8192,
        system=SYSTEM_PROMPT,
        messages=[{"role": "user", "content": user_message}]
    )

    return response.content[0].text

The Four Constraints That Make It Work

1. `stdlib only` — the single biggest improvement

Before adding this constraint: ~30% of generated scripts failed subprocess validation because they imported pandas, numpy, or other packages not present in the clean test environment.

After: failure rate dropped to ~10%, and the remaining failures are logic errors (wrong output format), not import errors.

2. `English variable names` — critical for bilingual output

Without this constraint: the translation LLM sometimes "helpfully" translated variable names like validar_codigo or archivo_salida into Spanish in the Spanish edition.

After: all variable names stay in English in both EN and ES chapters, which is correct behavior for a programming book.

3. `Every function must have a docstring`

This sounds minor. It's not. Docstrings force the model to articulate what a function does before writing it. The generated code is noticeably more coherent when docstrings are mandatory.

4. `End on a runnable script`

This is the most important constraint. It forces the model to produce a complete, coherent example that exercises everything in the chapter. It also means the final subprocess validation call has a meaningful target.

Translation Prompt

After the English chapter is generated and validated, the translation runs:


python
TRANSLATION_PROMPT = """
Translate the following technical Python book chapter from English to Spanish.

TRANSLATION RULES — these are mandatory:
1. All prose, headings, and explanations must be translated to Spanish
2. All code blocks must remain EXACTLY as they are — do not translate variable names, function names, comments, or string literals inside code blocks
3. The number of

 ```python code blocks must be identical to the original
4. Technical terms that are commonly used in English within Spanish technical communities (API, endpoint, pipeline, framework, debug) may remain in English
5. Do not add, remove, or reorder sections

Chapter to translate:

{english_chapter}
"""

def translate_chapter(en_content: str) -> str:
    response = client.messages.create(
        model="claude-opus-4-5",
        max_tokens=8192,
        messages=[{
            "role": "user",
            "content": TRANSLATION_PROMPT.format(english_chapter=en_content)
        }]
    )
    return response.content[0].text

Prompt Iteration Log

These are the prompts I removed after they made things worse:

❌ "Make the code production-ready" — produced over-engineered examples with complex error handling that made the learning objective harder to see.

❌ "Write in a conversational tone" — produced chatty prose that felt like a blog post, not a book chapter.

❌ "Include best practices" — vague instruction that added boilerplate comments without improving the code.

❌ "Imagine the reader is a beginner" — conflicted with the audience: experienced Python developers constraint, produced inconsistent chapters.

The current prompts are the result of about 40 generation runs across 4 books. They're conservative and explicit. They produce fewer surprises than clever prompts.

Full pipeline (including all prompt templates in PIPELINE_PROMPT_v4.md): germy5.gumroad.com/l/xhxkzz — pay what you want, min $9.99.

The outline.json Format That Drives My Automated Python Ebook Pipeline

German Yamil — Sun, 03 May 2026 19:28:37 +0000

The outline.json Format That Drives My Automated Python Ebook Pipeline

Everything in the pipeline starts with one file: outline.json.

It's the manifest. It defines what the pipeline generates, validates, translates, and publishes. Change the file, run the pipeline, get a different book.

Here's the full format, every field, and a real working example.

🎁 Free: AI Publishing Checklist — 7 steps in Python · Full pipeline: germy5.gumroad.com/l/xhxkzz (pay what you want, min $9.99)

The Schema

{
  "title": "string — full book title",
  "subtitle": "string — used in Gumroad listing and KDP metadata",
  "author": "string",
  "language_primary": "en",
  "language_secondary": "es",
  "target_word_count": 22000,
  "chapters": [
    {
      "number": 1,
      "title": "string — chapter title (used as H1)",
      "slug": "string — used for filename: chapter-01-intro",
      "word_target": 2200,
      "code_file": "string — script_01_intro.py",
      "learning_objective": "string — what the reader can do after this chapter",
      "prerequisites": ["chapter-slug-1"],
      "tags": ["python", "automation"],
      "notes": "string — optional hints for the generation prompt"
    }
  ],
  "style_guide": {
    "voice": "string",
    "audience": "string",
    "code_conventions": ["Use only Python stdlib", "All functions must have docstrings"],
    "avoid": ["passive voice", "marketing language"]
  },
  "gumroad": {
    "price_cents": 999,
    "customizable_price": true,
    "tags": ["python", "ebook", "automation"]
  }
}

Field Reference

Top-level fields

Field	Type	Required	Description
`title`	string	✅	Full book title. Used in EPUB metadata and Gumroad listing
`subtitle`	string	✅	Subtitle for KDP and Gumroad. Aim for keyword richness
`author`	string	✅	Author name as it appears on the cover and EPUB metadata
`language_primary`	string	✅	Source language code (`en`)
`language_secondary`	string	❌	Target language for translation (`es`). Omit to skip translation
`target_word_count`	integer	❌	Total book target. Used for validation: sum of chapter `word_target` must be within 15%
`chapters`	array	✅	Array of chapter objects (see below)
`style_guide`	object	❌	Injected into every chapter prompt to enforce consistent voice
`gumroad`	object	❌	Used by `gumroad_create.py` to build the listing automatically

Chapter fields

Field	Type	Required	Description
`number`	integer	✅	Chapter number. Determines processing order and filename prefix
`title`	string	✅	Chapter title. Used as H1 in the generated markdown
`slug`	string	✅	Filename-safe identifier. Output files: `{slug}-en.md`, `{slug}-es.md`, `{slug}.py`
`word_target`	integer	✅	Target word count for this chapter. Enforced: ±15% tolerance
`code_file`	string	✅	Output Python script name. This file goes through both validation gates
`learning_objective`	string	✅	Injected into prompt: "After this chapter, the reader will be able to..."
`prerequisites`	array	❌	List of chapter slugs that must be in `DONE` state before this chapter can start
`tags`	array	❌	Topic tags for this chapter. Used to tune prompt focus
`notes`	string	❌	Free-form hints injected into the generation prompt for this chapter only

style_guide fields

Field	Type	Description
`voice`	string	Tone descriptor injected into every prompt: `"direct, technical, no marketing language"`
`audience`	string	Audience definition: `"Python developers with 2+ years experience"`
`code_conventions`	array	Rules applied to every code block: `["Use only Python stdlib", "All variable names in English"]`
`avoid`	array	Patterns to suppress: `["passive voice", "hedging language", "numbered lists for 2-item sets"]`

Real Working Example

This is the actual outline.json used to produce The AI Publishing Pipeline:

{
  "title": "The AI Publishing Pipeline",
  "subtitle": "Automated Ebook System for Python Developers",
  "author": "German Yamil",
  "language_primary": "en",
  "language_secondary": "es",
  "target_word_count": 22000,
  "chapters": [
    {
      "number": 1,
      "title": "Architecture Overview: The Four-State Pipeline",
      "slug": "chapter-01-architecture",
      "word_target": 2200,
      "code_file": "script_01_state_machine.py",
      "learning_objective": "set up the chapter state machine and understand PENDING, RUNNING, DONE, NEEDS_REVIEW transitions",
      "tags": ["python", "architecture", "state-machine"]
    },
    {
      "number": 2,
      "title": "Code Validation: AST Parsing and Subprocess Isolation",
      "slug": "chapter-02-validation",
      "word_target": 2200,
      "code_file": "script_02_validation.py",
      "learning_objective": "implement two-gate code validation that prevents broken scripts from shipping",
      "prerequisites": ["chapter-01-architecture"],
      "notes": "Show both gates as composable functions. Include a deliberate failure example."
    },
    {
      "number": 3,
      "title": "Crash Recovery: Making Long Runs Resumable",
      "slug": "chapter-03-crash-recovery",
      "word_target": 2200,
      "code_file": "script_03_recovery.py",
      "learning_objective": "implement startup state normalization so any crash is safely recoverable"
    },
    {
      "number": 4,
      "title": "Translation QA: Bilingual Output with Semantic Validation",
      "slug": "chapter-04-translation",
      "word_target": 2200,
      "code_file": "script_04_translation_qa.py",
      "learning_objective": "generate Spanish translations and validate them with code fence diffing and word ratio checks"
    },
    {
      "number": 5,
      "title": "EPUB Assembly: Pandoc, Metadata, and epubcheck",
      "slug": "chapter-05-epub",
      "word_target": 2200,
      "code_file": "script_05_epub_assembly.py",
      "learning_objective": "assemble chapters into a validated EPUB3 file using Pandoc with proper metadata"
    }
  ],
  "style_guide": {
    "voice": "direct, technical, first-person singular, no marketing language",
    "audience": "Python developers with 2+ years experience who want to automate content production",
    "code_conventions": [
      "Use only Python stdlib unless the chapter is specifically about a third-party library",
      "All variable names, function names, and comments must be in English even in translated chapters",
      "Every function must have a docstring",
      "Include inline comments for non-obvious logic"
    ],
    "avoid": [
      "passive voice",
      "phrases like 'it is important to note'",
      "numbered lists for sets of 2 items (use prose instead)",
      "ending sections with 'In summary,...'"
    ]
  },
  "gumroad": {
    "price_cents": 999,
    "customizable_price": true,
    "tags": ["python", "ebook", "automation", "publishing"]
  }
}

How the Pipeline Uses outline.json

import json

def load_outline(path: str) -> dict:
    with open(path) as f:
        outline = json.load(f)
    # Validate required fields
    assert "title" in outline
    assert "chapters" in outline and len(outline["chapters"]) > 0
    for ch in outline["chapters"]:
        assert "slug" in ch and "word_target" in ch and "code_file" in ch
    return outline

outline = load_outline("outline.json")

for chapter_def in outline["chapters"]:
    chapter = Chapter.from_dict(chapter_def)
    if chapter.state == ChapterState.DONE:
        continue  # skip already-done chapters
    process_chapter(chapter, outline["style_guide"])

The style guide is injected into the generation prompt for every chapter. This is what makes the voice consistent across 10 chapters even though each is generated independently.

Forking for a New Book

To produce a new book:

Copy the schema above
Change title, subtitle, author
Write your 10 chapters — titles, slugs, learning_objective for each
Update style_guide.audience and code_conventions for your domain
Run python3 generate_chapters.py --outline outline.json

The pipeline handles everything else.

Full pipeline code: germy5.gumroad.com/l/xhxkzz — pay what you want, min $9.99.

22 Articles, 0 Sales: What Build-in-Public Really Looks Like

German Yamil — Tue, 28 Apr 2026 18:54:03 +0000

22 Articles, 0 Sales: What Build-in-Public Really Looks Like

I've published 22 articles about my automated Python ebook pipeline.

Total sales: 0.

I'm not going to dress this up. Here's the honest data, the math that explains it, and what I changed.

🎁 Free: AI Publishing Checklist — 7 steps in Python · Full pipeline: germy5.gumroad.com/l/xhxkzz (pay what you want, min $9.99)

The actual numbers (no spin)

Metric	Value
Articles published	22
Days live	17
Total views	~280
Views/day average	16.5
Reactions	3
Comments	2
Gumroad sales	0
Free downloads	0
Revenue	$0.00

Why 0 sales is mathematically expected

This took me a few days to understand clearly.

The funnel looks like this:

280 total article views
× 3–8% CTA click rate  =  8–22 estimated Gumroad visitors (total, 17 days)
× 1–2% conversion rate  =  0.08–0.44 expected sales

At my current traffic: zero sales is the most likely outcome. It's not a product problem or a price problem. It's a volume problem.

To generate one sale per week, I need approximately:

500–1,000 Gumroad visitors per week
Which requires ~7,000–14,000 article views per week
Which requires either 300+ views/article or many more articles

I have neither yet.

The mistakes I made

1. Publishing 10 articles in one day

On April 15th I published 10 articles in a single day. I thought volume would help.

It hurt. Dev.to's algorithm and Google both suppress bulk publishing — it signals automated spam. Those 10 articles average 11 views each. Articles published on other days average 35+ views.

Fix: One article per day maximum. I now have a cron job that publishes one article from a queue at 10am daily.

2. Wrong tags for 15 of the 17 original articles

I was tagging everything #automation and #tutorial. The data showed #career gets 3–5x more views per article on Dev.to.

I updated 6 zero-view articles to use #career and #productivity. Too early to see the full impact.

3. CTA was buried at the bottom

Every article linked to the paid product — but only at the very end. Most readers never reach the last paragraph.

Fix: Added a dual CTA (free + paid) within the first 400 words of every article.

4. Free product = 0 downloads

My free checklist has 0 downloads. That means my email list is empty. Every visitor who doesn't buy immediately is gone forever — no retargeting possible.

Fix: Moved the free product CTA before the paid CTA in all articles. Lower friction entry point.

5. No cover images

Articles without cover images are nearly invisible in the Dev.to feed — it's a thumbnail-first interface. I had 0 articles with cover images for the first 17 days.

Fix: Generated cover images with Pillow and uploaded them to the top 8 articles yesterday.

What I changed (automated, no manual work)

All of these ran via Python scripts against the Dev.to and Gumroad APIs:

✅ Tags updated on 6 zero-view articles → #career + #productivity
✅ Dual CTA (free + paid) inserted in all 22 articles
✅ Cover images generated (Pillow) and uploaded to top 8 articles
✅ Gumroad price changed from $12.99 fixed → $9.99+ pay-what-you-want
✅ Gumroad description rewritten with FAQ + 30-day guarantee
✅ Internal links added between top 5 articles
✅ Daily auto-publish cron installed (1 article/day from queue)
✅ Daily RSS ping cron running (9am)

What I haven't done yet that would actually move the needle

These require manual action or credentials I don't have set up:

Hacker News — one "Show HN" post can generate 500–2,000 views in 24 hours. Requires a manual post.
LinkedIn — zero presence. High purchase intent for this audience.
YouTube — zero presence. Highest trust-building channel for technical products.

The honest forecast

At the current pace without changes: first sale in 4–8 weeks as Google indexes the articles and organic search traffic starts.

With the fixes applied: possibly sooner, but traffic is still the bottleneck.

I'm not going to fake optimism. The pipeline works. The ebook is real. The market is real.

The distribution is the problem, and I'm still solving it.

Following this journey? Drop a comment with what you'd prioritize next. I'm genuinely taking suggestions.

The pipeline itself: germy5.gumroad.com/l/xhxkzz — pay what you want, min $9.99, 30-day refund.

From outline.json to Published EPUB: The Exact Command Sequence (Copy-Paste Ready)

German Yamil — Tue, 28 Apr 2026 14:25:25 +0000

From outline.json to Published EPUB: The Exact Command Sequence (Copy-Paste Ready)

Most pipeline documentation shows architecture diagrams. Here's what you actually type.

This is the exact command sequence — every command, every flag, expected output — to go from an empty directory to a published bilingual EPUB.

Copy, adapt, run.

The full pipeline with all scripts: germy5.gumroad.com/l/xhxkzz — $12.99, all 10 Python scripts included.

Prerequisites

# Install required tools
pip install anthropic requests
brew install pandoc        # macOS
# apt install pandoc       # Ubuntu/Debian

# Install epubcheck (Java required)
brew install epubcheck     # macOS
# or download from: https://github.com/w3c/epubcheck/releases

# Verify
python3 --version          # 3.10+
pandoc --version           # 3.x+
epubcheck --version        # 5.x+

Step 1: Create the chapter manifest

mkdir my_ebook && cd my_ebook
mkdir chapters assets

Create outline.json:

{
  "title": "Your Book Title",
  "author": "Your Name",
  "language_primary": "en",
  "language_secondary": "es",
  "chapters": [
    {
      "number": 1,
      "title": "Introduction and Architecture Overview",
      "slug": "chapter-01-intro",
      "word_target": 2200,
      "code_file": "script_01_intro.py",
      "learning_objective": "Reader will understand the pipeline architecture and be able to set up the project structure"
    }
  ]
}

Validate it parses correctly:

python3 -c "import json; data=json.load(open('outline.json')); print(f'✅ {len(data[\"chapters\"])} chapters loaded')"
# Expected: ✅ 10 chapters loaded

Step 2: Generate chapters

python3 generate_chapters.py \
  --outline outline.json \
  --output-dir chapters/ \
  --api-key $ANTHROPIC_API_KEY \
  --model claude-opus-4-5

# Expected output:
# [chapter-01] PENDING → RUNNING
# [chapter-01] Generating... (est. 45s)
# [chapter-01] Validating syntax...  ✅
# [chapter-01] Validating execution... ✅
# [chapter-01] RUNNING → DONE (2,247 words, 1 script)
# [chapter-02] PENDING → RUNNING
# ...
# [chapter-09] RUNNING → NEEDS_REVIEW (execution failed: ModuleNotFoundError)
# [chapter-10] PENDING → RUNNING
# ...
# Done. 9 DONE, 1 NEEDS_REVIEW.

If a chapter hits NEEDS_REVIEW:

# Check the error log
cat chapters/chapter-09/error.log
# Example: ModuleNotFoundError: No module named 'pandas'

# Re-run that specific chapter with adjusted prompt
python3 generate_chapters.py \
  --outline outline.json \
  --output-dir chapters/ \
  --api-key $ANTHROPIC_API_KEY \
  --chapter chapter-09 \
  --hint "Use only Python stdlib — no third-party imports"

# Expected:
# [chapter-09] NEEDS_REVIEW → PENDING (manual reset)
# [chapter-09] PENDING → RUNNING
# [chapter-09] Validating execution... ✅
# [chapter-09] RUNNING → DONE

Step 3: Validate all code (final check)

python3 validate_ast.py --chapters-dir chapters/

# Expected:
# Checking chapter-01/script_01_intro.py... ✅ syntax OK
# Checking chapter-02/script_02_state.py... ✅ syntax OK
# ...
# All 10 chapters: syntax valid.

python3 run_subprocess.py --chapters-dir chapters/ --timeout 30

# Expected:
# Running chapter-01/script_01_intro.py... exit code 0 ✅
# Running chapter-02/script_02_state.py... exit code 0 ✅
# ...
# All 10 scripts: clean execution.

If any script fails here (it shouldn't — the pipeline already validated during generation), go back to Step 2 for that chapter.

Step 4: Generate Spanish translation

python3 translate_qa.py \
  --chapters-dir chapters/ \
  --source-lang en \
  --target-lang es \
  --api-key $ANTHROPIC_API_KEY

# Expected:
# [chapter-01] Translating EN → ES...
# [chapter-01] Code fence check: EN=8 fences, ES=8 fences ✅
# [chapter-01] Word ratio: EN=2247, ES=2489 (ratio=1.11) ✅
# ...
# Translation complete. 10/10 chapters passed QA.

# If fence mismatch:
# [chapter-05] Code fence check: EN=12 fences, ES=10 fences ❌
# Chapter 05 ES saved to chapters/chapter-05/chapter-05-es-REVIEW.md

Fix translation issues manually in the -REVIEW.md file, then rename it to chapter-05-es.md.

Step 5: Assemble EPUBs

# Concatenate EN chapters
python3 assemble_epub.py \
  --chapters-dir chapters/ \
  --lang en \
  --output book_en.md

# Expected:
# Sorting chapters... found 10 files
# Concatenating... 22,847 words total
# Written to book_en.md ✅

# Generate EN EPUB
pandoc book_en.md \
  --output book_en.epub \
  --metadata-file metadata_en.yaml \
  --epub-cover-image assets/cover.png \
  --table-of-contents \
  --toc-depth=2 \
  --epub-chapter-level=1

# Expected: (no output = success)
# Verify:
ls -lh book_en.epub
# Expected: -rw-r--r-- 1 user group 847K book_en.epub

# Validate EPUB structure
epubcheck book_en.epub

# Expected:
# Validating using EPUB version 3.x rules.
# No errors or warnings detected.
# Messages: 0 fatals / 0 errors / 0 warnings / 0 infos

# Repeat for Spanish
pandoc book_es.md \
  --output book_es.epub \
  --metadata-file metadata_es.yaml \
  --epub-cover-image assets/cover.png \
  --table-of-contents \
  --toc-depth=2 \
  --epub-chapter-level=1

epubcheck book_es.epub

If epubcheck reports errors:

OPF-055: Missing metadata field → check metadata_en.yaml
PKG-007: Missing resource → cover image path issue
RSC-005: Malformed HTML → usually a code block not properly closed in Pandoc

Step 6: Create Gumroad listing

python3 gumroad_create.py \
  --token $GUMROAD_TOKEN \
  --title "Your Book Title" \
  --price 1299 \
  --description-file gumroad_description.md

# Expected:
# Creating product...
# ✅ Product created!
#    URL: https://yourusername.gumroad.com/l/your-slug
#    ID: xxxxxxxxxxxxxxxx
#    Price: $12.99

Upload the EPUB manually (Gumroad REST API doesn't support binary file upload):

Open the URL from the output
Edit Product → Files → Upload book_en.epub and book_es.epub
Save

Total time to this point: ~4–6 hours (including active monitoring and fixing NEEDS_REVIEW chapters).

Step 7: Submit to Amazon KDP (manual)

# Prepare KDP metadata (from the pipeline output)
cat kdp_metadata.json
# {
#   "title": "Your Book Title",
#   "subtitle": "...",
#   "description": "...",
#   "keywords": ["python", "automation", "ebook", ...],
#   "categories": ["Computers & Technology", "Programming"],
#   "price_usd": 9.99
# }

KDP doesn't have an API. Manual steps:

kdp.amazon.com → Add New Title → eBook
Fill from the JSON above
Upload book_en.epub
Upload cover (1600×2560px minimum)
Set price to $9.99 (70% royalty tier)
Submit for review (takes 24–72 hours)

The Full Sequence as a Shell Script

#!/bin/bash
set -e  # exit on any error

echo "=== AI Publishing Pipeline Run ==="
echo "Started: $(date)"

# Step 1: Validate manifest
python3 -c "import json; json.load(open('outline.json'))" && echo "✅ outline.json valid"

# Step 2: Generate
python3 generate_chapters.py --outline outline.json --output-dir chapters/ --api-key $ANTHROPIC_API_KEY

# Step 3: Final validation
python3 validate_ast.py --chapters-dir chapters/
python3 run_subprocess.py --chapters-dir chapters/ --timeout 30

# Step 4: Translate
python3 translate_qa.py --chapters-dir chapters/ --source-lang en --target-lang es --api-key $ANTHROPIC_API_KEY

# Step 5: Assemble
python3 assemble_epub.py --chapters-dir chapters/ --lang en --output book_en.md
python3 assemble_epub.py --chapters-dir chapters/ --lang es --output book_es.md

pandoc book_en.md -o book_en.epub --metadata-file metadata_en.yaml --epub-cover-image assets/cover.png --toc --toc-depth=2
pandoc book_es.md -o book_es.epub --metadata-file metadata_es.yaml --epub-cover-image assets/cover.png --toc --toc-depth=2

epubcheck book_en.epub && echo "✅ EN EPUB valid"
epubcheck book_es.epub && echo "✅ ES EPUB valid"

# Step 6: Publish
python3 gumroad_create.py --token $GUMROAD_TOKEN --title "Your Book Title" --price 1299 --description-file gumroad_description.md

echo ""
echo "=== Done ==="
echo "Completed: $(date)"
echo "Manual: upload EPUBs to Gumroad and submit to KDP"

Save as run_pipeline.sh, chmod +x run_pipeline.sh, and run it.

The full codebase (all 10 scripts): germy5.gumroad.com/l/xhxkzz ($12.99, 30-day refund).

How to Pick a Python Ebook Topic That People Actually Pay For (3-Step Validation)

German Yamil — Tue, 28 Apr 2026 13:52:56 +0000

How to Pick a Python Ebook Topic That People Actually Pay For (3-Step Validation)

The pipeline is the easy part.

I know — building an automated ebook generation system with state machines and validation gates sounds hard. But it's a solved problem once you know the architecture.

The hard part is picking a topic that has an audience willing to pay.

I've talked to developers who spent 4–6 hours running the pipeline, produced a technically flawless bilingual ebook, published it on Gumroad and KDP — and got zero sales.

Not because the pipeline failed. Because the topic had no buyers.

Here's the 3-step validation I run before spending a single hour generating content.

The pipeline that produces the ebook: germy5.gumroad.com/l/xhxkzz — but read this first before you run it.

The Core Question

Before anything else, answer this:

"Who is searching for this, and what are they searching for?"

Not "who would benefit from this" — that's a much larger group. Who is actively searching for a solution right now, using words you can target?

The difference:

"Developers who would benefit from learning FastAPI" → millions of people
"Developers searching 'fastapi production deployment checklist' → hundreds per month, high purchase intent

The second group is smaller. They're also far more likely to pay for a solution.

Filter 1: Search Volume Check (10 minutes)

Go to these tools (all free):

Google Keyword Planner — type your topic, look at monthly searches
Ahrefs Free Keyword Generator — more detailed, shows difficulty
Reddit — search for the topic, look at question threads

What you're looking for:

Searches between 500–5,000/month for a specific keyword.

Too low (under 500): not enough buyers.
Too high (over 20,000): you're competing with established publishers and free content.

The sweet spot: niche keywords with clear how-to intent.

Examples

Topic	Monthly searches	Purchase intent	Verdict
"python tutorial"	1M+	Low (free resources dominate)	❌ Too broad
"python ebook pipeline"	Low	High	✅ Niche enough
"fastapi deployment guide"	8K	Medium-High	🟡 Competitive
"python ast validation"	500	High (very specific)	✅ Good
"how to self publish python ebook"	Low-Medium	Very high (intent clear)	✅ Good

The filter: If you can't find at least one keyword with 200+ monthly searches AND clear how-to intent, move to a different topic.

Filter 2: Existing Product Audit (20 minutes)

Search for existing books on your topic:

Amazon KDP: Search the topic in the Kindle Store. Look at:
- How many results? (Over 100 = crowded, under 10 = might mean no demand)
- What are the ratings? (4.0+ with 50+ reviews = proven demand)
- What are the prices? ($9.99–$19.99 = healthy range)
- Are the top results recent? (Books from 2019 covering current topics = opportunity to update)
Gumroad: Search or browse by tag. Look at:
- Are there similar products?
- What's the price range?
- Do they have reviews/testimonials?

What you want to find:

Books that exist and have reviews. This confirms demand. You're not looking for a topic nobody has written about — you're looking for a topic where you can do it better, more specifically, or more recently.

Red flags:

No existing books → probably means no buyers, not that you found a gap
Existing books with hundreds of reviews → tough competition without strong differentiation
Books priced under $5 → low-value market, hard to make the math work

The filter: Find at least 2–3 existing products on the topic. If there are none, reconsider.

Filter 3: Community Demand Test (30 minutes)

Search Reddit, Dev.to, and Stack Overflow for your topic.

Specifically, look for:

Questions that come up repeatedly (same question, multiple threads)
"I wish there was a good resource on X" comments
Threads with high upvote counts on beginner-ish topics in otherwise advanced communities

Example Research for "Python automation for ebook publishing"

On Reddit (r/Python, r/selfpublishing, r/indiehackers):

"Is there a good Python resource for EPUB generation?" → multiple threads, moderate upvotes
"How do people validate code in technical ebooks?" → no direct thread, but related questions in r/learnpython

On Dev.to:

Existing articles on Python publishing get 50–200 views → shows interest
Comment section usually has 1–2 "I didn't know you could do this automatically"

On Stack Overflow:

Questions about epub3, pandoc, ast.parse validation → medium volume, clear how-to intent

The filter: Find at least 5 community threads where people are asking questions related to your topic. If you can't find any, that's a signal.

The Topic Matrix

After running all three filters, score your topic:

Filter	Score 0	Score 1	Score 2
Search volume	Under 200/month	200–2,000/month	2,000–20,000/month
Existing products	None	1–2 with reviews	3+ with reviews
Community threads	None found	1–4 threads	5+ threads

Total score:

0–2: Don't run the pipeline. Find a different topic.
3–4: Proceed with caution. Consider a lower price point.
5–6: Strong signal. Run the pipeline.

Topics Worth Considering in 2026

Based on this framework, topics with decent signals right now:

FastAPI production deployment (high search volume, gap in current resources)
Python CLI tools with Typer/Click (growing library, few dedicated ebooks)
LLM application architecture (high demand, very fast-moving — advantage if you're current)
Python data pipeline patterns (dbt, Prefect, Dagster — niche but active)
Automated testing strategies in Python (evergreen, always relevant)

The pipeline I built is designed for Python-code-forward topics. If your topic doesn't naturally have Python scripts as chapter deliverables, you'll need to adjust the validation gates.

Once you have a validated topic, the pipeline takes it from there.

Complete system: germy5.gumroad.com/l/xhxkzz ($12.99, 30-day refund).

Show Dev: I Built a Python Pipeline That Writes, Validates, and Publishes Bilingual Ebooks — Here's Everything

German Yamil — Tue, 28 Apr 2026 01:42:18 +0000

Show Dev: I Built a Python Pipeline That Writes, Validates, and Publishes Bilingual Ebooks

Six weeks ago I had an idea that felt slightly ridiculous.

What if I built an automated pipeline that generates a technical ebook — and then used that pipeline to produce the ebook that documents itself?

The ebook about the pipeline would be the proof that the pipeline works.

🎁 Free resource: AI Publishing Checklist — 7 steps to ship a technical ebook with Python (free, no email required) · Full pipeline: germy5.gumroad.com/l/xhxkzz (pay what you want, min $9.99)

What I built

A Python pipeline that:

Takes an outline.json (10 chapters, each with title, word target, code deliverable)
Generates each chapter using the Claude API
Validates every code snippet through two gates before advancing
Translates each chapter to Spanish with QA checks
Assembles two EPUBs (EN + ES) with Pandoc
Creates the Gumroad product listing via API

Total active time per book: 4–6 hours. The pipeline runs the rest unattended.

The core: two-gate code validation

Most technical ebooks have code that was never tested. I made that impossible.

Gate 1: AST parsing

import ast

def validate_syntax(code: str) -> bool:
    try:
        ast.parse(code)
        return True
    except SyntaxError as e:
        print(f"Syntax error at line {e.lineno}: {e.msg}")
        return False

Gate 2: Subprocess isolation

import subprocess, tempfile, os

def validate_execution(code: str, timeout: int = 30) -> bool:
    with tempfile.TemporaryDirectory() as tmpdir:
        path = os.path.join(tmpdir, "test.py")
        with open(path, "w") as f:
            f.write(code)
        result = subprocess.run(
            ["python3", path],
            capture_output=True, timeout=timeout, cwd=tmpdir
        )
        if result.returncode != 0:
            print(result.stderr.decode())
            return False
        return True

A chapter only reaches DONE state when both return True. There is no override.

The state machine

PENDING → RUNNING → DONE
                  ↘ NEEDS_REVIEW → (fix) → PENDING

Every state change writes to disk immediately. If the process crashes mid-generation, the next run resets RUNNING chapters to PENDING and skips DONE ones. I've had 3 crashes during production — no data loss, no re-doing finished chapters.

Translation QA

After English generation, the pipeline generates Spanish and checks:

Code fence count — EN and ES must have identical \\` fence pairs. Mismatch = dropped code block = hard failure
Word ratio — Spanish typically runs 10–15% longer than English. Deviation > 20% flags for review

python def validate_translation(en_content: str, es_content: str) -> bool: import re en_fences = len(re.findall(r'', en_content))
es_fences = len(re.findall(r'', es_content)) if en_fences != es_fences: raise ValueError(f"Fence mismatch: EN={en_fences}, ES={es_fences}") en_words = len(en_content.split()) es_words = len(es_content.split()) ratio = abs(en_words - es_words) / en_words if ratio > 0.20: print(f"Word ratio warning: {ratio:.2%} deviation") return True

The economics (stated plainly)

Item	Value
Infrastructure cost	$20/month (Claude Code Pro only)
Price	$9.99+ (pay what you want)
Break-even	2 sales
Time per book	4–6 hours active
Marginal cost, book #10	Same as book #1

What failed and what I learned

Failure 1: Published 10 articles on one day in April. Dev.to and Google suppressed the batch. Average 11 views/article for those vs. 54 views for the ones I published individually.

Lesson: Space content by at least 24 hours. One article per day maximum.

Failure 2: Translation sometimes produced code with Spanish variable names. Added explicit instruction to the prompt: "All variable names, function names, and comments must remain in English."

Failure 3: Some generated scripts used pandas or numpy which aren't in the clean subprocess environment. Fixed by adding to the prompt: "Use only Python stdlib. No third-party imports."

Failure 4 (ongoing): 0 sales so far after 16 days. 268 Dev.to views total. The math says I need ~3,000–5,000 views before expecting consistent sales. Working on volume.

The meta-proof

The ebook that documents this pipeline was produced by this pipeline.

Every one of its 10 chapters passed both validation gates before shipping. The Spanish edition was checked by the translation QA script. The EPUB was assembled and validated by epubcheck with zero errors.

I could claim this. Or I could build a system where it's the only possible outcome. I chose the second.

Free 7-step checklist: germy5.gumroad.com/l/vlvhld — free, no email

Full pipeline (10 scripts + complete ebook): germy5.gumroad.com/l/xhxkzz — pay what you want, min $9.99, 30-day refund

Questions? What part of the architecture would you build differently? Drop a comment — genuinely curious.

My Pipeline Crashed Mid-Generation 3 Times — Here's What I Learned About Crash Recovery

German Yamil — Tue, 28 Apr 2026 01:29:21 +0000

My Pipeline Crashed Mid-Generation 3 Times — Here's What I Learned About Crash Recovery

🎁 Free resource: AI Publishing Checklist — 7 steps to ship a technical ebook with Python (free, no email required) · Full pipeline + 10 scripts: germy5.gumroad.com/l/xhxkzz (pay what you want, min $9.99)

My laptop died mid-chapter on the third generation run.

Not a graceful shutdown. A hard power loss. The process was in RUNNING state on chapter 7 of 10 when the battery hit zero.

When I reopened the laptop: chapters 1–6 were in DONE state. Chapter 7 was in RUNNING. The pipeline resumed from chapter 7, treated the RUNNING state as an incomplete run, reset it to PENDING, and re-generated cleanly.

No manual intervention. No duplicate API calls for chapters 1–6. No data loss.

This is what a crash-safe state machine looks like in practice.

The full pipeline (including this state machine) is at germy5.gumroad.com/l/xhxkzz — $12.99, 30-day refund.

The Three Crashes

Crash 1: Hard Power Loss (Battery)

Chapter: 7 of 10
State at crash: RUNNING
Recovery: Chapter 7 reset to PENDING on next startup. Chapters 1–6 untouched (DONE). Re-generated chapter 7 from scratch.
API calls saved: 6 chapters × ~$0.05 each = $0.30

Small amount. But the principle matters — the system didn't re-do finished work.

Crash 2: API Rate Limit (429)

Chapter: 4 of 10
State at crash: RUNNING (generation was mid-stream when the 429 hit)
Initial behavior (before fix): The chapter was half-generated when the exception propagated. The state stayed RUNNING.

This exposed a bug: I wasn't resetting RUNNING to PENDING on startup. On restart, the pipeline skipped chapter 4 entirely (saw it as RUNNING = in progress) and moved to chapter 5.

Fix:

def on_startup(chapters):
    """
    Any chapter in RUNNING state on startup was interrupted.
    Reset it to PENDING so it gets re-generated.
    """
    for chapter in chapters:
        if chapter.state == ChapterState.RUNNING:
            print(f"[startup] Resetting chapter {chapter.id} from RUNNING → PENDING")
            chapter.state = ChapterState.PENDING
            save_state(chapter)

This became the canonical startup hook. Every run now calls on_startup() before processing begins.

Crash 3: Keyboard Interrupt (Ctrl+C)

Chapter: 2 of 10
State at crash: RUNNING
Recovery: Same as crash 1 after the startup fix. Chapter 2 reset to PENDING. Clean re-generation.

The keyboard interrupt (SIGINT) propagates through Python as a KeyboardInterrupt exception. I added a handler:

import signal, sys

def signal_handler(sig, frame):
    print("\n[interrupt] Caught SIGINT. State saved. Run again to resume.")
    sys.exit(0)

signal.signal(signal.SIGINT, signal_handler)

The sys.exit(0) triggers finally blocks and ensures the state file is written before the process exits.

The State Machine That Makes This Work

Four states. Strict transition rules. Disk write on every transition.

from enum import Enum
import json, os

class ChapterState(Enum):
    PENDING = "pending"
    RUNNING = "running"
    DONE = "done"
    NEEDS_REVIEW = "needs_review"

# Legal transitions
TRANSITIONS = {
    ChapterState.PENDING:       [ChapterState.RUNNING],
    ChapterState.RUNNING:       [ChapterState.DONE, ChapterState.NEEDS_REVIEW],
    ChapterState.DONE:          [],  # terminal
    ChapterState.NEEDS_REVIEW:  [ChapterState.PENDING],  # after human fix
}

STATE_FILE = "pipeline_state.json"

def transition(chapter, new_state: ChapterState):
    if new_state not in TRANSITIONS[chapter.state]:
        raise ValueError(
            f"Invalid transition: {chapter.state} → {new_state} "
            f"for chapter {chapter.id}"
        )
    chapter.state = new_state
    _persist(chapter)  # disk write happens here, before the next line

def _persist(chapter):
    """Write state to disk immediately. If this fails, we want to know."""
    state_data = load_all_state()
    state_data[chapter.id] = chapter.state.value
    with open(STATE_FILE, "w") as f:
        json.dump(state_data, f, indent=2)

def load_all_state() -> dict:
    if not os.path.exists(STATE_FILE):
        return {}
    with open(STATE_FILE) as f:
        return json.load(f)

Why _persist() before continuing:

If you write state after the operation completes, a crash between "operation done" and "state written" leaves you with work that happened but isn't recorded. On restart, you repeat the work.

If you write state before the operation, a crash between "state written" and "operation done" leaves you with a chapter in RUNNING state that will reset to PENDING on startup — and re-run cleanly.

The failure mode of "write before" is always recoverable. The failure mode of "write after" is sometimes not.

The Complete Chapter Processing Loop

def process_all_chapters(chapters):
    on_startup(chapters)  # reset any RUNNING → PENDING

    for chapter in chapters:
        if chapter.state == ChapterState.DONE:
            print(f"[skip] Chapter {chapter.id}: already DONE")
            continue

        if chapter.state == ChapterState.NEEDS_REVIEW:
            print(f"[block] Chapter {chapter.id}: NEEDS_REVIEW — fix and re-run")
            continue

        # Process PENDING chapters
        transition(chapter, ChapterState.RUNNING)

        try:
            content = generate_chapter(chapter)  # LLM API call
            code = extract_code(content)

            if not validate_syntax(code):
                transition(chapter, ChapterState.NEEDS_REVIEW)
                continue

            if not validate_execution(code):
                transition(chapter, ChapterState.NEEDS_REVIEW)
                continue

            chapter.content = content
            transition(chapter, ChapterState.DONE)

        except RateLimitError:
            # Rate limit: put back to PENDING, wait, retry next run
            transition(chapter, ChapterState.PENDING)
            print(f"Rate limit hit on chapter {chapter.id}. Re-run to continue.")
            break

        except Exception as e:
            transition(chapter, ChapterState.NEEDS_REVIEW)
            print(f"Unexpected error on chapter {chapter.id}: {e}")

What I'd Do Differently

1. Finer-grained state per operation.

The current system treats chapter generation as atomic. If generation succeeds but validation fails, the chapter goes to NEEDS_REVIEW. A future improvement: track which validation gate failed (FAILED_SYNTAX vs FAILED_EXECUTION) so the error message is more specific.

2. Distributed state lock for parallel runs.

If you ever run two pipeline instances simultaneously (for parallel chapter generation), you need a lock on the state file. SQLite is better than JSON for this case — it handles concurrent writes safely.

3. Automatic retry with backoff for rate limits.

Currently, a rate limit sends the chapter back to PENDING and halts. A better behavior: catch the Retry-After header, sleep, and retry the same chapter in the same run.

The complete pipeline with all recovery logic: germy5.gumroad.com/l/xhxkzz ($12.99, 30-day refund).

Why I Run Every Code Snippet Through Two Validation Gates Before Publishing

German Yamil — Tue, 28 Apr 2026 01:21:53 +0000

Why I Run Every Code Snippet Through Two Validation Gates Before Publishing

🎁 Free resource: AI Publishing Checklist — 7 steps to ship a technical ebook with Python (free, no email required) · Full pipeline + 10 scripts: germy5.gumroad.com/l/xhxkzz (pay what you want, min $9.99)

There's a hidden contract in every technical ebook:

"The code in this book was tested before you paid for it."

Most authors violate it without meaning to. They write the code from memory, paste it without running it, and ship. You buy it. By chapter 6, the imports from chapter 2 don't resolve.

I built a system to make that impossible.

The full validation system is part of the AI Publishing Pipeline at germy5.gumroad.com/l/xhxkzz — $12.99, includes all validation scripts.

The Problem With "I Tested This Locally"

"Locally" means:

Your specific Python version (3.11? 3.12? 3.13?)
Your specific installed packages
Your specific environment variables
Your specific file system layout

When a reader runs your code in their environment, those assumptions break. The script fails with ModuleNotFoundError or FileNotFoundError and the reader assumes they did something wrong.

They didn't. You did — by shipping code that was tested only in one environment.

Gate 1: AST Parsing

The first gate catches syntax errors before any execution happens.

import ast

def validate_syntax(code: str, chapter_id: str) -> bool:
    """
    Gate 1: Catch syntax errors at parse time.
    Fast, safe, no execution side effects.
    """
    try:
        tree = ast.parse(code)
        return True
    except SyntaxError as e:
        print(f"[{chapter_id}] Syntax error at line {e.lineno}: {e.msg}")
        print(f"  Offending text: {e.text}")
        return False

What this catches:

Missing closing parentheses
Incorrect indentation
Invalid f-string syntax
Python 2 syntax in a Python 3 script
Unclosed brackets, strings, or block structures

What this doesn't catch:

Wrong imports (import nonexistent_module passes AST)
Runtime errors (division by zero, missing files)
Logic errors (script runs but does the wrong thing)

AST parsing is the fast filter. Cheap to run, catches the obvious failures before you pay for an execution.

Gate 2: Subprocess Isolation

The second gate actually runs the script.

import subprocess
import tempfile
import os

def validate_execution(code: str, chapter_id: str, timeout: int = 30) -> bool:
    """
    Gate 2: Execute the script in a clean, isolated environment.
    Catches import errors, runtime exceptions, and infinite loops.
    """
    with tempfile.TemporaryDirectory() as tmpdir:
        script_path = os.path.join(tmpdir, "test_script.py")

        with open(script_path, "w", encoding="utf-8") as f:
            f.write(code)

        try:
            result = subprocess.run(
                ["python3", script_path],
                capture_output=True,
                timeout=timeout,
                cwd=tmpdir,          # clean working directory
                text=True
            )

            if result.returncode != 0:
                print(f"[{chapter_id}] Non-zero exit code: {result.returncode}")
                print(f"  stderr: {result.stderr[:500]}")
                return False

            return True

        except subprocess.TimeoutExpired:
            print(f"[{chapter_id}] Script exceeded {timeout}s timeout — possible infinite loop")
            return False

What this catches:

ModuleNotFoundError — import that doesn't exist
FileNotFoundError — path that doesn't exist in the clean environment
AttributeError, TypeError, ValueError — runtime exceptions
Infinite loops (via timeout)
Non-zero exit codes from sys.exit(1) or unhandled exceptions

Key design decisions:

tempfile.TemporaryDirectory() — each script runs in a fresh directory with no leftover files from previous scripts
cwd=tmpdir — the working directory is the temp dir, so relative paths fail loudly
timeout=30 — catches infinite loops without hanging the pipeline
capture_output=True — stderr is captured and logged, not lost

The State Machine Integration

These two gates integrate into the chapter state machine:

from enum import Enum

class ChapterState(Enum):
    PENDING = "pending"
    RUNNING = "running"
    DONE = "done"
    NEEDS_REVIEW = "needs_review"

def validate_chapter(chapter):
    """Run both gates. Chapter only reaches DONE if both pass."""
    chapter.state = ChapterState.RUNNING
    save_state(chapter)

    code = extract_code_block(chapter.content)

    # Gate 1
    if not validate_syntax(code, chapter.id):
        chapter.state = ChapterState.NEEDS_REVIEW
        save_state(chapter)
        return False

    # Gate 2
    if not validate_execution(code, chapter.id):
        chapter.state = ChapterState.NEEDS_REVIEW
        save_state(chapter)
        return False

    # Both gates passed
    chapter.state = ChapterState.DONE
    save_state(chapter)
    return True

A chapter can only be in DONE state if both gates returned True. There is no override path. There is no "I'll fix it in the next edition."

Failure Rates in Practice

In my pipeline runs, roughly 2–3 chapters out of 10 fail on first pass.

Common failure modes by frequency:

Failure	Gate	Frequency	Fix
Missing import (`import nonexistent`)	Gate 2	~40% of failures	Adjust prompt to use stdlib only
Script expects input file	Gate 2	~25%	Prompt to create sample data inline
Infinite loop in demo code	Gate 2 (timeout)	~15%	Add exit condition to prompt
Syntax error in generated code	Gate 1	~10%	Re-generate chapter
Non-zero exit for illustrative error	Gate 2	~10%	Wrap in try/except in prompt

The pipeline doesn't eliminate failures. It catches them before you ship.

What This Doesn't Catch

Be honest about limitations:

Silent semantic failures. A script that exits with code 0 but prints the wrong output passes both gates. If the chapter is demonstrating bubble sort and the generated code implements insertion sort — both gates pass, but the content is wrong.

Environment-specific modules. If the script imports boto3 or tensorflow and the reader doesn't have those installed, Gate 2 passes on my machine but fails on theirs.

Dependency on external services. A script that makes a real API call will fail if the API is down or the key is invalid.

For these cases, the pipeline flags chapters for manual review and includes instructions in the prompt to keep scripts self-contained with stdlib only.

The Result: A Guarantee You Can Actually Make

After running both gates, you can honestly say:

"Every code snippet in this ebook ran — in a clean subprocess — and returned exit code 0. That's not a claim. It's the precondition for publishing."

That's a guarantee worth making.

The complete validation system (both scripts + state machine integration) is included in the pipeline at germy5.gumroad.com/l/xhxkzz — $12.99, 30-day refund.

The Break-even Math That Makes Technical Ebook Publishing Worth It (Worked Example)

German Yamil — Tue, 28 Apr 2026 01:21:49 +0000

The Break-even Math That Makes Technical Ebook Publishing Worth It (Worked Example)

🎁 Free resource: AI Publishing Checklist — 7 steps to ship a technical ebook with Python (free, no email required) · Full pipeline + 10 scripts: germy5.gumroad.com/l/xhxkzz (pay what you want, min $9.99)

Before I built anything, I ran the numbers.

Not because I was optimistic. Because I needed to know how many copies I'd need to sell before I stopped losing money.

The answer was 2.

The pipeline behind this math: The automated system described here is available at germy5.gumroad.com/l/xhxkzz ($12.99 launch price, 30-day refund).

The Only Paid Tool

Most publishing advice hides the real costs. Here's mine:

Claude Code Pro: $20/month.

That's it. That's the entire infrastructure cost.

Everything else — Gumroad, Amazon KDP, Pandoc, Canva, NotebookLM, GitHub, epubcheck — is free.

The Break-even Formula

monthly_cost = 20.00       # Claude Code Pro
price_per_copy = 12.99     # launch price
gumroad_fee_pct = 0.10     # 10% platform fee
net_per_sale = price_per_copy * (1 - gumroad_fee_pct)  # $11.69

break_even_sales = monthly_cost / net_per_sale  # 1.71
break_even_sales = 2  # ceiling — 2 sales covers the month

2 sales per month = break even.

If you make 2 sales, you've paid for your infrastructure. Every sale after that is profit.

Why This Math Is Different

Most creator businesses have marginal costs that scale with output:

Freelancers: more clients = more hours
Course creators: more students = more support load
Consultants: more projects = more time

A technical ebook pipeline doesn't work that way.

Marginal cost of sale #100: $0 (same as sale #1).
Marginal cost of book #10: ~$3–5 in API tokens + 4–6 hours of your time.
Infrastructure cost at 20 books: still $20/month.

This is the structure that makes the catalog model interesting.

The Catalog Math (Real Numbers)

One book, conservative scenario

Scenario	Sales/month	Net/month
Break-even	2	$3.38
Modest	5	$38.45
Good	10	$96.90
Strong	20	$213.80

Net = (sales × $11.69) − $20

Five books, same conservative assumption (5 sales each)

25 sales × $11.69 = $292.25 gross
Minus $20 = $272.25 net

The $20 infrastructure cost covers all 5 books. Not $20 × 5.

Twenty books at 5 sales/month each

100 sales × $11.69 = $1,169 gross  
Minus $20 = $1,149 net

$1,149/month on a $20/month cost base.

This isn't passive income mythology. It's the arithmetic of a catalog with flat infrastructure costs.

The Time Cost (Don't Ignore It)

The math above leaves out your time. Let's add it back.

Per book:

4–6 hours of active work (setup, monitoring, review, publishing)
Spread over one working day

At $50/hour opportunity cost:

5 hours × $50 = $250 implicit cost per book

To recover $250 at $11.69/sale: 22 sales per book to cover time.

At 5 sales/month, that's 4.4 months to recover the time investment on one book.

This is why the catalog model requires patience. The economics improve dramatically as you add books (infrastructure stays flat) but each book needs time to accumulate sales.

The honest frame: this is a long-term catalog play, not a quick-flip product. If you need $1,000 next month, this isn't the path. If you're building a catalog that compounds over 12–24 months, the math is compelling.

The Pipeline That Makes This Feasible

The reason 4–6 hours per book is achievable (vs. 40–80 hours for manual writing) is code validation automation.

Instead of:

Writing a chapter (2 hours)
Adding code examples (1 hour)
Testing them manually (30 min)
Fixing them (30 min)
Translating to Spanish (2 hours)
Checking translation (1 hour)

The pipeline does:

Generate chapter + code (automated, 5 min)
ast.parse() → syntax check (automated, instant)
subprocess.run() → live execution check (automated, 30 seconds)
Generate Spanish translation (automated, 5 min)
Code fence count diff (automated, instant)
On failure → NEEDS_REVIEW state → you fix and re-run

Your active work is reviewing failures and publishing. The generation and validation are unattended.

Is This Worth It For You?

Yes, if:

You have a Python-based topic with an existing audience
You can commit 4–6 hours per book topic
You're thinking in catalog terms (5+ books over 12 months)
You want reusable infrastructure, not a one-time product

No, if:

You need fast income (catalog math takes months to compound)
You don't have a specific technical topic with search demand
You want someone else to handle the technical setup

The pipeline removes the production friction. It doesn't remove the need for a topic people want to pay for.

The complete pipeline — including the validation system, translation QA, EPUB assembly, and Gumroad integration — is at germy5.gumroad.com/l/xhxkzz ($12.99, 30-day refund, all 10 scripts included).

I Automated My Way to a Technical Ebook in 4 Hours — Here's the Exact Cost Breakdown

German Yamil — Mon, 27 Apr 2026 14:03:02 +0000

I Automated My Way to a Technical Ebook in 4 Hours — Here's the Exact Cost Breakdown

🎁 Free resource: AI Publishing Checklist — 7 steps to ship a technical ebook with Python (free, no email required) · Full pipeline + 10 scripts: germy5.gumroad.com/l/xhxkzz (pay what you want, min $9.99)

Most "passive income" breakdowns hide the real costs.

So here's mine — completely transparent: every dollar, every hour, every tool.

The pipeline behind this: Everything described here runs on a system available at germy5.gumroad.com/l/xhxkzz ($12.99 launch price, includes all 10 Python scripts and the complete automation stack).

The Stack (with real prices)

Tool	Purpose	Cost
Claude Code Pro	LLM API + pipeline orchestration	$20/month
Gumroad	Sales + delivery	Free (10% per sale)
Amazon KDP	EPUB distribution	Free (30–70% royalty)
Canva	Cover design	Free
Google NotebookLM	Research + outline	Free
Pandoc	EPUB assembly	Free
GitHub	Version control	Free
epubcheck	EPUB validation	Free

Total monthly infrastructure: $20.

Claude Code Pro is the only paid tool. Everything else is free.

The Time Breakdown (per book)

Here's where one working day goes:

Hour 1: Setup (~60 min active)

Write outline.json — 10 chapters, each with title, slug, target word count, and Python script deliverable
Configure the pipeline: API key, output directory, model parameters
Validate the manifest and run a test chapter to check the pipeline is working

Hours 2–3: Generation + Fixing (~90 min active, rest automated)

The pipeline runs mostly unattended. You monitor for NEEDS_REVIEW states.

In my experience: 2–3 chapters out of 10 fail on first pass. Common reasons:

Import that doesn't exist in the clean execution environment
Script that times out (infinite loop in generated code)
Code fence count mismatch in translation

Each fix cycle: read the error log, adjust the prompt for that chapter, re-run. Usually 10–15 minutes per failure.

Hour 4: Translation QA (~45 min active)

Spanish generation runs automatically. I spot-check 2–3 chapters for:

Variable names that slipped into Spanish
Technical terms that were over-translated
Code fence count alignment between EN and ES versions

Hours 5–6: Assembly + Publishing (~90 min active)

pandoc combined_en.md -o book_en.epub --metadata-file=metadata.yaml --epub-cover-image=cover.png --toc
epubcheck book_en.epub

Same for Spanish. Then:

Gumroad: API creates listing, manual upload for EPUB files
KDP: Upload, metadata, pricing, submit for review (KDP takes 24–72 hours)

Total active time: 4–6 hours. The pipeline runs the rest.

The Economics

Break-even

Monthly cost: $20 (Claude Code Pro)
Price per copy: $12.99
Break-even: ceil($20 / $12.99) = 2 sales

After 2 sales: every copy is pure margin.

Per-book scenario

Sales/month	Gross	Infrastructure	Net
2	$25.98	$20	$5.98
5	$64.95	$20	$44.95
10	$129.90	$20	$109.90
20	$259.80	$20	$239.80

Note: Gumroad takes 10% ($1.30/sale), so actual per-sale net is ~$11.69.

The catalog math

The infrastructure cost is flat — it doesn't increase per book.

Book #1: $20/month infrastructure.
Book #5: still $20/month infrastructure.
Book #20: still $20/month infrastructure.

At 5 books averaging 5 sales each:

25 sales × $11.69 = $292.25/month
Minus $20 = $272.25 net
Infrastructure stays at $20

At 20 books averaging 5 sales each:

100 sales × $11.69 = $1,169/month
Minus $20 = $1,149 net

This is why I'm building a catalog, not a single book.

What "4-6 hours" actually means

It doesn't mean sitting at your computer for 4–6 hours straight.

It means:

~2 hours of focused setup and monitoring at the start
~1 hour of review and fixing NEEDS_REVIEW chapters (spread throughout the day)
~1.5 hours of final assembly and uploading at the end

The pipeline runs for 3–5 hours in the background while you do other work.

What's not automated (yet)

Manual steps remaining:

Uploading the EPUB file to Gumroad (REST API doesn't support binary upload)
KDP cover upload (requires the KDP dashboard)
Google Console redirect URI for YouTube (if you want YouTube OAuth)

Everything else runs from the command line.

The honest risk

Will you make sales?

Depends entirely on topic selection and distribution.

The pipeline guarantees:

✅ Code that actually runs (AST + subprocess validation)
✅ Bilingual output (EN + ES) in one run
✅ EPUB assembly and validation
✅ Gumroad listing creation

The pipeline does not guarantee:

❌ Traffic to your Gumroad page
❌ A topic with an existing audience
❌ Sales

Those are editorial and marketing decisions. The technology is a solved problem.

Is it worth it?

For me: yes.

The alternative is writing manually, spending 40–80 hours on a book, and having no code validation guarantee. My pipeline produces a validated bilingual ebook in 4–6 hours. The marginal cost of books 2–20 is API calls + my time reviewing failures.

If you already know Python and want a reusable system to produce technical ebooks — the pipeline is at germy5.gumroad.com/l/xhxkzz ($12.99 launch price).

If you want to understand the architecture first, the complete technical breakdown is on Dev.to.

DEV Community: German Yamil

Python subprocess.run() Deep Dive: Isolation, Timeouts, and Captured Output

Python subprocess.run() Deep Dive: Isolation, Timeouts, and Captured Output

The signature

Pattern 1: Capture stdout and stderr separately

Pattern 2: Timeout enforcement

Pattern 3: Directory isolation with cwd

Pattern 4: Environment variable injection

Pattern 5: check=True for fail-fast pipelines

Pattern 6: stdin piping

Full validation harness

CompletedProcess reference

Further Reading

I'm Using Python to Automate My Own Marketing — Here's Every Script

I'm Using Python to Automate My Own Marketing — Here's Every Script

The stack: 4 APIs, 2 crons, 0 dashboards

Script 1: Auto-publish queue

Script 2: Bulk tag update

Script 3: Bulk CTA injection

Script 4: Cover image generation

Script 5: Imgur upload + Dev.to attachment

Script 6: RSS ping (daily cron, 9am)

Stats script

What this replaces

Further Reading

The Exact Prompts I Use to Generate Technical Ebook Chapters with Claude

The Exact Prompts I Use to Generate Technical Ebook Chapters with Claude

System Prompt

User Message Template

Building the prompt in code

The Four Constraints That Make It Work

1. stdlib only — the single biggest improvement

2. English variable names — critical for bilingual output

3. Every function must have a docstring

4. End on a runnable script

Translation Prompt

Prompt Iteration Log

Further Reading

The outline.json Format That Drives My Automated Python Ebook Pipeline

The outline.json Format That Drives My Automated Python Ebook Pipeline

The Schema

Field Reference

Top-level fields

Chapter fields

style_guide fields

Real Working Example

How the Pipeline Uses outline.json

Forking for a New Book

Further Reading

22 Articles, 0 Sales: What Build-in-Public Really Looks Like

22 Articles, 0 Sales: What Build-in-Public Really Looks Like

The actual numbers (no spin)

Why 0 sales is mathematically expected

The mistakes I made

1. Publishing 10 articles in one day

2. Wrong tags for 15 of the 17 original articles

3. CTA was buried at the bottom

4. Free product = 0 downloads

5. No cover images

What I changed (automated, no manual work)

What I haven't done yet that would actually move the needle

The honest forecast

From outline.json to Published EPUB: The Exact Command Sequence (Copy-Paste Ready)

From outline.json to Published EPUB: The Exact Command Sequence (Copy-Paste Ready)

Prerequisites

Step 1: Create the chapter manifest

Step 2: Generate chapters

Step 3: Validate all code (final check)

Step 4: Generate Spanish translation

Step 5: Assemble EPUBs

Step 6: Create Gumroad listing

Step 7: Submit to Amazon KDP (manual)

The Full Sequence as a Shell Script

Further Reading

How to Pick a Python Ebook Topic That People Actually Pay For (3-Step Validation)

How to Pick a Python Ebook Topic That People Actually Pay For (3-Step Validation)

The Core Question

Filter 1: Search Volume Check (10 minutes)

Examples

Filter 2: Existing Product Audit (20 minutes)

1. `stdlib only` — the single biggest improvement

2. `English variable names` — critical for bilingual output

3. `Every function must have a docstring`

4. `End on a runnable script`