humblebundle.py 0.2.0__tar.gz → 1.0.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 (55) hide show
  1. humblebundle_py-1.0.0/AGENTS.md +96 -0
  2. humblebundle_py-1.0.0/CHANGELOG.md +121 -0
  3. humblebundle_py-1.0.0/CONTRIBUTING.md +85 -0
  4. {humblebundle_py-0.2.0 → humblebundle_py-1.0.0}/LICENSE.txt +1 -1
  5. humblebundle_py-1.0.0/MANIFEST.in +13 -0
  6. humblebundle_py-1.0.0/PKG-INFO +367 -0
  7. humblebundle_py-1.0.0/README.md +318 -0
  8. humblebundle_py-1.0.0/docs/api.md +265 -0
  9. humblebundle_py-1.0.0/docs/architecture.md +137 -0
  10. humblebundle_py-1.0.0/docs/cli.md +208 -0
  11. humblebundle_py-1.0.0/docs/quickstart.md +225 -0
  12. humblebundle_py-1.0.0/humblebundle/__init__.py +171 -0
  13. humblebundle_py-1.0.0/humblebundle/__main__.py +8 -0
  14. humblebundle_py-1.0.0/humblebundle/_http.py +315 -0
  15. humblebundle_py-1.0.0/humblebundle/_parser.py +494 -0
  16. {humblebundle_py-0.2.0 → humblebundle_py-1.0.0}/humblebundle/_rsc.py +105 -72
  17. humblebundle_py-1.0.0/humblebundle/_values.py +239 -0
  18. humblebundle_py-1.0.0/humblebundle/cli.py +499 -0
  19. humblebundle_py-1.0.0/humblebundle/client.py +894 -0
  20. humblebundle_py-1.0.0/humblebundle/exceptions.py +97 -0
  21. humblebundle_py-1.0.0/humblebundle/get.py +139 -0
  22. humblebundle_py-1.0.0/humblebundle/logger.py +91 -0
  23. humblebundle_py-1.0.0/humblebundle/models.py +2083 -0
  24. humblebundle_py-1.0.0/humblebundle/py.typed +0 -0
  25. humblebundle_py-1.0.0/humblebundle.py.egg-info/PKG-INFO +367 -0
  26. humblebundle_py-1.0.0/humblebundle.py.egg-info/SOURCES.txt +41 -0
  27. humblebundle_py-1.0.0/humblebundle.py.egg-info/entry_points.txt +2 -0
  28. humblebundle_py-1.0.0/humblebundle.py.egg-info/requires.txt +7 -0
  29. humblebundle_py-1.0.0/llms.txt +348 -0
  30. humblebundle_py-1.0.0/pyproject.toml +135 -0
  31. humblebundle_py-1.0.0/setup.py +12 -0
  32. humblebundle_py-1.0.0/tests/conftest.py +82 -0
  33. humblebundle_py-1.0.0/tests/test_cli.py +500 -0
  34. humblebundle_py-1.0.0/tests/test_client.py +371 -0
  35. humblebundle_py-1.0.0/tests/test_get.py +83 -0
  36. humblebundle_py-1.0.0/tests/test_http.py +288 -0
  37. humblebundle_py-1.0.0/tests/test_models.py +172 -0
  38. humblebundle_py-1.0.0/tests/test_rsc.py +140 -0
  39. humblebundle_py-1.0.0/tests/test_store.py +718 -0
  40. humblebundle_py-1.0.0/tests/test_values_logging.py +133 -0
  41. humblebundle_py-0.2.0/PKG-INFO +0 -111
  42. humblebundle_py-0.2.0/README.md +0 -94
  43. humblebundle_py-0.2.0/humblebundle/__init__.py +0 -31
  44. humblebundle_py-0.2.0/humblebundle/__main__.py +0 -70
  45. humblebundle_py-0.2.0/humblebundle/_get.py +0 -382
  46. humblebundle_py-0.2.0/humblebundle/api.py +0 -193
  47. humblebundle_py-0.2.0/humblebundle/get.py +0 -20
  48. humblebundle_py-0.2.0/humblebundle/logger.py +0 -82
  49. humblebundle_py-0.2.0/humblebundle.py.egg-info/PKG-INFO +0 -111
  50. humblebundle_py-0.2.0/humblebundle.py.egg-info/SOURCES.txt +0 -15
  51. humblebundle_py-0.2.0/humblebundle.py.egg-info/requires.txt +0 -1
  52. humblebundle_py-0.2.0/setup.py +0 -51
  53. {humblebundle_py-0.2.0 → humblebundle_py-1.0.0}/humblebundle.py.egg-info/dependency_links.txt +0 -0
  54. {humblebundle_py-0.2.0 → humblebundle_py-1.0.0}/humblebundle.py.egg-info/top_level.txt +0 -0
  55. {humblebundle_py-0.2.0 → humblebundle_py-1.0.0}/setup.cfg +0 -0
