steam-shortcuts 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- steam_shortcuts-0.1.0/LICENSE +21 -0
- steam_shortcuts-0.1.0/PKG-INFO +167 -0
- steam_shortcuts-0.1.0/README.md +137 -0
- steam_shortcuts-0.1.0/pyproject.toml +68 -0
- steam_shortcuts-0.1.0/setup.cfg +4 -0
- steam_shortcuts-0.1.0/src/steam_shortcuts/__init__.py +32 -0
- steam_shortcuts-0.1.0/src/steam_shortcuts/api.py +167 -0
- steam_shortcuts-0.1.0/src/steam_shortcuts/cli.py +169 -0
- steam_shortcuts-0.1.0/src/steam_shortcuts/discovery.py +127 -0
- steam_shortcuts-0.1.0/src/steam_shortcuts/errors.py +78 -0
- steam_shortcuts-0.1.0/src/steam_shortcuts/models.py +56 -0
- steam_shortcuts-0.1.0/src/steam_shortcuts/process.py +36 -0
- steam_shortcuts-0.1.0/src/steam_shortcuts/service.py +222 -0
- steam_shortcuts-0.1.0/src/steam_shortcuts/vdf_store.py +173 -0
- steam_shortcuts-0.1.0/src/steam_shortcuts.egg-info/PKG-INFO +167 -0
- steam_shortcuts-0.1.0/src/steam_shortcuts.egg-info/SOURCES.txt +26 -0
- steam_shortcuts-0.1.0/src/steam_shortcuts.egg-info/dependency_links.txt +1 -0
- steam_shortcuts-0.1.0/src/steam_shortcuts.egg-info/entry_points.txt +2 -0
- steam_shortcuts-0.1.0/src/steam_shortcuts.egg-info/requires.txt +9 -0
- steam_shortcuts-0.1.0/src/steam_shortcuts.egg-info/top_level.txt +1 -0
- steam_shortcuts-0.1.0/tests/test_api_cli.py +119 -0
- steam_shortcuts-0.1.0/tests/test_cli.py +6 -0
- steam_shortcuts-0.1.0/tests/test_discovery.py +49 -0
- steam_shortcuts-0.1.0/tests/test_models.py +61 -0
- steam_shortcuts-0.1.0/tests/test_process.py +61 -0
- steam_shortcuts-0.1.0/tests/test_service.py +121 -0
- steam_shortcuts-0.1.0/tests/test_transaction.py +94 -0
- steam_shortcuts-0.1.0/tests/test_vdf_store.py +54 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Rodrigo Machado
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,167 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: steam-shortcuts
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Safely add non-Steam shortcuts through a Python API and CLI.
|
|
5
|
+
Author: Rodrigo Machado
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/msrodrigobr/steam-shortcuts
|
|
8
|
+
Project-URL: Source, https://github.com/msrodrigobr/steam-shortcuts
|
|
9
|
+
Project-URL: Issues, https://github.com/msrodrigobr/steam-shortcuts/issues
|
|
10
|
+
Keywords: steam,shortcuts,games,automation
|
|
11
|
+
Classifier: Development Status :: 3 - Alpha
|
|
12
|
+
Classifier: Intended Audience :: End Users/Desktop
|
|
13
|
+
Classifier: Operating System :: MacOS
|
|
14
|
+
Classifier: Operating System :: Microsoft :: Windows
|
|
15
|
+
Classifier: Operating System :: POSIX :: Linux
|
|
16
|
+
Classifier: Programming Language :: Python :: 3
|
|
17
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
18
|
+
Requires-Python: >=3.10
|
|
19
|
+
Description-Content-Type: text/markdown
|
|
20
|
+
License-File: LICENSE
|
|
21
|
+
Requires-Dist: psutil<8,>=5.9
|
|
22
|
+
Requires-Dist: vdf<4,>=3.4
|
|
23
|
+
Provides-Extra: dev
|
|
24
|
+
Requires-Dist: build<2,>=1.2; extra == "dev"
|
|
25
|
+
Requires-Dist: mypy<3,>=1.0; extra == "dev"
|
|
26
|
+
Requires-Dist: pytest<10,>=8; extra == "dev"
|
|
27
|
+
Requires-Dist: ruff<1,>=0.10; extra == "dev"
|
|
28
|
+
Requires-Dist: types-psutil<8,>=7; extra == "dev"
|
|
29
|
+
Dynamic: license-file
|
|
30
|
+
|
|
31
|
+
# steam-shortcuts
|
|
32
|
+
|
|
33
|
+
A portable Python library and command-line tool for adding non-Steam shortcuts to a local Steam profile without GUI automation.
|
|
34
|
+
|
|
35
|
+
It edits only Steam's per-user binary `userdata/<steam-id>/config/shortcuts.vdf`, never `localconfig.vdf`. Before replacing an existing shortcut file it creates a timestamped sibling backup, uses an atomic replacement, then rereads the VDF and verifies the exact shortcut it added.
|
|
36
|
+
|
|
37
|
+
Steam must be fully closed before using `add`. The tool refuses to write if it detects the main `steam` or `steam.exe` process. It will not murder Steam for you; that is a feature, not a missing feature.
|
|
38
|
+
|
|
39
|
+
## Status and support
|
|
40
|
+
|
|
41
|
+
- Windows is the primary acceptance target for Windows executable paths.
|
|
42
|
+
- Steam discovery supports Windows registry/default locations, common Linux locations (including Flatpak), and macOS.
|
|
43
|
+
- If a Steam root has multiple numeric profiles, `--steam-id` is required. The tool never guesses an account.
|
|
44
|
+
- The first release intentionally does not add artwork, modify Steam Cloud or `localconfig.vdf`, restart Steam, launch games, or drive the Steam UI.
|
|
45
|
+
|
|
46
|
+
## Install
|
|
47
|
+
|
|
48
|
+
Until this distribution is published, install a checkout into an isolated `pipx` environment:
|
|
49
|
+
|
|
50
|
+
```text
|
|
51
|
+
pipx install .
|
|
52
|
+
steam-shortcuts --help
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
After a published release exists, the equivalent will be:
|
|
56
|
+
|
|
57
|
+
```text
|
|
58
|
+
pipx install steam-shortcuts
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
After a published release exists, use it as a library in another Python project:
|
|
62
|
+
|
|
63
|
+
```text
|
|
64
|
+
python -m pip install steam-shortcuts
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
## Command-line use
|
|
68
|
+
|
|
69
|
+
First, inspect the local Steam installation and profiles:
|
|
70
|
+
|
|
71
|
+
```text
|
|
72
|
+
steam-shortcuts detect --json
|
|
73
|
+
steam-shortcuts list --steam-id 123456789 --json
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
Add a Windows executable. Quote the shell argument normally; do not add the internal Steam quotes yourself:
|
|
77
|
+
|
|
78
|
+
```text
|
|
79
|
+
steam-shortcuts add \
|
|
80
|
+
--steam-id 123456789 \
|
|
81
|
+
--name "My Game" \
|
|
82
|
+
--exe "D:\Games\My Game\Game.exe" \
|
|
83
|
+
--start-dir "D:\Games\My Game" \
|
|
84
|
+
--args "--windowed" \
|
|
85
|
+
--tag "Local" \
|
|
86
|
+
--json
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
Use `--dry-run` first whenever you are doing something unusual. It validates Steam discovery, profile selection, the executable, duplicates, and the planned fields without writing a VDF or backup:
|
|
90
|
+
|
|
91
|
+
```text
|
|
92
|
+
steam-shortcuts add \
|
|
93
|
+
--steam-id 123456789 \
|
|
94
|
+
--name "My Game" \
|
|
95
|
+
--exe "D:\Games\My Game\Game.exe" \
|
|
96
|
+
--dry-run --json
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
For portable or nonstandard installs, give the Steam root — the directory that contains `userdata`, not the VDF file itself:
|
|
100
|
+
|
|
101
|
+
```text
|
|
102
|
+
steam-shortcuts add \
|
|
103
|
+
--steam-root "E:\PortableSteam" \
|
|
104
|
+
--steam-id 123456789 \
|
|
105
|
+
--name "My Game" \
|
|
106
|
+
--exe "D:\Games\My Game\Game.exe"
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
A successful JSON result includes `status`, `profile_id`, `shortcuts_path`, a 32-bit shortcut ID, `steam://rungameid/...`, and `backup_path`. Rerunning the exact name/executable combination returns `already_exists` and creates no backup. Reusing an executable under a different display name is deliberately a conflict rather than a surprise duplicate.
|
|
110
|
+
|
|
111
|
+
Restart Steam normally after a successful add so it reloads `shortcuts.vdf`; then the item should appear in the library.
|
|
112
|
+
|
|
113
|
+
## Python API
|
|
114
|
+
|
|
115
|
+
```python
|
|
116
|
+
from pathlib import Path
|
|
117
|
+
from steam_shortcuts import add_shortcut
|
|
118
|
+
|
|
119
|
+
result = add_shortcut(
|
|
120
|
+
name="My Game",
|
|
121
|
+
executable=Path(r"D:\Games\My Game\Game.exe"),
|
|
122
|
+
start_dir=Path(r"D:\Games\My Game"),
|
|
123
|
+
launch_options="--windowed",
|
|
124
|
+
tags=("Local",),
|
|
125
|
+
steam_id="123456789", # omit only when exactly one profile exists
|
|
126
|
+
)
|
|
127
|
+
|
|
128
|
+
print(result.status, result.run_game_url, result.backup_path)
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
The API and CLI run on the same local user account that owns the Steam profile. They do not communicate with a Steam account, web API, or remote computer.
|
|
132
|
+
|
|
133
|
+
## Recovery
|
|
134
|
+
|
|
135
|
+
For an existing VDF, every successful mutation creates a sibling backup named like:
|
|
136
|
+
|
|
137
|
+
```text
|
|
138
|
+
shortcuts.vdf.bak.20261112T020000Z
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
If Steam rejects or does not show an added shortcut:
|
|
142
|
+
|
|
143
|
+
1. Fully exit Steam.
|
|
144
|
+
2. Preserve the current `shortcuts.vdf` for investigation instead of deleting it.
|
|
145
|
+
3. Replace it with the timestamped `.bak.*` file from the same directory.
|
|
146
|
+
4. Start Steam and verify the prior library state.
|
|
147
|
+
|
|
148
|
+
A malformed VDF is rejected without overwriting it. Keep that file and its error message; it is evidence, not clutter.
|
|
149
|
+
|
|
150
|
+
## Development
|
|
151
|
+
|
|
152
|
+
```text
|
|
153
|
+
python -m venv .venv
|
|
154
|
+
.venv/bin/python -m pip install -e ".[dev]"
|
|
155
|
+
.venv/bin/python -m pytest -q
|
|
156
|
+
.venv/bin/ruff check .
|
|
157
|
+
.venv/bin/mypy src
|
|
158
|
+
.venv/bin/python -m build
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
See `docs/acceptance-test.md` for the real Steam-client validation procedure.
|
|
162
|
+
|
|
163
|
+
## Public releases
|
|
164
|
+
|
|
165
|
+
Public releases are created by pushing a semantic version tag such as `v0.1.0`. The release workflow rebuilds the package, runs tests, linting, and type checks, then publishes with PyPI Trusted Publishing through GitHub OIDC. It intentionally contains no long-lived PyPI API token.
|
|
166
|
+
|
|
167
|
+
Before the first release, configure a pending PyPI trusted publisher for project `steam-shortcuts`, GitHub owner `msrodrigobr`, repository `steam-shortcuts`, workflow filename `publish.yml`, and the protected GitHub environment `pypi`. A pending publisher does not reserve a project name; publish promptly after configuration.
|
|
@@ -0,0 +1,137 @@
|
|
|
1
|
+
# steam-shortcuts
|
|
2
|
+
|
|
3
|
+
A portable Python library and command-line tool for adding non-Steam shortcuts to a local Steam profile without GUI automation.
|
|
4
|
+
|
|
5
|
+
It edits only Steam's per-user binary `userdata/<steam-id>/config/shortcuts.vdf`, never `localconfig.vdf`. Before replacing an existing shortcut file it creates a timestamped sibling backup, uses an atomic replacement, then rereads the VDF and verifies the exact shortcut it added.
|
|
6
|
+
|
|
7
|
+
Steam must be fully closed before using `add`. The tool refuses to write if it detects the main `steam` or `steam.exe` process. It will not murder Steam for you; that is a feature, not a missing feature.
|
|
8
|
+
|
|
9
|
+
## Status and support
|
|
10
|
+
|
|
11
|
+
- Windows is the primary acceptance target for Windows executable paths.
|
|
12
|
+
- Steam discovery supports Windows registry/default locations, common Linux locations (including Flatpak), and macOS.
|
|
13
|
+
- If a Steam root has multiple numeric profiles, `--steam-id` is required. The tool never guesses an account.
|
|
14
|
+
- The first release intentionally does not add artwork, modify Steam Cloud or `localconfig.vdf`, restart Steam, launch games, or drive the Steam UI.
|
|
15
|
+
|
|
16
|
+
## Install
|
|
17
|
+
|
|
18
|
+
Until this distribution is published, install a checkout into an isolated `pipx` environment:
|
|
19
|
+
|
|
20
|
+
```text
|
|
21
|
+
pipx install .
|
|
22
|
+
steam-shortcuts --help
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
After a published release exists, the equivalent will be:
|
|
26
|
+
|
|
27
|
+
```text
|
|
28
|
+
pipx install steam-shortcuts
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
After a published release exists, use it as a library in another Python project:
|
|
32
|
+
|
|
33
|
+
```text
|
|
34
|
+
python -m pip install steam-shortcuts
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
## Command-line use
|
|
38
|
+
|
|
39
|
+
First, inspect the local Steam installation and profiles:
|
|
40
|
+
|
|
41
|
+
```text
|
|
42
|
+
steam-shortcuts detect --json
|
|
43
|
+
steam-shortcuts list --steam-id 123456789 --json
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
Add a Windows executable. Quote the shell argument normally; do not add the internal Steam quotes yourself:
|
|
47
|
+
|
|
48
|
+
```text
|
|
49
|
+
steam-shortcuts add \
|
|
50
|
+
--steam-id 123456789 \
|
|
51
|
+
--name "My Game" \
|
|
52
|
+
--exe "D:\Games\My Game\Game.exe" \
|
|
53
|
+
--start-dir "D:\Games\My Game" \
|
|
54
|
+
--args "--windowed" \
|
|
55
|
+
--tag "Local" \
|
|
56
|
+
--json
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
Use `--dry-run` first whenever you are doing something unusual. It validates Steam discovery, profile selection, the executable, duplicates, and the planned fields without writing a VDF or backup:
|
|
60
|
+
|
|
61
|
+
```text
|
|
62
|
+
steam-shortcuts add \
|
|
63
|
+
--steam-id 123456789 \
|
|
64
|
+
--name "My Game" \
|
|
65
|
+
--exe "D:\Games\My Game\Game.exe" \
|
|
66
|
+
--dry-run --json
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
For portable or nonstandard installs, give the Steam root — the directory that contains `userdata`, not the VDF file itself:
|
|
70
|
+
|
|
71
|
+
```text
|
|
72
|
+
steam-shortcuts add \
|
|
73
|
+
--steam-root "E:\PortableSteam" \
|
|
74
|
+
--steam-id 123456789 \
|
|
75
|
+
--name "My Game" \
|
|
76
|
+
--exe "D:\Games\My Game\Game.exe"
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
A successful JSON result includes `status`, `profile_id`, `shortcuts_path`, a 32-bit shortcut ID, `steam://rungameid/...`, and `backup_path`. Rerunning the exact name/executable combination returns `already_exists` and creates no backup. Reusing an executable under a different display name is deliberately a conflict rather than a surprise duplicate.
|
|
80
|
+
|
|
81
|
+
Restart Steam normally after a successful add so it reloads `shortcuts.vdf`; then the item should appear in the library.
|
|
82
|
+
|
|
83
|
+
## Python API
|
|
84
|
+
|
|
85
|
+
```python
|
|
86
|
+
from pathlib import Path
|
|
87
|
+
from steam_shortcuts import add_shortcut
|
|
88
|
+
|
|
89
|
+
result = add_shortcut(
|
|
90
|
+
name="My Game",
|
|
91
|
+
executable=Path(r"D:\Games\My Game\Game.exe"),
|
|
92
|
+
start_dir=Path(r"D:\Games\My Game"),
|
|
93
|
+
launch_options="--windowed",
|
|
94
|
+
tags=("Local",),
|
|
95
|
+
steam_id="123456789", # omit only when exactly one profile exists
|
|
96
|
+
)
|
|
97
|
+
|
|
98
|
+
print(result.status, result.run_game_url, result.backup_path)
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
The API and CLI run on the same local user account that owns the Steam profile. They do not communicate with a Steam account, web API, or remote computer.
|
|
102
|
+
|
|
103
|
+
## Recovery
|
|
104
|
+
|
|
105
|
+
For an existing VDF, every successful mutation creates a sibling backup named like:
|
|
106
|
+
|
|
107
|
+
```text
|
|
108
|
+
shortcuts.vdf.bak.20261112T020000Z
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
If Steam rejects or does not show an added shortcut:
|
|
112
|
+
|
|
113
|
+
1. Fully exit Steam.
|
|
114
|
+
2. Preserve the current `shortcuts.vdf` for investigation instead of deleting it.
|
|
115
|
+
3. Replace it with the timestamped `.bak.*` file from the same directory.
|
|
116
|
+
4. Start Steam and verify the prior library state.
|
|
117
|
+
|
|
118
|
+
A malformed VDF is rejected without overwriting it. Keep that file and its error message; it is evidence, not clutter.
|
|
119
|
+
|
|
120
|
+
## Development
|
|
121
|
+
|
|
122
|
+
```text
|
|
123
|
+
python -m venv .venv
|
|
124
|
+
.venv/bin/python -m pip install -e ".[dev]"
|
|
125
|
+
.venv/bin/python -m pytest -q
|
|
126
|
+
.venv/bin/ruff check .
|
|
127
|
+
.venv/bin/mypy src
|
|
128
|
+
.venv/bin/python -m build
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
See `docs/acceptance-test.md` for the real Steam-client validation procedure.
|
|
132
|
+
|
|
133
|
+
## Public releases
|
|
134
|
+
|
|
135
|
+
Public releases are created by pushing a semantic version tag such as `v0.1.0`. The release workflow rebuilds the package, runs tests, linting, and type checks, then publishes with PyPI Trusted Publishing through GitHub OIDC. It intentionally contains no long-lived PyPI API token.
|
|
136
|
+
|
|
137
|
+
Before the first release, configure a pending PyPI trusted publisher for project `steam-shortcuts`, GitHub owner `msrodrigobr`, repository `steam-shortcuts`, workflow filename `publish.yml`, and the protected GitHub environment `pypi`. A pending publisher does not reserve a project name; publish promptly after configuration.
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=68"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "steam-shortcuts"
|
|
7
|
+
version = "0.1.0"
|
|
8
|
+
description = "Safely add non-Steam shortcuts through a Python API and CLI."
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.10"
|
|
11
|
+
license = "MIT"
|
|
12
|
+
license-files = ["LICENSE"]
|
|
13
|
+
authors = [{name = "Rodrigo Machado"}]
|
|
14
|
+
keywords = ["steam", "shortcuts", "games", "automation"]
|
|
15
|
+
classifiers = [
|
|
16
|
+
"Development Status :: 3 - Alpha",
|
|
17
|
+
"Intended Audience :: End Users/Desktop",
|
|
18
|
+
"Operating System :: MacOS",
|
|
19
|
+
"Operating System :: Microsoft :: Windows",
|
|
20
|
+
"Operating System :: POSIX :: Linux",
|
|
21
|
+
"Programming Language :: Python :: 3",
|
|
22
|
+
"Programming Language :: Python :: 3 :: Only",
|
|
23
|
+
]
|
|
24
|
+
dependencies = [
|
|
25
|
+
"psutil>=5.9,<8",
|
|
26
|
+
"vdf>=3.4,<4",
|
|
27
|
+
]
|
|
28
|
+
|
|
29
|
+
[project.urls]
|
|
30
|
+
Homepage = "https://github.com/msrodrigobr/steam-shortcuts"
|
|
31
|
+
Source = "https://github.com/msrodrigobr/steam-shortcuts"
|
|
32
|
+
Issues = "https://github.com/msrodrigobr/steam-shortcuts/issues"
|
|
33
|
+
|
|
34
|
+
[project.scripts]
|
|
35
|
+
steam-shortcuts = "steam_shortcuts.cli:main"
|
|
36
|
+
|
|
37
|
+
[project.optional-dependencies]
|
|
38
|
+
dev = [
|
|
39
|
+
"build>=1.2,<2",
|
|
40
|
+
"mypy>=1.0,<3",
|
|
41
|
+
"pytest>=8,<10",
|
|
42
|
+
"ruff>=0.10,<1",
|
|
43
|
+
"types-psutil>=7,<8",
|
|
44
|
+
]
|
|
45
|
+
|
|
46
|
+
[tool.setuptools]
|
|
47
|
+
package-dir = {"" = "src"}
|
|
48
|
+
|
|
49
|
+
[tool.setuptools.packages.find]
|
|
50
|
+
where = ["src"]
|
|
51
|
+
|
|
52
|
+
[tool.pytest.ini_options]
|
|
53
|
+
pythonpath = ["src"]
|
|
54
|
+
testpaths = ["tests"]
|
|
55
|
+
addopts = "-ra"
|
|
56
|
+
|
|
57
|
+
[tool.ruff]
|
|
58
|
+
line-length = 100
|
|
59
|
+
target-version = "py310"
|
|
60
|
+
|
|
61
|
+
[tool.ruff.lint]
|
|
62
|
+
select = ["E", "F", "I", "UP", "B", "SIM"]
|
|
63
|
+
|
|
64
|
+
[tool.mypy]
|
|
65
|
+
files = ["src"]
|
|
66
|
+
python_version = "3.10"
|
|
67
|
+
strict = true
|
|
68
|
+
warn_unreachable = true
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
"""Portable, safe management of local Steam non-Steam shortcuts."""
|
|
2
|
+
|
|
3
|
+
from .api import add_shortcut
|
|
4
|
+
from .errors import (
|
|
5
|
+
InvalidExecutable,
|
|
6
|
+
InvalidShortcutFile,
|
|
7
|
+
ProfileNotFound,
|
|
8
|
+
ProfileSelectionRequired,
|
|
9
|
+
ShortcutConflict,
|
|
10
|
+
ShortcutVerificationFailed,
|
|
11
|
+
SteamNotFound,
|
|
12
|
+
SteamRunning,
|
|
13
|
+
)
|
|
14
|
+
from .models import ShortcutRequest, ShortcutResult, SteamProfile
|
|
15
|
+
|
|
16
|
+
__version__ = "0.1.0"
|
|
17
|
+
|
|
18
|
+
__all__ = [
|
|
19
|
+
"add_shortcut",
|
|
20
|
+
"InvalidShortcutFile",
|
|
21
|
+
"InvalidExecutable",
|
|
22
|
+
"ProfileNotFound",
|
|
23
|
+
"ProfileSelectionRequired",
|
|
24
|
+
"ShortcutConflict",
|
|
25
|
+
"ShortcutVerificationFailed",
|
|
26
|
+
"ShortcutRequest",
|
|
27
|
+
"ShortcutResult",
|
|
28
|
+
"SteamNotFound",
|
|
29
|
+
"SteamProfile",
|
|
30
|
+
"SteamRunning",
|
|
31
|
+
"__version__",
|
|
32
|
+
]
|
|
@@ -0,0 +1,167 @@
|
|
|
1
|
+
"""Public library API for local Steam shortcut management."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from collections.abc import Iterable
|
|
6
|
+
from dataclasses import dataclass
|
|
7
|
+
from pathlib import Path
|
|
8
|
+
|
|
9
|
+
from .discovery import discover_steam_root, list_profile_ids, select_profile
|
|
10
|
+
from .models import ShortcutRequest, ShortcutResult, SteamProfile
|
|
11
|
+
from .process import ensure_steam_not_running
|
|
12
|
+
from .service import (
|
|
13
|
+
ShortcutAdditionPlan,
|
|
14
|
+
add_shortcut_to_profile,
|
|
15
|
+
plan_shortcut_addition,
|
|
16
|
+
to_unsigned_int32,
|
|
17
|
+
)
|
|
18
|
+
from .vdf_store import VdfMap, VdfValue, load_shortcuts
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
@dataclass(frozen=True, slots=True)
|
|
22
|
+
class SteamInstallation:
|
|
23
|
+
"""A discovered Steam root and the numeric user profiles beneath it."""
|
|
24
|
+
|
|
25
|
+
steam_root: Path
|
|
26
|
+
profile_ids: tuple[str, ...]
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
@dataclass(frozen=True, slots=True)
|
|
30
|
+
class ShortcutPreview:
|
|
31
|
+
"""An addition plan resolved to one Steam profile without a file write."""
|
|
32
|
+
|
|
33
|
+
steam_root: Path
|
|
34
|
+
profile: SteamProfile
|
|
35
|
+
plan: ShortcutAdditionPlan
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
@dataclass(frozen=True, slots=True)
|
|
39
|
+
class ShortcutListing:
|
|
40
|
+
"""A shortcut shown by the list API."""
|
|
41
|
+
|
|
42
|
+
index: str
|
|
43
|
+
name: str
|
|
44
|
+
executable: str
|
|
45
|
+
app_id: int | None
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
def detect_steam(steam_root: Path | None = None) -> SteamInstallation:
|
|
49
|
+
"""Discover Steam and return its selectable local profiles."""
|
|
50
|
+
root = discover_steam_root(steam_root)
|
|
51
|
+
return SteamInstallation(steam_root=root, profile_ids=list_profile_ids(root))
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
def list_shortcuts(
|
|
55
|
+
*,
|
|
56
|
+
steam_root: Path | None = None,
|
|
57
|
+
steam_id: str | None = None,
|
|
58
|
+
) -> tuple[SteamProfile, tuple[ShortcutListing, ...]]:
|
|
59
|
+
"""List non-Steam shortcuts from exactly one selected profile."""
|
|
60
|
+
installation = detect_steam(steam_root)
|
|
61
|
+
profile = select_profile(installation.steam_root, steam_id)
|
|
62
|
+
root = load_shortcuts(profile.shortcuts_path)
|
|
63
|
+
shortcuts = _shortcut_map(root)
|
|
64
|
+
listings = tuple(
|
|
65
|
+
_listing(index, entry)
|
|
66
|
+
for index, entry in sorted(shortcuts.items(), key=_shortcut_sort_key)
|
|
67
|
+
if isinstance(entry, dict)
|
|
68
|
+
)
|
|
69
|
+
return profile, listings
|
|
70
|
+
|
|
71
|
+
|
|
72
|
+
def preview_shortcut(
|
|
73
|
+
*,
|
|
74
|
+
name: str,
|
|
75
|
+
executable: Path,
|
|
76
|
+
start_dir: Path | None = None,
|
|
77
|
+
launch_options: str = "",
|
|
78
|
+
icon: Path | None = None,
|
|
79
|
+
tags: Iterable[str] = (),
|
|
80
|
+
steam_root: Path | None = None,
|
|
81
|
+
steam_id: str | None = None,
|
|
82
|
+
) -> ShortcutPreview:
|
|
83
|
+
"""Resolve and validate an add operation without changing Steam files."""
|
|
84
|
+
installation = detect_steam(steam_root)
|
|
85
|
+
ensure_steam_not_running()
|
|
86
|
+
profile = select_profile(installation.steam_root, steam_id)
|
|
87
|
+
request = ShortcutRequest(
|
|
88
|
+
name=name,
|
|
89
|
+
executable=executable,
|
|
90
|
+
start_dir=start_dir,
|
|
91
|
+
launch_options=launch_options,
|
|
92
|
+
icon=icon,
|
|
93
|
+
tags=tuple(tags),
|
|
94
|
+
)
|
|
95
|
+
plan = plan_shortcut_addition(load_shortcuts(profile.shortcuts_path), request)
|
|
96
|
+
return ShortcutPreview(steam_root=installation.steam_root, profile=profile, plan=plan)
|
|
97
|
+
|
|
98
|
+
|
|
99
|
+
def add_shortcut(
|
|
100
|
+
*,
|
|
101
|
+
name: str,
|
|
102
|
+
executable: Path,
|
|
103
|
+
start_dir: Path | None = None,
|
|
104
|
+
launch_options: str = "",
|
|
105
|
+
icon: Path | None = None,
|
|
106
|
+
tags: Iterable[str] = (),
|
|
107
|
+
steam_root: Path | None = None,
|
|
108
|
+
steam_id: str | None = None,
|
|
109
|
+
) -> ShortcutResult:
|
|
110
|
+
"""Safely add a non-Steam shortcut and return its verified result."""
|
|
111
|
+
tag_values = tuple(tags)
|
|
112
|
+
preview = preview_shortcut(
|
|
113
|
+
name=name,
|
|
114
|
+
executable=executable,
|
|
115
|
+
start_dir=start_dir,
|
|
116
|
+
launch_options=launch_options,
|
|
117
|
+
icon=icon,
|
|
118
|
+
tags=tag_values,
|
|
119
|
+
steam_root=steam_root,
|
|
120
|
+
steam_id=steam_id,
|
|
121
|
+
)
|
|
122
|
+
request = ShortcutRequest(
|
|
123
|
+
name=name,
|
|
124
|
+
executable=executable,
|
|
125
|
+
start_dir=start_dir,
|
|
126
|
+
launch_options=launch_options,
|
|
127
|
+
icon=icon,
|
|
128
|
+
tags=tag_values,
|
|
129
|
+
)
|
|
130
|
+
return add_shortcut_to_profile(
|
|
131
|
+
preview.profile.shortcuts_path,
|
|
132
|
+
preview.profile.profile_id,
|
|
133
|
+
request,
|
|
134
|
+
)
|
|
135
|
+
|
|
136
|
+
|
|
137
|
+
def _shortcut_map(root: VdfMap) -> dict[str, VdfValue]:
|
|
138
|
+
shortcuts = root["shortcuts"]
|
|
139
|
+
if not isinstance(shortcuts, dict):
|
|
140
|
+
raise ValueError("'shortcuts' must be a mapping")
|
|
141
|
+
return shortcuts
|
|
142
|
+
|
|
143
|
+
|
|
144
|
+
def _listing(index: str, entry: dict[str, VdfValue]) -> ShortcutListing:
|
|
145
|
+
name = entry.get("AppName", entry.get("appname", ""))
|
|
146
|
+
executable = entry.get("Exe", entry.get("exe", ""))
|
|
147
|
+
raw_app_id = entry.get("appid")
|
|
148
|
+
app_id = (
|
|
149
|
+
to_unsigned_int32(raw_app_id)
|
|
150
|
+
if isinstance(raw_app_id, int) and not isinstance(raw_app_id, bool)
|
|
151
|
+
else None
|
|
152
|
+
)
|
|
153
|
+
return ShortcutListing(
|
|
154
|
+
index=index,
|
|
155
|
+
name=name if isinstance(name, str) else "",
|
|
156
|
+
executable=_unquote(executable) if isinstance(executable, str) else "",
|
|
157
|
+
app_id=app_id,
|
|
158
|
+
)
|
|
159
|
+
|
|
160
|
+
|
|
161
|
+
def _shortcut_sort_key(item: tuple[str, VdfValue]) -> tuple[int, int | str]:
|
|
162
|
+
index, _ = item
|
|
163
|
+
return (0, int(index)) if index.isdecimal() else (1, index)
|
|
164
|
+
|
|
165
|
+
|
|
166
|
+
def _unquote(value: str) -> str:
|
|
167
|
+
return value.strip().removeprefix('"').removesuffix('"')
|