Skip to content

docs: README with contents and ADR index; log a failed left-open check - #18

Merged
Akinzou merged 1 commit into
masterfrom
docs/readme-contents
Nov 9, 2026
Merged

Akinzou merged 1 commit into
masterfrom
docs/readme-contents

Conversation

@Akinzou

@Akinzou Akinzou commented Nov 9, 2026

Copy link
Copy Markdown
Owner

Goal

The owner asked for a README that holds every essential, starts with a table of contents and links the ADRs. It may exceed 300 lines.

What changed

  • README (451 lines):
    • a table of contents;
    • an index of all 11 ADRs;
    • new sections: connecting (argument table), magic scope (symbol/ticket table, magic 0 on a single-bot account, netting), reading positions, error kinds with what to do, batch failures, logging, the MetaTrader5 re-export, and a checklist before trading real money.
    • Links to repository files are absolute GitHub URLs, because PyPI does not resolve relative links. Anchor links in the table of contents still do not jump on PyPI, and the README says so.
  • scripts/check_file_length.py: the top-level README.md may have up to 600 lines. Every other file keeps 300. A ceiling rather than no limit, so that a pasted log cannot slip through. Tests: tests/unit/test_check_file_length.py.
  • Fix in magic_scope: a defaulted close/cancel that matched nothing used to drop an Err from its follow-up listing of other magics. Ok([]) could then read as "flat" without any warning on netting. It now logs a warning that it could not check. The call stays Ok. This was in 3.0.0 and was found by review round 2. ADR 0011 and the CHANGELOG are updated.

Verification

  • 358 tests pass. ruff, ruff format, mypy --strict and the length check are clean.
  • The README has no broken anchors and no relative links (checked by script).
  • Symbol scoping was checked live on the demo account: close_positions("EURGBP") and cancel_pending_orders("EURGBP"), with and without ANY_MAGIC, left a EURUSD position and a EURUSD limit order untouched.

Review history

Two /code-review high rounds, with the severity filter fixed in advance: the README contradicts the code, or the guard breaks.

  • Round 1, fixed:
    • the batch example said "still open" for pre-batch errors (ticket=None) and for OUTCOME_UNKNOWN;
    • the real-money checklist had the same mistake;
    • relative links break on PyPI;
    • the README exemption had no limit;
    • the warning text was split across two lines;
    • the advice for 10026 was wrong;
    • pre-send NO_PRICE retries were not mentioned.
  • Round 2, fixed:
    • the headline overstated the protection under the default magic=0;
    • the dropped listing error (above);
    • REJECTED covers "already closed" (10036);
    • ticket with an explicit magic still filters;
    • INVALID_FILLING is not fixable by the caller;
    • the demo tests are not in the wheel.
  • The last fix commit had no third review round.

Named debt

  • Links point to blob/master. The README frozen on PyPI for a release shows the docs as they are on master later, not as they were for that release. Pinning links to the tag at release time would fix this but needs a release step; it was not done here.

…ed left-open check

README: a table of contents, an ADR index, and sections for connecting,
magic-number scope (symbol, ticket, magic 0 on a single-bot account,
netting), error kinds with what to do, batch failures and a checklist
before trading real money. Links to repository files are absolute GitHub
URLs, because PyPI does not resolve relative ones.

check_file_length: the top-level README.md may have up to 600 lines (the
owner's call); every other file keeps 300. I chose a higher ceiling over
no limit, because no limit would let a pasted log through unnoticed.

magic_scope: a defaulted close/cancel that matched nothing dropped an Err
from its follow-up listing of other magics, so Ok([]) could read as "flat"
in silence. It now logs a warning. The call stays Ok, because it did what
was asked, and an Err would invite a retry of an action that already ran.
@Akinzou
Akinzou merged commit 07d486b into master Nov 9, 2026
8 checks passed
@Akinzou
Akinzou deleted the docs/readme-contents branch November 14, 2026 01:24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant