pyflexweb 0.1.2__py3-none-any.whl

pyflexweb/__init__.py

@@ -0,0 +1,13 @@
+"""
+PyFlexWeb - Interactive Brokers Flex Web Service Client
+
+A command-line tool to easily download IBKR Flex Activity and Trade Confirmation reports.
+"""
+
+try:
+    from importlib.metadata import version
+except ImportError:
+    # Python < 3.8
+    from importlib_metadata import version  # type: ignore
+
+__version__ = version("pyflexweb")

pyflexweb/cli.py

@@ -0,0 +1,213 @@
+"""
+Command-line interface for PyFlexWeb.
+
+This module provides the main entry point and argument parsing for the PyFlexWeb CLI.
+"""
+
+import sys
+
+import click
+
+from .database import FlexDatabase
+from .handlers import (
+    handle_download_command,
+    handle_fetch_command,
+    handle_query_command,
+    handle_request_command,
+    handle_token_command,
+)
+
+
+# Common options
+def common_options(func):
+    """Common options for commands that fetch reports."""
+    func = click.option("--output", help="Output filename (for single report downloads only)")(func)
+    func = click.option(
+        "--output-dir",
+        help="Directory to save reports (default: current directory)",
+    )(func)
+    func = click.option(
+        "--poll-interval",
+        type=int,
+        default=30,
+        help="Seconds to wait between polling attempts (default: 30)",
+    )(func)
+    func = click.option(
+        "--max-attempts",
+        type=int,
+        default=20,
+        help="Maximum number of polling attempts (default: 20)",
+    )(func)
+    return func
+
+
+@click.group(invoke_without_command=True)
+@click.version_option(package_name="pyflexweb")
+@click.pass_context
+def cli(ctx):
+    """Download IBKR Flex reports using the Interactive Brokers flex web service."""
+    db = FlexDatabase()
+    ctx.ensure_object(dict)
+    ctx.obj["db"] = db
+
+    # If no command is provided, show help text
+    if ctx.invoked_subcommand is None:
+        click.echo(ctx.get_help())
+        exit(1)
+
+    return 0
+
+
+# Token commands
+@cli.group()
+@click.pass_context
+def token(ctx):
+    """Manage IBKR Flex token."""
+    pass
+
+
+@token.command("set")
+@click.argument("token_value")
+@click.pass_context
+def token_set(ctx, token_value):
+    """Set your IBKR token."""
+    args = type("Args", (), {"subcommand": "set", "token": token_value})
+    return handle_token_command(args, ctx.obj["db"])
+
+
+@token.command("get")
+@click.pass_context
+def token_get(ctx):
+    """Display your stored token."""
+    args = type("Args", (), {"subcommand": "get"})
+    return handle_token_command(args, ctx.obj["db"])
+
+
+@token.command("unset")
+@click.pass_context
+def token_unset(ctx):
+    """Remove your stored token."""
+    args = type("Args", (), {"subcommand": "unset"})
+    return handle_token_command(args, ctx.obj["db"])
+
+
+# Query commands
+@cli.group(invoke_without_command=True)
+@click.pass_context
+def query(ctx):
+    """Manage Flex query IDs."""
+    if ctx.invoked_subcommand is None:
+        # Default to 'list' if no subcommand is provided
+        args = type("Args", (), {"subcommand": "list"})
+        return handle_query_command(args, ctx.obj["db"])
+    return 0
+
+
+@query.command("add")
+@click.argument("query_id")
+@click.option("--name", required=True, help="A descriptive name for the query")
+@click.pass_context
+def query_add(ctx, query_id, name):
+    """Add a new query ID."""
+    args = type("Args", (), {"subcommand": "add", "query_id": query_id, "name": name})
+    return handle_query_command(args, ctx.obj["db"])
+
+
+@query.command("remove")
+@click.argument("query_id")
+@click.pass_context
+def query_remove(ctx, query_id):
+    """Remove a query ID."""
+    args = type("Args", (), {"subcommand": "remove", "query_id": query_id})
+    return handle_query_command(args, ctx.obj["db"])
+
+
+@query.command("rename")
+@click.argument("query_id")
+@click.option("--name", required=True, help="The new name for the query")
+@click.pass_context
+def query_rename(ctx, query_id, name):
+    """Rename a query."""
+    args = type("Args", (), {"subcommand": "rename", "query_id": query_id, "name": name})
+    return handle_query_command(args, ctx.obj["db"])
+
+
+@query.command("list")
+@click.pass_context
+def query_list(ctx):
+    """List all stored query IDs."""
+    args = type("Args", (), {"subcommand": "list"})
+    return handle_query_command(args, ctx.obj["db"])
+
+
+# Report request command
+@cli.command("request")
+@click.argument("query_id")
+@click.pass_context
+def request(ctx, query_id):
+    """Request a Flex report."""
+    args = type("Args", (), {"query_id": query_id})
+    return handle_request_command(args, ctx.obj["db"])
+
+
+# Report fetch command
+@cli.command("fetch")
+@click.argument("request_id")
+@common_options
+@click.pass_context
+def fetch(ctx, request_id, output, output_dir, poll_interval, max_attempts):
+    """Fetch a requested report."""
+    args = type(
+        "Args",
+        (),
+        {
+            "request_id": request_id,
+            "output": output,
+            "output_dir": output_dir,
+            "poll_interval": poll_interval,
+            "max_attempts": max_attempts,
+        },
+    )
+    return handle_fetch_command(args, ctx.obj["db"])
+
+
+# All-in-one download command
+@cli.command("download")
+@click.option("--query", default="all", help="The query ID to download a report for (default: all)")
+@click.option("--force", is_flag=True, help="Force download even if report was already downloaded today")
+@common_options
+@click.pass_context
+def download(ctx, query, force, output, output_dir, poll_interval, max_attempts):
+    """Request and download a report in one step.
+
+    If --query is not specified, downloads all queries not updated in 24 hours.
+    """
+    args = type(
+        "Args",
+        (),
+        {
+            "query": query,
+            "force": force,
+            "output": output,
+            "output_dir": output_dir,
+            "poll_interval": poll_interval,
+            "max_attempts": max_attempts,
+        },
+    )
+    return handle_download_command(args, ctx.obj["db"])
+
+
+def main():
+    """Main entry point for the CLI."""
+    try:
+        sys.exit(cli())  # pylint: disable=no-value-for-parameter
+    except Exception as e:  # pylint: disable=broad-except
+        click.echo(f"Error: {e}", err=True)
+        return 1
+    finally:
+        # No need to close db here as it's managed within the cli context
+        pass
+
+
+if __name__ == "__main__":
+    sys.exit(main())

