fmsave 0.4.0__tar.gz

fmsave-0.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Randal S. Olson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fmsave-0.4.0/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: fmsave
+Version: 0.4.0
+Summary: Read Football Manager 26 save files into Python records, DataFrames, CSV and JSON.
+Keywords: football-manager,fm26,save,parser,data
+Author: Randal S. Olson
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Games/Entertainment
+Classifier: Typing :: Typed
+Requires-Dist: backports-zstd>=1.7 ; python_full_version < '3.14'
+Requires-Dist: pandas>=2.2 ; extra == 'pandas'
+Requires-Dist: polars>=1.0 ; extra == 'polars'
+Requires-Python: >=3.12
+Project-URL: Repository, https://github.com/rhiever/fmsave
+Project-URL: Issues, https://github.com/rhiever/fmsave/issues
+Provides-Extra: pandas
+Provides-Extra: polars
+Description-Content-Type: text/markdown
+
+# fmsave
+
+Read your Football Manager 26 saves from disk into Python records, DataFrames, CSV and JSON.
+
+## Install
+
+fmsave needs Python 3.12 or newer.
+
+```console
+uvx fmsave info path/to/career.fm   # try it without installing
+pip install fmsave
+pip install "fmsave[pandas]"        # adds Table.to_pandas()
+```
+
+## Quickstart
+
+```python
+import fmsave
+
+with fmsave.open("career.fm") as career_save:
+    my_club = career_save.managed_clubs()[0]  # empty when you are between jobs
+    squad = career_save.players().where(club_uid=my_club.club_uid)
+
+    for player in squad.sorted_by(lambda player: player.ability.current, reverse=True)[:5]:
+        print(player.name, player.age, player.ability.current, player.attributes.finishing)
+        # "Alex Example" 24 148 16
+
+    squad_frame = squad.to_pandas()  # needs fmsave[pandas]
+    squad.write_csv("squad.csv")
+```
+
+A player carries his names, birth date and age, nationality, club, height, positions, all 24
+attributes, the eight personality attributes, current and potential ability, reputation, transfer
+value, condition, traits, his contract and any unserved ban. Records and tables are immutable and
+keep working after the save is closed.
+
+Each reader returns a `Table`: `where(...)`, `filter(...)`, `sorted_by(...)`, `find(name=...)`,
+`by_uid(...)`, `by_id(...)` and `coverage`, plus `to_dicts()`, `to_columns()`, `to_pandas()`,
+`to_polars()`, `write_csv(...)`, `write_json(...)` and `write_jsonl(...)`.
+
+## What else it reads
+
+Twenty-six readers in all, each returning a `Table` of records:
+
+- **People** — `players()`, `contracts()`, `suspensions()`, `staff()`, `staff_lists()`
+- **Clubs** — `clubs()`, `managed_clubs()`, `finances()`, `sponsorships()`, `facilities()`,
+  `stadiums()`, `affiliates()`, `job_vacancies()`
+- **Competitions** — `stages()`, `competitions()`, `fixtures()`, `league_tables()`,
+  `competition_rules()`, `transfer_windows()`, `player_match_stats()`
+- **Injuries** — `injury_types()`, `injuries()`
+- **Your own club's work**, which only the club you manage stores — `training()`, `mentoring()`,
+  `tactics()`, `set_pieces()`
+
+Every field is either verified against the game or unconfirmed; ask with
+`fmsave.field_status(fmsave.Player, "contract.wage")`. Values come from the save as stored, a value
+fmsave cannot read is `None` rather than a guess, and money is kept in the unit the game stores it
+in, which is not the currency it displays.
+
+Each reader also measures what it decoded against loose bounds drawn from a couple of careers. A
+save unlike them can miss one and still be read perfectly well, so a missed bound is a warning and
+you get the table anyway. Pass `strict=True` to `fmsave.open` to have one raise instead.
+
+## What it cannot read
+
+- **Names the game renders from its own installed database.** Competitions, leagues, nations,
+  cities and all but a couple of hundred grounds. fmsave ships none of these and reads nothing from
+  your game install. Competitions carry `database_id`, the id every outside name source is keyed
+  on, so you can supply your own map — see [Competition names](#competition-names).
+- **Links the save does not store**, such as which competition a rules block belongs to, or which
+  ground a club plays at. Worked out from the fixture calendar where possible, left empty where not.
+- **Meanings for numbers the game never displayed**, such as staff job titles or the settings
+  inside a tactic. These come back as raw numbers rather than as labels fmsave guessed at.
+- **What the save keeps only in part or not at all** — scores for about three quarters of a
+  career's matches, injuries older than about two years, and today's availability, line-ups, staff
+  attribute values, card counts, club debt and asking prices.
+
+## Competition names
+
+```python
+competition_names = fmsave.read_competition_names("competition-names.csv")
+with fmsave.open("career.fm", competition_names=competition_names) as career_save:
+    for competition in career_save.competitions():
+        print(competition.database_id, competition.name)  # 12345 "Example League"
+```
+
+The file is UTF-8, two columns, `database_id` then `name`; a leading header row is skipped. Any
+mapping of database id to name works too. Without a map, `name` and every denormalised
+`competition_name` is `None`. About one competition in ten carries no database id and can never be
+named, and one the game created during a career carries an id no outside source holds.
+
+## Command line
+
+```console
+fmsave info career.fm
+fmsave export career.fm players --managed-club -o squad.csv
+fmsave export career.fm players --nation 7 --columns name,age,club_name,contract_wage
+fmsave validate career.fm --json
+```
+
+`export` writes any of the twenty-six tables as CSV, JSON or JSON Lines, and needs a scope:
+`--club`, `--managed-club`, `--competition`, `--nation` or `--all`. Nested groups flatten to
+`contract_wage`-style columns and a coded value gives a label column plus a `_code` column, so JSON
+is the lossless format. `validate` runs every reader and reports its checks, counts and coverage,
+holding no names, uids or text from the save, so it is safe to paste into an issue.
+
+## Where saves live
+
+- macOS: `~/Library/Application Support/Sports Interactive/Football Manager 26/games/`
+- Windows: usually `Documents\Sports Interactive\Football Manager 26\games\`
+- Steam Cloud and other stores may keep saves somewhere else.
+
+If the game is running, copy the save and read the copy.
+
+## Safety
+
+fmsave is read-only. It never modifies saves, makes no network connections, and does not read game
+memory. Using it to gain an advantage in shared online careers may break platform or community
+rules.
+
+## Support
+
+fmsave is a hobby project, maintained on a best-effort basis. Report problems through
+[GitHub issues](https://github.com/rhiever/fmsave/issues), and never attach save files. See
+[CONTRIBUTING.md](CONTRIBUTING.md) for how to report a wrong value without sharing real data. To
+request removal of any content, open an issue with the rights request form.
+
+## Disclaimer
+
+fmsave is an unofficial fan project. It is not affiliated with, endorsed by, or sponsored by Sports
+Interactive or SEGA. Football Manager, Sports Interactive and SEGA are trademarks or registered
+trademarks of their respective owners.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

fmsave-0.4.0/README.md

@@ -0,0 +1,135 @@
+# fmsave
+
+Read your Football Manager 26 saves from disk into Python records, DataFrames, CSV and JSON.
+
+## Install
+
+fmsave needs Python 3.12 or newer.
+
+```console
+uvx fmsave info path/to/career.fm   # try it without installing
+pip install fmsave
+pip install "fmsave[pandas]"        # adds Table.to_pandas()
+```
+
+## Quickstart
+
+```python
+import fmsave
+
+with fmsave.open("career.fm") as career_save:
+    my_club = career_save.managed_clubs()[0]  # empty when you are between jobs
+    squad = career_save.players().where(club_uid=my_club.club_uid)
+
+    for player in squad.sorted_by(lambda player: player.ability.current, reverse=True)[:5]:
+        print(player.name, player.age, player.ability.current, player.attributes.finishing)
+        # "Alex Example" 24 148 16
+
+    squad_frame = squad.to_pandas()  # needs fmsave[pandas]
+    squad.write_csv("squad.csv")
+```
+
+A player carries his names, birth date and age, nationality, club, height, positions, all 24
+attributes, the eight personality attributes, current and potential ability, reputation, transfer
+value, condition, traits, his contract and any unserved ban. Records and tables are immutable and
+keep working after the save is closed.
+
+Each reader returns a `Table`: `where(...)`, `filter(...)`, `sorted_by(...)`, `find(name=...)`,
+`by_uid(...)`, `by_id(...)` and `coverage`, plus `to_dicts()`, `to_columns()`, `to_pandas()`,
+`to_polars()`, `write_csv(...)`, `write_json(...)` and `write_jsonl(...)`.
+
+## What else it reads
+
+Twenty-six readers in all, each returning a `Table` of records:
+
+- **People** — `players()`, `contracts()`, `suspensions()`, `staff()`, `staff_lists()`
+- **Clubs** — `clubs()`, `managed_clubs()`, `finances()`, `sponsorships()`, `facilities()`,
+  `stadiums()`, `affiliates()`, `job_vacancies()`
+- **Competitions** — `stages()`, `competitions()`, `fixtures()`, `league_tables()`,
+  `competition_rules()`, `transfer_windows()`, `player_match_stats()`
+- **Injuries** — `injury_types()`, `injuries()`
+- **Your own club's work**, which only the club you manage stores — `training()`, `mentoring()`,
+  `tactics()`, `set_pieces()`
+
+Every field is either verified against the game or unconfirmed; ask with
+`fmsave.field_status(fmsave.Player, "contract.wage")`. Values come from the save as stored, a value
+fmsave cannot read is `None` rather than a guess, and money is kept in the unit the game stores it
+in, which is not the currency it displays.
+
+Each reader also measures what it decoded against loose bounds drawn from a couple of careers. A
+save unlike them can miss one and still be read perfectly well, so a missed bound is a warning and
+you get the table anyway. Pass `strict=True` to `fmsave.open` to have one raise instead.
+
+## What it cannot read
+
+- **Names the game renders from its own installed database.** Competitions, leagues, nations,
+  cities and all but a couple of hundred grounds. fmsave ships none of these and reads nothing from
+  your game install. Competitions carry `database_id`, the id every outside name source is keyed
+  on, so you can supply your own map — see [Competition names](#competition-names).
+- **Links the save does not store**, such as which competition a rules block belongs to, or which
+  ground a club plays at. Worked out from the fixture calendar where possible, left empty where not.
+- **Meanings for numbers the game never displayed**, such as staff job titles or the settings
+  inside a tactic. These come back as raw numbers rather than as labels fmsave guessed at.
+- **What the save keeps only in part or not at all** — scores for about three quarters of a
+  career's matches, injuries older than about two years, and today's availability, line-ups, staff
+  attribute values, card counts, club debt and asking prices.
+
+## Competition names
+
+```python
+competition_names = fmsave.read_competition_names("competition-names.csv")
+with fmsave.open("career.fm", competition_names=competition_names) as career_save:
+    for competition in career_save.competitions():
+        print(competition.database_id, competition.name)  # 12345 "Example League"
+```
+
+The file is UTF-8, two columns, `database_id` then `name`; a leading header row is skipped. Any
+mapping of database id to name works too. Without a map, `name` and every denormalised
+`competition_name` is `None`. About one competition in ten carries no database id and can never be
+named, and one the game created during a career carries an id no outside source holds.
+
+## Command line
+
+```console
+fmsave info career.fm
+fmsave export career.fm players --managed-club -o squad.csv
+fmsave export career.fm players --nation 7 --columns name,age,club_name,contract_wage
+fmsave validate career.fm --json
+```
+
+`export` writes any of the twenty-six tables as CSV, JSON or JSON Lines, and needs a scope:
+`--club`, `--managed-club`, `--competition`, `--nation` or `--all`. Nested groups flatten to
+`contract_wage`-style columns and a coded value gives a label column plus a `_code` column, so JSON
+is the lossless format. `validate` runs every reader and reports its checks, counts and coverage,
+holding no names, uids or text from the save, so it is safe to paste into an issue.
+
+## Where saves live
+
+- macOS: `~/Library/Application Support/Sports Interactive/Football Manager 26/games/`
+- Windows: usually `Documents\Sports Interactive\Football Manager 26\games\`
+- Steam Cloud and other stores may keep saves somewhere else.
+
+If the game is running, copy the save and read the copy.
+
+## Safety
+
+fmsave is read-only. It never modifies saves, makes no network connections, and does not read game
+memory. Using it to gain an advantage in shared online careers may break platform or community
+rules.
+
+## Support
+
+fmsave is a hobby project, maintained on a best-effort basis. Report problems through
+[GitHub issues](https://github.com/rhiever/fmsave/issues), and never attach save files. See
+[CONTRIBUTING.md](CONTRIBUTING.md) for how to report a wrong value without sharing real data. To
+request removal of any content, open an issue with the rights request form.
+
+## Disclaimer
+
+fmsave is an unofficial fan project. It is not affiliated with, endorsed by, or sponsored by Sports
+Interactive or SEGA. Football Manager, Sports Interactive and SEGA are trademarks or registered
+trademarks of their respective owners.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

fmsave-0.4.0/pyproject.toml

@@ -0,0 +1,102 @@
+[project]
+name = "fmsave"
+version = "0.4.0"
+description = "Read Football Manager 26 save files into Python records, DataFrames, CSV and JSON."
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = [
+    "football-manager",
+    "fm26",
+    "save",
+    "parser",
+    "data",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Games/Entertainment",
+    "Typing :: Typed",
+]
+dependencies = ["backports.zstd>=1.7; python_version < '3.14'"]
+
+[[project.authors]]
+name = "Randal S. Olson"
+
+[project.optional-dependencies]
+pandas = ["pandas>=2.2"]
+polars = ["polars>=1.0"]
+
+[project.urls]
+Repository = "https://github.com/rhiever/fmsave"
+Issues = "https://github.com/rhiever/fmsave/issues"
+
+[project.scripts]
+fmsave = "fmsave.cli:main"
+
+[dependency-groups]
+test = [
+    "pytest>=9.1",
+    "pytest-cov>=7.1",
+    "pytest-timeout>=2.4",
+    "hypothesis>=6.168",
+    "syrupy>=6.1",
+    "pandas>=2.2",
+    "polars>=1.0",
+]
+dev = [
+    { include-group = "test" },
+    "ruff>=0.16.7,<0.17",
+    "pyright>=1.1.414",
+]
+
+[build-system]
+requires = ["uv_build>=0.12.13,<0.13"]
+build-backend = "uv_build"
+
+[tool.uv]
+default-groups = ["dev"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.pyright]
+include = [
+    "src",
+    "tests",
+    "scripts",
+]
+typeCheckingMode = "standard"
+strict = [
+    "src",
+    "scripts",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["."]
+strict = true
+addopts = ["-ra"]
+timeout = "300"
+markers = [
+    "corpus: needs the local private corpus (never runs in CI)",
+    "corpus_fast: corpus tier for open, info, players and clubs",
+    "corpus_full: corpus tier for every reader",
+]
+
+[tool.coverage.run]
+branch = true
+source = ["fmsave"]
+
+[tool.coverage.report]
+fail_under = 90
+show_missing = true

fmsave-0.4.0/pyproject.toml.orig

@@ -0,0 +1,87 @@
+[project]
+name = "fmsave"
+version = "0.4.0"
+description = "Read Football Manager 26 save files into Python records, DataFrames, CSV and JSON."
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Randal S. Olson" }]
+keywords = ["football-manager", "fm26", "save", "parser", "data"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Games/Entertainment",
+    "Typing :: Typed",
+]
+dependencies = ["backports.zstd>=1.7; python_version < '3.14'"]
+
+[project.optional-dependencies]
+pandas = ["pandas>=2.2"]
+polars = ["polars>=1.0"]
+
+[project.urls]
+Repository = "https://github.com/rhiever/fmsave"
+Issues = "https://github.com/rhiever/fmsave/issues"
+
+[project.scripts]
+fmsave = "fmsave.cli:main"
+
+[dependency-groups]
+test = [
+    "pytest>=9.1",
+    "pytest-cov>=7.1",
+    "pytest-timeout>=2.4",
+    "hypothesis>=6.168",
+    "syrupy>=6.1",
+    "pandas>=2.2",
+    "polars>=1.0",
+]
+dev = [
+    { include-group = "test" },
+    "ruff>=0.16.7,<0.17",
+    "pyright>=1.1.414",
+]
+
+[build-system]
+requires = ["uv_build>=0.12.13,<0.13"]
+build-backend = "uv_build"
+
+[tool.uv]
+default-groups = ["dev"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.pyright]
+include = ["src", "tests", "scripts"]
+typeCheckingMode = "standard"
+strict = ["src", "scripts"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["."]
+strict = true
+addopts = ["-ra"]
+timeout = "300"
+markers = [
+    "corpus: needs the local private corpus (never runs in CI)",
+    "corpus_fast: corpus tier for open, info, players and clubs",
+    "corpus_full: corpus tier for every reader",
+]
+
+[tool.coverage.run]
+branch = true
+source = ["fmsave"]
+
+[tool.coverage.report]
+fail_under = 90
+show_missing = true