humblebundle.py 0.1.0__tar.gz → 0.2.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.
Files changed (26) hide show
  1. humblebundle_py-0.2.0/PKG-INFO +111 -0
  2. humblebundle_py-0.2.0/README.md +94 -0
  3. humblebundle_py-0.2.0/humblebundle/__init__.py +31 -0
  4. humblebundle_py-0.2.0/humblebundle/__main__.py +70 -0
  5. humblebundle_py-0.2.0/humblebundle/_get.py +382 -0
  6. humblebundle_py-0.2.0/humblebundle/_rsc.py +280 -0
  7. humblebundle_py-0.2.0/humblebundle/api.py +193 -0
  8. humblebundle_py-0.2.0/humblebundle/get.py +20 -0
  9. humblebundle_py-0.2.0/humblebundle/logger.py +82 -0
  10. humblebundle_py-0.2.0/humblebundle.py.egg-info/PKG-INFO +111 -0
  11. {humblebundle.py-0.1.0 → humblebundle_py-0.2.0}/humblebundle.py.egg-info/SOURCES.txt +3 -0
  12. humblebundle_py-0.2.0/humblebundle.py.egg-info/requires.txt +1 -0
  13. humblebundle_py-0.2.0/setup.py +51 -0
  14. humblebundle.py-0.1.0/PKG-INFO +0 -16
  15. humblebundle.py-0.1.0/README.md +0 -1
  16. humblebundle.py-0.1.0/humblebundle/__init__.py +0 -15
  17. humblebundle.py-0.1.0/humblebundle/__main__.py +0 -0
  18. humblebundle.py-0.1.0/humblebundle/api.py +0 -37
  19. humblebundle.py-0.1.0/humblebundle/get.py +0 -161
  20. humblebundle.py-0.1.0/humblebundle.py.egg-info/PKG-INFO +0 -16
  21. humblebundle.py-0.1.0/humblebundle.py.egg-info/requires.txt +0 -1
  22. humblebundle.py-0.1.0/setup.py +0 -31
  23. {humblebundle.py-0.1.0 → humblebundle_py-0.2.0}/LICENSE.txt +0 -0
  24. {humblebundle.py-0.1.0 → humblebundle_py-0.2.0}/humblebundle.py.egg-info/dependency_links.txt +0 -0
  25. {humblebundle.py-0.1.0 → humblebundle_py-0.2.0}/humblebundle.py.egg-info/top_level.txt +0 -0
  26. {humblebundle.py-0.1.0 → humblebundle_py-0.2.0}/setup.cfg +0 -0
