⚙️ examples/common/env.py
¶
Helpers for loading environment, auto‑patching protobuf shims, and creating a ready‑to‑use MT5 account (with graceful shutdown). No code changes required in your examples — just await connect()
/ await shutdown(acc)
🧭 What this module does¶
- Applies pb2 shim on import (
pb2_shim.apply_patch()
), so you can import enums/messages fromMetaRpcMT5.*
consistently. - Loads environment via
python-dotenv
if available (.env
is optional). - Picks the best adapter: prefers
MetaRpcMT5Ex.MT5AccountEx
, falls back toMetaRpcMT5.mt5_account.MT5Account
. -
Connects with retries: tries
-
connect_by_server_name(server_name, …)
connect_by_host_port(host, port, …)
connect(host=…, port=…, timeout_seconds=…)
(ordeadline
variant)- Shuts down nicely: attempts
disconnect()
→close()
→shutdown()
(awaits if coroutine).
🔌 Public API¶
async def connect() -> MT5Account:
"""Returns a connected MT5 account using env vars and small backoff between retries."""
async def shutdown(acc) -> None:
"""Best‑effort graceful disconnect. Safe to call multiple times; ignores errors."""
🌍 Environment variables¶
These are read at import / connect time (with defaults where noted):
# credentials & routing
MT5_LOGIN=12345678
MT5_PASSWORD=secret
MT5_SERVER=MetaQuotes-Demo
GRPC_SERVER=mt5.mrpc.pro:443
# connection behavior
TIMEOUT_SECONDS=90
CONNECT_RETRIES=3
# app behavior
MT5_ENABLE_TRADING=0 # 1 = allow trading examples
MT5_SYMBOL=EURUSD # default symbol
MT5_VOLUME=0.10 # default lot size
Tip: If
.env
exists, it will be auto‑loaded bypython-dotenv
(if installed). Otherwise use your shell to export variables.
🧪 Minimal usage example¶
# comments intentionally in English
import asyncio
from examples.common.env import connect, shutdown
async def main():
acc = await connect()
try:
print("[OK] connected as:", getattr(acc, "user", None))
# ... do your calls here ...
finally:
await shutdown(acc)
print("[OK] shutdown")
if __name__ == "__main__":
asyncio.run(main())
🧯 Troubleshooting¶
- Wrong creds / server → adapter raises on
connect_*
; checkMT5_LOGIN/MT5_PASSWORD/MT5_SERVER
. - gRPC unreachable → verify
GRPC_SERVER
(host:port), firewall/VPN, and rundiag_connect.py
first. - Timeouts → increase
TIMEOUT_SECONDS
orCONNECT_RETRIES
. - Trading examples skip actions → you likely have
MT5_ENABLE_TRADING=0
.
Adapter preference¶
try:
from MetaRpcMT5Ex import MT5AccountEx as MT5Account
except Exception:
from MetaRpcMT5.mt5_account import MT5Account
If the extended adapter is present, you’ll get extra capabilities for free — the rest of your code doesn’t change.
📝 Notes¶
- Adds project roots to
sys.path
(ROOT
,package
,ext
) so that imports work in example runs. - Uses a small incremental sleep between retries (0.5s, 1.0s, …) for friendlier backoff.
shutdown()
is idempotent-ish: safe even if the connection partially failed.
That’s it. Keep calm and await connect()
.