steam-data-reader 1.0.0.dev1__py3-none-any.whl

steam_data_reader-1.0.0.dev1.dist-info/METADATA

@@ -0,0 +1,472 @@
+Metadata-Version: 2.4
+Name: steam-data-reader
+Version: 1.0.0.dev1
+Summary: Offline DuckDB queries for downloadable current Steam snapshots
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.11
+Requires-Dist: duckdb<2,>=1.4
+Requires-Dist: pytz>=2025.2
+Requires-Dist: steam-data-schema==1.0.0.dev1
+Description-Content-Type: text/markdown
+
+# Steam Data Reader
+
+**Development release `1.0.0.dev1` — snapshot schema `1.0`.** The initial snapshot has an input cutoff of **October 21, 2026, 19:10:39 UTC**. It contains 259,424 catalog entries, with details for 10,517 apps and review summaries for 10,807. Initial collection is incomplete: most apps still lack details, genres and reviews. Unknown values are not empty values or zero reviews. Genre and review filters therefore cover only the collected subset. The development download host is rate-limited; regular snapshot updates and production availability are not yet promised.
+
+Download a current Steam catalog and query it locally with Python. You do not need an AWS account, Steam account, API key, or the collection application's source code. Queries run against a local DuckDB database; they do not contact Steam or AWS.
+
+The dataset contains the latest known information for catalog apps, including games, demos, and DLC. It includes descriptions, classifications, developer/publisher labels, available review summaries and prices, relationships, and collection provenance. It excludes historical observations, individual reviews, raw responses, and media files. A description can contain HTML or media URLs; no referenced media is fetched automatically.
+
+Current discovery requests games and DLC from Steam's catalog endpoint, excluding software, videos/series, and hardware. Demo AppIDs are additionally discovered through game relationships; the endpoint has no documented demo inclusion flag. This does not claim exhaustive discovery of every special Steam app type. First-seen timestamps record discovery in collected evidence, not an app's creation or release on Steam.
+
+## Set up your environment
+
+Use Python 3.11 or newer. Clean installations have been tested on Python 3.11–3.14 on Linux and Python 3.13 on macOS and Windows. The publisher's Python and AWS setup is not required.
+
+Create a virtual environment and install the reader:
+
+```sh
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install "steam-data-reader==1.0.0.dev1"
+```
+
+This is a development prerelease. The exact version above selects it explicitly; to follow subsequent preview releases, use `python -m pip install --upgrade --pre steam-data-reader`. It does not claim a stable 1.0 API. The matching `steam-data-schema==1.0.0.dev1` dependency is installed automatically; its package version is separate from snapshot schema `1.0`.
+
+Read the complete guide from the installed distribution, without this repository or an Internet connection:
+
+```sh
+steam-snapshot --version
+steam-snapshot readme > steam-data-reader-README.md
+```
+
+On Windows, use `py` to create the environment if appropriate, and activate it with `.venv\Scripts\Activate.ps1` in PowerShell.
+
+The package installs DuckDB and its shared schema definitions. The initial design does not require pandas, PyArrow, boto3, or AWS CLI.
+
+The reader also installs `pytz`, needed by DuckDB's conversion of UTC timestamps to Python datetime values. Python and JSON retain exact integers; JavaScript consumers should account for their language's integer precision limits when interpreting large JSON numbers.
+
+Keep at least 10 GiB of free disk space before synchronization during preview testing. A 260,000-app synthetic capacity test used a roughly 445 MB baseline download, a 1.9 GB installed DuckDB file, and 7.37 GiB of peak reader working storage including staging. Weekly replacement also temporarily retains the existing database. These are synthetic measurements, not a forecast of the final Steam dataset: repeated templates affect compression. Published requirements will be checked against the complete real export. Query memory depends on the operation; the reader streams results where possible.
+
+Synchronization uses a 2,048 MB DuckDB working-memory budget plus Python/runtime overhead and can spill work to temporary disk. Allow several GB of available RAM during sync. The default budget for ordinary read-only queries is 768 MB. These are engine budgets, not limits on the process's total memory.
+
+## Fetch the latest catalog
+
+The preview uses an anonymous HTTPS development endpoint. No hosting-provider account, API key, or browser interaction is required to download it.
+
+Choose a local directory. First sync uses the built-in public R2 index URL; later syncs remember your selected source:
+
+```sh
+steam-snapshot sync --directory ./steam-catalog
+steam-snapshot info --directory ./steam-catalog
+```
+
+The built-in index is **https://pub-93fc6f5a294444c1adec0db48e691e3a.r2.dev/latest.json**. You can override it with `sync --source HTTPS_INDEX_URL` or Python `sync(..., source_url=HTTPS_INDEX_URL)`. Precedence is explicit override, then the directory's saved source, then this built-in default; an existing custom source is not silently switched.
+
+The first sync downloads the advertised full baseline and every available increment needed to reach the latest complete combined dataset. It verifies their checksums, installs a local database, and remembers the source URL. You do not choose archive filenames, infer dates, or apply increments yourself. Here **complete** means the complete published baseline-plus-increment state; it does **not** mean that Steam collection is complete or that every app has details.
+
+Later, close any Python or DuckDB connections to that directory and run:
+
+```sh
+steam-snapshot sync --directory ./steam-catalog
+```
+
+Within the same baseline chain, sync downloads only missing increments. Whenever a replacement baseline is published, it stages that baseline plus all its advertised increments before replacing your installed database. A missed publication day does not require a nonexistent file; manifests identify the actual preceding publication. If no newer version is advertised, sync leaves the installed data in place and downloads no data bundles.
+
+The intended cadence is **approximately weekly baselines and daily increments**, not a fixed Monday/midnight contract. Publication may be early, delayed, skipped, or consolidated into a catch-up increment; a new baseline can appear at any time, including for a schema transition. The reader follows the actual index and manifests, regardless of calendar dates. One successful sync reaches the latest version advertised by the index it fetched; run sync again to pick up any release published while it was running. During this initial preview, updates are manual and no daily service schedule is enabled.
+
+The index and `info` output identify actual versions and input/publication times. Publication time does not guarantee that every app was collected then, and the full bootstrap may still be incomplete.
+
+If a download or update fails, retry sync. The command exits nonzero on failure; Python raises `SyncError` with the installed and target versions. Partial files are not treated as installed data. For updates within one baseline chain, earlier successfully applied increments remain usable; the error reports the installed version and the target not yet reached. A failed replacement leaves the old usable database intact. If an old dependency has expired, the updater uses the newest baseline instead of skipping updates. If connections are open, close them before retrying; sync never kills your other processes.
+
+An installed catalog works offline. Opening/querying it does not automatically check for updates. `info` reports what is installed locally, not whether a newer online version exists.
+
+### If a new baseline needs a newer reader
+
+Schema changes happen only at a new full baseline; all increments in that baseline's chain use the exact same schema version. Dataset publication versions, schema versions, and Python package versions are separate. Normal daily data updates do not require reinstalling Python software.
+
+Sync checks compatibility from small manifests before downloading the large baseline or replacing installed data. If your reader does not support the new schema, it reports the incoming schema, required reader version, and installed version, and leaves the existing database usable. A reader already supporting the new schema proceeds normally.
+
+When prompted, upgrade in the same virtual environment that runs your application, restart any running Python program that imported the old package, then retry:
+
+```sh
+python -m pip install --upgrade --pre steam-data-reader
+steam-snapshot sync --directory ./steam-catalog
+```
+
+The necessary compatible schema dependency is installed through the reader package's dependency requirements; you normally do not upgrade it separately. The updater never runs pip automatically. If the required reader does not support your Python version, follow its environment requirements before retrying. A breaking schema change can also require changes to your own SQL or application code; consult the linked migration notes. Without upgrading you may continue querying your older installed data offline, but sync cannot claim to have installed the new version.
+
+Python applications can perform the same explicit synchronization:
+
+```python
+from steam_data_reader import sync
+
+status = sync("./steam-catalog")  # Built-in R2 source on first sync; saved source thereafter.
+print(status.installed_version, status.complete)
+```
+
+Keep synchronization separate from an open query session. A session reads one dataset version from beginning to end.
+
+## Run basic queries from the command line
+
+You do not need to write Python code for the built-in queries. These commands use exactly the same filters, fields, ordering, and serializers as the Python functions below. They use only the installed local dataset; update it separately when you want new data.
+
+List the catalog's minimal fields, or restrict the listing:
+
+```sh
+steam-snapshot list-apps --directory ./steam-catalog --limit 20
+steam-snapshot list-apps --directory ./steam-catalog --name-contains space --app-type game --min-reviews 100 --min-positive-percentage 80 --fields steam_appid,name,genres,total_reviews,positive_percentage --format json --output space-games.json
+```
+
+Without `--limit`, all matches are returned. Available list flags mirror Python arguments: `--name-prefix`, `--name-contains`, repeatable `--appid`, `--app-type`, `--genre-id`, `--developer-name`, `--publisher-name`, `--genre-match any|all`, inclusive review/percentage minimum and maximum flags, `--fields`, `--order-by`, `--limit`, and `--after-appid`. Quote names containing spaces in your shell. Use repeated flags for sets; a comma-separated `--fields` value selects output fields. See the filter definitions below for exact semantics.
+
+Get full details for specified appIDs, or export selected fields as TSV:
+
+```sh
+steam-snapshot get-apps --directory ./steam-catalog 620 1794680 2230760
+steam-snapshot get-apps --directory ./steam-catalog 620 1794680 --fields steam_appid,name,total_reviews --format tsv --output selected.tsv
+steam-snapshot list-genres --directory ./steam-catalog --format tsv
+steam-snapshot info --directory ./steam-catalog
+```
+
+Record-query commands default to JSON on standard output. `--output PATH` writes a file instead; TSV file output also writes its metadata sidecar. Standard-output TSV contains a header and records only, while dataset/schema version and missing-ID notices go to standard error. Use file output when you need the full portable TSV/metadata pair. JSON carries its metadata envelope on both file and standard output. `info` prints local dataset metadata as JSON.
+
+Progress, warnings, and diagnostics go to standard error so they do not corrupt redirected query output. Exit codes are 0 for success (including no matches or explicitly reported missing appIDs), 1 for operational failures, 2 for invalid arguments, and 3 when the reader/protocol/schema is incompatible. Use `steam-snapshot --help` or a subcommand's `--help` without opening a database or downloading data. Keep the installed version unchanged when paging across several CLI calls, and close other query sessions before syncing.
+
+## Query from Python
+
+The examples below use the implemented interface and illustrative Steam appIDs. Results depend on actual coverage in your downloaded version.
+
+### List apps
+
+```python
+from steam_data_reader import Catalog
+
+with Catalog.open("./steam-catalog") as catalog:
+    for app in catalog.list_apps():
+        print(app["steam_appid"], app["name"], app["app_type"])
+```
+
+The default fields are `steam_appid`, `name`, `developers`, `publishers`, and `app_type`. Developers and publishers are lists. With no filter or limit, this enumerates the entire catalog, including entries with unavailable details. Names/types may be null for unresolved records.
+
+### Filter and select fields
+
+```python
+with Catalog.open("./steam-catalog") as catalog:
+    genres = catalog.list_genres().to_list()
+    print(genres)  # Discover exact genre IDs and labels from this dataset.
+
+    result = catalog.list_apps(
+        name_contains="space",
+        app_types=["game"],
+        min_reviews=100,
+        min_positive_percentage=80,
+        fields=[
+            "steam_appid", "name", "developers", "genres",
+            "total_reviews", "positive_percentage",
+        ],
+        limit=100,
+    )
+    apps = result.to_list()
+```
+
+To add a genre filter, pass `genre_ids=["<id-from-list_genres>"]`. `genre_match="any"` matches at least one requested genre; `"all"` requires every requested genre. Genres, categories, and Steam tags are different classifications. Tag coverage is initially unsupported and must not be inferred from genres.
+
+Available list filters:
+
+- `appids`, `name_prefix`, `name_contains`, `app_types`.
+- `genre_ids` and `genre_match`.
+- `developer_names` and `publisher_names` for exact labels under the documented text normalization.
+- Inclusive `min_reviews`, `max_reviews`, `min_positive_percentage`, and `max_positive_percentage` bounds.
+
+Each app query returns at most one record per appID even if several genres or organizations match. Different filters combine with AND; values inside a set combine with OR except for `genre_match="all"`. A provided empty set matches nothing; an empty genre set with `"all"` and empty search text are rejected. Prefix/substring matching is literal, Unicode-normalized and case-insensitive; `%` and `_` have no wildcard meaning. Developer/publisher labels use the same normalization but must match the whole label, including punctuation.
+
+Unknown well-formed genre IDs, app types, or organization names simply match no records. Invalid arguments or field names produce errors. Numeric bounds exclude null metrics. Positivity is a percentage on a 0–100 scale, not Steam's review-score category; it is null for zero or unavailable totals. Review filters use the snapshot's declared default review series.
+
+Results default to appID ascending. `order_by="name"` sorts by normalized name with appID as a tie-breaker; `order_by="steam_appid"` is the default. With appID ordering, `after_appid=LAST_ID` and `limit=N` retrieve the next page from the same dataset version and filters. There is no hidden default limit.
+
+### Get full information for selected apps
+
+```python
+with Catalog.open("./steam-catalog") as catalog:
+    result = catalog.get_apps([620, 1794680, 2230760])
+    apps = result.to_list()
+    print(result.missing_appids)
+```
+
+With no `fields` selection, this returns all supported exported app fields, current relationships, acquisition status, and field provenance. It does not include raw Steam responses, history, or fields the publisher has not acquired.
+
+Repeated requested IDs are deduplicated and output follows their first-requested order. An empty list returns no apps. IDs absent from the catalog appear in `missing_appids`; an app retained in the catalog with unavailable details still appears as a record. Unknown values are not silently converted to empty strings or zero.
+
+Use `fields=["steam_appid", "name", "genres", "total_reviews"]` to restrict results. appID is always included. `list_apps(fields=None)` uses minimal fields; `get_apps(fields=None)` requests full information. Fields not selected are omitted rather than returned as null.
+
+### Export JSON or tab-delimited CSV
+
+```python
+with Catalog.open("./steam-catalog") as catalog:
+    result = catalog.list_apps(
+        app_types=["game"],
+        fields=["steam_appid", "name", "genres", "total_reviews", "positive_percentage"],
+    )
+    result.write_json("games.json")
+    result.write_tsv("games.tsv")
+```
+
+Both exports refer to the same pinned version. JSON contains `dataset_version`, `schema_version`, `missing_appids`, and a `rows` array. Python records and JSON preserve lists/objects; JSON uses null for unavailable values.
+
+TSV has a header and one logical record per app, with standard double-quote escaping for embedded tabs, newlines, and quotes. Lists/objects are compact JSON within a cell. Null uses `\N`; non-null scalar strings double their backslashes, so empty strings and a literal null-marker string remain distinguishable. Structured JSON cells retain JSON's own escaping. Timestamps are UTC ISO strings. The sibling `games.tsv.metadata.json` describes versions, types, encoding, missing IDs, row count, and the TSV hash/length. It is written last as the completion record. Keep it with the TSV; a missing sidecar or mismatched hash means the pair is incomplete or stale.
+
+A CSV-aware parser must read TSV; splitting each physical line on tabs is insufficient for quoted multiline descriptions. No spreadsheet formula interpretation is intended.
+
+`to_list()` materializes results in memory. Iteration and file exports stream rows where possible. Expensive descriptions and provenance are omitted from listing defaults; request them when needed.
+
+### Inspect the installed dataset
+
+```python
+with Catalog.open("./steam-catalog") as catalog:
+    print(catalog.dataset_info())
+```
+
+This reports versions, publication/input boundaries, coverage, supported features, default contexts/review series, and freshness summaries. An app's description and review counts may have different observation times. A later failed check does not make an older retained value freshly observed. Consult `provenance` and `acquisition_status` when freshness matters.
+
+## Build an independent client application
+
+Everything required for a client is in the installed reader/schema distributions and this README. No publisher repository, prior conversation, AWS SDK, AWS credentials, Steam API key, or knowledge of ingestion internals is required. Install, sync explicitly, then query within a read-only `Catalog` session. The following example is a starting point for a separate application that needs game candidates:
+
+```python
+from steam_data_reader import Catalog, sync
+
+path = "./steam-catalog"
+result = sync(path)
+if not result.complete:
+    raise RuntimeError("Snapshot synchronization did not finish")
+
+with Catalog.open(path) as catalog:
+    snapshot = catalog.dataset_info()
+    print(snapshot["dataset_version"], snapshot["input_boundary_at"])
+    print(catalog.list_genres().to_list())
+    for game in catalog.list_apps(
+        name_contains="space",
+        fields=["steam_appid", "name", "app_type", "developers", "publishers", "genres", "steam_url"],
+        limit=100,
+    ):
+        print(game)
+```
+
+For genre selection, discover IDs with `list_genres()` and use `genre_ids=[...]` with the filters documented above. For explicit games, use `get_apps([appid, ...])`. Use `steam_appid` as the join key for your own application data, and retain the snapshot version with derived results. Names are not unique identifiers; this dataset does not supply a comprehensive alias dictionary or a game-title-to-video matching algorithm. Demo and DLC appIDs remain distinct from the full game; inspect typed relationships when that distinction matters.
+
+A YouTube discovery application can use those names/genres as candidate input and keep its YouTube API integration, credentials, search/matching logic, channels/videos and results in its own project. This package contains **no YouTube data or YouTube API functionality**. During the partial import, enumerate the broad catalog when useful, and do not interpret missing genres/review counts as evidence that an app has no genres/reviews. The documented Python methods and public `steam` views below are the supported client interfaces; transport tables and publisher code are not integration dependencies.
+
+## Power users: use the database directly
+
+The reader is a convenience layer, not a restriction on analysis. You can use the underlying read-only DuckDB connection or open the database with DuckDB yourself. Public views live in the `steam` schema. Private storage tables and cache filenames are not supported interfaces.
+
+```python
+with Catalog.open("./steam-catalog") as catalog:
+    rows = catalog.connection.execute(
+        """
+        SELECT steam_appid, name, total_reviews, positive_percentage
+        FROM steam.apps
+        WHERE app_type = ? AND total_reviews >= ?
+        ORDER BY total_reviews DESC, steam_appid
+        LIMIT ?
+        """,
+        ["game", 1000, 20],
+    ).fetchall()
+```
+
+For an independent application, the installed database file is `catalog.duckdb` in your chosen directory:
+
+```python
+import duckdb
+
+with duckdb.connect("./steam-catalog/catalog.duckdb", read_only=True) as connection:
+    version = connection.execute(
+        "SELECT dataset_version FROM steam.snapshot_info"
+    ).fetchone()[0]
+```
+
+Keep connections read-only and close them before sync. Do not alter the installed database to add your own application tables; use a separate database/file and join by `steam_appid`. A query session must stay on one dataset version. Parameters represent values; public schema names are fixed names from the reference below.
+
+For general DuckDB/SQL guidance, consult the official [Python interface](https://duckdb.org/docs/stable/clients/python/overview) and [parameterized SQL interface](https://duckdb.org/docs/stable/clients/python/dbapi). This guide documents this dataset's contract rather than teaching SQL.
+
+### Schema and types
+
+The following is the schema version 1.0 contract, defined by `steam-data-schema`. All views represent current state only. Every schema change, including an additive one, occurs only at a new full baseline. Unknown unsupported versions fail explicitly before installation; see the upgrade workflow above.
+
+Conventions:
+
+- `steam_appid` is a `BIGINT`; counts and price minor units are exact integers. Source genre/category/tag IDs are `VARCHAR` and stay in their own namespaces.
+- Times are nullable `TIMESTAMPTZ`, normalized to UTC. Python uses timezone-aware datetime values; exported JSON/TSV use ISO 8601 UTC strings.
+- Structured fields are typed lists or DuckDB `JSON`, decoded into lists/objects by the convenience API. Source-supplied requirement objects can vary in shape and are retained as JSON.
+- All descriptive/metric fields may be null unless explicitly identified as a required key. Null alone does not distinguish unsupported from unavailable; consult feature support, field provenance/state, and acquisition status.
+- Initial descriptive/price context is US/English, with returned currency recorded. Additional contexts must be explicitly identified; default views never mix them implicitly.
+
+**`steam.apps` — one row per retained `steam_appid`.** This convenient joined view is also the ordinary query field registry:
+
+```text
+steam_appid BIGINT                         -- required, unique key
+name VARCHAR; app_type VARCHAR
+steam_url VARCHAR                         -- canonical convenience URL
+short_description VARCHAR; detailed_description VARCHAR; about_the_game VARCHAR
+website VARCHAR; supported_languages VARCHAR
+required_age VARCHAR                      -- normalized textual source value; not a verified age rating
+is_free BOOLEAN; controller_support VARCHAR
+platforms JSON
+pc_requirements JSON; mac_requirements JSON; linux_requirements JSON
+release_info JSON                         -- source text, coming-soon, optional parsed date/precision
+content_descriptors JSON; support_info JSON; ratings JSON
+header_image VARCHAR; capsule_image VARCHAR; capsule_imagev5 VARCHAR  -- URLs only
+extensions JSON                           -- namespaced, documented current source extensions
+first_seen_at TIMESTAMPTZ; last_seen_at TIMESTAMPTZ
+name_origin VARCHAR                       -- details, catalog, or unknown; catalog fallback is marked
+
+developers VARCHAR[]; publishers VARCHAR[]
+genres JSON                               -- list of {genre_id, label}
+categories JSON                           -- list of {category_id, label}
+tags JSON                                 -- list of {tag_id, label}; null if unsupported/unknown
+
+default_review_series_id VARCHAR
+reviews_observed_at TIMESTAMPTZ
+total_positive BIGINT; total_negative BIGINT; total_reviews BIGINT
+positive_percentage DOUBLE
+review_score BIGINT; review_score_desc VARCHAR
+
+price_country VARCHAR; price_currency VARCHAR
+price_initial_minor BIGINT; price_final_minor BIGINT
+price_discount_percentage BIGINT; price_observed_at TIMESTAMPTZ
+```
+
+`name` may fall back to the most recent catalog label when details have never supplied a name; `name_origin` and field provenance identify that fallback. Preserve source `app_type` values such as `game`, `demo`, and `dlc`; unknown stays null. An empty known developer/genre set is `[]`, while unsupported/unknown is null with supporting state metadata. `last_seen_at` means latest successful catalog/source visibility under its declared definition, not proof of current purchase availability; the field registry must identify the contributing source. A free app, absent price, and zero-priced discounted offer are distinct states.
+
+For full app records, the Python interface also supports structured fields `relationships`, `acquisition_status`, and `provenance`, assembled from the views below. They are not additional columns of `steam.apps`. `relationships` contains outgoing links; reverse links are available through direct SQL.
+
+**`steam.review_summaries`** has key `(steam_appid, review_series_id)`:
+
+```text
+steam_appid BIGINT; review_series_id VARCHAR
+observed_at TIMESTAMPTZ; source_id VARCHAR; observation_id VARCHAR
+total_positive BIGINT; total_negative BIGINT; total_reviews BIGINT
+positive_percentage DOUBLE; review_score BIGINT; review_score_desc VARCHAR
+```
+
+A row represents the latest valid summary for that series. No row means no successful current retained summary; check acquisition status rather than inventing zero. `positive_percentage` is `100 * positive / total`, null for zero total. Counts must satisfy `positive + negative = total` and be nonnegative. `review_score`/label are separately supplied source categories.
+
+**`steam.review_series`** has key `review_series_id VARCHAR`, with `definition_json JSON` and `description VARCHAR`. The definition identifies endpoint/version, language scope, purchase-type scope, sentiment selection, off-topic filtering, and interpretation version. `steam.apps` selects only the series named in `steam.snapshot_info`; never combine incompatible series. The initial intended series covers all languages/purchase types and both sentiments with off-topic filtering, subject to the validated source adapter's declared definition.
+
+**`steam.prices`** has key `(steam_appid, country, language, currency)`:
+
+```text
+steam_appid BIGINT; country VARCHAR; language VARCHAR; currency VARCHAR
+initial_minor BIGINT; final_minor BIGINT; discount_percentage BIGINT
+observed_at TIMESTAMPTZ; source_id VARCHAR; observation_id VARCHAR
+```
+
+Currency is retained as returned; do not assume a minor-unit scale for every possible currency. The initial US context is expected to return USD where offered, but the value is explicit. The configured default context populates the convenience price columns in `steam.apps`; different currencies are not silently compared or converted.
+
+**Classification dictionaries and memberships:**
+
+```text
+steam.genres:         genre_id VARCHAR [key], label VARCHAR
+steam.app_genres:     steam_appid BIGINT, genre_id VARCHAR [composite key]
+steam.categories:    category_id VARCHAR [key], label VARCHAR
+steam.app_categories: steam_appid BIGINT, category_id VARCHAR [composite key]
+steam.tags:           tag_id VARCHAR [key], label VARCHAR
+steam.app_tags:       steam_appid BIGINT, tag_id VARCHAR [composite key],
+                      source_rank BIGINT nullable, source_weight DOUBLE nullable
+```
+
+Only retain tag rank/weight if actually supplied and defined by the source. Empty tag views plus `unsupported` feature coverage mean tags were not acquired, not that all apps were observed to have no tags. Labels are display values, not guaranteed unique identifiers. Membership keys reference their corresponding dictionary.
+
+For example, use a genre ID returned by `list_genres()`:
+
+```python
+with Catalog.open("./steam-catalog") as catalog:
+    rows = catalog.connection.execute(
+        """
+        SELECT a.steam_appid, a.name
+        FROM steam.apps AS a
+        JOIN steam.app_genres AS g USING (steam_appid)
+        WHERE g.genre_id = ?
+        ORDER BY a.steam_appid
+        """,
+        ["<genre-id>"],
+    ).fetchall()
+```
+
+**`steam.app_organizations`** has key `(steam_appid, role, organization_id)`:
+
+```text
+steam_appid BIGINT; role VARCHAR            -- developer or publisher
+organization_id VARCHAR; original_name VARCHAR
+source_id VARCHAR; source_url VARCHAR nullable
+identity_quality VARCHAR                   -- source_label or verified_source_identity
+```
+
+Organization IDs are source-scoped identifiers, not universal company IDs. Exact source labels remain distinct until stronger evidence justifies a mapping. An organization can occupy both roles. Optional URLs are source-backed links, not proof that a generated search URL identifies a company.
+
+**`steam.app_relationships`** has key `(steam_appid, relation_type, target_appid)`:
+
+```text
+steam_appid BIGINT; target_appid BIGINT; relation_type VARCHAR
+source_id VARCHAR; observation_id VARCHAR; observed_at TIMESTAMPTZ
+```
+
+The direction of `demo_of`/`dlc_of` is demo/DLC to full game. Other labels such as `related_content` preserve what the source actually establishes; a soundtrack must not be reclassified as DLC solely because a game links it. The source app must exist in the catalog; a target can be unresolved and is not an invitation to borrow the target's metrics. Multiple contributing observations are represented in provenance rather than duplicating a logical relationship row.
+
+Identity relationship labels are distinct: `appdetails_identity_reference` points from a requested appID to the different ID in a quarantined details response (unresolved); `store_item_app` points from a store item to its explicitly reported application; `store_parent` records StoreBrowse's store-parent field and does not assert `dlc_of`. No label merges app records or borrows metadata or review counts. These labels and the `steam.store_browse` source use the existing open string fields in schema 1.0. A failed refresh preserves last-good relationships; a successful item can explicitly clear an earlier mapping or parent. Reference discovery can retain an app absent from the catalog, but cannot reconstruct all delisted apps that no retained source references.
+
+**`steam.field_provenance`** has key `(steam_appid, field_name, context_id, provenance_id)`:
+
+```text
+steam_appid BIGINT; field_name VARCHAR; context_id VARCHAR; provenance_id VARCHAR
+source_id VARCHAR nullable; observation_id VARCHAR nullable; observed_at TIMESTAMPTZ nullable
+value_state VARCHAR; timestamp_quality VARCHAR
+context_json JSON; parser_version VARCHAR; resolution_version VARCHAR
+source_url VARCHAR nullable
+```
+
+`value_state` is `observed_value`, `observed_empty`, `unknown`, `unsupported`, or `unavailable`; `timestamp_quality` identifies observed, source-reported, derived, or unknown timing as applicable. The stable `provenance_id` identifies a contribution or declared field state. Unknown/unsupported states can have null source/observation identifiers; the exporter must not invent source observations to fill them. Missing provenance for a known field must not be interpreted as a successful empty observation. An unavailable latest check can coexist with an older `observed_value`; those different facts appear in the separate status view. Derived values carry provenance for their contributing inputs. All public source URLs omit credentials and private storage paths.
+
+**`steam.acquisition_status`** has key `(steam_appid, source_id, data_family, context_id)`:
+
+```text
+steam_appid BIGINT; source_id VARCHAR; data_family VARCHAR; context_id VARCHAR
+context_json JSON
+latest_attempt_at TIMESTAMPTZ nullable
+latest_attempt_status VARCHAR             -- success, unavailable, failed, or not_attempted
+last_success_at TIMESTAMPTZ nullable
+support_status VARCHAR                    -- supported, unsupported, or unknown
+```
+
+`last_success_at` refers to a successful acquisition and may differ from an individual selected field's observation time. A field absent from a later response does not acquire a newer value timestamp. Context IDs are stable identifiers defined by the schema contract for the canonical source/context definition, not account-specific identifiers.
+
+**`steam.snapshot_info`** has exactly one row:
+
+```text
+dataset_id VARCHAR; dataset_version VARCHAR; chain_id VARCHAR
+baseline_version VARCHAR; increment_sequence BIGINT; schema_version VARCHAR
+published_at TIMESTAMPTZ; input_boundary_at TIMESTAMPTZ
+source_release_id VARCHAR                  -- public opaque identifier, not an internal run ID
+logical_state_sha256 VARCHAR               -- excludes snapshot_info itself and redundant views
+app_count BIGINT; default_review_series_id VARCHAR
+metadata_country VARCHAR; metadata_language VARCHAR
+price_country VARCHAR; price_language VARCHAR
+coverage_json JSON; feature_support_json JSON; freshness_json JSON
+```
+
+The row describes the installed version even when a newer version is advertised online. Coverage reports preserved unresolved apps and unsupported features. Collection timestamps, review-series definitions, and contexts should accompany analytical interpretations; publication date alone does not establish freshness.
+
+### Compatibility and extension policy
+
+The documented views and Python fields are the supported interface. Internal tables, transport shards, and caches may change without being query interfaces. New optional fields/views may be added in a new schema minor version at a baseline; incompatible column/key/type/unit/meaning changes require a schema major version. Increments must retain their baseline's exact schema version. The installed reader/shared contract declares which versions it supports; unrecognized future minor versions are not assumed compatible. New software releases can support both earlier and upcoming schemas, so a schema change does not always require another package upgrade. Do not rely on `SELECT *` having a permanent column order in your own application; select named fields.
+
+Namespace extension fields by source and document their types/provenance. No extension can silently redefine an established field. History and source collection are outside this package; users who want custom analysis use these current-state views or join their own datasets by appID.
+
+## Software license
+
+The reader and shared-schema packages use the MIT license included in each distribution. This software license does not license Steam data or other third-party content in snapshots.

steam_data_reader-1.0.0.dev1.dist-info/RECORD

@@ -0,0 +1,10 @@
+steam_data_reader/__init__.py,sha256=E4iwjMvMuImlhihVuRL5EJ2rBA_ABc3_DQBwXXYJOwU,322
+steam_data_reader/catalog.py,sha256=9jt9f_hky2D1oa1Ay0q37qaRTTDmeM-dcG_4wTiCAss,13562
+steam_data_reader/cli.py,sha256=ZF0B8_9R7n5KR_R3Q7j1kG0rKeBPMScMigmgNUsK66w,4097
+steam_data_reader/database.py,sha256=N1FiuUfJb5-bNuYmjTrIlD5SYJ8z8STlFM5b6-l_v6w,11458
+steam_data_reader/sync.py,sha256=GPbbxglL93efrTCqUU_J5qUDrtBMksuSOtDGS053OMc,14944
+steam_data_reader-1.0.0.dev1.dist-info/METADATA,sha256=aSioyGXlguJSkSN07cCg0ZIOmXREyVDWQXoTpGept-Q,36089
+steam_data_reader-1.0.0.dev1.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+steam_data_reader-1.0.0.dev1.dist-info/entry_points.txt,sha256=nkmmL9H2VWjakhdWAmTUfyTqWBbFHAYu8k5zh3waMzo,62
+steam_data_reader-1.0.0.dev1.dist-info/licenses/LICENSE,sha256=eYDBQ0veiU5htuSPpskxfcqZ1IswqEmtLvRLM7U_fS8,1080
+steam_data_reader-1.0.0.dev1.dist-info/RECORD,,

steam_data_reader-1.0.0.dev1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

steam_data_reader-1.0.0.dev1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+steam-snapshot = steam_data_reader.cli:main

steam_data_reader-1.0.0.dev1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Steam Data contributors
+
+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.