dceoy
1 line
39 KiB
JSON
1 line
39 KiB
JSON
{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"],"fields":{"title":{"boost":1000.0},"text":{"boost":1.0},"tags":{"boost":1000000.0}}},"docs":[{"location":"","title":"mt5cli","text":"<p>Command-line tool for MetaTrader 5 data export.</p>"},{"location":"#overview","title":"Overview","text":"<p>mt5cli is a CLI application that exports MetaTrader 5 trading data to multiple file formats. It is built on top of pdmt5, a pandas-based data handler for MetaTrader 5.</p>"},{"location":"#features","title":"Features","text":"<ul> <li>Multi-format export: CSV, JSON, Parquet, and SQLite3 output formats</li> <li>Auto-detection: Format detection from file extensions</li> <li>Comprehensive data access: Rates, ticks, account info, symbols, orders, positions, and trading history</li> <li>Flexible timeframes: Named timeframes (M1, H1, D1, etc.) and numeric values</li> <li>Connection management: Optional credentials, server, and timeout configuration</li> </ul>"},{"location":"#installation","title":"Installation","text":"<pre><code>pip install mt5cli\n</code></pre>"},{"location":"#quick-start","title":"Quick Start","text":"<pre><code># Export account information to CSV\nmt5cli -o account.csv account-info\n\n# Export EURUSD M1 rates to Parquet\nmt5cli -o rates.parquet rates-from --symbol EURUSD --timeframe M1 \\\n --date-from 2024-01-01 --count 1000\n\n# Export ticks to JSON\nmt5cli -o ticks.json ticks-from --symbol EURUSD \\\n --date-from 2024-01-01 --count 500 --flags ALL\n\n# Export symbols to SQLite3 with custom table name\nmt5cli -o data.db --table symbols symbols --group \"*USD*\"\n\n# Export with connection credentials\nmt5cli --login 12345 --password mypass --server MyBroker-Demo \\\n -o positions.csv positions\n</code></pre>"},{"location":"#commands","title":"Commands","text":""},{"location":"#rates","title":"Rates","text":"Command Description <code>rates-from</code> Export rates from a start date <code>rates-from-pos</code> Export rates from a start position <code>rates-range</code> Export rates for a date range"},{"location":"#ticks","title":"Ticks","text":"Command Description <code>ticks-from</code> Export ticks from a start date <code>ticks-range</code> Export ticks for a date range"},{"location":"#information","title":"Information","text":"Command Description <code>account-info</code> Export account information <code>terminal-info</code> Export terminal information <code>version</code> Export MetaTrader 5 version information <code>last-error</code> Export the last error information <code>symbols</code> Export symbol list <code>symbol-info</code> Export symbol details <code>symbol-info-tick</code> Export the last tick for a symbol <code>market-book</code> Export market depth (order book)"},{"location":"#trading","title":"Trading","text":"Command Description <code>orders</code> Export active orders <code>positions</code> Export open positions <code>history-orders</code> Export historical orders <code>history-deals</code> Export historical deals <code>order-check</code> Check funds sufficiency for a trade request <code>order-send</code> Send a trade request to the trade server (<code>--yes</code> required) <p>Use <code>order-check</code> to validate a request payload before running <code>order-send --yes</code>.</p>"},{"location":"#global-options","title":"Global Options","text":"Option Description <code>-o, --output</code> Output file path (required) <code>-f, --format</code> Output format (auto-detected from extension if omitted) <code>--table</code> Table name for SQLite3 output (default: \"data\") <code>--login</code> Trading account login <code>--password</code> Trading account password <code>--server</code> Trading server name <code>--path</code> Path to MetaTrader5 terminal EXE file <code>--timeout</code> Connection timeout in milliseconds <code>--log-level</code> Logging level (DEBUG, INFO, WARNING, ERROR)"},{"location":"#requirements","title":"Requirements","text":"<ul> <li>Python 3.11+</li> <li>Windows OS (MetaTrader 5 requirement)</li> <li>MetaTrader 5 platform</li> </ul>"},{"location":"#api-reference","title":"API Reference","text":"<p>Browse the API documentation for detailed module information:</p> <ul> <li>CLI Module - CLI application with export commands and utility functions</li> </ul>"},{"location":"#development","title":"Development","text":"<p>This project follows strict code quality standards:</p> <ul> <li>Type hints required (strict mode)</li> <li>Comprehensive linting with Ruff</li> <li>Test coverage tracking</li> <li>Google-style docstrings</li> </ul>"},{"location":"#license","title":"License","text":"<p>MIT License - see LICENSE file for details.</p>"},{"location":"api/","title":"API Reference","text":"<p>This section contains the complete API documentation for mt5cli.</p>"},{"location":"api/#modules","title":"Modules","text":"<p>The mt5cli package consists of the following modules:</p>"},{"location":"api/#cli","title":"CLI","text":"<p>Command-line interface module providing typer-based commands for exporting MetaTrader 5 data to CSV, JSON, Parquet, and SQLite3 formats.</p>"},{"location":"api/#architecture-overview","title":"Architecture Overview","text":"<p>The package follows a simple architecture built on top of pdmt5:</p> <ol> <li>CLI Layer (<code>cli.py</code>): Typer application with subcommands for each data type, custom Click parameter types for datetime/timeframe/tick flags parsing, and format detection/export utilities.</li> <li>Data Layer (via <code>pdmt5</code>): Uses <code>Mt5DataClient</code> and <code>Mt5Config</code> from the pdmt5 package for all MetaTrader 5 data access.</li> </ol>"},{"location":"api/#usage-guidelines","title":"Usage Guidelines","text":"<p>All modules follow these conventions:</p> <ul> <li>Type Safety: All functions include comprehensive type hints</li> <li>Error Handling: User-friendly error messages via typer</li> <li>Documentation: Google-style docstrings with examples</li> <li>Validation: Custom Click parameter types for input validation</li> </ul>"},{"location":"api/#quick-start","title":"Quick Start","text":"<pre><code># Export account information to CSV\nmt5cli -o account.csv account-info\n\n# Export EURUSD H1 rates to Parquet\nmt5cli -o rates.parquet rates-from --symbol EURUSD --timeframe H1 \\\n --date-from 2024-01-01 --count 1000\n\n# Export ticks to JSON\nmt5cli -o ticks.json ticks-from --symbol EURUSD \\\n --date-from 2024-01-01 --count 500 --flags ALL\n\n# Export to SQLite3 with custom table name\nmt5cli -o data.db --table symbols symbols --group \"*USD*\"\n</code></pre>"},{"location":"api/#python-api","title":"Python API","text":"<pre><code>from mt5cli import detect_format, export_dataframe\nimport pandas as pd\n\n# Detect output format from file extension\nfmt = detect_format(Path(\"output.parquet\")) # Returns \"parquet\"\n\n# Export a DataFrame\ndf = pd.DataFrame({\"symbol\": [\"EURUSD\"], \"bid\": [1.1234]})\nexport_dataframe(df, Path(\"output.csv\"), \"csv\")\n</code></pre>"},{"location":"api/#examples","title":"Examples","text":"<p>See individual module pages for detailed usage examples and code samples.</p>"},{"location":"api/cli/","title":"CLI Module","text":""},{"location":"api/cli/#mt5cli.cli","title":"mt5cli.cli","text":"<p>Command-line interface for MetaTrader 5 data export.</p>"},{"location":"api/cli/#mt5cli.cli.DATETIME_TYPE","title":"DATETIME_TYPE <code>module-attribute</code>","text":"<pre><code>DATETIME_TYPE = _DateTimeType()\n</code></pre>"},{"location":"api/cli/#mt5cli.cli.REQUEST_TYPE","title":"REQUEST_TYPE <code>module-attribute</code>","text":"<pre><code>REQUEST_TYPE = _RequestType()\n</code></pre>"},{"location":"api/cli/#mt5cli.cli.TICK_FLAGS_TYPE","title":"TICK_FLAGS_TYPE <code>module-attribute</code>","text":"<pre><code>TICK_FLAGS_TYPE = _TickFlagsType()\n</code></pre>"},{"location":"api/cli/#mt5cli.cli.TICK_FLAG_MAP","title":"TICK_FLAG_MAP <code>module-attribute</code>","text":"<pre><code>TICK_FLAG_MAP: dict[str, int] = {\n \"ALL\": 1,\n \"INFO\": 2,\n \"TRADE\": 4,\n}\n</code></pre>"},{"location":"api/cli/#mt5cli.cli.TIMEFRAME_MAP","title":"TIMEFRAME_MAP <code>module-attribute</code>","text":"<pre><code>TIMEFRAME_MAP: dict[str, int] = {\n \"M1\": 1,\n \"M2\": 2,\n \"M3\": 3,\n \"M4\": 4,\n \"M5\": 5,\n \"M6\": 6,\n \"M10\": 10,\n \"M12\": 12,\n \"M15\": 15,\n \"M20\": 20,\n \"M30\": 30,\n \"H1\": 16385,\n \"H2\": 16386,\n \"H3\": 16387,\n \"H4\": 16388,\n \"H6\": 16390,\n \"H8\": 16392,\n \"H12\": 16396,\n \"D1\": 16408,\n \"W1\": 32769,\n \"MN1\": 49153,\n}\n</code></pre>"},{"location":"api/cli/#mt5cli.cli.TIMEFRAME_TYPE","title":"TIMEFRAME_TYPE <code>module-attribute</code>","text":"<pre><code>TIMEFRAME_TYPE = _TimeframeType()\n</code></pre>"},{"location":"api/cli/#mt5cli.cli.app","title":"app <code>module-attribute</code>","text":"<pre><code>app = Typer(\n name=\"mt5cli\",\n help=\"Export MetaTrader5 data to CSV, JSON, Parquet, or SQLite3.\",\n)\n</code></pre>"},{"location":"api/cli/#mt5cli.cli.logger","title":"logger <code>module-attribute</code>","text":"<pre><code>logger = getLogger(__name__)\n</code></pre>"},{"location":"api/cli/#mt5cli.cli.LogLevel","title":"LogLevel","text":"<p> Bases: <code>StrEnum</code></p> <p>Logging verbosity levels.</p>"},{"location":"api/cli/#mt5cli.cli.LogLevel.DEBUG","title":"DEBUG <code>class-attribute</code> <code>instance-attribute</code>","text":"<pre><code>DEBUG = 'DEBUG'\n</code></pre>"},{"location":"api/cli/#mt5cli.cli.LogLevel.ERROR","title":"ERROR <code>class-attribute</code> <code>instance-attribute</code>","text":"<pre><code>ERROR = 'ERROR'\n</code></pre>"},{"location":"api/cli/#mt5cli.cli.LogLevel.INFO","title":"INFO <code>class-attribute</code> <code>instance-attribute</code>","text":"<pre><code>INFO = 'INFO'\n</code></pre>"},{"location":"api/cli/#mt5cli.cli.LogLevel.WARNING","title":"WARNING <code>class-attribute</code> <code>instance-attribute</code>","text":"<pre><code>WARNING = 'WARNING'\n</code></pre>"},{"location":"api/cli/#mt5cli.cli.OutputFormat","title":"OutputFormat","text":"<p> Bases: <code>StrEnum</code></p> <p>Supported output file formats.</p>"},{"location":"api/cli/#mt5cli.cli.OutputFormat.csv","title":"csv <code>class-attribute</code> <code>instance-attribute</code>","text":"<pre><code>csv = 'csv'\n</code></pre>"},{"location":"api/cli/#mt5cli.cli.OutputFormat.json","title":"json <code>class-attribute</code> <code>instance-attribute</code>","text":"<pre><code>json = 'json'\n</code></pre>"},{"location":"api/cli/#mt5cli.cli.OutputFormat.parquet","title":"parquet <code>class-attribute</code> <code>instance-attribute</code>","text":"<pre><code>parquet = 'parquet'\n</code></pre>"},{"location":"api/cli/#mt5cli.cli.OutputFormat.sqlite3","title":"sqlite3 <code>class-attribute</code> <code>instance-attribute</code>","text":"<pre><code>sqlite3 = 'sqlite3'\n</code></pre>"},{"location":"api/cli/#mt5cli.cli.account_info","title":"account_info","text":"<pre><code>account_info(ctx: Context) -> None\n</code></pre> <p>Export account information.</p> Source code in <code>mt5cli/cli.py</code> <pre><code>@app.command()\ndef account_info(ctx: typer.Context) -> None:\n \"\"\"Export account information.\"\"\"\n _execute_export(ctx, lambda c: c.account_info_as_df())\n</code></pre>"},{"location":"api/cli/#mt5cli.cli.detect_format","title":"detect_format","text":"<pre><code>detect_format(\n output_path: Path, explicit_format: str | None = None\n) -> str\n</code></pre> <p>Detect the output format from a file extension or explicit format string.</p> <p>Parameters:</p> Name Type Description Default <code>output_path</code> <code>Path</code> <p>Path to the output file.</p> required <code>explicit_format</code> <code>str | None</code> <p>Explicitly specified format, if any.</p> <code>None</code> <p>Returns:</p> Type Description <code>str</code> <p>The detected format string.</p> <p>Raises:</p> Type Description <code>ValueError</code> <p>If the format cannot be determined.</p> Source code in <code>mt5cli/cli.py</code> <pre><code>def detect_format(\n output_path: Path,\n explicit_format: str | None = None,\n) -> str:\n \"\"\"Detect the output format from a file extension or explicit format string.\n\n Args:\n output_path: Path to the output file.\n explicit_format: Explicitly specified format, if any.\n\n Returns:\n The detected format string.\n\n Raises:\n ValueError: If the format cannot be determined.\n \"\"\"\n if explicit_format is not None:\n return explicit_format\n suffix = output_path.suffix.lower()\n if suffix in _FORMAT_EXTENSIONS:\n return _FORMAT_EXTENSIONS[suffix]\n msg = (\n f\"Cannot detect format from extension '{suffix}'.\"\n \" Use --format to specify the output format.\"\n )\n raise ValueError(msg)\n</code></pre>"},{"location":"api/cli/#mt5cli.cli.export_dataframe","title":"export_dataframe","text":"<pre><code>export_dataframe(\n df: DataFrame,\n output_path: Path,\n output_format: str,\n table_name: str = \"data\",\n) -> None\n</code></pre> <p>Export a pandas DataFrame to the specified file format.</p> <p>Parameters:</p> Name Type Description Default <code>df</code> <code>DataFrame</code> <p>DataFrame to export.</p> required <code>output_path</code> <code>Path</code> <p>Path to the output file.</p> required <code>output_format</code> <code>str</code> <p>Output format (csv, json, parquet, or sqlite3).</p> required <code>table_name</code> <code>str</code> <p>Table name for SQLite3 output.</p> <code>'data'</code> <p>Raises:</p> Type Description <code>ValueError</code> <p>If the output format is not supported.</p> Source code in <code>mt5cli/cli.py</code> <pre><code>def export_dataframe(\n df: pd.DataFrame,\n output_path: Path,\n output_format: str,\n table_name: str = \"data\",\n) -> None:\n \"\"\"Export a pandas DataFrame to the specified file format.\n\n Args:\n df: DataFrame to export.\n output_path: Path to the output file.\n output_format: Output format (csv, json, parquet, or sqlite3).\n table_name: Table name for SQLite3 output.\n\n Raises:\n ValueError: If the output format is not supported.\n \"\"\"\n if output_format == \"csv\":\n df.to_csv(output_path, index=False)\n elif output_format == \"json\":\n df.to_json(\n output_path,\n orient=\"records\",\n date_format=\"iso\",\n indent=2,\n )\n elif output_format == \"parquet\":\n df.to_parquet(output_path, index=False)\n elif output_format == \"sqlite3\":\n with sqlite3.connect(output_path) as conn:\n df.to_sql( # type: ignore[reportUnknownMemberType]\n table_name,\n conn,\n if_exists=\"replace\",\n index=False,\n )\n else:\n msg = f\"Unsupported output format: {output_format}\"\n raise ValueError(msg)\n</code></pre>"},{"location":"api/cli/#mt5cli.cli.history_deals","title":"history_deals","text":"<pre><code>history_deals(\n ctx: Context,\n date_from: Annotated[\n datetime | None,\n Option(\n click_type=DATETIME_TYPE, help=\"Start date.\"\n ),\n ] = None,\n date_to: Annotated[\n datetime | None,\n Option(click_type=DATETIME_TYPE, help=\"End date.\"),\n ] = None,\n group: Annotated[\n str | None, Option(help=\"Group filter.\")\n ] = None,\n symbol: Annotated[\n str | None, Option(help=\"Symbol filter.\")\n ] = None,\n ticket: Annotated[\n int | None, Option(help=\"Order ticket.\")\n ] = None,\n position: Annotated[\n int | None, Option(help=\"Position ticket.\")\n ] = None,\n) -> None\n</code></pre> <p>Export historical deals.</p> Source code in <code>mt5cli/cli.py</code> <pre><code>@app.command()\ndef history_deals(\n ctx: typer.Context,\n date_from: Annotated[\n datetime | None,\n typer.Option(click_type=DATETIME_TYPE, help=\"Start date.\"),\n ] = None,\n date_to: Annotated[\n datetime | None,\n typer.Option(click_type=DATETIME_TYPE, help=\"End date.\"),\n ] = None,\n group: Annotated[str | None, typer.Option(help=\"Group filter.\")] = None,\n symbol: Annotated[str | None, typer.Option(help=\"Symbol filter.\")] = None,\n ticket: Annotated[int | None, typer.Option(help=\"Order ticket.\")] = None,\n position: Annotated[int | None, typer.Option(help=\"Position ticket.\")] = None,\n) -> None:\n \"\"\"Export historical deals.\"\"\"\n _execute_export(\n ctx,\n lambda c: c.history_deals_get_as_df(\n date_from=date_from,\n date_to=date_to,\n group=group,\n symbol=symbol,\n ticket=ticket,\n position=position,\n ),\n )\n</code></pre>"},{"location":"api/cli/#mt5cli.cli.history_orders","title":"history_orders","text":"<pre><code>history_orders(\n ctx: Context,\n date_from: Annotated[\n datetime | None,\n Option(\n click_type=DATETIME_TYPE, help=\"Start date.\"\n ),\n ] = None,\n date_to: Annotated[\n datetime | None,\n Option(click_type=DATETIME_TYPE, help=\"End date.\"),\n ] = None,\n group: Annotated[\n str | None, Option(help=\"Group filter.\")\n ] = None,\n symbol: Annotated[\n str | None, Option(help=\"Symbol filter.\")\n ] = None,\n ticket: Annotated[\n int | None, Option(help=\"Order ticket.\")\n ] = None,\n position: Annotated[\n int | None, Option(help=\"Position ticket.\")\n ] = None,\n) -> None\n</code></pre> <p>Export historical orders.</p> Source code in <code>mt5cli/cli.py</code> <pre><code>@app.command()\ndef history_orders(\n ctx: typer.Context,\n date_from: Annotated[\n datetime | None,\n typer.Option(click_type=DATETIME_TYPE, help=\"Start date.\"),\n ] = None,\n date_to: Annotated[\n datetime | None,\n typer.Option(click_type=DATETIME_TYPE, help=\"End date.\"),\n ] = None,\n group: Annotated[str | None, typer.Option(help=\"Group filter.\")] = None,\n symbol: Annotated[str | None, typer.Option(help=\"Symbol filter.\")] = None,\n ticket: Annotated[int | None, typer.Option(help=\"Order ticket.\")] = None,\n position: Annotated[int | None, typer.Option(help=\"Position ticket.\")] = None,\n) -> None:\n \"\"\"Export historical orders.\"\"\"\n _execute_export(\n ctx,\n lambda c: c.history_orders_get_as_df(\n date_from=date_from,\n date_to=date_to,\n group=group,\n symbol=symbol,\n ticket=ticket,\n position=position,\n ),\n )\n</code></pre>"},{"location":"api/cli/#mt5cli.cli.last_error","title":"last_error","text":"<pre><code>last_error(ctx: Context) -> None\n</code></pre> <p>Export the last error information.</p> Source code in <code>mt5cli/cli.py</code> <pre><code>@app.command()\ndef last_error(ctx: typer.Context) -> None:\n \"\"\"Export the last error information.\"\"\"\n _execute_export(ctx, lambda c: c.last_error_as_df())\n</code></pre>"},{"location":"api/cli/#mt5cli.cli.main","title":"main","text":"<pre><code>main() -> None\n</code></pre> <p>Run the mt5cli CLI.</p> Source code in <code>mt5cli/cli.py</code> <pre><code>def main() -> None:\n \"\"\"Run the mt5cli CLI.\"\"\"\n app()\n</code></pre>"},{"location":"api/cli/#mt5cli.cli.market_book","title":"market_book","text":"<pre><code>market_book(\n ctx: Context,\n symbol: Annotated[str, Option(help=\"Symbol name.\")],\n) -> None\n</code></pre> <p>Export market depth (order book) for a symbol.</p> Source code in <code>mt5cli/cli.py</code> <pre><code>@app.command()\ndef market_book(\n ctx: typer.Context,\n symbol: Annotated[str, typer.Option(help=\"Symbol name.\")],\n) -> None:\n \"\"\"Export market depth (order book) for a symbol.\"\"\"\n _execute_export(\n ctx,\n lambda c: c.market_book_get_as_df(symbol=symbol),\n )\n</code></pre>"},{"location":"api/cli/#mt5cli.cli.order_check","title":"order_check","text":"<pre><code>order_check(\n ctx: Context,\n request: Annotated[\n dict[str, Any],\n Option(\n click_type=REQUEST_TYPE,\n help=_REQUEST_OPTION_HELP,\n ),\n ],\n) -> None\n</code></pre> <p>Check funds sufficiency for a trading operation.</p> Source code in <code>mt5cli/cli.py</code> <pre><code>@app.command()\ndef order_check(\n ctx: typer.Context,\n request: Annotated[\n dict[str, Any],\n typer.Option(click_type=REQUEST_TYPE, help=_REQUEST_OPTION_HELP),\n ],\n) -> None:\n \"\"\"Check funds sufficiency for a trading operation.\"\"\"\n _execute_export(\n ctx,\n lambda c: c.order_check_as_df(request=request),\n )\n</code></pre>"},{"location":"api/cli/#mt5cli.cli.order_send","title":"order_send","text":"<pre><code>order_send(\n ctx: Context,\n request: Annotated[\n dict[str, Any],\n Option(\n click_type=REQUEST_TYPE,\n help=_REQUEST_OPTION_HELP,\n ),\n ],\n yes: Annotated[\n bool,\n Option(\n \"--yes\", help=\"Confirm the live trade request.\"\n ),\n ] = False,\n) -> None\n</code></pre> <p>Send a trading operation request to the trade server.</p> <p>Raises:</p> Type Description <code>BadParameter</code> <p>If --yes is not provided.</p> Source code in <code>mt5cli/cli.py</code> <pre><code>@app.command()\ndef order_send(\n ctx: typer.Context,\n request: Annotated[\n dict[str, Any],\n typer.Option(click_type=REQUEST_TYPE, help=_REQUEST_OPTION_HELP),\n ],\n yes: Annotated[\n bool,\n typer.Option(\"--yes\", help=\"Confirm the live trade request.\"),\n ] = False,\n) -> None:\n \"\"\"Send a trading operation request to the trade server.\n\n Raises:\n typer.BadParameter: If --yes is not provided.\n \"\"\"\n if not yes:\n msg = \"Pass --yes to send a live trade request.\"\n raise typer.BadParameter(msg, param_hint=\"--yes\")\n _execute_export(\n ctx,\n lambda c: c.order_send_as_df(request=request),\n )\n</code></pre>"},{"location":"api/cli/#mt5cli.cli.orders","title":"orders","text":"<pre><code>orders(\n ctx: Context,\n symbol: Annotated[\n str | None, Option(help=\"Symbol filter.\")\n ] = None,\n group: Annotated[\n str | None, Option(help=\"Group filter.\")\n ] = None,\n ticket: Annotated[\n int | None, Option(help=\"Ticket filter.\")\n ] = None,\n) -> None\n</code></pre> <p>Export active orders.</p> Source code in <code>mt5cli/cli.py</code> <pre><code>@app.command()\ndef orders(\n ctx: typer.Context,\n symbol: Annotated[str | None, typer.Option(help=\"Symbol filter.\")] = None,\n group: Annotated[str | None, typer.Option(help=\"Group filter.\")] = None,\n ticket: Annotated[int | None, typer.Option(help=\"Ticket filter.\")] = None,\n) -> None:\n \"\"\"Export active orders.\"\"\"\n _execute_export(\n ctx,\n lambda c: c.orders_get_as_df(\n symbol=symbol,\n group=group,\n ticket=ticket,\n ),\n )\n</code></pre>"},{"location":"api/cli/#mt5cli.cli.parse_datetime","title":"parse_datetime","text":"<pre><code>parse_datetime(value: str) -> datetime\n</code></pre> <p>Parse an ISO 8601 datetime string to a timezone-aware datetime.</p> <p>Parameters:</p> Name Type Description Default <code>value</code> <code>str</code> <p>ISO 8601 datetime string (e.g., '2024-01-01' or '2024-01-01T12:00:00+00:00').</p> required <p>Returns:</p> Type Description <code>datetime</code> <p>Parsed datetime with UTC timezone if no timezone is specified.</p> <p>Raises:</p> Type Description <code>ValueError</code> <p>If the string cannot be parsed.</p> Source code in <code>mt5cli/cli.py</code> <pre><code>def parse_datetime(value: str) -> datetime:\n \"\"\"Parse an ISO 8601 datetime string to a timezone-aware datetime.\n\n Args:\n value: ISO 8601 datetime string (e.g., '2024-01-01' or\n '2024-01-01T12:00:00+00:00').\n\n Returns:\n Parsed datetime with UTC timezone if no timezone is specified.\n\n Raises:\n ValueError: If the string cannot be parsed.\n \"\"\"\n try:\n dt = datetime.fromisoformat(value)\n except ValueError:\n msg = f\"Invalid datetime format: '{value}'. Use ISO 8601 format.\"\n raise ValueError(msg) from None\n if dt.tzinfo is None:\n dt = dt.replace(tzinfo=UTC)\n return dt\n</code></pre>"},{"location":"api/cli/#mt5cli.cli.parse_request","title":"parse_request","text":"<pre><code>parse_request(value: str) -> dict[str, Any]\n</code></pre> <p>Parse a JSON-formatted order request string or file reference.</p> <p>Parameters:</p> Name Type Description Default <code>value</code> <code>str</code> <p>JSON object string, or '@path' to read JSON from a file.</p> required <p>Returns:</p> Type Description <code>dict[str, Any]</code> <p>Parsed request dictionary.</p> <p>Raises:</p> Type Description <code>ValueError</code> <p>If the request file cannot be read or the value is not a JSON object.</p> Source code in <code>mt5cli/cli.py</code> <pre><code>def parse_request(value: str) -> dict[str, Any]:\n \"\"\"Parse a JSON-formatted order request string or file reference.\n\n Args:\n value: JSON object string, or '@path' to read JSON from a file.\n\n Returns:\n Parsed request dictionary.\n\n Raises:\n ValueError: If the request file cannot be read or the value is not a\n JSON object.\n \"\"\"\n if value.startswith(\"@\"):\n path = Path(value[1:])\n try:\n text = path.read_text(encoding=\"utf-8\")\n except (OSError, UnicodeDecodeError) as exc:\n msg = f\"Failed to read JSON request file '{path}': {exc}\"\n raise ValueError(msg) from exc\n else:\n text = value\n try:\n parsed: object = json.loads(text)\n except json.JSONDecodeError as exc:\n msg = f\"Invalid JSON request: {exc}\"\n raise ValueError(msg) from exc\n if not _is_request_dict(parsed):\n msg = \"Order request must be a JSON object.\"\n raise ValueError(msg)\n return parsed\n</code></pre>"},{"location":"api/cli/#mt5cli.cli.parse_tick_flags","title":"parse_tick_flags","text":"<pre><code>parse_tick_flags(value: str) -> int\n</code></pre> <p>Parse tick flags string or integer value.</p> <p>Parameters:</p> Name Type Description Default <code>value</code> <code>str</code> <p>Tick flag name (ALL, INFO, TRADE) or integer value.</p> required <p>Returns:</p> Type Description <code>int</code> <p>Integer tick flag value.</p> <p>Raises:</p> Type Description <code>ValueError</code> <p>If the flag is invalid.</p> Source code in <code>mt5cli/cli.py</code> <pre><code>def parse_tick_flags(value: str) -> int:\n \"\"\"Parse tick flags string or integer value.\n\n Args:\n value: Tick flag name (ALL, INFO, TRADE) or integer value.\n\n Returns:\n Integer tick flag value.\n\n Raises:\n ValueError: If the flag is invalid.\n \"\"\"\n upper = value.upper()\n if upper in TICK_FLAG_MAP:\n return TICK_FLAG_MAP[upper]\n try:\n return int(value)\n except ValueError:\n valid = \", \".join(TICK_FLAG_MAP)\n msg = f\"Invalid tick flags: '{value}'. Use one of: {valid}, or an integer.\"\n raise ValueError(msg) from None\n</code></pre>"},{"location":"api/cli/#mt5cli.cli.parse_timeframe","title":"parse_timeframe","text":"<pre><code>parse_timeframe(value: str) -> int\n</code></pre> <p>Parse a timeframe string or integer value.</p> <p>Parameters:</p> Name Type Description Default <code>value</code> <code>str</code> <p>Timeframe name (e.g., 'M1', 'H1', 'D1') or integer value.</p> required <p>Returns:</p> Type Description <code>int</code> <p>Integer timeframe value.</p> <p>Raises:</p> Type Description <code>ValueError</code> <p>If the timeframe is invalid.</p> Source code in <code>mt5cli/cli.py</code> <pre><code>def parse_timeframe(value: str) -> int:\n \"\"\"Parse a timeframe string or integer value.\n\n Args:\n value: Timeframe name (e.g., 'M1', 'H1', 'D1') or integer value.\n\n Returns:\n Integer timeframe value.\n\n Raises:\n ValueError: If the timeframe is invalid.\n \"\"\"\n upper = value.upper()\n if upper in TIMEFRAME_MAP:\n return TIMEFRAME_MAP[upper]\n try:\n return int(value)\n except ValueError:\n valid = \", \".join(TIMEFRAME_MAP)\n msg = f\"Invalid timeframe: '{value}'. Use one of: {valid}, or an integer.\"\n raise ValueError(msg) from None\n</code></pre>"},{"location":"api/cli/#mt5cli.cli.positions","title":"positions","text":"<pre><code>positions(\n ctx: Context,\n symbol: Annotated[\n str | None, Option(help=\"Symbol filter.\")\n ] = None,\n group: Annotated[\n str | None, Option(help=\"Group filter.\")\n ] = None,\n ticket: Annotated[\n int | None, Option(help=\"Ticket filter.\")\n ] = None,\n) -> None\n</code></pre> <p>Export open positions.</p> Source code in <code>mt5cli/cli.py</code> <pre><code>@app.command()\ndef positions(\n ctx: typer.Context,\n symbol: Annotated[str | None, typer.Option(help=\"Symbol filter.\")] = None,\n group: Annotated[str | None, typer.Option(help=\"Group filter.\")] = None,\n ticket: Annotated[int | None, typer.Option(help=\"Ticket filter.\")] = None,\n) -> None:\n \"\"\"Export open positions.\"\"\"\n _execute_export(\n ctx,\n lambda c: c.positions_get_as_df(\n symbol=symbol,\n group=group,\n ticket=ticket,\n ),\n )\n</code></pre>"},{"location":"api/cli/#mt5cli.cli.rates_from","title":"rates_from","text":"<pre><code>rates_from(\n ctx: Context,\n symbol: Annotated[str, Option(help=\"Symbol name.\")],\n timeframe: Annotated[\n int,\n Option(\n click_type=TIMEFRAME_TYPE,\n help=\"Timeframe (e.g., M1, H1, D1, or integer).\",\n ),\n ],\n date_from: Annotated[\n datetime,\n Option(\n click_type=DATETIME_TYPE,\n help=\"Start date in ISO 8601 format.\",\n ),\n ],\n count: Annotated[\n int, Option(help=\"Number of records.\")\n ],\n) -> None\n</code></pre> <p>Export rates from a start date.</p> Source code in <code>mt5cli/cli.py</code> <pre><code>@app.command()\ndef rates_from(\n ctx: typer.Context,\n symbol: Annotated[str, typer.Option(help=\"Symbol name.\")],\n timeframe: Annotated[\n int,\n typer.Option(\n click_type=TIMEFRAME_TYPE,\n help=\"Timeframe (e.g., M1, H1, D1, or integer).\",\n ),\n ],\n date_from: Annotated[\n datetime,\n typer.Option(\n click_type=DATETIME_TYPE,\n help=\"Start date in ISO 8601 format.\",\n ),\n ],\n count: Annotated[int, typer.Option(help=\"Number of records.\")],\n) -> None:\n \"\"\"Export rates from a start date.\"\"\"\n _execute_export(\n ctx,\n lambda c: c.copy_rates_from_as_df(\n symbol=symbol,\n timeframe=timeframe,\n date_from=date_from,\n count=count,\n ),\n )\n</code></pre>"},{"location":"api/cli/#mt5cli.cli.rates_from_pos","title":"rates_from_pos","text":"<pre><code>rates_from_pos(\n ctx: Context,\n symbol: Annotated[str, Option(help=\"Symbol name.\")],\n timeframe: Annotated[\n int,\n Option(\n click_type=TIMEFRAME_TYPE, help=\"Timeframe.\"\n ),\n ],\n start_pos: Annotated[\n int,\n Option(help=\"Start position (0 = current bar).\"),\n ],\n count: Annotated[\n int, Option(help=\"Number of records.\")\n ],\n) -> None\n</code></pre> <p>Export rates from a start position.</p> Source code in <code>mt5cli/cli.py</code> <pre><code>@app.command()\ndef rates_from_pos(\n ctx: typer.Context,\n symbol: Annotated[str, typer.Option(help=\"Symbol name.\")],\n timeframe: Annotated[\n int,\n typer.Option(\n click_type=TIMEFRAME_TYPE,\n help=\"Timeframe.\",\n ),\n ],\n start_pos: Annotated[int, typer.Option(help=\"Start position (0 = current bar).\")],\n count: Annotated[int, typer.Option(help=\"Number of records.\")],\n) -> None:\n \"\"\"Export rates from a start position.\"\"\"\n _execute_export(\n ctx,\n lambda c: c.copy_rates_from_pos_as_df(\n symbol=symbol,\n timeframe=timeframe,\n start_pos=start_pos,\n count=count,\n ),\n )\n</code></pre>"},{"location":"api/cli/#mt5cli.cli.rates_range","title":"rates_range","text":"<pre><code>rates_range(\n ctx: Context,\n symbol: Annotated[str, Option(help=\"Symbol name.\")],\n timeframe: Annotated[\n int,\n Option(\n click_type=TIMEFRAME_TYPE, help=\"Timeframe.\"\n ),\n ],\n date_from: Annotated[\n datetime,\n Option(\n click_type=DATETIME_TYPE, help=\"Start date.\"\n ),\n ],\n date_to: Annotated[\n datetime,\n Option(click_type=DATETIME_TYPE, help=\"End date.\"),\n ],\n) -> None\n</code></pre> <p>Export rates for a date range.</p> Source code in <code>mt5cli/cli.py</code> <pre><code>@app.command()\ndef rates_range(\n ctx: typer.Context,\n symbol: Annotated[str, typer.Option(help=\"Symbol name.\")],\n timeframe: Annotated[\n int,\n typer.Option(\n click_type=TIMEFRAME_TYPE,\n help=\"Timeframe.\",\n ),\n ],\n date_from: Annotated[\n datetime,\n typer.Option(click_type=DATETIME_TYPE, help=\"Start date.\"),\n ],\n date_to: Annotated[\n datetime,\n typer.Option(click_type=DATETIME_TYPE, help=\"End date.\"),\n ],\n) -> None:\n \"\"\"Export rates for a date range.\"\"\"\n _execute_export(\n ctx,\n lambda c: c.copy_rates_range_as_df(\n symbol=symbol,\n timeframe=timeframe,\n date_from=date_from,\n date_to=date_to,\n ),\n )\n</code></pre>"},{"location":"api/cli/#mt5cli.cli.symbol_info","title":"symbol_info","text":"<pre><code>symbol_info(\n ctx: Context,\n symbol: Annotated[str, Option(help=\"Symbol name.\")],\n) -> None\n</code></pre> <p>Export symbol details.</p> Source code in <code>mt5cli/cli.py</code> <pre><code>@app.command()\ndef symbol_info(\n ctx: typer.Context,\n symbol: Annotated[str, typer.Option(help=\"Symbol name.\")],\n) -> None:\n \"\"\"Export symbol details.\"\"\"\n _execute_export(\n ctx,\n lambda c: c.symbol_info_as_df(symbol=symbol),\n )\n</code></pre>"},{"location":"api/cli/#mt5cli.cli.symbol_info_tick","title":"symbol_info_tick","text":"<pre><code>symbol_info_tick(\n ctx: Context,\n symbol: Annotated[str, Option(help=\"Symbol name.\")],\n) -> None\n</code></pre> <p>Export the last tick for a symbol.</p> Source code in <code>mt5cli/cli.py</code> <pre><code>@app.command()\ndef symbol_info_tick(\n ctx: typer.Context,\n symbol: Annotated[str, typer.Option(help=\"Symbol name.\")],\n) -> None:\n \"\"\"Export the last tick for a symbol.\"\"\"\n _execute_export(\n ctx,\n lambda c: c.symbol_info_tick_as_df(symbol=symbol),\n )\n</code></pre>"},{"location":"api/cli/#mt5cli.cli.symbols","title":"symbols","text":"<pre><code>symbols(\n ctx: Context,\n group: Annotated[\n str | None,\n Option(help=\"Symbol group filter (e.g., *USD*).\"),\n ] = None,\n) -> None\n</code></pre> <p>Export symbol list.</p> Source code in <code>mt5cli/cli.py</code> <pre><code>@app.command()\ndef symbols(\n ctx: typer.Context,\n group: Annotated[\n str | None,\n typer.Option(help=\"Symbol group filter (e.g., *USD*).\"),\n ] = None,\n) -> None:\n \"\"\"Export symbol list.\"\"\"\n _execute_export(\n ctx,\n lambda c: c.symbols_get_as_df(group=group),\n )\n</code></pre>"},{"location":"api/cli/#mt5cli.cli.terminal_info","title":"terminal_info","text":"<pre><code>terminal_info(ctx: Context) -> None\n</code></pre> <p>Export terminal information.</p> Source code in <code>mt5cli/cli.py</code> <pre><code>@app.command()\ndef terminal_info(ctx: typer.Context) -> None:\n \"\"\"Export terminal information.\"\"\"\n _execute_export(ctx, lambda c: c.terminal_info_as_df())\n</code></pre>"},{"location":"api/cli/#mt5cli.cli.ticks_from","title":"ticks_from","text":"<pre><code>ticks_from(\n ctx: Context,\n symbol: Annotated[str, Option(help=\"Symbol name.\")],\n date_from: Annotated[\n datetime,\n Option(\n click_type=DATETIME_TYPE, help=\"Start date.\"\n ),\n ],\n count: Annotated[int, Option(help=\"Number of ticks.\")],\n flags: Annotated[\n int,\n Option(\n click_type=TICK_FLAGS_TYPE,\n help=\"Tick flags (ALL, INFO, TRADE, or integer).\",\n ),\n ],\n) -> None\n</code></pre> <p>Export ticks from a start date.</p> Source code in <code>mt5cli/cli.py</code> <pre><code>@app.command()\ndef ticks_from(\n ctx: typer.Context,\n symbol: Annotated[str, typer.Option(help=\"Symbol name.\")],\n date_from: Annotated[\n datetime,\n typer.Option(click_type=DATETIME_TYPE, help=\"Start date.\"),\n ],\n count: Annotated[int, typer.Option(help=\"Number of ticks.\")],\n flags: Annotated[\n int,\n typer.Option(\n click_type=TICK_FLAGS_TYPE,\n help=\"Tick flags (ALL, INFO, TRADE, or integer).\",\n ),\n ],\n) -> None:\n \"\"\"Export ticks from a start date.\"\"\"\n _execute_export(\n ctx,\n lambda c: c.copy_ticks_from_as_df(\n symbol=symbol,\n date_from=date_from,\n count=count,\n flags=flags,\n ),\n )\n</code></pre>"},{"location":"api/cli/#mt5cli.cli.ticks_range","title":"ticks_range","text":"<pre><code>ticks_range(\n ctx: Context,\n symbol: Annotated[str, Option(help=\"Symbol name.\")],\n date_from: Annotated[\n datetime,\n Option(\n click_type=DATETIME_TYPE, help=\"Start date.\"\n ),\n ],\n date_to: Annotated[\n datetime,\n Option(click_type=DATETIME_TYPE, help=\"End date.\"),\n ],\n flags: Annotated[\n int,\n Option(\n click_type=TICK_FLAGS_TYPE, help=\"Tick flags.\"\n ),\n ],\n) -> None\n</code></pre> <p>Export ticks for a date range.</p> Source code in <code>mt5cli/cli.py</code> <pre><code>@app.command()\ndef ticks_range(\n ctx: typer.Context,\n symbol: Annotated[str, typer.Option(help=\"Symbol name.\")],\n date_from: Annotated[\n datetime,\n typer.Option(click_type=DATETIME_TYPE, help=\"Start date.\"),\n ],\n date_to: Annotated[\n datetime,\n typer.Option(click_type=DATETIME_TYPE, help=\"End date.\"),\n ],\n flags: Annotated[\n int,\n typer.Option(click_type=TICK_FLAGS_TYPE, help=\"Tick flags.\"),\n ],\n) -> None:\n \"\"\"Export ticks for a date range.\"\"\"\n _execute_export(\n ctx,\n lambda c: c.copy_ticks_range_as_df(\n symbol=symbol,\n date_from=date_from,\n date_to=date_to,\n flags=flags,\n ),\n )\n</code></pre>"},{"location":"api/cli/#mt5cli.cli.version","title":"version","text":"<pre><code>version(ctx: Context) -> None\n</code></pre> <p>Export MetaTrader5 version information.</p> Source code in <code>mt5cli/cli.py</code> <pre><code>@app.command()\ndef version(ctx: typer.Context) -> None:\n \"\"\"Export MetaTrader5 version information.\"\"\"\n _execute_export(ctx, lambda c: c.version_as_df())\n</code></pre>"}]} |