Metadata-Version: 2.1
Name: wikibase-reconcile
Version: 0.2.0
Summary: A concurrent client to reconcile entities against wikidata.
Author-email: Paul Balluff <paul.balluff@gmail.com>
Project-URL: Homepage, https://github.com/mrwunderbar666/wikibase_reconcile
Project-URL: Bug Tracker, https://github.com/mrwunderbar666/wikibase_reconcile/sampleproject/issues
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests
Requires-Dist: importlib-metadata ; python_version == "3.8"

# Wikibase Reconcile

An multi-threaded client to reconcile against wikidata.

This project is inspired by [reconciler](https://pypi.org/project/reconciler/). If you look for stable and mature software, I recommend using the excellent package `reconciler`.


## Features

- Concurrent requests to wikidata reconiliation API
- Makes atomic requests and is more robust when the API returns errors
- Takes a pandas dataframe as input and also as output
- User has rather high degree of control (but also needs more code)

## Installation

```
pip install wikibase-reconcile
```

## Usage

```python
from wikibase_reconcile import Client

client = Client()

# Initialize some simple test data
characters = [
    {"type": "Q15632617", "query": "Marge Simpson"},
    {"type": "Q15632617", "query": "Homer Simpson"},
    {"type": "Q15632617", "query": "Bart Simpson"},
    {"type": "Q15632617", "query": "Lisa Simpson"},
    {"type": "Q15632617", "query": "Maggie Simpson"},
    {"type": "Q15632617", "query": "Abraham Simpson"},
    {"type": "Q15632617", "query": "Apu Nahasapeemapetilon"},
    {"type": "Q15632617", "query": "Barney Gumble"}
]

df = pd.DataFrame(characters)

# reconcile each search query against the type "Fictional Human"
results = client.reconcile(df)

# Turn results into a dataframe, keep only the top result
df_reconciled = client.results_to_pandas(results)
```

### Fallback Logic

You can specify an additional fallback search string in case the first attempt did not yield any result:


```python
query = {"type": "Q15632617", "query": "Marge Simpson", "fallback_query": "Marjorie Bouvier"}
```

One use case for fallback queries are lemmatized versions of the original query.

If this still yields no results, then the reconciler will attempt to match the first part of the query, by splitting the query at every hyphen character (`-`) and taking the first part. **This logic is likely to change in future versions.**

The final fallback is to ignore the type and try to reconcile against any type. The default API server (`https://wikidata.reconci.link/`) will then match against the generic entity type (Q35120).
