talk-python-cli 0.1.2__tar.gz → 0.2.0__tar.gz

{talk_python_cli-0.1.2 → talk_python_cli-0.2.0}/.claude/settings.local.json

@@ -5,7 +5,10 @@
       "Bash(./venv/bin/python -m talk_python_cli.app status:*)",
       "Bash(./venv/bin/talkpython status:*)",
       "Bash(./venv/bin/pip install:*)",
-      "Bash(./venv/bin/talkpython:*)"
+      "Bash(./venv/bin/talkpython:*)",
+      "Bash(gh issue view:*)",
+      "Bash(pyrefly check:*)",
+      "Bash(uv lock:*)"
     ]
   }
 }

talk_python_cli-0.2.0/CLAUDE.md

@@ -0,0 +1,150 @@
+# CLAUDE.md — Agent Instructions for talk-python-cli
+
+## Project Overview
+
+CLI client for the Talk Python to Me podcast and Talk Python Training courses.
+Wraps a remote MCP server (`https://talkpython.fm/api/mcp`) using JSON-RPC 2.0
+over HTTP. The CLI is a **thin client** — all business logic lives on the server.
+The CLI handles argument parsing, HTTP transport, and output formatting.
+
+Published on PyPI as `talk-python-cli`. Entry point: `talkpython`.
+
+## Critical Rules
+
+- **Use `uv pip install`, never `pip install`.**
+- **Virtual environment is `./venv`, NOT `./.venv`.**
+- **After every code edit, run: `ruff format && ruff check --fix`**
+- **Use `pyrefly check` to validate type information after changes.**
+- Do not add unnecessary abstractions, comments, or docstrings to unchanged code.
+- **Update `change-log.md` after every major change** (new features, breaking changes, notable fixes). Follow the [Keep a Changelog](https://keepachangelog.com/) format already in use.
+
+## Build & Run
+
+```bash
+# Activate venv
+source venv/bin/activate
+
+# Install in editable mode
+uv pip install -e ".[dev]"
+
+# Run CLI
+talkpython --help
+talkpython episodes search "fastapi"
+talkpython status
+
+# Run tests
+pytest
+
+# Lint & format (ALWAYS after edits)
+ruff format && ruff check --fix
+
+# Type check (ALWAYS after edits)
+pyrefly check
+```
+
+## Project Structure
+
+```
+src/talk_python_cli/
+  __init__.py       # Version from importlib.metadata
+  __main__.py       # python -m entry point
+  app.py            # Root Cyclopts app, global options, meta-handler, status cmd
+  client.py         # MCPClient: httpx-based JSON-RPC 2.0 client
+  formatting.py     # Rich output: Markdown panels (text) or JSON
+  episodes.py       # Episode commands (search, get, list, recent, transcript)
+  guests.py         # Guest commands (search, get, list)
+  courses.py        # Course commands (search, get, list)
+
+tests/
+  conftest.py       # Shared fixtures, JSON-RPC response builders
+  test_client.py    # MCPClient tests
+  test_episodes.py  # Episode command tests
+  test_guests.py    # Guest command tests
+  test_courses.py   # Course command tests
+```
+
+## Architecture & Key Patterns
+
+### CLI Framework: Cyclopts (not Click, not Typer)
+
+- Root app in `app.py` with sub-apps for episodes, guests, courses.
+- **Meta-app launcher** (`@app.meta.default`): intercepts all invocations to
+  process global options (`--format`, `--url`) before dispatching to subcommands.
+- Parameters use `Annotated[type, cyclopts.Parameter(...)]` for docs/defaults.
+- Cyclopts auto-converts snake_case commands to kebab-case (e.g. `transcript_vtt` → `transcript-vtt`).
+
+### Client Pattern
+
+- `MCPClient` in `client.py` wraps httpx for JSON-RPC 2.0 over HTTP.
+- Lazy initialization: `_ensure_initialized()` runs MCP handshake on first call.
+- Session ID tracked via `Mcp-Session-Id` response header.
+- `call_tool(tool_name, arguments)` is the only public API for MCP tool calls.
+- Output format sent as URL query param: `?format=json` when JSON mode.
+- No authentication required (public API).
+
+### Lazy Client Access (avoids circular imports)
+
+Each command module retrieves the client via a local helper:
+```python
+def _client():
+    from talk_python_cli.app import get_client
+    return get_client()
+```
+This deferred import avoids circular dependency since `app.py` imports the command modules.
+
+### Output Formatting
+
+- `display(content, format)` in `formatting.py` routes to markdown or JSON renderer.
+- Text mode: Rich Markdown panel with "Talk Python" theme (cyan border, monokai code).
+- JSON mode on TTY: pretty-printed with syntax highlighting.
+- JSON mode piped: compact single-line JSON for scripting.
+
+### Adding a New Command
+
+1. Add function in the appropriate module (`episodes.py`, `guests.py`, `courses.py`).
+2. Decorate with `@sub_app.default` or just define as a regular function in the sub-app.
+3. Call `_client().call_tool('tool_name', {'arg': value})` to invoke the MCP tool.
+4. Pass result to `display(result, _client().output_format)`.
+5. Add tests in the corresponding test file using `pytest-httpx` mocks.
+
+### Adding a New Command Group
+
+1. Create `src/talk_python_cli/newgroup.py` with a `cyclopts.App(name='newgroup')`.
+2. Register in `app.py`: `app.command(newgroup.sub_app)`.
+3. Create `tests/test_newgroup.py`.
+
+## Testing
+
+- Framework: **pytest** with **pytest-httpx** for HTTP mocking.
+- `conftest.py` provides helpers: `jsonrpc_result()`, `tool_result()`, `add_init_responses()`.
+- Every test must call `add_init_responses(httpx_mock)` before making MCP client calls.
+- Tests verify JSON-RPC request structure, argument passing, and response handling.
+
+## Dependencies
+
+| Package      | Purpose                        |
+|-------------|--------------------------------|
+| cyclopts    | CLI framework (commands, args) |
+| httpx       | HTTP client for MCP calls      |
+| rich        | Terminal output formatting      |
+| pytest      | Testing (dev)                  |
+| pytest-httpx| HTTP mocking in tests (dev)    |
+
+Build system: **hatchling**. Package manager: **uv**.
+
+## Config Files
+
+- `pyproject.toml` — Package metadata, dependencies, entry points, build config
+- `ruff.toml` — Line length 120, single quotes, target Python 3.14
+- `pyrefly.toml` — Type checker config, search path includes `src/`
+- `uv.lock` — Locked dependencies (committed)
+
+## Style Conventions
+
+- Line length: 120
+- Quotes: single quotes
+- Modern Python type syntax: `dict | None` not `Optional[dict]`
+- `from __future__ import annotations` in all modules
+- Private helpers prefixed with `_`
+- Minimal docstrings: only on public functions/classes
+- Python target: 3.12+ (currently targeting 3.14 in tooling)

{talk_python_cli-0.1.2 → talk_python_cli-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: talk-python-cli
-Version: 0.1.2
+Version: 0.2.0
 Summary: CLI for the Talk Python to Me podcast and courses
 Project-URL: Homepage, https://github.com/talkpython/talk-python-cli
 Project-URL: Source, https://github.com/talkpython/talk-python-cli
@@ -44,12 +44,12 @@ Unlock 500+ episodes of [Talk Python to Me](https://talkpython.fm), full transcr
 Requires Python 3.12+.
 
 ```bash
-# Try it instantly with uvx (no install needed)
-uvx --from talk-python-cli talkpython episodes recent
-
-# Or install it permanently with uv
+# Install it permanently with uv
 uv tool install talk-python-cli
 
+# Or try it instantly with uvx (no install needed)
+uvx --from talk-python-cli talkpython episodes recent
+
 # Or with pip
 pip install talk-python-cli
 ```
@@ -58,6 +58,8 @@ This installs the `talkpython` command.
 
 ## Quick start
 
+Copy this whole block and paste it into your terminal to see what you get.
+
 ```bash
 # Search for episodes about FastAPI
 talkpython episodes search "FastAPI"
@@ -109,41 +111,55 @@ talkpython courses list
 
 ## Output formats
 
-The CLI auto-detects the best output format:
+The CLI supports three output formats via `--format`:
 
-- **Interactive terminal** — Rich-formatted Markdown with styled panels and color.
-- **Piped / redirected** — Compact JSON, ready for processing.
-
-Override the default with `--format`:
+- **`text`** (default) — Rich-formatted Markdown with styled panels and color for human reading.
+- **`json`** — Structured JSON, pretty-printed on a TTY or compact when piped.
+- **`markdown`** — Raw Markdown output with no Rich formatting. Ideal for piping into AI agents, LLMs, and automation tools that consume Markdown natively.
 
 ```bash
 # Force JSON output in the terminal
 talkpython --format json episodes search "async"
 
+# Raw Markdown for AI agents and LLM pipelines
+talkpython --format markdown episodes get 535
+
 # Force rich text output even when piping
 talkpython --format text episodes recent | less -R
 ```
 
+## Agentic AI and LLM integration
+
+Use `--format markdown` when feeding output to AI agents, LLMs, or RAG pipelines. This gives you clean, raw Markdown without terminal styling — exactly what language models expect:
+
+```bash
+# Feed an episode summary to an LLM
+talkpython --format markdown episodes get 535 | llm "Summarize this podcast episode"
+
+# Grab a transcript for RAG ingestion
+talkpython --format markdown episodes transcript 535 | your-rag-pipeline ingest
+
+# Pipe course details into an AI agent
+talkpython --format markdown courses get 57 | your-agent process
+```
+
 ## Piping JSON to other tools
 
-Because the CLI outputs JSON automatically when piped, it integrates naturally with tools like `jq`, `llm`, or your own scripts:
+The `--format json` output integrates naturally with tools like `jq` or your own scripts:
 
 ```bash
 # Extract episode titles with jq
-talkpython episodes search "testing" | jq '.title'
+talkpython --format json episodes search "testing" | jq '.title'
 
-# Feed episode data into an LLM
-talkpython episodes get 535 | llm "Summarize this podcast episode"
-
-# Grab a transcript for RAG ingestion
-talkpython episodes transcript 535 | your-rag-pipeline ingest
+# Process structured data in a script
+talkpython --format json episodes recent | python process_episodes.py
 ```
 
 ## Global options
 
 | Option | Description |
 |--------|-------------|
-| `--format text\|json` | Force output format (auto-detected by default) |
+| `--format text\|json\|markdown` | Output format: `text` (rich), `json`, or `markdown` (raw) |
 | `--url <mcp-url>` | Override the MCP server URL (default: `https://talkpython.fm/api/mcp`) |
 | `--version`, `-V` | Show version |
 

{talk_python_cli-0.1.2 → talk_python_cli-0.2.0}/README.md

@@ -17,12 +17,12 @@ Unlock 500+ episodes of [Talk Python to Me](https://talkpython.fm), full transcr
 Requires Python 3.12+.
 
 ```bash
-# Try it instantly with uvx (no install needed)
-uvx --from talk-python-cli talkpython episodes recent
-
-# Or install it permanently with uv
+# Install it permanently with uv
 uv tool install talk-python-cli
 
+# Or try it instantly with uvx (no install needed)
+uvx --from talk-python-cli talkpython episodes recent
+
 # Or with pip
 pip install talk-python-cli
 ```
@@ -31,6 +31,8 @@ This installs the `talkpython` command.
 
 ## Quick start
 
+Copy this whole block and paste it into your terminal to see what you get.
+
 ```bash
 # Search for episodes about FastAPI
 talkpython episodes search "FastAPI"
@@ -82,41 +84,55 @@ talkpython courses list
 
 ## Output formats
 
-The CLI auto-detects the best output format:
+The CLI supports three output formats via `--format`:
 
-- **Interactive terminal** — Rich-formatted Markdown with styled panels and color.
-- **Piped / redirected** — Compact JSON, ready for processing.
-
-Override the default with `--format`:
+- **`text`** (default) — Rich-formatted Markdown with styled panels and color for human reading.
+- **`json`** — Structured JSON, pretty-printed on a TTY or compact when piped.
+- **`markdown`** — Raw Markdown output with no Rich formatting. Ideal for piping into AI agents, LLMs, and automation tools that consume Markdown natively.
 
 ```bash
 # Force JSON output in the terminal
 talkpython --format json episodes search "async"
 
+# Raw Markdown for AI agents and LLM pipelines
+talkpython --format markdown episodes get 535
+
 # Force rich text output even when piping
 talkpython --format text episodes recent | less -R
 ```
 
+## Agentic AI and LLM integration
+
+Use `--format markdown` when feeding output to AI agents, LLMs, or RAG pipelines. This gives you clean, raw Markdown without terminal styling — exactly what language models expect:
+
+```bash
+# Feed an episode summary to an LLM
+talkpython --format markdown episodes get 535 | llm "Summarize this podcast episode"
+
+# Grab a transcript for RAG ingestion
+talkpython --format markdown episodes transcript 535 | your-rag-pipeline ingest
+
+# Pipe course details into an AI agent
+talkpython --format markdown courses get 57 | your-agent process
+```
+
 ## Piping JSON to other tools
 
-Because the CLI outputs JSON automatically when piped, it integrates naturally with tools like `jq`, `llm`, or your own scripts:
+The `--format json` output integrates naturally with tools like `jq` or your own scripts:
 
 ```bash
 # Extract episode titles with jq
-talkpython episodes search "testing" | jq '.title'
+talkpython --format json episodes search "testing" | jq '.title'
 
-# Feed episode data into an LLM
-talkpython episodes get 535 | llm "Summarize this podcast episode"
-
-# Grab a transcript for RAG ingestion
-talkpython episodes transcript 535 | your-rag-pipeline ingest
+# Process structured data in a script
+talkpython --format json episodes recent | python process_episodes.py
 ```
 
 ## Global options
 
 | Option | Description |
 |--------|-------------|
-| `--format text\|json` | Force output format (auto-detected by default) |
+| `--format text\|json\|markdown` | Output format: `text` (rich), `json`, or `markdown` (raw) |
 | `--url <mcp-url>` | Override the MCP server URL (default: `https://talkpython.fm/api/mcp`) |
 | `--version`, `-V` | Show version |
 

{talk_python_cli-0.1.2 → talk_python_cli-0.2.0}/change-log.md

@@ -5,6 +5,21 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.0] - 2026-02-07
+
+### Added
+- `--format markdown` output mode for raw Markdown without Rich formatting, ideal for AI agents, LLMs, and RAG pipelines
+- New "Agentic AI and LLM integration" section in README
+- `display_markdown_raw()` in `formatting.py` for plain stdout output
+- Tests for markdown format: query param propagation, raw output, and display routing
+
+### Changed
+- `--format` flag now accepts `text`, `json`, or `markdown` (was `text` or `json`)
+- MCP client sends `?format=markdown` query param to server when markdown format is selected
+- README "Output formats" and "Piping JSON to other tools" sections updated for the new format
+
+---
+
 ## [0.1.2] - 2026-02-07
 
 ### Added

{talk_python_cli-0.1.2 → talk_python_cli-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "talk-python-cli"
-version = "0.1.2"
+version = "0.2.0"
 description = "CLI for the Talk Python to Me podcast and courses"
 requires-python = ">=3.12"
 license = "MIT"

{talk_python_cli-0.1.2 → talk_python_cli-0.2.0}/src/talk_python_cli/__init__.py

@@ -2,4 +2,4 @@
 
 from importlib.metadata import version
 
-__version__ = version("talk-python-cli")
+__version__ = version('talk-python-cli')

{talk_python_cli-0.1.2 → talk_python_cli-0.2.0}/src/talk_python_cli/app.py

@@ -82,10 +82,10 @@ def status() -> None:
 def launcher(
     *tokens: Annotated[str, cyclopts.Parameter(show=False, allow_leading_hyphen=True)],
     format: Annotated[
-        Literal['text', 'json'],
+        Literal['text', 'json', 'markdown'],
         cyclopts.Parameter(
             name='--format',
-            help="Output format: 'text' (rich Markdown) or 'json'.",
+            help="Output format: 'text' (rich Markdown), 'json', or 'markdown' (raw).",
         ),
     ] = 'text',
     url: Annotated[

{talk_python_cli-0.1.2 → talk_python_cli-0.2.0}/src/talk_python_cli/client.py

@@ -46,8 +46,8 @@ class MCPClient:
         return self._msg_id
 
     def _url(self) -> str:
-        if self.output_format == 'json':
-            return f'{self.base_url}?format=json'
+        if self.output_format in ('json', 'markdown'):
+            return f'{self.base_url}?format={self.output_format}'
         return self.base_url
 
     def _post(self, payload: dict) -> httpx.Response:

{talk_python_cli-0.1.2 → talk_python_cli-0.2.0}/src/talk_python_cli/formatting.py

@@ -39,10 +39,17 @@ def display(content: str, output_format: str) -> None:
     """Route content to the appropriate renderer."""
     if output_format == 'json':
         display_json(content)
+    elif output_format == 'markdown':
+        display_markdown_raw(content)
     else:
         display_markdown(content)
 
 
+def display_markdown_raw(content: str) -> None:
+    """Print raw Markdown content to stdout without any Rich formatting."""
+    print(content)
+
+
 def display_markdown(content: str) -> None:
     """Render Markdown content with Rich, wrapped in a styled panel."""
     md = Markdown(content, code_theme='monokai')

{talk_python_cli-0.1.2 → talk_python_cli-0.2.0}/tests/test_client.py

@@ -197,6 +197,35 @@ class TestOutputFormat:
             assert 'format=json' in str(req.url)
         client.close()
 
+    def test_markdown_format_adds_query_param(self, httpx_mock: HTTPXMock) -> None:
+        md_url = f'{DEFAULT_URL}?format=markdown'
+        client = MCPClient(base_url=DEFAULT_URL, output_format='markdown')
+
+        httpx_mock.add_response(
+            method='POST',
+            url=md_url,
+            json=jsonrpc_result(
+                1,
+                {
+                    'protocolVersion': '2025-03-26',
+                    'capabilities': {'tools': {}},
+                    'serverInfo': {'name': 'test', 'version': '0.1'},
+                },
+            ),
+            headers={'mcp-session-id': 's1'},
+        )
+        httpx_mock.add_response(method='POST', url=md_url, status_code=202, headers={'mcp-session-id': 's1'})
+        httpx_mock.add_response(
+            method='POST',
+            url=md_url,
+            json=tool_result(3, '# Episode 535\n\nSome markdown content'),
+        )
+
+        client.call_tool('get_episodes')
+        for req in httpx_mock.get_requests():
+            assert 'format=markdown' in str(req.url)
+        client.close()
+
 
 class TestContextManager:
     """Verify MCPClient works as a context manager."""

talk_python_cli-0.2.0/tests/test_formatting.py

@@ -0,0 +1,38 @@
+"""Tests for output formatting."""
+
+from __future__ import annotations
+
+from talk_python_cli.formatting import display, display_markdown_raw
+
+
+class TestDisplayMarkdownRaw:
+    def test_prints_raw_content(self, capsys) -> None:
+        display_markdown_raw('# Hello\n\nSome **bold** text')
+
+        captured = capsys.readouterr()
+        assert captured.out == '# Hello\n\nSome **bold** text\n'
+
+    def test_no_rich_markup_in_output(self, capsys) -> None:
+        display_markdown_raw('## Heading\n- item 1\n- item 2')
+
+        captured = capsys.readouterr()
+        # Raw markdown should appear verbatim — no Rich panel borders or styling
+        assert '## Heading' in captured.out
+        assert '- item 1' in captured.out
+        assert '╭' not in captured.out  # no Rich panel border
+
+
+class TestDisplayRouting:
+    def test_markdown_format_routes_to_raw(self, capsys) -> None:
+        display('# Raw markdown', 'markdown')
+
+        captured = capsys.readouterr()
+        assert captured.out == '# Raw markdown\n'
+
+    def test_text_format_does_not_print_raw(self, capsys) -> None:
+        display('# Rendered', 'text')
+
+        captured = capsys.readouterr()
+        # Text mode uses Rich console, so raw '# Rendered' should NOT appear verbatim
+        # (Rich renders it as a heading without the # prefix)
+        assert '# Rendered' not in captured.out

{talk_python_cli-0.1.2 → talk_python_cli-0.2.0}/uv.lock

@@ -235,7 +235,7 @@ wheels = [
 
 [[package]]
 name = "talk-python-cli"
-version = "0.1.1"
+version = "0.2.0"
 source = { editable = "." }
 dependencies = [
     { name = "cyclopts" },