@@ -0,0 +1,96 @@
1
+ # AGENTS.md
2
+
3
+ Instructions for AI coding agents working **in this repository**. For instructions
4
+ on *using* the library, read [`llms.txt`](llms.txt) first — it is the compact API
5
+ reference. Human-oriented docs live in [`README.md`](README.md).
6
+
7
+ ## What this project is
8
+
9
+ `humblebundle.py` is an unofficial, typed Python client for humblebundle.com.
10
+ It reads public page data only. Runtime code lives in `humblebundle/`, tests in
11
+ `tests/`.
12
+
13
+ ## Ground rules
14
+
15
+ 1. **No network in tests.** Every test must run offline. Build page fixtures with
16
+ `tests/conftest.py::make_page` / `feed_page` and inject a fake source
17
+ (`FakeSource` or the `source_factory` fixture) into `HumbleBundleClient`.
18
+ Never call the live site from a test.
19
+ 2. **Keep the layers separate.** Each module has exactly one job:
20
+ * `_rsc.py` — Next.js flight payload → plain Python values. No Humble-specific
21
+ knowledge, no model imports.
22
+ * `_parser.py` — locate the blocks (`feedItems`, `tiers.bundleItems`,
23
+ `subscriptionProducts`, `storeLayout`, `products` + `pagination`) inside
24
+ resolved rows.
25
+ * `models.py` — typed, frozen value objects and their `from_*` constructors.
26
+ * `client.py` — orchestration of transport + parser + models. No parsing or
27
+ URL/anomaly logic inline.
28
+ * `_http.py` — transport concerns only (headers, timeout, retries, cookies,
29
+ errors).
30
+ 3. **Models are frozen dataclasses with `slots=True` and `kw_only=True`.**
31
+ Fields must be declared at class level, typed, and carry
32
+ `metadata={"doc": "..."}`, because `describe_models()` (and therefore
33
+ `humblebundle schema`) publishes that metadata to users and AI agents.
34
+ Skip fields from the public surface by prefixing the name with `_` (for
35
+ example `Bundle._client`).
36
+ 4. **`to_dict()` must stay JSON-serialisable.** Route new values through
37
+ `_jsonable()` in `models.py`; never leak datetimes or `Money` objects.
38
+ 5. **All public callables need Google-style docstrings** with `Args`, `Returns`
39
+ and `Raises` where applicable, plus a short runnable example for anything a
40
+ newcomer would call first. Doctest examples that need the network must be
41
+ marked `# doctest: +SKIP`.
42
+ 6. **Errors:** raise from `exceptions.py` only. `FetchError` carries `url` and
43
+ `status_code`. Never swallow exceptions (the old `logger.Logger` decorator
44
+ that did so has been removed on purpose).
45
+ 7. **Logging:** use `logger.get_logger()`; never `print()` in library code, never
46
+ configure handlers outside `logger.configure_logging()`.
47
+ 8. **Compatibility:** `humblebundle.get.*`, the module-level helpers and
48
+ `Bundle.stepin()` are part of the public contract. Deprecate before removing.
49
+ 9. **Python floor is 3.10** (`pyproject.toml`). Keep annotations PEP 604 style
50
+ (`str | None`) with `from __future__ import annotations`.
51
+ 10. **Store search is a POST, not a GET.** It goes through
52
+ `HttpClient.post_text()` (multipart, written with `http.client` because
53
+ Cloudflare rejects `requests`/`urllib3` on that endpoint) and needs the
54
+ Next.js server-action id from `_parser.search_action_from_script()`. Never
55
+ "fix" this by switching the search call back to `requests`; check the live
56
+ site first and keep the id cache/override (`store_search_action=`).
57
+ 11. **Age gates are answered with a cookie**
58
+ (`HttpClient.set_cookie("age_gate_verified_birthdate", ...)`), then the page
59
+ is re-fetched. Tests must cover both the unlocked page and the
60
+ `AgeVerificationError` path.
61
+
62
+ ## When the site changes
63
+
64
+ Symptoms: `PageDataError` / `BundleNotFoundError` / `StoreProductNotFoundError`
65
+ in production, a 403 on store search, or fixtures no longer resembling real
66
+ HTML. Then:
67
+
68
+ 1. Add a *fixture-first* test that reproduces the new payload in
69
+ `tests/conftest.py` style (synthetic HTML with `self.__next_f.push`).
70
+ 2. Fix `_rsc.py` if the flight framing changed, or `_parser.py` if only the
71
+ location/shape of the block changed — prefer `_parser.py`.
72
+ 3. Update `models.py` field mapping in the relevant `from_*` classmethod, keeping
73
+ field names stable (add new fields, deprecate old ones).
74
+ 4. Update `llms.txt` field tables and `CHANGELOG.md`.
75
+
76
+ ## Commands
77
+
78
+ ```bash
79
+ python -m pytest # hermetic suite
80
+ python -m pytest --cov=humblebundle
81
+ python -m ruff check .
82
+ python -m ruff format --check .
83
+ python -m mypy
84
+ ```
85
+
86
+ Release helpers on this machine: `python build_release.py` then
87
+ `pwsh ./publish.ps1` (builds sdist/wheel with setuptools 65 and uploads via
88
+ twine). Version lives in `humblebundle/__init__.py::__version__` and is read by
89
+ `pyproject.toml` (`dynamic = ["version"]`).
90
+
91
+ ## Definition of done
92
+
93
+ - New behaviour has a test that fails without the change.
94
+ - `pytest`, `ruff` and `mypy` are clean.
95
+ - `README.md` / `llms.txt` / `CHANGELOG.md` updated if the public surface moved.
96
+ - `humblebundle schema` output still describes every model field.
@@ -0,0 +1,121 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project are documented here. The format follows
4
+ [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project adheres
5
+ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
6
+
7
+ ## [1.0.0] — 2026-11-19
8
+
9
+ ### Added
10
+
11
+ - `HumbleBundleClient` — one object that owns the HTTP transport and returns
12
+ typed models. Context manager support, configurable timeout, retries with
13
+ exponential backoff, `Retry-After` handling and optional session reuse.
14
+ - `AsyncHumbleBundleClient` — the same API for `asyncio` code.
15
+ - Typed, frozen models: `Bundle`, `BundleItem`, `ChoiceGame`, `Tier`,
16
+ `Money` and `HumbleChoice`. All are mapping-like, JSON-serialisable via
17
+ `to_dict()` and keep the original payload in `.raw`.
18
+ - Humble Store support, following the same structure as the bundle API:
19
+ - `client.store(path_or_url="store")` → `Store` for the landing page, a
20
+ promotion page (`store/page/<slug>`) or a category feed.
21
+ - `client.store_product(slug_or_url)` → `StoreProductDetail` for one product,
22
+ including description, developers, publishers, genres, media, editions,
23
+ distributions, critic reviews, links, ESRB/PEGI ratings, age ratings, system
24
+ requirements and DLC relationships.
25
+ - `client.store_search(query="", page=1, per_page=25, sort=None, genres=None,
26
+ platforms=None, delivery_methods=None)` → `StoreSearch`, with paging
27
+ (`has_next`, `next_page()`, …), sorting and refinement filters.
28
+ - Store models: `Store`, `StoreSection`, `StoreProduct`, `StoreProductDetail`,
29
+ `StorePromotion`, `StoreSearch`, `StoreDistribution`, `StoreEdition`,
30
+ `StoreLink` and `CriticReview`. All are frozen, mapping-like, JSON-safe and
31
+ keep the source payload in `.raw`.
32
+ - `StoreSort` (`RELEVANCE`, `TOP_DISCOUNTS`, `ALPHABETICAL`, `NEWEST`) with
33
+ `coerce()` for strings and aliases.
34
+ - `Store.section(name)`, `Store.sections`, `Store.promotions`,
35
+ `StoreProduct.discount_percent`, `StoreProduct.currency` and
36
+ `StoreSearch.facets` for the filter counts the site returns.
37
+ - Store-aware module helpers: `humblebundle.store()`, `store_product()` and
38
+ `store_search()`.
39
+ - `HumbleBundleClient(age_gate_birthdate=...)` — adult products are unlocked by
40
+ answering the store's age gate; `store_product(..., birthdate=...)` overrides
41
+ it per call. Pass `None` to disable and get `AgeVerificationError` instead.
42
+ - `HumbleBundleClient(store_search_action=...)` — override the Next.js server
43
+ action id used for search, which is otherwise discovered from the page's
44
+ JavaScript and cached per client.
45
+ - `HttpClient.post_text(...)` for multipart form POSTs and
46
+ `HttpClient.set_cookie(...)` for session cookies.
47
+ - CLI: `store`, `store-product` and `store-search` commands. Tables gained
48
+ `BASE_PRICE` and `DISCOUNT_PERCENT` columns, shown only when they carry
49
+ information, with blank cells for products that have no discount.
50
+ - Parser support for the store: `store_sections`, `store_landing`,
51
+ `store_promotions`, `store_product_detail`, `store_price_block`,
52
+ `search_block`, `is_age_gate`, `script_paths` and `search_action_from_script`.
53
+ - `_values` helpers `plain_text()`, `slugify()` and `carousel_urls()`.
54
+ - `ProductCollection` — read-only mapping with `first`, `titles`, `search()`
55
+ and `to_dict()`.
56
+ - `Category` enum for feed selection (`games`, `books`, `software`, `bundles`,
57
+ `all`).
58
+ - Exception hierarchy: `HumbleBundleError`, `FetchError`, `RateLimitError`,
59
+ `PageDataError`, `BundleNotFoundError`, `StoreProductNotFoundError`,
60
+ `AgeVerificationError`, `AuthenticationError`. `FetchError` exposes
61
+ `status_code` and `url`.
62
+ - `humblebundle.configure_logging()` / `silence()` helpers. The library now uses
63
+ standard `logging` only (no printing, no root-logger configuration).
64
+ - `py.typed` marker (PEP 561) so type checkers see the annotations.
65
+ - `humblebundle schema` command and `humblebundle.describe_models()` — a
66
+ machine-readable description of every model field, intended for AI agents.
67
+ - `llms.txt`, `AGENTS.md`, `CONTRIBUTING.md` and `docs/` guides.
68
+ - Hermetic `pytest` suite covering the RSC reader, models, client, HTTP
69
+ transport, CLI, store and logging (no network access).
70
+ - `pyproject.toml` packaging metadata, ruff and mypy configuration, pre-commit
71
+ hooks and a GitHub Actions CI workflow.
72
+
73
+ ### Changed
74
+
75
+ - `product.price`, `product.msrp` and `product.retail_value` are `Money` value
76
+ objects (`amount`, `currency`) instead of bare floats. Use
77
+ `product.price.amount` for the number.
78
+ - `bundles()` returns `ProductCollection[Bundle]` and `choices()` returns
79
+ `HumbleChoice` instead of plain dictionaries. Both remain `Mapping`s, so
80
+ ``len()``, indexing, iteration, ``.values()`` and ``dict(...)`` keep working.
81
+ - Timestamps (`start_date`, `end_date`) are timezone-aware UTC `datetime`
82
+ objects rather than raw strings.
83
+ - `Bundle.stepin()` is deprecated in favour of `Bundle.items()`.
84
+ - `choices(month, year)` no longer pretends to fetch historical months; the
85
+ arguments label the result because Humble removed the per-month pages.
86
+ - The reverse-engineered `Logger` decorator (which swallowed exceptions) is
87
+ gone; errors propagate and logging is opt-in.
88
+ - Minimum Python version is now 3.10.
89
+ - `describe_models()` now also reports `store_sorts` and the store models.
90
+ - Store search is a multipart POST sent with `http.client` rather than
91
+ `requests`: Cloudflare rejects the `urllib3` TLS fingerprint on that endpoint.
92
+ GET requests are unchanged.
93
+ - Table output degrades gracefully when the console cannot encode a title
94
+ (for example `~` on a legacy Windows code page) instead of raising
95
+ `UnicodeEncodeError`.
96
+
97
+ ### Removed
98
+
99
+ - `humblebundle._get`, `humblebundle.api` internals and the `logger.Logger`
100
+ decorator class. Their replacements are `client`, `_parser` and
101
+ `humblebundle.configure_logging`.
102
+ - The undocumented `_Login` class; use `HumbleBundleClient.login()`.
103
+
104
+ ### Fixed
105
+
106
+ - Login attempts no longer silently return an unparsed `requests.Response`;
107
+ failures raise `AuthenticationError` with the site's reason.
108
+ - Page-data changes now raise `PageDataError` with an actionable message
109
+ instead of `KeyError`/`TypeError` deep inside parsing.
110
+
111
+ ## [0.2.0] — 2026-11-18
112
+
113
+ ### Changed
114
+
115
+ - Rewrote the page reader for Humble's Next.js (App Router) front end: page data
116
+ now comes from the React Server Components flight payload instead of
117
+ `application/json` script islands.
118
+
119
+ ## [0.1.0]
120
+
121
+ - Initial release: bundle feed, bundle items and Humble Choice helpers.
@@ -0,0 +1,85 @@
1
+ # Contributing
2
+
3
+ Thanks for helping out. This project is a small, focused client; the bar is
4
+ "keep it small, keep it typed, keep it tested".
5
+
6
+ ## Setup
7
+
8
+ ```bash
9
+ git clone https://github.com/markemicek/humblebundle.py
10
+ cd humblebundle.py
11
+ python -m pip install -e ".[dev]"
12
+ ```
13
+
14
+ ## Checks
15
+
16
+ ```bash
17
+ python -m pytest # hermetic: no network access
18
+ python -m pytest --cov=humblebundle --cov-report=term-missing
19
+ python -m ruff check .
20
+ python -m ruff format --check .
21
+ python -m mypy
22
+ ```
23
+
24
+ All four must pass before a pull request is merged. CI runs them on Python
25
+ 3.10–3.13 for Windows, macOS and Linux.
26
+
27
+ ## Adding a field to a model
28
+
29
+ Models are frozen `dataclass`es with `slots=True` and `kw_only=True`. A field is
30
+ visible to users (and to `humblebundle schema`) unless its name starts with `_`.
31
+
32
+ 1. Add the field with a type, a default and `metadata={"doc": "..."}`.
33
+ 2. Map it in the model's `from_payload` / `from_page` / `from_feed_item`
34
+ constructor.
35
+ 3. Add it to the table in `llms.txt` and, if user-visible, to `README.md`.
36
+ 4. Add a test asserting the parsed value and that `to_dict()` stays
37
+ JSON-serialisable.
38
+
39
+ ## Adding a parsed value
40
+
41
+ Normalise URLs, timestamps and list shapes in `_values.py`. Never let raw page
42
+ shapes leak into models — model fields must be plain, predictable types
43
+ (`str`, `int`, `float`, `bool`, `datetime`, tuples, or other models).
44
+
45
+ ## Tests
46
+
47
+ The suite must run offline. Use `tests/conftest.py` helpers:
48
+
49
+ ```python
50
+ from conftest import feed_page, make_page
51
+
52
+
53
+ def test_something(source_factory):
54
+ source = source_factory({"games": feed_page({"productKey": "x", "title": "X"})})
55
+ bundles = HumbleBundleClient(source=source).bundles()
56
+ assert bundles["x"].title == "X"
57
+ ```
58
+
59
+ When humblebundle.com changes its payload, add a fixture that reproduces the new
60
+ shape, make the test fail, then fix `_parser.py`/`models.py`.
61
+
62
+ ## Commit and PR style
63
+
64
+ * Conventional commits (`feat:`, `fix:`, `docs:`, `test:`, `refactor:`, `chore:`).
65
+ * One logical change per PR; update `CHANGELOG.md` under *Unreleased*.
66
+ * Describe the user-visible impact, not the file list.
67
+
68
+ ## Behaviour that will not be merged
69
+
70
+ * Anything that circumvents Humble's authentication, captcha or rate limits.
71
+ * Features that scrape personal account data or redistribute keys.
72
+ * Dependency additions without a strong reason — `requests` is the only runtime
73
+ dependency by design.
74
+
75
+ ## Release
76
+
77
+ Maintainers only:
78
+
79
+ ```bash
80
+ python build_release.py # build sdist + wheel with normalized names
81
+ pwsh ./publish.ps1 # twine check + upload (token typed into a prompt)
82
+ ```
83
+
84
+ Bump `humblebundle/__init__.py::__version__` and add a `CHANGELOG.md` entry
85
+ first. The version is read from that attribute by `pyproject.toml`.
@@ -1,6 +1,6 @@
1
1
  MIT License
2
2
 
3
- Copyright (c) [year] [fullname]
3
+ Copyright (c) 2026 ghostapps
4
4
 
5
5
  Permission is hereby granted, free of charge, to any person obtaining a copy
6
6
  of this software and associated documentation files (the "Software"), to deal
@@ -0,0 +1,13 @@
1
+ include LICENSE.txt
2
+ include README.md
3
+ include CHANGELOG.md
4
+ include CONTRIBUTING.md
5
+ include AGENTS.md
6
+ include llms.txt
7
+ include pyproject.toml
8
+
9
+ recursive-include docs *.md
10
+ recursive-include tests *.py
11
+ recursive-include humblebundle py.typed
12
+
13
+ global-exclude __pycache__ *.py[cod] .DS_Store