Allow user to specify alternative server from config and enforce simvue.Run keyword arguments

[kzscisoft]

Add Config Option for Alternative Profiles & Enforced Keyword Arguments for simvue.Run.

Issue: N/A

Python Version(s) Tested: 3.13

Operating System(s): Ubuntu 25.10

Documentation PR: Issue on Docs repo.

📝 Summary

• Allows the user to specify multiple servers in their simvue.toml configuration file and specify which to use.
• Enforces keyword arguments in simvue.Run.__init__ due to large number of arguments, this is to ensure the user is clear and absolute in their intention, i.e. due to multiple string arguments ("profile", "mode" etc.) this ensures mode isn't read as a profile.

🔄 Changes

simvue.toml:

[server]
url = "https://simvue.example.com"
token = "not-a-token"

[profiles.dev]
url = "https://simvue-dev.example.com"
token = "not-a-token"

SimvueConfiguration class:

SimvueConfiguration.fetch(mode="online", profile="dev")

simvue.Run class:

with simvue.Run(server_profile="dev") as run:
  ...

✔️ Checklist

• Unit and integration tests passing.
• Pre-commit hooks passing.
• Quality checks passing.
• Updated the documentation.

[james-panayis]

Technically, forcing keyword arguments in Run.__init__ is a breaking change, so should arguably be delayed until a major release. However, I suspect it's uncommon for anyone to pass any arguments to Run.__init__ at all, and when they do they're likely to already be using keyword arguments, so perhaps this is fine. Do we think it's worth immediately breaking this now instead of just deprecating positional arguments and then removing them in v3.0.0? I'm ambivalent.

[james-panayis]

If we have "default" as the default argument, then a user attempting to create a profile called 'default' will get unexpected behaviour. Ie, if the simvue.toml file is:

[server]
url = "https://simvue.example.com"
token = "not-a-token"

[profiles.default]
url = "https://simvue-dev.example.com"
token = "not-a-token"

And the user does:

Run(server_profile="default")

Then it'll use the first url, not the second.

This can be fixed by changing this to:

Suggested change

	profile: str = "default",
	profile: str | None = None,

and changing the if profile == "default": line below

[james-panayis]

Two comments. Otherwise, this will is a very convenient feature - it'll make things much easier for me, for example!

My only other thought is that maybe this should not be mentioned in the official docs. A normal user is very unlikely to ever interact with multiple Simvue servers, so this option is likely to confuse them. I think this is essentially a 'dev feature'.