diff --git a/docs/api/helpers.md b/docs/api/helpers.md index 3996a8b..a81ad24 100644 --- a/docs/api/helpers.md +++ b/docs/api/helpers.md @@ -22,16 +22,23 @@ from swgoh_comlink.helpers import DataItems comlink = SwgohComlink() -# Single collection -units = comlink.get_game_data(items=DataItems.UNITS) +# Single segment (server-accepted) +segment1 = comlink.get_game_data(items=DataItems.SEGMENT1) -# Multiple collections via addition -data = comlink.get_game_data(items=DataItems.SKILL + DataItems.EQUIPMENT) +# Multiple segments combined +data = comlink.get_game_data(items=DataItems.SEGMENT1 + DataItems.SEGMENT2) # All collections everything = comlink.get_game_data(items=DataItems.ALL) ``` +!!! note + Comlink servers validate `items` against the server-side `GameDataItemsEnum`. They + accept the `SEGMENT1`–`SEGMENT4` aggregates and `DataItems.ALL`, but may reject raw + single-collection bit values (e.g. `DataItems.UNITS`) with an HTTP 400. Prefer the + segment aggregates for `get_game_data()` calls. The single-bit members remain useful + for inspecting / composing custom bitfields and for `Constants.get()` lookups. + Use `DataItems.members()` to list all available member names. ::: swgoh_comlink.helpers._data_items.DataItems diff --git a/docs/migration.md b/docs/migration.md index 782715d..902423c 100644 --- a/docs/migration.md +++ b/docs/migration.md @@ -159,15 +159,17 @@ from swgoh_comlink.helpers import Constants # All three forms still work: Constants.get("UnitDefinitions") # -> '137438953472' (legacy name) Constants.get("UNITS") # -> '137438953472' (DataItems name) -Constants.get("Segment1") # -> '206158430208' (class attribute) +Constants.get("Segment1") # -> '2097151' (class attribute) ``` -**Recommendation:** Prefer using `DataItems` enum values directly for type safety: +**Recommendation:** Prefer using `DataItems` enum values directly for type safety, and +use the segment aggregates (`SEGMENT1`–`SEGMENT4`) when calling `get_game_data()` — see +[GameDataItems server alignment](#9-gamedataitems-server-alignment) below: ```python from swgoh_comlink.helpers import DataItems -items = DataItems.UNITS | DataItems.CATEGORY +items = DataItems.SEGMENT1 + DataItems.SEGMENT2 data = comlink.get_game_data(items=items) ``` @@ -263,6 +265,41 @@ default to `None`. brackets in parallel batches via `asyncio.gather`. No code changes are needed on your side — the return format is identical. +## 9. GameDataItems server alignment + +`DataItems` and `Constants` were re-synced against the live `GameDataItemsEnum` that +`get_enums()` now exposes. Two practical impacts: + +**`Segment2` and `Segment4` aggregate values changed.** If you hardcoded the integers +in your own code (rather than referencing the constants by name), update them: + +| Constant | Old value | New value | +|----------|-----------|-----------| +| `DataItems.SEGMENT2` / `Constants.Segment2` | `68717379584` | `1125968624222208` | +| `DataItems.SEGMENT4` / `Constants.Segment4` | `281200098803712` | `3377424842620928` | + +`SEGMENT1` (`2097151`) and `SEGMENT3` (`206158430208`) are unchanged. + +Code that references the constant by name (`DataItems.SEGMENT2`, `Constants.Segment2`, +`Constants.get("Segment2")`) picks up the new values automatically. + +**`get_game_data(items=...)` now requires server-accepted values.** Comlink servers +validate `items` against the server-side `GameDataItemsEnum` and may reject raw +single-collection bit values with an HTTP 400. Prefer the `SEGMENT1`–`SEGMENT4` +aggregates and `DataItems.ALL`: + +```diff +- comlink.get_game_data(items=DataItems.UNITS) ++ comlink.get_game_data(items=DataItems.SEGMENT1) +``` + +The single-bit `DataItems` members (e.g. `UNITS`, `SKILL`, `EQUIPMENT`) remain useful +for inspecting / composing custom bitfields and for `Constants.get()` lookups. + +**New members added** (from the live `GameDataItemsEnum`): `ABILITY_DECISION_TREE`, +`ERA_DEFINITION`, `UBS_UPDATE`. New legacy-name aliases: `AbilityDecisionTrees`, +`EraDefinitions`, `UBSUpdate`, `EpisodeDefinitions` (plural), `AccountLinking`. + ## Summary of changes | Area | Before (v1.x) | After | @@ -281,3 +318,6 @@ default to `None`. | `get_gac_brackets(limit=)` | Sentinel default | `int` default `0` (0 = no limit) | | GAC bracket scanning | Linear O(n) | Exponential probe + binary search O(log n) | | Migration checker | Not available | `swgoh-migrate` CLI / `python -m swgoh_comlink.migrate` | +| `DataItems.SEGMENT2` value | `68717379584` | `1125968624222208` (server-aligned) | +| `DataItems.SEGMENT4` value | `281200098803712` | `3377424842620928` (server-aligned) | +| `get_game_data(items=)` single-bit values | Accepted | Rejected (HTTP 400); use segment aggregates | diff --git a/examples/Async/get_game_data.py b/examples/Async/get_game_data.py index 4003bef..8cf489c 100644 --- a/examples/Async/get_game_data.py +++ b/examples/Async/get_game_data.py @@ -7,7 +7,7 @@ import asyncio from swgoh_comlink import SwgohComlinkAsync -from swgoh_comlink.helpers import Constants +from swgoh_comlink.helpers import Constants, DataItems async def main(): @@ -16,13 +16,15 @@ async def main(): # Retrieve all of the available game data game_data = await cl.get_game_data(items="ALL") - # Alternatively, retrieve only the unit information collection - unit_data = await cl.get_game_data(items="UnitDefinitions") + # Retrieve a single segment. The Comlink server validates `items` against its + # GameDataItemsEnum and accepts the Segment1-4 aggregates; raw single-collection + # bit values (e.g. DataItems.UNITS) may be rejected with an HTTP 400. + segment1_data = await cl.get_game_data(items=DataItems.SEGMENT1) - # This is the same call as above but without the PVE units - unit_data_no_pve = await cl.get_game_data(items="UnitDefinitions", include_pve_units=False) + # The same call without the PVE units + segment1_no_pve = await cl.get_game_data(items=DataItems.SEGMENT1, include_pve_units=False) - # If you want to get more than one collection at once, simply combine the collection values + # Combine segments to request multiple collections at once game_data_segments_1_and_2 = await cl.get_game_data(items=Constants.Segment1 + Constants.Segment2) # Note that the 'items' and legacy 'request_segment' parameters are mutually exclusive. diff --git a/examples/Sync/get_game_data.py b/examples/Sync/get_game_data.py index cc8565c..8d96b56 100644 --- a/examples/Sync/get_game_data.py +++ b/examples/Sync/get_game_data.py @@ -5,7 +5,7 @@ """ from swgoh_comlink import SwgohComlink -from swgoh_comlink.helpers import Constants +from swgoh_comlink.helpers import Constants, DataItems # Create an instance of SwgohComlink cl = SwgohComlink() @@ -13,13 +13,15 @@ # Retrieve all of the available game data game_data = cl.get_game_data(items="ALL") -# Alternatively, retrieve only the unit information collection -unit_data = cl.get_game_data(items="UnitDefinitions") +# Retrieve a single segment. The Comlink server validates `items` against its +# GameDataItemsEnum and accepts the Segment1-4 aggregates; raw single-collection +# bit values (e.g. DataItems.UNITS) may be rejected with an HTTP 400. +segment1_data = cl.get_game_data(items=DataItems.SEGMENT1) -# This is the same call as above but without the PVE units -unit_data_no_pve = cl.get_game_data(items="UnitDefinitions", include_pve_units=False) +# The same call without the PVE units +segment1_no_pve = cl.get_game_data(items=DataItems.SEGMENT1, include_pve_units=False) -# If you want to get more than one collection at once, simply combine the collection values +# Combine segments to request multiple collections at once game_data_segments_1_and_2 = cl.get_game_data(items=Constants.Segment1 + Constants.Segment2) # Note that the 'items' and legacy 'request_segment' parameters are mutually exclusive. diff --git a/src/swgoh_comlink/helpers/_data_items.py b/src/swgoh_comlink/helpers/_data_items.py index ca7c4c5..4cef96a 100644 --- a/src/swgoh_comlink/helpers/_data_items.py +++ b/src/swgoh_comlink/helpers/_data_items.py @@ -16,9 +16,14 @@ class DataItems(IntFlag): more than one collection in a single call. Examples: - effect = comlink.get_game_data(items=DataItems.EFFECT) - skill_equipment = comlink.get_game_data(items=(DataItems.SKILL + DataItems.EQUIPMENT)) - units_no_pve = comlink.get_game_data(items=DataItems.UNITS, include_pve_units=False) + segment1 = comlink.get_game_data(items=DataItems.SEGMENT1) + segments_1_and_2 = comlink.get_game_data(items=(DataItems.SEGMENT1 + DataItems.SEGMENT2)) + segment3_no_pve = comlink.get_game_data(items=DataItems.SEGMENT3, include_pve_units=False) + + Note: + Comlink servers validate `items` against the server-side `GameDataItemsEnum` and may reject + raw single-collection bit values (e.g. `DataItems.UNITS`) with an HTTP 400. The `SEGMENT1`– + `SEGMENT4` aggregates (and `DataItems.ALL`) are the values the server explicitly accepts. Some of the DataItems members are actually aliases for other members. For example, the `TABLE` member is an alias for the `XP_TABLE` member. This is done because both members represent the same collection in the game data.