Metadata-Version: 2.1
Name: pcgw_api
Version: 0.2.0
Summary: Client for the PCGamingWiki API
Author-Email: Idlusen <boulanger.m@mailoo.org>
License: LGPL-2.1
Requires-Python: >=3.13
Requires-Dist: httpx>=0.28.1
Description-Content-Type: text/markdown

# pcgw_api: Python client for the PCGamingWiki API

# Installation
```
pip install pcgw_api
```

# Usage
## Searching
```python
import pcgw_api
client = pcgw_api.PCGW()
for result in client.search("Celeste"):
  print(result)
```
Search is performed with a SQL LIKE query. In the future you will be able to search with opensearch,
allowing more flexible results at the expense of less informative data wich will require further
requests to get interesting information.

There is also `PCGW.async_search` should you need an asynchronous version.

## Fetching data

### Data already present
The above search function returns `Game` objects, which have all the information from the 
tables of the PCGamingWiki database. The tables are accessible as attributes:
```python
cuphead = client.search("Cuphead")[0]
print(cuphead.infobox.genres)
print(cuphead.availability.available_from)
print(cuphead.multiplayer.local_players)
```
See [`tables.py`](https://github.com/Idlusen/pcgw_api/blob/main/src/pcgw_api/tables.py) for the full list of available fields.

### Specific types
Dates are parsed as `datetime` python objects and fields indicating the support of the game
for a feature are generally parsed into a `Support` enum object:
```python
print(', '.join(str(date.year) for date in cuphead.infobox.released))
print(cuphead.input.controller_hotplugging == pcgw_api.Support.TRUE) # True
print(cuphead.input.controller_hotplugging == pcgw_api.Support.HACKABLE) # False
print(cuphead.input.mouse_sensitivity == pcgw_api.Support.NA) # True
```
`Support` is falsy for the values NULL, NA, UNKNOWN and FALSE, truthy otherwise:
```python
print(bool(cuphead.input.controller_support)) # True
if cuphead.input.controller_support:
  print("This will be printed")
```
### Data needing more requests
Language and engine information require additionnal requests to fetch the data, it is fetched on the first call to `Game.get_languages` or `Game.get_engines` and then cached:
```python
for l in cuphead.get_languages():
  print(f'{l.language} audio:{l.audio} subtitles:{l.subtitles}')
print(', '.join(e.engine for e in cuphead.get_engines()))
```

### Fetching game information by ID
It is possible to request specific games with `PCGW.get_game` or `PCGW.get_games`:
```python
print(client.get_game(page_id=63516).name) # Cuphead
print(client.get_game(steam_id=268910).name) # Cuphead
print(client.get_game(gog_id=1963513391).name) # Cuphead
print(client.get_game(page_name="Cuphead").name)
results = client.get_games(page_names=("Fez", "Limbo", "notagame"))
print(results["Fez"].name) # Fez
print(results["notagame"]) # None
```
`get_games` uses a single HTTP request.
`get_games` accepts the parameters `page_ids` and `page_names` and returns a dictionary
with these identifiers as keys to the resulting `Game` objects. Fetching multiple games
at a time with steam or gog ids is not supported as these ids can actually refer to
more than one PCGamingWiki page.

### Helper functions
It is possible to retrieve the set of values of a given table/field pair in the database:
```python
print(client.get_possible_values('Infobox_game', 'themes'))
print(client.get_possible_values('Infobox_game', 'available_on'))
print(client.get_possible_values('Input', 'other_button_prompts'))
print(client.get_possible_values('L10n', 'language'))
```