@@ -0,0 +1,111 @@
1
+ Metadata-Version: 2.1
2
+ Name: humblebundle.py
3
+ Version: 0.2.0
4
+ Summary: HumbleBundle.com unofficial web interaction.
5
+ Author: ghostapps
6
+ Project-URL: Source, https://github.com/markemicek/humblebundle.py
7
+ Keywords: python,humblebundle,games,webapi
8
+ Classifier: Development Status :: 4 - Beta
9
+ Classifier: Intended Audience :: Developers
10
+ Classifier: Programming Language :: Python :: 3
11
+ Classifier: Operating System :: Unix
12
+ Classifier: Operating System :: MacOS :: MacOS X
13
+ Classifier: Operating System :: Microsoft :: Windows
14
+ Requires-Python: >=3.8
15
+ Description-Content-Type: text/markdown
16
+ License-File: LICENSE.txt
17
+
18
+ # humblebundle.py
19
+
20
+ Unofficial Python client for [humblebundle.com](https://www.humblebundle.com).
21
+ List live bundles, open a bundle to get the games/books/software inside it, and
22
+ pull this month's Humble Choice games — without a browser.
23
+
24
+ ```bash
25
+ pip install humblebundle.py
26
+ ```
27
+
28
+ ## Usage
29
+
30
+ ```python
31
+ import humblebundle
32
+
33
+ # Live bundles per category: games, books, software, bundles/all
34
+ bundles = humblebundle.get.bundles(['games'])
35
+
36
+ for bundle in bundles.values():
37
+ print(bundle.title, bundle.price, bundle.end_date)
38
+ print(bundle.included_item_titles[:3])
39
+
40
+ # Open a bundle and get the items inside it
41
+ items = bundles['survivalfittest_bundle'].stepin()
42
+ for item in items.values():
43
+ print(item.title, item.msrp, item.developers, item.publishers)
44
+ ```
45
+
46
+ ```python
47
+ import humblebundle
48
+
49
+ # A single bundle by slug or URL
50
+ bundle = humblebundle.get.bundle('survival-fittest')
51
+ print(bundle.title, bundle.retail_value, len(bundle.tiers))
52
+
53
+ # This month's Humble Choice games
54
+ choices = humblebundle.get.choices()
55
+ for game in choices.values():
56
+ print(game.title, game.developers, game.price, game.end_date)
57
+ ```
58
+
59
+ Products are `_Product` objects: every field is available as an attribute, the
60
+ untouched source object is kept in `.raw`, and the object is mapping-like too
61
+ (`product['title']`, `product.to_dict()`, `dict(product)`).
62
+
63
+ ### Common fields
64
+
65
+ | Field | Description |
66
+ | --- | --- |
67
+ | `name` | Machine key of the product |
68
+ | `title` | Display title |
69
+ | `url` / `product_url` | Absolute product URL (bundles) |
70
+ | `price` | Current price, as a float in `currency` |
71
+ | `retail_value` | Total value of the contents |
72
+ | `items_count` | Number of items in the bundle |
73
+ | `included_item_titles` | Titles of the items in the bundle |
74
+ | `platforms` / `delivery_methods` | e.g. `windows`, `steam` |
75
+ | `start_date` / `end_date` | ISO-8601 timestamps |
76
+ | `developers` / `publishers` | Names (bundle items and Choice games) |
77
+ | `raw` | The full source object |
78
+
79
+ ## Command line
80
+
81
+ ```bash
82
+ python -m humblebundle bundles games
83
+ python -m humblebundle bundle survival-fittest
84
+ python -m humblebundle items games survival-fittest
85
+ python -m humblebundle choices
86
+ ```
87
+
88
+ Each command prints JSON.
89
+
90
+ ## How it works
91
+
92
+ Humble Bundle moved to a Next.js (App Router) front end. Page data is no longer
93
+ published in `<script type="application/json">` islands; it is streamed inside
94
+ the React Server Components "flight" payload embedded in the HTML.
95
+
96
+ `humblebundle._rsc` extracts that payload, splits it into rows and resolves the
97
+ `"$<row-id>"` / `"$<row-id>:<path>"` references the format uses, so the rest of
98
+ the package only deals with plain dictionaries and lists.
99
+
100
+ ## Notes
101
+
102
+ - Only public page data is read; no login or account access is used.
103
+ - The current Humble Choice month is the only one available — Humble removed the
104
+ per-month pages, so `choices()` accepts (and ignores) `month`/`year`.
105
+ - humblebundle.com asks automated clients to be respectful; keep request volume
106
+ low and cache results in your own code.
107
+ - This project is not affiliated with Humble Bundle.
108
+
109
+ ## License
110
+
111
+ MIT — see [LICENSE.txt](LICENSE.txt).
@@ -0,0 +1,94 @@
1
+ # humblebundle.py
2
+
3
+ Unofficial Python client for [humblebundle.com](https://www.humblebundle.com).
4
+ List live bundles, open a bundle to get the games/books/software inside it, and
5
+ pull this month's Humble Choice games — without a browser.
6
+
7
+ ```bash
8
+ pip install humblebundle.py
9
+ ```
10
+
11
+ ## Usage
12
+
13
+ ```python
14
+ import humblebundle
15
+
16
+ # Live bundles per category: games, books, software, bundles/all
17
+ bundles = humblebundle.get.bundles(['games'])
18
+
19
+ for bundle in bundles.values():
20
+ print(bundle.title, bundle.price, bundle.end_date)
21
+ print(bundle.included_item_titles[:3])
22
+
23
+ # Open a bundle and get the items inside it
24
+ items = bundles['survivalfittest_bundle'].stepin()
25
+ for item in items.values():
26
+ print(item.title, item.msrp, item.developers, item.publishers)
27
+ ```
28
+
29
+ ```python
30
+ import humblebundle
31
+
32
+ # A single bundle by slug or URL
33
+ bundle = humblebundle.get.bundle('survival-fittest')
34
+ print(bundle.title, bundle.retail_value, len(bundle.tiers))
35
+
36
+ # This month's Humble Choice games
37
+ choices = humblebundle.get.choices()
38
+ for game in choices.values():
39
+ print(game.title, game.developers, game.price, game.end_date)
40
+ ```
41
+
42
+ Products are `_Product` objects: every field is available as an attribute, the
43
+ untouched source object is kept in `.raw`, and the object is mapping-like too
44
+ (`product['title']`, `product.to_dict()`, `dict(product)`).
45
+
46
+ ### Common fields
47
+
48
+ | Field | Description |
49
+ | --- | --- |
50
+ | `name` | Machine key of the product |
51
+ | `title` | Display title |
52
+ | `url` / `product_url` | Absolute product URL (bundles) |
53
+ | `price` | Current price, as a float in `currency` |
54
+ | `retail_value` | Total value of the contents |
55
+ | `items_count` | Number of items in the bundle |
56
+ | `included_item_titles` | Titles of the items in the bundle |
57
+ | `platforms` / `delivery_methods` | e.g. `windows`, `steam` |
58
+ | `start_date` / `end_date` | ISO-8601 timestamps |
59
+ | `developers` / `publishers` | Names (bundle items and Choice games) |
60
+ | `raw` | The full source object |
61
+
62
+ ## Command line
63
+
64
+ ```bash
65
+ python -m humblebundle bundles games
66
+ python -m humblebundle bundle survival-fittest
67
+ python -m humblebundle items games survival-fittest
68
+ python -m humblebundle choices
69
+ ```
70
+
71
+ Each command prints JSON.
72
+
73
+ ## How it works
74
+
75
+ Humble Bundle moved to a Next.js (App Router) front end. Page data is no longer
76
+ published in `<script type="application/json">` islands; it is streamed inside
77
+ the React Server Components "flight" payload embedded in the HTML.
78
+
79
+ `humblebundle._rsc` extracts that payload, splits it into rows and resolves the
80
+ `"$<row-id>"` / `"$<row-id>:<path>"` references the format uses, so the rest of
81
+ the package only deals with plain dictionaries and lists.
82
+
83
+ ## Notes
84
+
85
+ - Only public page data is read; no login or account access is used.
86
+ - The current Humble Choice month is the only one available — Humble removed the
87
+ per-month pages, so `choices()` accepts (and ignores) `month`/`year`.
88
+ - humblebundle.com asks automated clients to be respectful; keep request volume
89
+ low and cache results in your own code.
90
+ - This project is not affiliated with Humble Bundle.
91
+
92
+ ## License
93
+
94
+ MIT — see [LICENSE.txt](LICENSE.txt).
@@ -0,0 +1,31 @@
1
+ """
2
+ HumbleBundle Unofficial Client
3
+
4
+ This package provides a client interface to interact with the HumbleBundle
5
+ website. It retrieves bundle listings, the items inside a bundle, and the
6
+ current month's Humble Choice games.
7
+
8
+ Modules:
9
+ get: Bundle and Humble Choice helpers.
10
+
11
+ Usage:
12
+ import humblebundle
13
+
14
+ bundles = humblebundle.get.bundles(['games'])
15
+ items = bundles['survivalfittest_bundle'].stepin()
16
+ choices = humblebundle.get.choices()
17
+ """
18
+ from . import get
19
+ from ._get import bundle, bundles, choices
20
+ from .api import HumbleBundleError
21
+
22
+ __version__ = "0.2.0"
23
+
24
+ __all__ = [
25
+ "get",
26
+ "bundles",
27
+ "bundle",
28
+ "choices",
29
+ "HumbleBundleError",
30
+ "__version__",
31
+ ]
@@ -0,0 +1,70 @@
1
+ """
2
+ Command line interface.
3
+
4
+ Examples:
5
+ python -m humblebundle bundles games
6
+ python -m humblebundle choices
7
+ python -m humblebundle items games survival-fittest
8
+ """
9
+
10
+ import argparse
11
+ import json
12
+ import sys
13
+
14
+ import humblebundle
15
+
16
+
17
+ def _dump(products):
18
+ """Render a mapping of products as JSON."""
19
+ data = {name: product.to_dict() for name, product in products.items()}
20
+ print(json.dumps(data, indent=2, default=str))
21
+
22
+
23
+ def main(argv=None):
24
+ """Entry point for ``python -m humblebundle``."""
25
+ parser = argparse.ArgumentParser(
26
+ prog="humblebundle",
27
+ description="Query humblebundle.com from the command line.",
28
+ )
29
+ parser.add_argument(
30
+ "command",
31
+ choices=["bundles", "bundle", "items", "choices"],
32
+ help=(
33
+ "bundles: list live bundles; bundle: one bundle; "
34
+ "items: the items inside a bundle; choices: this month's Humble Choice"
35
+ ),
36
+ )
37
+ parser.add_argument(
38
+ "args",
39
+ nargs="*",
40
+ help="bundles: categories (default games). bundle/items: a bundle slug.",
41
+ )
42
+ options = parser.parse_args(argv)
43
+
44
+ if options.command == "choices":
45
+ _dump(humblebundle.get.choices())
46
+ return 0
47
+
48
+ if options.command == "bundles":
49
+ _dump(humblebundle.get.bundles(options.args or ["games"]))
50
+ return 0
51
+
52
+ if not options.args:
53
+ parser.error(f"{options.command} needs a bundle slug")
54
+
55
+ slug = options.args[-1]
56
+ product = humblebundle.get.bundle(slug)
57
+ if product is None:
58
+ print(f"no data for {slug}", file=sys.stderr)
59
+ return 1
60
+
61
+ if options.command == "bundle":
62
+ _dump({slug: product})
63
+ return 0
64
+
65
+ _dump(product.stepin() or {})
66
+ return 0
67
+
68
+
69
+ if __name__ == "__main__":
70
+ raise SystemExit(main())
@@ -0,0 +1,382 @@
1
+ """
2
+ Public helpers that turn humblebundle.com pages into ``_Product`` objects.
3
+
4
+ Everything here is built from the data humblebundle.com publishes today:
5
+
6
+ * category pages (``/games``, ``/books``, ``/software``, ``/bundles``) expose a
7
+ ``feedItems`` list;
8
+ * a single bundle page exposes ``tiers`` -> ``bundleItems``;
9
+ * ``/membership`` exposes this month's Humble Choice games through
10
+ ``subscriptionProducts``.
11
+
12
+ The old ``landingPage-json-data`` / ``webpack-monthly-product-data`` /
13
+ ``webpack-bundle-page-data`` JSON islands the previous releases parsed no longer
14
+ exist, so those are gone.
15
+ """
16
+
17
+ import logging
18
+ from typing import Dict, List, Optional
19
+
20
+ from .api import (
21
+ _absolute,
22
+ _get_bundle_games,
23
+ _get_bundles,
24
+ _get_choice,
25
+ _money,
26
+ )
27
+ from .logger import Logger
28
+
29
+ MEMBERSHIP_URL = "https://www.humblebundle.com/membership"
30
+
31
+ DEFAULT_CATEGORIES = ["games"]
32
+
33
+
34
+ def _names(values) -> List[str]:
35
+ """Flatten the ``[{'name': ...}]`` lists the site uses into plain names."""
36
+ names = []
37
+ for value in values or []:
38
+ if isinstance(value, dict):
39
+ name = value.get("name") or value.get("payeeName")
40
+ else:
41
+ name = value
42
+ if name:
43
+ names.append(name)
44
+ return names
45
+
46
+
47
+ def _media_urls(carousel) -> List[str]:
48
+ """Flatten a bundle item carousel into a list of image/video URLs."""
49
+ urls = []
50
+ for entry in carousel or []:
51
+ if isinstance(entry, dict):
52
+ url = entry.get("imageUrl") or entry.get("videoUrl")
53
+ else:
54
+ url = entry
55
+ if url:
56
+ urls.append(url)
57
+ return urls
58
+
59
+
60
+ class _Product:
61
+ """
62
+ A bundle, an item inside a bundle, or a Humble Choice game.
63
+
64
+ Every field humblebundle.com publishes for the product is exposed as an
65
+ attribute, and the untouched source object is kept in :attr:`raw`. Instances
66
+ are also mapping-like, so ``product['title']`` and ``dict(product)`` work.
67
+
68
+ Attributes:
69
+ name (str): Machine key of the product.
70
+ raw (dict): The source object this instance was built from.
71
+ """
72
+
73
+ def __init__(self, name, raw=None, **kwargs):
74
+ self.name = name
75
+ self.raw = raw if raw is not None else dict(kwargs)
76
+ for key, value in kwargs.items():
77
+ setattr(self, key, value)
78
+
79
+ def keys(self):
80
+ """Return the attribute names (``raw`` excluded)."""
81
+ return [key for key in vars(self) if key != "raw"]
82
+
83
+ def __getitem__(self, key):
84
+ return getattr(self, key)
85
+
86
+ def to_dict(self):
87
+ """Return the product as a plain dictionary."""
88
+ return {key: getattr(self, key) for key in self.keys()}
89
+
90
+ def __repr__(self):
91
+ title = getattr(self, "title", None) or self.name
92
+ return f"<_Product {title!r}>"
93
+
94
+ @Logger(logging.ERROR)
95
+ def stepin(self):
96
+ """
97
+ Retrieve the items contained in this bundle.
98
+
99
+ Returns:
100
+ Dict[str, _Product]: Item key -> item. Each item carries
101
+ ``title``, ``description``, ``image``, ``msrp``, ``developers``,
102
+ ``publishers``, ``delivery_methods``, ``platforms`` and
103
+ ``media``.
104
+
105
+ Example:
106
+ bundles = humblebundle.get.bundles(['games'])
107
+ items = bundles['survivalfittest_bundle'].stepin()
108
+ print(items['cubicodyssey_survivalfittest_bundle'].title)
109
+ """
110
+ target = getattr(self, "product_url", None) or getattr(self, "slug", None)
111
+ return _bundle_items(target)
112
+
113
+
114
+ def _feed_product(feed_item) -> Optional[_Product]:
115
+ """
116
+ Convert a single ``feedItems`` entry into a :class:`_Product`.
117
+
118
+ Args:
119
+ feed_item (dict): One entry of a category page's ``feedItems`` list.
120
+
121
+ Returns:
122
+ _Product | None: ``None`` when the entry does not describe a product
123
+ (editorial entries share the same list).
124
+ """
125
+ value = (feed_item or {}).get("value")
126
+ if not isinstance(value, dict) or not value.get("title"):
127
+ return None
128
+
129
+ name = value.get("productKey") or value.get("slug") or value.get("id")
130
+ if not name:
131
+ return None
132
+
133
+ price = value.get("displayPrice") or {}
134
+ current_price = price.get("currentPrice") or {}
135
+ url = _absolute(value.get("url"))
136
+ included = list(value.get("includedItemTitles") or [])
137
+
138
+ fields = {
139
+ "id": value.get("id"),
140
+ "product_key": value.get("productKey"),
141
+ "slug": value.get("slug"),
142
+ "title": value.get("title"),
143
+ "url": url,
144
+ "product_url": url,
145
+ "type": value.get("productType"),
146
+ "product_type": value.get("productType"),
147
+ "category": value.get("category"),
148
+ "thumbnail": value.get("thumbnail"),
149
+ "title_image_url": value.get("titleImageUrl"),
150
+ "high_res_tile_image": value.get("titleImageUrl"),
151
+ "tile_logo": value.get("thumbnail"),
152
+ "tile_name": value.get("title"),
153
+ "tile_short_name": value.get("title"),
154
+ "items_count": value.get("itemsCount"),
155
+ "number_of_issues": value.get("numberOfIssues"),
156
+ "included_item_titles": included,
157
+ "highlights": included,
158
+ "platforms": list(value.get("platforms") or []),
159
+ "delivery_methods": list(value.get("deliveryMethods") or []),
160
+ "price": _money(current_price),
161
+ "base_price": _money(price.get("basePrice")),
162
+ "currency": current_price.get("currencyCode"),
163
+ "on_sale": price.get("isSale"),
164
+ "retail_value": _money(value.get("value")),
165
+ "num_sold": value.get("numSold"),
166
+ "bundles_sold": value.get("numSold"),
167
+ "start_date": value.get("startDate"),
168
+ "end_date": value.get("endDate"),
169
+ "detailed_marketing_blurb": value.get("description"),
170
+ "short_marketing_blurb": value.get("tagline") or value.get("tag"),
171
+ }
172
+ return _Product(name, raw=value, **fields)
173
+
174
+
175
+ @Logger(logging.ERROR)
176
+ def _bundle_items(url: str) -> Dict[str, _Product]:
177
+ """
178
+ Retrieve the items inside a bundle.
179
+
180
+ Args:
181
+ url (str): Absolute or relative URL of the bundle page.
182
+
183
+ Returns:
184
+ Dict[str, _Product]: Item key -> item.
185
+ """
186
+ data = _get_bundle_games(url) or {}
187
+ instances = {}
188
+
189
+ for tier in data.get("tiers") or []:
190
+ if not isinstance(tier, dict):
191
+ continue
192
+ for item in tier.get("bundleItems") or []:
193
+ if not isinstance(item, dict):
194
+ # Some bundles reference an item already listed in another tier.
195
+ continue
196
+ name = item.get("key") or item.get("id")
197
+ if not name:
198
+ continue
199
+
200
+ msrp = item.get("msrp") if isinstance(item.get("msrp"), dict) else {}
201
+ carousel = item.get("carousel") or []
202
+ fields = {
203
+ "title": item.get("title"),
204
+ "Title": item.get("title"),
205
+ "description": item.get("description"),
206
+ "image": item.get("thumbnailImageUrl"),
207
+ "thumbnail": item.get("thumbnailImageUrl"),
208
+ "msrp": _money(msrp),
209
+ "currency": msrp.get("currencyCode"),
210
+ "developers": _names(item.get("developers")),
211
+ "publishers": _names(item.get("publishers")),
212
+ "raw_developers": item.get("developers") or [],
213
+ "raw_publishers": item.get("publishers") or [],
214
+ "delivery_methods": list(item.get("deliveryMethods") or []),
215
+ "platforms": list(item.get("platforms") or []),
216
+ "item_content_type": item.get("bundleType"),
217
+ "bundle_type": item.get("bundleType"),
218
+ "carousel": carousel,
219
+ "media": _media_urls(carousel),
220
+ "youtube_link": None,
221
+ "tpkd_skus": list(item.get("tpkdSkus") or []),
222
+ "tier_id": tier.get("id"),
223
+ "tier_sku": tier.get("sku"),
224
+ }
225
+ instances[name] = _Product(name, raw=item, **fields)
226
+
227
+ return instances
228
+
229
+
230
+ @Logger(logging.ERROR)
231
+ def bundles(bundles: List[str] = None) -> Dict[str, _Product]:
232
+ """
233
+ Retrieve bundle listings from Humble Bundle.
234
+
235
+ Args:
236
+ bundles (list of str | str, optional): Categories to load -- one or more
237
+ of ``'games'``, ``'books'``, ``'software'``, ``'bundles'``/``'all'``.
238
+ Defaults to ``['games']``.
239
+
240
+ Returns:
241
+ Dict[str, _Product]: Product key -> bundle. Each bundle exposes
242
+ ``title``, ``url``, ``price``, ``end_date``, ``items_count``,
243
+ ``included_item_titles`` and the rest of :class:`_Product`, plus
244
+ ``stepin()`` for the items inside it.
245
+
246
+ Example:
247
+ bundles = humblebundle.get.bundles(['games'])
248
+ for bundle in bundles.values():
249
+ print(bundle.title, bundle.price)
250
+ print(bundle.included_item_titles)
251
+ """
252
+ if bundles is None:
253
+ categories = list(DEFAULT_CATEGORIES)
254
+ elif isinstance(bundles, str):
255
+ categories = [bundles]
256
+ else:
257
+ categories = list(bundles)
258
+
259
+ instances = {}
260
+ for category in categories:
261
+ data = _get_bundles(str(category).lower()) or {}
262
+ for feed_item in data.get("feedItems") or []:
263
+ product = _feed_product(feed_item)
264
+ if product is not None:
265
+ instances[product.name] = product
266
+
267
+ return instances
268
+
269
+
270
+ @Logger(logging.ERROR)
271
+ def bundle(slug_or_url: str) -> Optional[_Product]:
272
+ """
273
+ Retrieve a single bundle.
274
+
275
+ Args:
276
+ slug_or_url (str): Bundle slug (``'survival-fittest'``) or full URL.
277
+
278
+ Returns:
279
+ _Product | None: The bundle, including ``description``, ``price``,
280
+ ``end_date`` and its ``tiers`` (see ``raw``), or ``None`` if the page
281
+ could not be read.
282
+ """
283
+ if not slug_or_url:
284
+ return None
285
+
286
+ target = slug_or_url
287
+ if not target.startswith("http"):
288
+ relative = target.lstrip("/")
289
+ if not relative.startswith(("games/", "books/", "software/")):
290
+ relative = f"games/{relative}"
291
+ target = relative
292
+
293
+ data = _get_bundle_games(target)
294
+ if not data:
295
+ return None
296
+
297
+ name = data.get("slug") or slug_or_url
298
+ value = data.get("value") if isinstance(data.get("value"), dict) else {}
299
+ fields = {
300
+ "id": data.get("id"),
301
+ "slug": data.get("slug"),
302
+ "title": data.get("title"),
303
+ "url": _absolute(f"/{data.get('bundleType', 'games')}/{data.get('slug')}"),
304
+ "product_url": _absolute(f"/{data.get('bundleType', 'games')}/{data.get('slug')}"),
305
+ "description": data.get("description"),
306
+ "headline": data.get("headline"),
307
+ "category": data.get("bundleType"),
308
+ "bundle_types": list(data.get("bundleTypes") or []),
309
+ "logo_image_url": data.get("logoImageUrl"),
310
+ "thumbnail": data.get("thumbnailImageUrl"),
311
+ "title_image_url": data.get("logoImageUrl"),
312
+ "retail_value": _money(value),
313
+ "currency": value.get("currencyCode") if value else None,
314
+ "num_sold": data.get("numSold"),
315
+ "start_date": data.get("startDate"),
316
+ "end_date": data.get("endDate"),
317
+ "tiers": data.get("tiers") or [],
318
+ }
319
+ return _Product(name, raw=data, **fields)
320
+
321
+
322
+ @Logger(logging.ERROR)
323
+ def choices(month: str = None, year: int = None) -> Dict[str, _Product]:
324
+ """
325
+ Retrieve this month's Humble Choice games.
326
+
327
+ Humble Bundle removed the ``/membership/<month>-<year>`` pages, so only the
328
+ current month can be retrieved. ``month`` and ``year`` are still accepted so
329
+ existing call sites keep working.
330
+
331
+ Args:
332
+ month (str, optional): Ignored. Kept for backwards compatibility.
333
+ year (int, optional): Ignored. Kept for backwards compatibility.
334
+
335
+ Returns:
336
+ Dict[str, _Product]: Product key -> game. Each game exposes ``title``,
337
+ ``description``, ``developers``, ``genres``, ``delivery_methods``,
338
+ ``platforms``, ``media`` and ``price``.
339
+
340
+ Example:
341
+ games = humblebundle.get.choices()
342
+ for game in games.values():
343
+ print(game.title, game.developers)
344
+ """
345
+ data = _get_choice(month, year) or {}
346
+ media_items = [item for item in (data.get("mediaItems") or []) if isinstance(item, dict)]
347
+
348
+ instances = {}
349
+ for product in data.get("subscriptionProducts") or []:
350
+ name = product.get("id")
351
+ if not name:
352
+ continue
353
+
354
+ title = product.get("title")
355
+ price = product.get("displayPrice") or {}
356
+ current_price = price.get("currentPrice") or {}
357
+ media = [
358
+ item.get("imageUrl") or item.get("videoUrl")
359
+ for item in media_items
360
+ if item.get("title") == title
361
+ ]
362
+ fields = {
363
+ "title": title,
364
+ "parent_url": MEMBERSHIP_URL,
365
+ "product_url": product.get("url") or MEMBERSHIP_URL,
366
+ "description": product.get("description"),
367
+ "thumbnail": product.get("thumbnail"),
368
+ "price": _money(current_price),
369
+ "currency": current_price.get("currencyCode"),
370
+ "on_sale": price.get("isSale"),
371
+ "developers": _names(product.get("developers")),
372
+ "raw_developers": product.get("developers") or [],
373
+ "genres": list(product.get("genres") or []),
374
+ "delivery_methods": list(product.get("deliveryMethods") or []),
375
+ "platforms": list(product.get("platforms") or []),
376
+ "media": [url for url in media if url],
377
+ "product_type": product.get("productType"),
378
+ "end_date": product.get("endDate"),
379
+ }
380
+ instances[name] = _Product(name, raw=product, **fields)
381
+
382
+ return instances