feat: add gen codes (generate, toGenCode, parseGenCode, genCodeFromLink)

Author: vlydev

cs2_inspect/gen_codes.py

@@ -0,0 +1,194 @@
+"""Gen code utilities for CS2 inspect links.
+
+Gen codes are space-separated command strings used on community servers:
+    !gen {defindex} {paintindex} {paintseed} {paintwear}
+    !gen {defindex} {paintindex} {paintseed} {paintwear} {s0_id} {s0_wear} ... {s4_id} {s4_wear} [{kc_id} {kc_wear} ...]
+
+Stickers are always represented as 5 slot pairs (padded with 0 0 for empty slots).
+Keychains follow stickers without padding.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from .models import ItemPreviewData, Sticker
+
+INSPECT_BASE = "steam://rungame/730/76561202255233023/+csgo_econ_action_preview%20"
+
+
+def _format_float(value: float, precision: int = 8) -> str:
+    """Format float, stripping trailing zeros up to 8 decimal places."""
+    formatted = f"{value:.{precision}f}".rstrip("0").rstrip(".")
+    return formatted or "0"
+
+
+def _serialize_sticker_pairs(stickers: list[Sticker], pad_to: Optional[int] = None) -> list[str]:
+    """Serialize stickers to pairs of [id, wear], optionally padding to fixed number of slots."""
+    result: list[str] = []
+    filtered = [s for s in stickers if s.sticker_id != 0]
+
+    if pad_to is not None:
+        slot_map = {s.slot: s for s in filtered}
+        for slot in range(pad_to):
+            s = slot_map.get(slot)
+            if s:
+                result.append(str(s.sticker_id))
+                result.append(_format_float(float(s.wear) if s.wear is not None else 0.0))
+            else:
+                result.extend(["0", "0"])
+    else:
+        for s in sorted(filtered, key=lambda x: x.slot):
+            result.append(str(s.sticker_id))
+            result.append(_format_float(float(s.wear) if s.wear is not None else 0.0))
+
+    return result
+
+
+def to_gen_code(item: ItemPreviewData, prefix: str = "!gen") -> str:
+    """Convert an ItemPreviewData to a gen code string.
+
+    Args:
+        item: The item to convert.
+        prefix: The command prefix, e.g. ``"!gen"`` or ``"!g"``.
+
+    Returns:
+        A space-separated gen code string like ``"!gen 7 474 306 0.22540508"``.
+    """
+    wear_str = _format_float(float(item.paintwear)) if item.paintwear is not None else "0"
+    parts = [
+        str(item.defindex),
+        str(item.paintindex),
+        str(item.paintseed),
+        wear_str,
+    ]
+
+    has_stickers = any(s.sticker_id != 0 for s in item.stickers)
+    has_keychains = any(s.sticker_id != 0 for s in item.keychains)
+
+    if has_stickers or has_keychains:
+        parts.extend(_serialize_sticker_pairs(item.stickers, pad_to=5))
+        parts.extend(_serialize_sticker_pairs(item.keychains))
+
+    payload = " ".join(parts)
+    return f"{prefix} {payload}" if prefix else payload
+
+
+def generate(
+    def_index: int,
+    paint_index: int,
+    paint_seed: int,
+    paint_wear: float,
+    *,
+    rarity: int = 0,
+    quality: int = 0,
+    stickers: Optional[list[Sticker]] = None,
+    keychains: Optional[list[Sticker]] = None,
+) -> str:
+    """Generate a full Steam inspect URL from item parameters.
+
+    Args:
+        def_index: Weapon definition ID (e.g. 7 = AK-47).
+        paint_index: Skin/paint ID.
+        paint_seed: Pattern index (0-1000).
+        paint_wear: Float value (0.0-1.0).
+        rarity: Item rarity tier (0-7).
+        quality: Item quality (e.g. 9 = StatTrak).
+        stickers: List of Sticker objects applied to the item.
+        keychains: List of Sticker objects used as keychains.
+
+    Returns:
+        A full ``steam://rungame/...`` inspect URL.
+    """
+    from .inspect_link import serialize
+
+    data = ItemPreviewData(
+        defindex=def_index,
+        paintindex=paint_index,
+        paintseed=paint_seed,
+        paintwear=paint_wear,
+        rarity=rarity,
+        quality=quality,
+        stickers=stickers or [],
+        keychains=keychains or [],
+    )
+    hex_str = serialize(data)
+    return f"{INSPECT_BASE}{hex_str}"
+
+
+def gen_code_from_link(hex_or_url: str, prefix: str = "!gen") -> str:
+    """Generate a gen code string from an existing CS2 inspect link.
+
+    Deserializes the inspect link and converts the item data to gen code format.
+
+    Args:
+        hex_or_url: A hex payload or full steam:// inspect URL.
+        prefix: The command prefix, e.g. ``"!gen"`` or ``"!g"``.
+
+    Returns:
+        A gen code string like ``"!gen 7 474 306 0.22540508"``.
+    """
+    from .inspect_link import deserialize
+    item = deserialize(hex_or_url)
+    return to_gen_code(item, prefix)
+
+
+def parse_gen_code(gen_code: str) -> ItemPreviewData:
+    """Parse a gen code string into an ItemPreviewData.
+
+    Accepts codes like:
+        ``"!gen 7 474 306 0.22540508"``
+        ``"7 941 2 0.22540508 0 0 0 0 7203 0 0 0 0 0 36 0"``
+
+    Args:
+        gen_code: The gen code string to parse.
+
+    Returns:
+        An :class:`ItemPreviewData` with the parsed values.
+
+    Raises:
+        ValueError: If the code has fewer than 4 numeric tokens.
+    """
+    tokens = gen_code.strip().split()
+    # Skip leading !-prefixed command (e.g. !gen, !g)
+    if tokens and tokens[0].startswith("!"):
+        tokens = tokens[1:]
+
+    if len(tokens) < 4:
+        raise ValueError(
+            f"Gen code must have at least 4 tokens (defindex paintindex paintseed paintwear), got: {gen_code!r}"
+        )
+
+    def_index = int(tokens[0])
+    paint_index = int(tokens[1])
+    paint_seed = int(tokens[2])
+    paint_wear = float(tokens[3])
+    rest = tokens[4:]
+
+    stickers: list[Sticker] = []
+    keychains: list[Sticker] = []
+
+    if len(rest) >= 10:
+        # 5 sticker pairs
+        sticker_tokens = rest[:10]
+        for slot in range(5):
+            sid = int(sticker_tokens[slot * 2])
+            wear = float(sticker_tokens[slot * 2 + 1])
+            if sid != 0:
+                stickers.append(Sticker(slot=slot, sticker_id=sid, wear=wear))
+        rest = rest[10:]
+
+    for i in range(0, len(rest) - 1, 2):
+        sid = int(rest[i])
+        wear = float(rest[i + 1])
+        if sid != 0:
+            keychains.append(Sticker(slot=i // 2, sticker_id=sid, wear=wear))
+
+    return ItemPreviewData(
+        defindex=def_index,
+        paintindex=paint_index,
+        paintseed=paint_seed,
+        paintwear=paint_wear,
+        stickers=stickers,
+        keychains=keychains,
+    )

tests/test_gen_codes.py

@@ -0,0 +1,113 @@
+"""Tests for gen code functionality."""
+
+from cs2_inspect import generate, parse_gen_code, to_gen_code
+from cs2_inspect import ItemPreviewData, Sticker
+
+INSPECT_BASE = "steam://rungame/730/76561202255233023/+csgo_econ_action_preview%20"
+
+
+class TestToGenCode:
+    def test_basic_item(self):
+        item = ItemPreviewData(defindex=7, paintindex=474, paintseed=306,
+                               paintwear=0.22540508210659027)
+        code = to_gen_code(item)
+        assert code == "!gen 7 474 306 0.22540508"
+
+    def test_custom_prefix(self):
+        item = ItemPreviewData(defindex=7, paintindex=474, paintseed=306,
+                               paintwear=0.22540508210659027)
+        code = to_gen_code(item, prefix="!g")
+        assert code == "!g 7 474 306 0.22540508"
+
+    def test_with_sticker_in_slot_2(self):
+        item = ItemPreviewData(
+            defindex=7, paintindex=941, paintseed=2,
+            paintwear=0.22540508210659027,
+            stickers=[Sticker(slot=2, sticker_id=7203, wear=0.0)],
+        )
+        code = to_gen_code(item, prefix="!g")
+        assert code == "!g 7 941 2 0.22540508 0 0 0 0 7203 0 0 0 0 0"
+
+    def test_with_sticker_and_keychain(self):
+        item = ItemPreviewData(
+            defindex=7, paintindex=941, paintseed=2,
+            paintwear=0.22540508210659027,
+            stickers=[Sticker(slot=2, sticker_id=7203, wear=0.0)],
+            keychains=[Sticker(slot=0, sticker_id=36, wear=0.0)],
+        )
+        code = to_gen_code(item, prefix="!g")
+        assert code == "!g 7 941 2 0.22540508 0 0 0 0 7203 0 0 0 0 0 36 0"
+
+    def test_zero_wear_float_format(self):
+        item = ItemPreviewData(defindex=7, paintindex=474, paintseed=306,
+                               paintwear=0.0)
+        code = to_gen_code(item)
+        assert code == "!gen 7 474 306 0"
+
+
+class TestParseGenCode:
+    def test_basic_parse(self):
+        item = parse_gen_code("!gen 7 474 306 0.22540508")
+        assert item.defindex == 7
+        assert item.paintindex == 474
+        assert item.paintseed == 306
+        assert abs(item.paintwear - 0.22540508) < 1e-6
+
+    def test_parse_without_prefix(self):
+        item = parse_gen_code("7 474 306 0.22540508")
+        assert item.defindex == 7
+
+    def test_parse_with_sticker(self):
+        item = parse_gen_code("!gen 7 941 2 0.22540508 0 0 0 0 7203 0 0 0 0 0")
+        assert len(item.stickers) == 1
+        assert item.stickers[0].slot == 2
+        assert item.stickers[0].sticker_id == 7203
+
+    def test_parse_with_sticker_and_keychain(self):
+        item = parse_gen_code("!g 7 941 2 0.22540508 0 0 0 0 7203 0 0 0 0 0 36 0")
+        assert len(item.stickers) == 1
+        assert item.stickers[0].sticker_id == 7203
+        assert len(item.keychains) == 1
+        assert item.keychains[0].sticker_id == 36
+
+
+class TestGenCodeFromLink:
+    def test_from_hex(self):
+        from cs2_inspect import generate, gen_code_from_link
+        url = generate(7, 474, 306, 0.22540508)
+        hex_payload = url.split("csgo_econ_action_preview%20")[1]
+        code = gen_code_from_link(hex_payload)
+        assert code.startswith("!gen 7 474 306")
+
+    def test_from_full_url(self):
+        from cs2_inspect import generate, gen_code_from_link
+        url = generate(7, 474, 306, 0.22540508)
+        code = gen_code_from_link(url)
+        assert code.startswith("!gen 7 474 306")
+
+
+class TestGenerate:
+    def test_returns_inspect_url(self):
+        url = generate(7, 474, 306, 0.22540508)
+        assert url.startswith(INSPECT_BASE)
+
+    def test_roundtrip(self):
+        from cs2_inspect import deserialize
+        url = generate(7, 474, 306, 0.22540508)
+        # Extract hex payload and deserialize
+        hex_payload = url.split(INSPECT_BASE)[1]
+        item = deserialize(hex_payload)
+        assert item.defindex == 7
+        assert item.paintindex == 474
+        assert item.paintseed == 306
+        assert item.paintwear is not None
+        assert abs(item.paintwear - 0.22540508) < 1e-5
+
+    def test_with_stickers(self):
+        from cs2_inspect import deserialize
+        stickers = [Sticker(slot=0, sticker_id=123, wear=0.1)]
+        url = generate(7, 474, 306, 0.22540508, stickers=stickers)
+        hex_payload = url.split(INSPECT_BASE)[1]
+        item = deserialize(hex_payload)
+        assert len(item.stickers) == 1
+        assert item.stickers[0].sticker_id == 123