Allow overriding the TR app version and User-Agent from the environment

[twannooitmeer]

Summary

The v2 web login identifies itself to Trade Republic as their own web frontend, using two values that describe someone else's deployment:

• APP_VERSION (2.2631.13), sent as X-TR-App-Version
• the browser User-Agent in _default_headers

Trade Republic can invalidate either at any moment. A frontend release makes APP_VERSION stale, and the login endpoints then answer 426 CLIENT_VERSION_OUTDATED, which is exactly what #250 was. A change to their bot filtering can make the User-Agent the thing being rejected.

Neither failure needs a code change to fix. It needs a different string. But because both are baked into the module, a user locked out today has to wait for a release, and you have to cut one under time pressure. The comment above APP_VERSION already anticipates this ("bump when TR starts rejecting stale versions"); this PR just makes the bump something a user can do locally.

What changed

Two environment variables, read at the point of use:

Variable	Overrides	Use it when
PYTR_TR_APP_VERSION	X-TR-App-Version	Login fails with 426 CLIENT_VERSION_OUTDATED
PYTR_TR_USER_AGENT	User-Agent on every request	Login is rejected in a way that looks like bot filtering

PYTR_TR_APP_VERSION=2.2700.4 pytr login --v2

Unset or empty keeps the built-in default, so an empty assignment can never send an empty header. The defaults are unchanged, so this is a no-op for anyone who does not set the variables.

Two details worth a look

The User-Agent override applies to a per-instance copy of _default_headers. That dict is a class attribute and was previously passed straight to requests.Session, which mutates what it is given. Copying it is needed for the override to stay on one instance, and it independently stops a session from writing into state shared by every instance. There is a test pinning the no-leak property.

X-TR-Device-Info stays consistent with whatever User-Agent is in force. browserVersion is scraped out of the UA with a regex, so an override has to flow through to the fingerprint or the two would contradict each other on the wire. A non-Chrome override leaves browserVersion empty rather than reporting a version the browser never claimed, which matches how the frontend omits fields it cannot fill.

Tests

Six tests added to tests/test_api_urls.py, covering both overrides, the empty-value fallback, the absence of cross-instance leakage, and the device-info consistency in both the Chrome and non-Chrome cases. Full suite: 224 passed. ruff format --check and ruff check clean.

I verified the four behavioural tests fail if the override logic is removed while the new constants are kept, so they are pinning behaviour rather than just imports.

Docs

A short "If web login suddenly stops working" section under Authentication, documenting both variables, where to read the current values off the live frontend in dev tools, and asking anyone who needs one to open an issue so the default gets updated for everyone.

Notes

Split out of #355, which is now documentation only after #380 landed the v2 login. This is the one idea from that PR that did not survive the merge, and #380 hardcodes both values, so the gap is still open on master.

Happy to add WEB_PLATFORM to the same mechanism if you want it, though it seems much less likely to move than the build version.

[RealCLanger]

Thanks for this contribution, this makes sense and I'd like to merge it. However, there are errors in the checks with mksync. Can you please check and repair?

It would certainly also be nice if the environment override handling for WEB_PLATFORM would be added as well, though the value is less likely to change.

[RealCLanger]

Since I've made additional changes upstream, you also need to sync and likely resolve your PR branch.

[twannooitmeer]

Both points addressed, and the branch is synced with current master (merge, no force-push).

The failing check was the README one, not a test. The new If web login suddenly stops working heading was missing its entry in the mksync-generated table of contents, so diff -u README.md <(mksync README.md) differed by exactly that one line. Regenerated with the documented uvx mksync@0.1.5 -i README.md, which adds the entry and nothing else.

One thing worth flagging: the CI step for this uses sed -z, which does not exist on BSD/macOS sed. Running that command verbatim on a Mac makes both sides of the diff fail, so it compares two empty streams and always exits 0. It looks like a pass locally while CI fails, which is a confusing way to lose half an hour. I checked mine with a portable equivalent (perl -0pe 's/\n*$//') and confirmed it fails when I remove the TOC entry, so the check is really passing now and not just silently degenerate. Happy to send a separate PR making that step portable if you would like.

WEB_PLATFORM override added as PYTR_TR_PLATFORM, same semantics as the other two: unset or empty keeps the built-in web-pro, so an empty assignment can never send an empty X-Tr-Platform. Documented in the same table, with a test.

Verified locally against all five CI steps: pytest (226 passed), ruff@0.9.6 check, ruff@0.9.6 format --check --diff, mypy ., and the mksync diff. I also mutation-tested the new test, confirming it fails when the override is removed, so it pins behaviour rather than just the constant.

The workflow run is sitting at action_required and needs your approval to execute.

[RealCLanger]

Thanks for following up. We're getting there. I made a few hopefully final review comments. And, yes, another PR to repair the mksync check on mac would be more than welcome.

[RealCLanger]

Maybe we should just name it USER_AGENT which is more inline with the names APP_VERSION and WEB_PLATFORM above.

[RealCLanger]

I think the comment here in the code is too verbose, given that we more or less write the same in README.md. I suggest to make less words here.

[RealCLanger]

Suggested change

	_default_headers = {"User-Agent": DEFAULT_USER_AGENT}
	_default_headers = {"User-Agent": os.environ.get(ENV_USER_AGENT) or DEFAULT_USER_AGENT}

Initialize _default_headers using the environment in the central place, no?

[RealCLanger]

Please sort the variables like above, e.g. ENV_APP_VERSION, ENV_PLATFORM, ENV_USER_AGENT

[RealCLanger]

If you follow my suggestion to initialize _default_headers using ENV_USER_AGENT, this whole block is not necessary. Or is there any other reason to clone the dict here for usage?

[RealCLanger]

Please also fix the ordering here in the sense of APP_VERSION, PLATFORM, USER_AGENT

[twannooitmeer]

All six addressed, and the branch is synced with current master.

• DEFAULT_USER_AGENT is now USER_AGENT.
• ENV_ constants sorted APP_VERSION, PLATFORM, USER_AGENT, and the test import too.
• Block comment cut down, since the README covers when to use which.
• _default_headers initialised from the environment as you suggested, and the __init__ block removed.

On the clone: you were right, and my stated reason for it was wrong. I claimed requests mutates the header dict it is handed. It does not; it merges headers into a new dict per request and leaves the session's own dict alone. I checked rather than assuming this time. The clone only existed because __init__ wrote into _default_headers, and writing into a class attribute would have leaked the override into every instance. Reading the environment where the attribute is defined removes the write, so the copy has no reason to exist. Removed, along with the test that pinned the non-leaking.

One consequence worth naming, in case you would rather avoid it: the User-Agent is now resolved when the class body executes, so os.environ changes made after pytr.api is imported no longer affect it, whereas APP_VERSION and WEB_PLATFORM are still read per call. For the CLI the two are indistinguishable, since the environment is set before the process starts, so I went with your version. The three User-Agent tests reimport the module to observe the override, in a fixture that restores it afterwards. If you would prefer all three to read at the same time, this one line in __init__ does it without bringing the block back:

self._default_headers = {**self._default_headers, "User-Agent": os.environ.get(ENV_USER_AGENT) or USER_AGENT}

Happy either way, it is your call.

Verified against all five CI steps locally: pytest (228 passed), ruff@0.9.6 check, ruff@0.9.6 format --check --diff, mypy ., and the mksync diff. I confirmed the three User-Agent tests still fail when the override is removed, so the reimport is not hiding anything.

The mksync fix is #390.