pyflexweb/client.py

@@ -0,0 +1,75 @@
+"""Client module for communicating with IBKR Flex Web Service."""
+
+import sys
+import xml.etree.ElementTree as ET
+
+import requests
+
+
+class IBKRFlexClient:
+    """Handles communication with the IBKR Flex Web Service."""
+
+    BASE_URL = "https://gdcdyn.interactivebrokers.com/Universal/servlet"
+    REQUEST_URL = f"{BASE_URL}/FlexStatementService.SendRequest"
+    STATEMENT_URL = f"{BASE_URL}/FlexStatementService.GetStatement"
+
+    def __init__(self, token: str):
+        self.token = token
+
+    def request_report(self, query_id: str) -> str | None:
+        """Request a report from IBKR and return the request ID if successful."""
+        url = f"{self.REQUEST_URL}?t={self.token}&q={query_id}&v=3"
+
+        try:
+            response = requests.get(url)
+            response.raise_for_status()
+
+            # Parse the XML response
+            root = ET.fromstring(response.text)
+            status = root.find(".//Status").text
+
+            if status == "Success":
+                request_id = root.find(".//ReferenceCode").text
+                return request_id
+            else:
+                error = root.find(".//ErrorMessage").text
+                print(f"Error requesting report: {error}", file=sys.stderr)
+                return None
+
+        except requests.exceptions.RequestException as e:
+            print(f"Network error: {e}", file=sys.stderr)
+            return None
+        except ET.ParseError as e:
+            print(f"Error parsing response: {e}", file=sys.stderr)
+            return None
+
+    def get_report(self, request_id: str) -> str | None:
+        """Get a report using the request ID. Returns the XML content if successful."""
+        url = f"{self.STATEMENT_URL}?t={self.token}&q={request_id}&v=3"
+
+        try:
+            response = requests.get(url)
+            response.raise_for_status()
+
+            # Check if this is an error response
+            if "<ErrorCode>" in response.text:
+                root = ET.fromstring(response.text)
+                status = root.find(".//Status").text
+
+                if status == "Pending":
+                    return None  # Report not ready yet
+
+                error = root.find(".//ErrorMessage")
+                if error is not None:
+                    print(f"Error retrieving report: {error.text}", file=sys.stderr)
+                return None
+
+            # If we got here, we have the actual report
+            return response.text
+
+        except requests.exceptions.RequestException as e:
+            print(f"Network error: {e}", file=sys.stderr)
+            return None
+        except ET.ParseError as e:
+            print(f"Error parsing response: {e}", file=sys.stderr)
+            return None

pyflexweb/database.py

