Core¶

Result[T], errors, and execution primitives.

Result[T]¶

Result¶

Result ¶

Bases: BaseModel, Generic[T]

Typed outcome of an SDK operation.

A Result is either successful (success=True, data is set) or failed (success=False, error_code and error_message are set). The model validator enforces this invariant at construction time so an invalid state is impossible to construct.

ATTRIBUTE	DESCRIPTION
`success`	`True` if the operation completed without error. TYPE: `bool`
`data`	The operation's return value. Always `None` on failure. TYPE: `T \| None`
`error_code`	MT5 error code on failure; `None` on success. TYPE: `int \| None`
`error_message`	Human-readable error description; `None` on success. TYPE: `str \| None`
`context`	The MT5 API function name that was called (e.g. `"positions_get"`). TYPE: `str \| None`
`operation`	Logical operation name, usually the same as `context`. TYPE: `str \| None`

ok `classmethod` ¶

ok(
    data: T,
    context: str | None = None,
    operation: str | None = None,
) -> Result[T]

Construct a successful result.

PARAMETER	DESCRIPTION
`data`	The value to carry. May be `None` for void operations. TYPE: `T`
`context`	MT5 API function name for tracing. TYPE: `str \| None` DEFAULT: `None`
`operation`	Logical operation name for tracing. TYPE: `str \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`Result[T]`	A `Result` with `success=True` and `data` set.

fail `classmethod` ¶

fail(
    error: MT5ErrorInfo,
    context: str,
    operation: str | None = None,
) -> Result[T]

Construct a failed result from an MT5ErrorInfo.

PARAMETER	DESCRIPTION
`error`	The error captured from `mt5.last_error()` or an SDK-internal sentinel. TYPE: `MT5ErrorInfo`
`context`	MT5 API function name where the failure occurred. TYPE: `str`
`operation`	Logical operation name for tracing. TYPE: `str \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`Result[T]`	A `Result` with `success=False`, `data=None`, and the
`Result[T]`	error fields populated from `error`.

Errors¶

MT5Error¶

MT5Error ¶

Bases: Exception

Base exception for all SDK-level errors.

MT5ConnectionError¶

MT5ConnectionError ¶

Bases: MT5Error

Raised when a connection lifecycle operation fails unrecoverably.

MT5ExecutionError¶

MT5ExecutionError ¶

Bases: MT5Error

Raised when a data retrieval or trade execution fails unrecoverably.

MT5ErrorInfo¶

MT5ErrorInfo ¶

Bases: BaseModel

Structured representation of an MT5 error.

Produced by mt5.last_error() after every MT5 API call and carried inside Result objects so callers can inspect failure details without catching exceptions.

ATTRIBUTE	DESCRIPTION
`code`	MT5 error code (0 means no error; negative codes are SDK-internal). TYPE: `int`
`message`	Human-readable description of the error. TYPE: `str`

Usage¶

Every operation returns Result[T]:

res = mt5.positions()

if res.success:
    # Success path
    for p in res.data:
        print(p.symbol)
else:
    # Failure path
    print(f"Operation: {res.operation}")
    print(f"Error code: {res.error_code}")
    print(f"Message: {res.error_message}")

Exceptions are reserved for unrecoverable situations (e.g., during object construction). You will not encounter them in normal usage.