talk-python-cli 0.1.0__py3-none-any.whl

talk_python_cli/__init__.py

@@ -0,0 +1,3 @@
+"""Talk Python to Me CLI — query podcast episodes, guests, and courses."""
+
+__version__ = '0.1.0'

talk_python_cli/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running as ``python -m talk_python_cli``."""
+
+from talk_python_cli.app import main
+
+main()

talk_python_cli/app.py

@@ -0,0 +1,91 @@
+"""Root Cyclopts application with global options."""
+
+from __future__ import annotations
+
+import sys
+from typing import Annotated, Literal
+
+import cyclopts
+
+from talk_python_cli import __version__
+from talk_python_cli.client import DEFAULT_URL, MCPClient
+from talk_python_cli.formatting import is_tty, print_error
+
+# ── Shared state ─────────────────────────────────────────────────────────────
+# The meta-app handler stores the client here so command modules can access it.
+_client: MCPClient | None = None
+
+
+def get_client() -> MCPClient:
+    """Return the active MCPClient (set by the meta-app launcher)."""
+    assert _client is not None, 'MCPClient not initialised — this is a bug'
+    return _client
+
+
+# ── Root app ─────────────────────────────────────────────────────────────────
+app = cyclopts.App(
+    name='talkpython',
+    help='CLI for the Talk Python to Me podcast and courses.\n\n'
+    'Query episodes, guests, transcripts, and training courses\n'
+    'from the Talk Python MCP server.',
+    version=__version__,
+    version_flags=['--version', '-V'],
+)
+
+# ── Register sub-apps (imported here to avoid circular imports) ──────────────
+from talk_python_cli.courses import courses_app  # noqa: E402
+from talk_python_cli.episodes import episodes_app  # noqa: E402
+from talk_python_cli.guests import guests_app  # noqa: E402
+
+app.command(episodes_app)
+app.command(guests_app)
+app.command(courses_app)
+
+
+# ── Meta-app: handles global options before dispatching to sub-commands ──────
+@app.meta.default
+def launcher(
+    *tokens: Annotated[str, cyclopts.Parameter(show=False, allow_leading_hyphen=True)],
+    format: Annotated[
+        Literal['text', 'json'],
+        cyclopts.Parameter(
+            name='--format',
+            help="Output format: 'text' (rich Markdown) or 'json'. Defaults to 'json' when stdout is piped.",
+        ),
+    ] = None,  # type: ignore
+    url: Annotated[
+        str,
+        cyclopts.Parameter(
+            name='--url',
+            help='MCP server URL.',
+            show_default=True,
+        ),
+    ] = DEFAULT_URL,
+) -> None:
+    global _client
+
+    # Auto-detect: default to json when piped, text when interactive
+    if format is None:
+        format = 'text' if is_tty() else 'json'
+
+    _client = MCPClient(base_url=url, output_format=format)
+    try:
+        app(tokens)
+    except Exception as exc:
+        print_error(str(exc))
+        sys.exit(1)
+    finally:
+        _client.close()
+        _client = None
+
+
+# ── Entrypoint ───────────────────────────────────────────────────────────────
+def main() -> None:
+    """CLI entrypoint — called by the ``talkpython`` console script."""
+    try:
+        app.meta()
+    except SystemExit:
+        raise
+    except Exception as exc:
+        print_error(str(exc))
+        sys.exit(1)

talk_python_cli/client.py

@@ -0,0 +1,144 @@
+"""MCP HTTP client — thin JSON-RPC 2.0 wrapper over httpx."""
+
+from __future__ import annotations
+
+import httpx
+
+from talk_python_cli import __version__
+
+DEFAULT_URL = 'https://talkpython.fm/api/mcp'
+_PROTOCOL_VERSION = '2025-03-26'
+_CLIENT_INFO = {'name': 'talk-python-cli', 'version': __version__}
+
+
+class MCPError(Exception):
+    """Raised when the MCP server returns a JSON-RPC error."""
+
+    def __init__(self, code: int, message: str, data: object = None):
+        self.code = code
+        self.message = message
+        self.data = data
+        super().__init__(f'MCP error {code}: {message}')
+
+
+class MCPClient:
+    """Synchronous client for the Talk Python MCP server (Streamable HTTP)."""
+
+    def __init__(self, base_url: str = DEFAULT_URL, output_format: str = 'text'):
+        self.base_url = base_url.rstrip('/')
+        self.output_format = output_format
+        self._msg_id = 0
+        self._session_id: str | None = None
+        self._initialized = False
+        self._http = httpx.Client(
+            timeout=30.0,
+            headers={
+                'Content-Type': 'application/json',
+                'Accept': 'application/json, text/event-stream',
+                'User-Agent': f'talk-python-cli/{__version__}',
+            },
+        )
+
+    # -- internal helpers -----------------------------------------------------
+
+    def _next_id(self) -> int:
+        self._msg_id += 1
+        return self._msg_id
+
+    def _url(self) -> str:
+        if self.output_format == 'json':
+            return f'{self.base_url}?format=json'
+        return self.base_url
+
+    def _post(self, payload: dict) -> httpx.Response:
+        """Send a JSON-RPC request, attaching session header if available."""
+        headers: dict[str, str] = {}
+        if self._session_id:
+            headers['Mcp-Session-Id'] = self._session_id
+        resp = self._http.post(self._url(), json=payload, headers=headers)
+        # Capture session id from response
+        if 'mcp-session-id' in resp.headers:
+            self._session_id = resp.headers['mcp-session-id']
+        resp.raise_for_status()
+        return resp
+
+    def _send_request(self, method: str, params: dict | None = None) -> dict:
+        """Send a JSON-RPC *request* (expects a response with an id)."""
+        payload: dict = {
+            'jsonrpc': '2.0',
+            'id': self._next_id(),
+            'method': method,
+        }
+        if params is not None:
+            payload['params'] = params
+
+        resp = self._post(payload)
+        body = resp.json()
+
+        if 'error' in body:
+            err = body['error']
+            raise MCPError(err.get('code', -1), err.get('message', 'Unknown error'), err.get('data'))
+
+        return body.get('result', {})
+
+    def _send_notification(self, method: str, params: dict | None = None) -> None:
+        """Send a JSON-RPC *notification* (no id, no response expected)."""
+        payload: dict = {
+            'jsonrpc': '2.0',
+            'method': method,
+        }
+        if params is not None:
+            payload['params'] = params
+        self._post(payload)
+
+    # -- MCP lifecycle --------------------------------------------------------
+
+    def _initialize(self) -> None:
+        """Perform the MCP initialize handshake."""
+        self._send_request(
+            'initialize',
+            {
+                'protocolVersion': _PROTOCOL_VERSION,
+                'capabilities': {},
+                'clientInfo': _CLIENT_INFO,
+            },
+        )
+        self._send_notification('notifications/initialized')
+        self._initialized = True
+
+    def _ensure_initialized(self) -> None:
+        if not self._initialized:
+            self._initialize()
+
+    # -- public API -----------------------------------------------------------
+
+    def call_tool(self, tool_name: str, arguments: dict | None = None) -> str:
+        """Call an MCP tool and return the text content from the first result.
+
+        Returns the raw text string from the server (Markdown or JSON depending
+        on the ``output_format`` passed at construction time).
+        """
+        self._ensure_initialized()
+
+        result = self._send_request(
+            'tools/call',
+            {
+                'name': tool_name,
+                'arguments': arguments or {},
+            },
+        )
+
+        # MCP tools/call result: {"content": [{"type": "text", "text": "..."}]}
+        content_list = result.get('content', [])
+        texts = [item['text'] for item in content_list if item.get('type') == 'text']
+        return '\n'.join(texts)
+
+    def close(self) -> None:
+        """Close the underlying HTTP client."""
+        self._http.close()
+
+    def __enter__(self) -> MCPClient:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()

talk_python_cli/courses.py

@@ -0,0 +1,59 @@
+"""Course commands — search, get, list."""
+
+from __future__ import annotations
+
+import cyclopts
+
+from talk_python_cli.formatting import display
+
+courses_app = cyclopts.App(
+    name='courses',
+    help='Browse and search Talk Python Training courses.',
+)
+
+
+def _client():
+    from talk_python_cli.app import get_client
+
+    return get_client()
+
+
+@courses_app.command
+def search(query: str, *, course_id: int | None = None) -> None:
+    """Search courses, chapters, and lectures by keyword.
+
+    Parameters
+    ----------
+    query
+        Keywords for course, chapter, or lecture titles.
+    course_id
+        Limit search to a specific course (optional).
+    """
+    client = _client()
+    args: dict = {'query': query}
+    if course_id is not None:
+        args['course_id'] = course_id
+    content = client.call_tool('search_courses', args)
+    display(content, client.output_format)
+
+
+@courses_app.command
+def get(course_id: int) -> None:
+    """Get full details for a course by ID, including chapters and lectures.
+
+    Parameters
+    ----------
+    course_id
+        The course ID.
+    """
+    client = _client()
+    content = client.call_tool('get_course_details', {'course_id': course_id})
+    display(content, client.output_format)
+
+
+@courses_app.command(name='list')
+def list_courses() -> None:
+    """List all available Talk Python Training courses."""
+    client = _client()
+    content = client.call_tool('get_courses')
+    display(content, client.output_format)

talk_python_cli/episodes.py

@@ -0,0 +1,99 @@
+"""Episode commands — search, get, list, recent, transcript."""
+
+from __future__ import annotations
+
+import cyclopts
+
+from talk_python_cli.formatting import display
+
+episodes_app = cyclopts.App(
+    name='episodes',
+    help='Browse and search Talk Python to Me podcast episodes.',
+)
+
+
+def _client():
+    from talk_python_cli.app import get_client
+
+    return get_client()
+
+
+@episodes_app.command
+def search(query: str, *, limit: int = 10) -> None:
+    """Search episodes by keyword.
+
+    Parameters
+    ----------
+    query
+        Search keywords for episode titles and descriptions.
+    limit
+        Maximum number of results to return.
+    """
+    client = _client()
+    args = {'query': query, 'limit': limit}
+    content = client.call_tool('search_episodes', args)
+    display(content, client.output_format)
+
+
+@episodes_app.command
+def get(show_id: int) -> None:
+    """Get full details for an episode by its show ID.
+
+    Parameters
+    ----------
+    show_id
+        Episode show ID (e.g. 400).
+    """
+    client = _client()
+    content = client.call_tool('get_episode', {'show_id': show_id})
+    display(content, client.output_format)
+
+
+@episodes_app.command(name='list')
+def list_episodes() -> None:
+    """List all podcast episodes with their show IDs and titles."""
+    client = _client()
+    content = client.call_tool('get_episodes')
+    display(content, client.output_format)
+
+
+@episodes_app.command
+def recent(*, limit: int = 10) -> None:
+    """Get the most recently published episodes.
+
+    Parameters
+    ----------
+    limit
+        Number of recent episodes to return.
+    """
+    client = _client()
+    content = client.call_tool('get_recent_episodes', {'limit': limit})
+    display(content, client.output_format)
+
+
+@episodes_app.command
+def transcript(show_id: int) -> None:
+    """Get the full plain-text transcript for an episode.
+
+    Parameters
+    ----------
+    show_id
+        Episode show ID.
+    """
+    client = _client()
+    content = client.call_tool('get_transcript_for_episode', {'show_id': show_id})
+    display(content, client.output_format)
+
+
+@episodes_app.command(name='transcript-vtt')
+def transcript_vtt(show_id: int) -> None:
+    """Get the transcript in WebVTT format (with timestamps).
+
+    Parameters
+    ----------
+    show_id
+        Episode show ID.
+    """
+    client = _client()
+    content = client.call_tool('get_transcript_vtt', {'show_id': show_id})
+    display(content, client.output_format)

talk_python_cli/formatting.py

@@ -0,0 +1,94 @@
+"""Output formatting — Rich Markdown rendering and JSON display."""
+
+from __future__ import annotations
+
+import json
+import sys
+
+from rich.console import Console
+from rich.markdown import Markdown
+from rich.panel import Panel
+from rich.text import Text
+from rich.theme import Theme
+
+# ── Custom theme for Talk Python branding ────────────────────────────────────
+_TALK_PYTHON_THEME = Theme(
+    {
+        'tp.title': 'bold cyan',
+        'tp.heading': 'bold magenta',
+        'tp.id': 'bold yellow',
+        'tp.url': 'blue underline',
+        'tp.date': 'green',
+        'tp.dim': 'dim',
+        'tp.error': 'bold red',
+        'tp.success': 'bold green',
+        'tp.label': 'bold white',
+    }
+)
+
+console = Console(theme=_TALK_PYTHON_THEME, highlight=False)
+error_console = Console(theme=_TALK_PYTHON_THEME, stderr=True, highlight=False)
+
+
+def is_tty() -> bool:
+    """Return True if stdout is connected to a terminal."""
+    return sys.stdout.isatty()
+
+
+def display(content: str, output_format: str) -> None:
+    """Route content to the appropriate renderer."""
+    if output_format == 'json':
+        display_json(content)
+    else:
+        display_markdown(content)
+
+
+def display_markdown(content: str) -> None:
+    """Render Markdown content with Rich, wrapped in a styled panel."""
+    md = Markdown(content, code_theme='monokai')
+
+    panel = Panel(
+        md,
+        border_style='cyan',
+        title='[bold cyan]Talk Python[/bold cyan]',
+        title_align='left',
+        padding=(1, 2),
+    )
+    console.print(panel)
+
+
+def display_json(content: str) -> None:
+    """Output JSON content — pretty-printed if on a TTY, raw otherwise."""
+    try:
+        data = json.loads(content)
+    except json.JSONDecodeError, TypeError:
+        # Server may have returned Markdown even though JSON was requested;
+        # fall back to printing the raw text.
+        console.print(content)
+        return
+
+    if is_tty():
+        from rich.syntax import Syntax
+
+        formatted = json.dumps(data, indent=2, ensure_ascii=False)
+        syntax = Syntax(formatted, 'json', theme='monokai', word_wrap=True)
+        console.print(syntax)
+    else:
+        # Raw compact JSON for piping
+        print(json.dumps(data, ensure_ascii=False))
+
+
+def print_error(message: str) -> None:
+    """Print a styled error message to stderr."""
+    error_console.print(
+        Text.assemble(
+            ('ERROR', 'bold red'),
+            (' ', ''),
+            (message, 'red'),
+        )
+    )
+
+
+def print_info(message: str) -> None:
+    """Print a styled informational message."""
+    console.print(f'[tp.dim]{message}[/tp.dim]')

talk_python_cli/guests.py

@@ -0,0 +1,56 @@
+"""Guest commands — search, get, list."""
+
+from __future__ import annotations
+
+import cyclopts
+
+from talk_python_cli.formatting import display
+
+guests_app = cyclopts.App(
+    name='guests',
+    help='Browse and search Talk Python to Me podcast guests.',
+)
+
+
+def _client():
+    from talk_python_cli.app import get_client
+
+    return get_client()
+
+
+@guests_app.command
+def search(query: str, *, limit: int = 10) -> None:
+    """Search guests by name.
+
+    Parameters
+    ----------
+    query
+        Guest name or partial name to search for.
+    limit
+        Maximum number of results to return.
+    """
+    client = _client()
+    content = client.call_tool('search_guests', {'query': query, 'limit': limit})
+    display(content, client.output_format)
+
+
+@guests_app.command
+def get(guest_id: int) -> None:
+    """Get detailed info about a guest by their ID.
+
+    Parameters
+    ----------
+    guest_id
+        The guest ID.
+    """
+    client = _client()
+    content = client.call_tool('get_guest_by_id', {'guest_id': guest_id})
+    display(content, client.output_format)
+
+
+@guests_app.command(name='list')
+def list_guests() -> None:
+    """List all podcast guests, sorted by number of appearances."""
+    client = _client()
+    content = client.call_tool('get_guests')
+    display(content, client.output_format)

talk_python_cli-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,13 @@
+talk_python_cli/__init__.py,sha256=05NfNnHR3JpU6LYq_GWjTERnI7FInPp_pmF9L1qk7uI,100
+talk_python_cli/__main__.py,sha256=CiR9VEA51QfEByCah9e1uvR7gqiFDoBmsRgFVWltjBU,100
+talk_python_cli/app.py,sha256=gzfruXfL8pDxr8pEFCTrUKzGfZGKr3Af87jtiHNlfRs,3224
+talk_python_cli/client.py,sha256=NR48azeJlfHYFMqikUSjfrFOmCVClyOlq4yd0hyvxHY,4778
+talk_python_cli/courses.py,sha256=EgWFbhLFeBTotDHu3xZ4fyiJokgWY2ZLFVaDRTU6NNo,1478
+talk_python_cli/episodes.py,sha256=7Mm6uZ_jzMV6JBPv-1xbmINo7eyI4ylKvsT4_xT3Umw,2453
+talk_python_cli/formatting.py,sha256=Ww3pfIAK50Ms2MSSkKrKjvwam_5C3ltEB1klHRGeM8U,2699
+talk_python_cli/guests.py,sha256=O5MpmnhbACx1czKbV_p9KZywRwEo4jxOM5y8oU3ix50,1314
+talk_python_cli-0.1.0.dist-info/METADATA,sha256=SkfLFf8i5jH2whFa8DCKxufxZ6dvzXjB0xoscxwt_HU,1038
+talk_python_cli-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+talk_python_cli-0.1.0.dist-info/entry_points.txt,sha256=Q7eLneKcuKeoSY_Ps-RyMb8BF1q6QPytIZ0ZYm7fhBg,56
+talk_python_cli-0.1.0.dist-info/licenses/LICENSE,sha256=E1rfm5mKKkNGtHcctSAevPdM0uk6DqdPlcM48R1jGM4,1068
+talk_python_cli-0.1.0.dist-info/RECORD,,

talk_python_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

talk_python_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+talkpython = talk_python_cli.app:main

talk_python_cli-0.1.0.dist-info/licenses/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.