@@ -0,0 +1,293 @@
+"""Database module for storing tokens, queries, and request history."""
+
+import os
+import sqlite3
+from datetime import datetime, timedelta
+
+import platformdirs
+
+
+class FlexDatabase:
+    """Manages the local database for tokens, queries, and request history."""
+
+    DB_VERSION = 2  # Increment when schema changes
+
+    def __init__(self):
+        self.db_dir = platformdirs.user_data_dir("pyflexweb")
+        os.makedirs(self.db_dir, exist_ok=True)
+        self.db_path = os.path.join(self.db_dir, "status.db")
+        self.conn = self._init_db()
+
+    def get_db_path(self) -> str:
+        """Return the path to the database file."""
+        return self.db_path
+
+    def _init_db(self) -> sqlite3.Connection:
+        conn = sqlite3.connect(self.db_path)
+        cursor = conn.cursor()
+
+        # Create tables if they don't exist
+        cursor.execute(
+            """
+        CREATE TABLE IF NOT EXISTS config (
+            key TEXT PRIMARY KEY,
+            value TEXT NOT NULL
+        )
+        """
+        )
+
+        cursor.execute(
+            """
+        CREATE TABLE IF NOT EXISTS queries (
+            id TEXT PRIMARY KEY,
+            name TEXT,
+            added_on DATETIME DEFAULT CURRENT_TIMESTAMP
+        )
+        """
+        )
+
+        cursor.execute(
+            """
+        CREATE TABLE IF NOT EXISTS requests (
+            request_id TEXT PRIMARY KEY,
+            query_id TEXT,
+            status TEXT,
+            requested_at DATETIME,
+            completed_at DATETIME,
+            last_updated DATETIME,
+            output_path TEXT,
+            FOREIGN KEY (query_id) REFERENCES queries(id)
+        )
+        """
+        )
+
+        # Check if migration needed
+        self._check_migration(conn)
+
+        return conn
+
+    def _check_migration(self, conn: sqlite3.Connection) -> None:
+        """Check if database needs migration and perform if needed."""
+        cursor = conn.cursor()
+
+        # Get current database version
+        cursor.execute("SELECT value FROM config WHERE key = 'db_version' LIMIT 1")
+        result = cursor.fetchone()
+        current_version = int(result[0]) if result else 0
+
+        # If already at current version, no migration needed
+        if current_version >= self.DB_VERSION:
+            return
+
+        # Perform migrations
+        if current_version < 1:
+            # Add last_updated column to requests table
+            try:
+                cursor.execute("ALTER TABLE requests ADD COLUMN last_updated DATETIME")
+                conn.commit()
+            except sqlite3.OperationalError:
+                # Column might already exist
+                pass
+
+        if current_version < 2:
+            # Remove report_type column from queries table
+            # First get all existing queries
+            cursor.execute("PRAGMA table_info(queries)")
+            columns = cursor.fetchall()
+            has_report_type = any(col[1] == "report_type" for col in columns)
+
+            if has_report_type:
+                # Get all existing data
+                cursor.execute("SELECT id, name FROM queries")
+                queries = cursor.fetchall()
+
+                # Drop and recreate the table
+                cursor.execute("DROP TABLE queries")
+                cursor.execute(
+                    """
+                CREATE TABLE queries (
+                    id TEXT PRIMARY KEY,
+                    name TEXT,
+                    added_on DATETIME DEFAULT CURRENT_TIMESTAMP
+                )
+                """
+                )
+
+                # Reinsert the data
+                for query_id, name in queries:
+                    cursor.execute("INSERT INTO queries (id, name) VALUES (?, ?)", (query_id, name))
+
+        # Update the version
+        cursor.execute(
+            "INSERT OR REPLACE INTO config VALUES (?, ?)",
+            ("db_version", str(self.DB_VERSION)),
+        )
+        conn.commit()
+
+    def set_token(self, token: str) -> None:
+        cursor = self.conn.cursor()
+        cursor.execute("INSERT OR REPLACE INTO config VALUES (?, ?)", ("token", token))
+        self.conn.commit()
+
+    def get_token(self) -> str | None:
+        cursor = self.conn.cursor()
+        cursor.execute("SELECT value FROM config WHERE key = ?", ("token",))
+        result = cursor.fetchone()
+        return result[0] if result else None
+
+    def unset_token(self) -> None:
+        cursor = self.conn.cursor()
+        cursor.execute("DELETE FROM config WHERE key = ?", ("token",))
+        self.conn.commit()
+
+    def add_query(self, query_id: str, name: str) -> None:
+        cursor = self.conn.cursor()
+        cursor.execute("INSERT OR REPLACE INTO queries (id, name) VALUES (?, ?)", (query_id, name))
+        self.conn.commit()
+
+    def remove_query(self, query_id: str) -> bool:
+        cursor = self.conn.cursor()
+        cursor.execute("DELETE FROM queries WHERE id = ?", (query_id,))
+        self.conn.commit()
+        return cursor.rowcount > 0
+
+    def rename_query(self, query_id: str, new_name: str) -> bool:
+        cursor = self.conn.cursor()
+        cursor.execute("UPDATE queries SET name = ? WHERE id = ?", (new_name, query_id))
+        self.conn.commit()
+        return cursor.rowcount > 0
+
+    def list_queries(self) -> list[tuple[str, str]]:
+        cursor = self.conn.cursor()
+        cursor.execute("SELECT id, name FROM queries ORDER BY added_on")
+        return cursor.fetchall()
+
+    def add_request(self, request_id: str, query_id: str) -> None:
+        cursor = self.conn.cursor()
+        cursor.execute(
+            "INSERT INTO requests (request_id, query_id, status, requested_at) VALUES (?, ?, ?, ?)",
+            (request_id, query_id, "pending", datetime.now().isoformat()),
+        )
+        self.conn.commit()
+
+    def update_request_status(self, request_id: str, status: str, output_path: str | None = None) -> None:
+        cursor = self.conn.cursor()
+        now = datetime.now().isoformat()
+
+        if status == "completed":
+            cursor.execute(
+                "UPDATE requests SET status = ?, completed_at = ?, output_path = ?, last_updated = ? WHERE request_id = ?",
+                (status, now, output_path, now, request_id),
+            )
+        else:
+            cursor.execute(
+                "UPDATE requests SET status = ?, last_updated = ? WHERE request_id = ?",
+                (status, now, request_id),
+            )
+        self.conn.commit()
+
+    def get_request_info(self, request_id: str) -> dict | None:
+        cursor = self.conn.cursor()
+        cursor.execute(
+            "SELECT request_id, query_id, status, requested_at, completed_at, output_path FROM requests WHERE request_id = ?",
+            (request_id,),
+        )
+        result = cursor.fetchone()
+        if not result:
+            return None
+
+        return {
+            "request_id": result[0],
+            "query_id": result[1],
+            "status": result[2],
+            "requested_at": result[3],
+            "completed_at": result[4],
+            "output_path": result[5],
+        }
+
+    def get_query_info(self, query_id: str) -> dict | None:
+        cursor = self.conn.cursor()
+        cursor.execute("SELECT id, name FROM queries WHERE id = ?", (query_id,))
+        result = cursor.fetchone()
+        if not result:
+            return None
+
+        return {"id": result[0], "name": result[1]}
+
+    def get_latest_request(self, query_id: str) -> dict | None:
+        cursor = self.conn.cursor()
+        cursor.execute(
+            "SELECT request_id FROM requests WHERE query_id = ? ORDER BY requested_at DESC LIMIT 1",
+            (query_id,),
+        )
+        result = cursor.fetchone()
+        if not result:
+            return None
+
+        return self.get_request_info(result[0])
+
+    def get_queries_not_updated(self, hours: int = 24) -> list[dict]:
+        """Get queries that haven't been updated in the specified hours."""
+        cursor = self.conn.cursor()
+        cutoff_time = (datetime.now() - timedelta(hours=hours)).isoformat()
+
+        # Get all queries
+        cursor.execute("SELECT id, name FROM queries")
+        all_queries = cursor.fetchall()
+
+        result = []
+        for query_id, name in all_queries:
+            # Check if this query has a successful request within the time period
+            cursor.execute(
+                """
+                SELECT r.request_id FROM requests r
+                WHERE r.query_id = ?
+                  AND r.status = 'completed'
+                  AND (r.last_updated > ? OR r.completed_at > ?)
+                ORDER BY r.last_updated DESC
+                LIMIT 1
+            """,
+                (query_id, cutoff_time, cutoff_time),
+            )
+
+            recent_request = cursor.fetchone()
+
+            if not recent_request:
+                # No recent successful request, include this query
+                result.append({"id": query_id, "name": name})
+
+        return result
+
+    def get_query_with_last_request(self, query_id: str) -> dict | None:
+        """Get query info along with its latest request."""
+        query_info = self.get_query_info(query_id)
+        if not query_info:
+            return None
+
+        latest_request = self.get_latest_request(query_id)
+        if latest_request:
+            query_info["latest_request"] = latest_request
+
+        return query_info
+
+    def get_all_queries_with_status(self) -> list[dict]:
+        """Get all queries with their latest request status."""
+        cursor = self.conn.cursor()
+        cursor.execute("SELECT id, name FROM queries ORDER BY added_on")
+        queries = cursor.fetchall()
+
+        result = []
+        for query_id, name in queries:
+            query_info = {"id": query_id, "name": name, "latest_request": None}
+
+            # Get latest request for this query
+            latest_request = self.get_latest_request(query_id)
+            if latest_request:
+                query_info["latest_request"] = latest_request
+
+            result.append(query_info)
+
+        return result
+
+    def close(self) -> None:
+        self.conn.close()