talk-python-cli 0.1.0__tar.gz

talk_python_cli-0.1.0/.claude/settings.local.json

@@ -0,0 +1,7 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(UV_PROJECT_ENVIRONMENT=venv uv run pytest:*)"
+    ]
+  }
+}

talk_python_cli-0.1.0/.gitignore

@@ -0,0 +1,205 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   uv.lock is committed to version control for reproducible installs.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/

talk_python_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Talk Python
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

talk_python_cli-0.1.0/PKG-INFO

@@ -0,0 +1,25 @@
+Metadata-Version: 2.4
+Name: talk-python-cli
+Version: 0.1.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
+Project-URL: Documentation, https://github.com/talkpython/talk-python-cli
+Author-email: Michael Kennedy <michael@talkpython.fm>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Topic :: Education
+Classifier: Topic :: Multimedia :: Sound/Audio
+Requires-Python: >=3.12
+Requires-Dist: cyclopts>=3.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: rich>=13.0

talk_python_cli-0.1.0/README.md

@@ -0,0 +1,132 @@
+# Talk Python CLI
+
+[![PyPI version](https://badge.fury.io/py/talk-python-cli.svg)](https://pypi.org/project/talk-python-cli/)
+[![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://opensource.org/licenses/MIT)
+
+Unlock 500+ episodes of [Talk Python to Me](https://talkpython.fm), full transcripts, guest profiles, and 50+ [Talk Python Training](https://training.talkpython.fm) courses — all from your terminal. Search, browse, and pipe structured data into your scripts, AI agents, or automation workflows.
+
+## Why use this?
+
+- **Automation** — Query episode data, guest info, and course catalogs from scripts and pipelines.
+- **LLM & AI integration** — Pipe JSON or Markdown output directly into AI agents, RAG systems, or chat workflows. Feed transcripts into RAG pipelines, build podcast assistants, or enrich your AI tools with real Python community knowledge.
+- **Quick lookups** — Search episodes, pull transcripts, and browse courses without leaving the terminal.
+
+## Installation
+
+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
+uv tool install talk-python-cli
+
+# Or with pip
+pip install talk-python-cli
+```
+
+This installs the `talkpython` command.
+
+## Quick start
+
+```bash
+# Search for episodes about FastAPI
+talkpython episodes search "FastAPI"
+
+# Get full details for a specific episode
+talkpython episodes get 535
+
+# Pull the transcript for an episode
+talkpython episodes transcript 535
+
+# List recent episodes
+talkpython episodes recent --limit 5
+
+# Search for a guest
+talkpython guests search "Hynek"
+
+# Browse all training courses
+talkpython courses list
+```
+
+## Commands
+
+### Episodes
+
+| Command | Description |
+|---------|-------------|
+| `talkpython episodes search <query> [--limit N]` | Search episodes by keyword (default limit: 10) |
+| `talkpython episodes get <show_id>` | Get full details for an episode |
+| `talkpython episodes list` | List all episodes |
+| `talkpython episodes recent [--limit N]` | Get the most recent episodes |
+| `talkpython episodes transcript <show_id>` | Get the plain-text transcript |
+| `talkpython episodes transcript-vtt <show_id>` | Get the WebVTT transcript (with timestamps) |
+
+### Guests
+
+| Command | Description |
+|---------|-------------|
+| `talkpython guests search <query> [--limit N]` | Search guests by name |
+| `talkpython guests get <guest_id>` | Get details for a specific guest |
+| `talkpython guests list` | List all guests, sorted by number of appearances |
+
+### Courses
+
+| Command | Description |
+|---------|-------------|
+| `talkpython courses search <query> [--course_id N]` | Search courses, chapters, and lectures |
+| `talkpython courses get <course_id>` | Get full course details including chapters and lectures |
+| `talkpython courses list` | List all available training courses |
+
+## Output formats
+
+The CLI auto-detects the best output format:
+
+- **Interactive terminal** — Rich-formatted Markdown with styled panels and color.
+- **Piped / redirected** — Compact JSON, ready for processing.
+
+Override the default with `--format`:
+
+```bash
+# Force JSON output in the terminal
+talkpython --format json episodes search "async"
+
+# Force rich text output even when piping
+talkpython --format text episodes recent | less -R
+```
+
+## 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:
+
+```bash
+# Extract episode titles with jq
+talkpython 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
+```
+
+## Global options
+
+| Option | Description |
+|--------|-------------|
+| `--format text\|json` | Force output format (auto-detected by default) |
+| `--url <mcp-url>` | Override the MCP server URL (default: `https://talkpython.fm/api/mcp`) |
+| `--version`, `-V` | Show version |
+
+## Part of the Talk Python ecosystem
+
+Talk Python CLI is one way to tap into the data behind the [Talk Python to Me](https://talkpython.fm) podcast and [Talk Python Training](https://training.talkpython.fm) courses. It connects to the same public [MCP server](https://talkpython.fm/api/mcp) that powers Talk Python's AI integrations — so whether you're building an agent, a search tool, or just want quick answers from the terminal, you're working with the real data.
+
+- [Talk Python to Me Podcast](https://talkpython.fm)
+- [Talk Python Training](https://training.talkpython.fm)
+
+## License
+
+MIT

talk_python_cli-0.1.0/plans/001-talk-python-cli.plan.md

@@ -0,0 +1,197 @@
+# Plan 001: Talk Python CLI — Standalone Package
+
+## Context
+
+The Talk Python MCP server at `https://talkpython.fm/api/mcp` exposes 12 tools for querying
+podcast episodes, guests, transcripts, and courses via JSON-RPC 2.0. This project is a
+**standalone, open-source CLI tool** (`talkpython`) that wraps those MCP tools as terminal
+commands.
+
+Full server documentation (tool names, parameters, descriptions):
+**https://talkpython.fm/api/mcp/docs**
+
+The package will be published to PyPI as `talk-python-cli` with the command name `talkpython`.
+
+### MCP server tools (reference)
+
+The server (v1.3.0) is public, read-only, no authentication required. Transport: Streamable HTTP.
+
+| CLI command                      | MCP tool name              | Parameters                              |
+|----------------------------------|----------------------------|-----------------------------------------|
+| `episodes search`                | `search_episodes`          | `query` (str), `limit` (int, optional)  |
+| `episodes get`                   | `get_episode`              | `show_id` (int)                         |
+| `episodes list`                  | `get_episodes`             | *(none)*                                |
+| `episodes recent`                | `get_recent_episodes`      | `limit` (int, optional)                 |
+| `episodes transcript`            | `get_transcript_for_episode` | `show_id` (int)                       |
+| `episodes transcript-vtt`        | `get_transcript_vtt`       | `show_id` (int)                         |
+| `guests search`                  | `search_guests`            | `query` (str), `limit` (int, optional)  |
+| `guests get`                     | `get_guest_by_id`          | `guest_id` (int)                        |
+| `guests list`                    | `get_guests`               | *(none)*                                |
+| `courses search`                 | `search_courses`           | `query` (str), `course_id` (int, opt.)  |
+| `courses get`                    | `get_course_details`       | `course_id` (int)                       |
+| `courses list`                   | `get_courses`              | *(none)*                                |
+
+### Server-side prerequisite
+
+The MCP server needs `?format=json` query parameter support so the CLI can receive structured
+data instead of pre-formatted Markdown. That change lives in the main Talk Python web app repo
+(not this one) and must be deployed before the CLI's `--format json` and auto-JSON-on-pipe
+features work. The CLI should:
+
+- Default to requesting `format=text` (works with the server today)
+- Support `--format json` for when the server-side change is deployed
+- Degrade gracefully if the server ignores the format parameter
+
+## Project structure
+
+Package lives at the repo root (not nested in a subdirectory):
+
+Managed with **uv** — no manual venv creation, use `uv run`, `uv sync`, `uv lock`, etc.
+
+```
+talk-python-cli/
+├── pyproject.toml
+├── uv.lock                        # Committed to version control
+├── LICENSE
+├── README.md
+├── .gitignore
+├── src/
+│   └── talk_python_cli/
+│       ├── __init__.py         # Version string
+│       ├── __main__.py         # python -m talk_python_cli support
+│       ├── app.py              # Root Cyclopts app + global options
+│       ├── client.py           # MCP HTTP client (httpx JSON-RPC wrapper)
+│       ├── formatting.py       # Output formatting (rich Markdown or JSON)
+│       ├── episodes.py         # Episode commands sub-app
+│       ├── guests.py           # Guest commands sub-app
+│       └── courses.py          # Course commands sub-app
+└── tests/
+    ├── __init__.py
+    ├── conftest.py             # Shared fixtures (mock MCP responses)
+    ├── test_client.py          # MCPClient unit tests
+    ├── test_episodes.py        # Episode command tests
+    ├── test_guests.py          # Guest command tests
+    └── test_courses.py         # Course command tests
+```
+
+## Dependencies (pyproject.toml)
+
+Created via `uv init`, then `uv add cyclopts httpx rich` and `uv add --dev pytest pytest-httpx`.
+
+```toml
+[project]
+name = "talk-python-cli"
+version = "0.1.0"
+description = "CLI for the Talk Python to Me podcast and courses"
+requires-python = ">=3.12"
+license = "MIT"
+authors = [
+    { name = "Michael Kennedy", email = "michael@talkpython.fm" },
+]
+dependencies = [
+    "cyclopts>=3.0",
+    "httpx>=0.27",
+    "rich>=13.0",
+]
+
+[project.scripts]
+talkpython = "talk_python_cli.app:main"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "pytest-httpx>=0.34",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+```
+
+The `uv.lock` file is committed for reproducible installs.
+
+## CLI commands
+
+```
+talkpython [--format text|json] [--url URL]
+
+talkpython episodes search QUERY [--limit N]
+talkpython episodes get SHOW_ID
+talkpython episodes list
+talkpython episodes recent [--limit N]
+talkpython episodes transcript SHOW_ID
+talkpython episodes transcript-vtt SHOW_ID
+
+talkpython guests search QUERY [--limit N]
+talkpython guests get GUEST_ID
+talkpython guests list
+
+talkpython courses search QUERY [--course-id ID]
+talkpython courses get COURSE_ID
+talkpython courses list
+```
+
+Global option `--format` defaults to `text` (rendered Markdown) but can be set to `json`
+for machine-readable output. `--url` defaults to `https://talkpython.fm/api/mcp`.
+
+### Auto-detection for piped output
+
+When stdout is not a TTY (piped to another command), default to JSON format
+for scripting convenience: `talkpython episodes recent | jq '.[]'`
+
+## Key module designs
+
+**`client.py`** — Thin wrapper around httpx making JSON-RPC calls:
+```python
+class MCPClient:
+    def __init__(self, base_url: str, output_format: str = 'text'):
+        self.base_url = base_url
+        self.output_format = output_format
+        self._msg_id = 0
+
+    def call_tool(self, tool_name: str, arguments: dict) -> dict:
+        # POST to base_url?format={output_format}
+        # JSON-RPC 2.0 envelope: {"jsonrpc":"2.0","id":N,"method":"tools/call","params":{...}}
+        # Returns the result content text
+```
+
+**`formatting.py`** — Handles display:
+- `text` format: render Markdown from server using rich
+- `json` format: print with optional pretty-printing
+
+**`app.py`** — Root app with global params:
+```python
+app = cyclopts.App(name='talkpython', help='Talk Python to Me CLI')
+# Register sub-apps
+app.command(episodes_app)
+app.command(guests_app)
+app.command(courses_app)
+```
+
+**`episodes.py`**, **`guests.py`**, **`courses.py`** — Each defines a sub-app:
+```python
+episodes_app = cyclopts.App(name='episodes', help='Podcast episode commands')
+
+@episodes_app.command
+def search(query: str, *, limit: int = 10):
+    ...
+```
+
+## Implementation order
+
+1. `uv init` — create `pyproject.toml`, then add dependencies with `uv add`
+2. Implement `client.py` (HTTP JSON-RPC client)
+3. Implement `formatting.py` (output rendering)
+4. Implement `app.py` + command modules (`episodes.py`, `guests.py`, `courses.py`)
+5. Add `__main__.py` for `python -m` support
+6. Add tests with mocked HTTP responses (`uv add --dev pytest pytest-httpx`)
+7. Verify against live server
+
+## Verification
+
+1. **Sync**: `uv sync` (installs all deps including dev group)
+2. **Unit tests**: `uv run pytest tests/ -v`
+3. **Smoke test**: `uv run talkpython episodes recent --limit 3`
+4. **JSON output**: `uv run talkpython --format json episodes recent --limit 3`
+5. **Piped output**: `uv run talkpython episodes recent | head` — should auto-detect JSON format
+6. **Module entry**: `uv run python -m talk_python_cli episodes recent --limit 3`

talk_python_cli-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[project]
+name = "talk-python-cli"
+version = "0.1.0"
+description = "CLI for the Talk Python to Me podcast and courses"
+requires-python = ">=3.12"
+license = "MIT"
+authors = [
+    { name = "Michael Kennedy", email = "michael@talkpython.fm" },
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: 3.15",
+    "Topic :: Multimedia :: Sound/Audio",
+    "Topic :: Education",
+]
+dependencies = [
+    "cyclopts>=3.0",
+    "httpx>=0.27",
+    "rich>=13.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/talkpython/talk-python-cli"
+Source = "https://github.com/talkpython/talk-python-cli"
+Documentation = "https://github.com/talkpython/talk-python-cli"
+
+[project.scripts]
+talkpython = "talk_python_cli.app:main"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "pytest-httpx>=0.34",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/talk_python_cli"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"

talk_python_cli-0.1.0/pyrefly.toml

@@ -0,0 +1,45 @@
+###### configuring what to type check and where to import from
+
+# check all files in "."
+project-includes = ["."]
+# exclude dotfiles
+project-excludes = ["**/.[!/.]*", "**/*venv/**"]
+# perform an upward search for `.gitignore`, `.ignore`, and `.git/info/exclude`, and
+# add those to `project-excludes` automatically
+use-ignore-files = true
+# import project files from "src" (main package) and "." (tests)
+search-path = ["src", "."]
+# let Pyrefly try to guess your search path
+disable-search-path-heuristics = false
+# do not include any third-party packages (except those provided by an interpreter)
+site-package-path = []
+
+###### configuring your python environment
+
+python-platform = "darwin"
+# assume the Python version we're using is 3.14, without querying an interpreter
+python-version = "3.14"
+# is Pyrefly disallowed from querying for an interpreter to automatically determine your
+# `python-platform`, `python-version`, and extra entries to `site-package-path`?
+skip-interpreter-query = false
+# query the default Python interpreter on your system, if installed and `python_platform`,
+# `python-version`, or `site-package-path` are unset.
+# python-interpreter = null # this is commented out because there are no `null` values in TOML
+
+#### configuring your type check settings
+
+# wildcards for which Pyrefly will unconditionally replace the import with `typing.Any`
+replace-imports-with-any = []
+# wildcards for which Pyrefly will replace the import with `typing.Any` if it can't be found
+ignore-missing-imports = []
+# should Pyrefly skip type checking if we find a generated file?
+ignore-errors-in-generated-code = false
+# what should Pyrefly do when it encounters a function that is untyped?
+untyped-def-behavior = "check-and-infer-return-type"
+# can Pyrefly recognize ignore directives other than `# pyrefly: ignore` and `# type: ignore`
+permissive-ignores = false
+
+[errors]
+# this is an empty table, meaning all errors are enabled by default
+
+# no `[[sub-config]]` entries are included, since there are none by default