#!/usr/bin/env python
# coding: utf-8

# # Tutorial 1: API requests (WikiWho wrapper)
# 
# The WikiWho class wraps the [WikiWho API](https://api.wikiwho.net/en/api/v1.0.0-beta/) and [WikiWho Edit Persistence API](https://www.wikiwho.net/en/edit_persistence/v1.0.0-beta/) requests into functions, through the `api` attribute (`WikiWhoAPI` class).

# ## 1. Create an instance of WikiWho
# 
# The `api` attribute of the `WikiWho` class contains all the functions to call the APIs.

# In[ ]:


from wikiwho_wrapper import WikiWho
ww = WikiWho(lng='en')


# #### Parameters of WikiWho
# 
# - *wikiwho_api_username* (str, optional): WikiWho API username
# - *wikiwho_api_password* (str, optional): WikiWho API password
# - *wikiwho_api_key* (str, optional): WikiWho API key
# - *lng* (str, optional): the language that needs to be query
# - *protocol* (str, optional): the protocol of the url
# - *domain* (str, optional): the domain that hosts the api
# - *version* (str, optional): the version of the api
# - *attempts* (int, optional): the number of attempts before giving up trying to connect

# ## 2. Querying all content
# 
# The method `all_content()` corresponds to the following requests:
# 
#     GET /all_content/{article_title}/ 
#     GET /all_content/{article_id}/ 
#     
# Internally, the method will discern by the two call depending on the type first parameter (`str` for `article_title` and `int` for `article_id`)

# In[ ]:


ww.api.all_content("Bioglass_45S5")


# ***You can also use all the parameters of the [WikiWho API](https://api.wikiwho.net/en/api/v1.0.0-beta/)***
# 
# - *article* (Union[int, str]): page id (int) or title (str) of the page.
# - *o_rev_id* (bool, optional): Origin revision ID per token
# - *editor* (bool, optional): Editor ID/Name per token
# - *token_id* (bool, optional): Token ID per token
# - *out* (bool, optional): Outbound revision IDs per token
# - *_in* (bool, optional): Outbound revision IDs per token

# ## 3. Query Revisions IDS
# 
# The method `rev_ids_of_article()` corresponds to the following requests:
# 
#     GET /rev_ids/{article_title}/
#     GET /rev_ids/page_id/{page_id}/
#     
# As in the previous case, ***You can also use all the parameters of the [WikiWho API](https://api.wikiwho.net/en/api/v1.0.0-beta/)***

# In[ ]:


ww.api.rev_ids_of_article(article='Bioglass_45S5')


# ## 4. Query the content of specific revisions
# 
# In this case, there are three methods that match the 5 different requests:
# 
# - `last_rev_content()`:
# 
#         GET /rev_content/{article_title}/
#         GET /rev_content/page_id/{page_id}/
#     
# - `specific_rev_content_by_rev_id()`:
#     
#         GET /rev_content/{article_title}/{rev_id}/ 
#         GET /rev_content/rev_id/{rev_id}
# 
# - `range_rev_content_by_article_title()`:
# 
#         GET /rev_content/{article_title}/{start_rev_id}/{end_rev_id}/ 
# 
#     
# As in the previous case, ***You can also use all the parameters of the [WikiWho API](https://api.wikiwho.net/en/api/v1.0.0-beta/)***

# In[ ]:


ww.api.range_rev_content_by_article_title(article='Bioglass_45S5',  start_rev_id=18064039,  end_rev_id=207995408)


# ## 5. Query the content of persistance of actions
# 
# In this case, there is one method that match the 3 different requests:
# 
# - `edit_persistence()`:
# 
#         GET /editor/{editor_id}/
#         GET /page/{page_id}/
#         GET /page/editor/{page_id}/{editor_id}/
# 
# As in the previous case, ***You can also use all the parameters of the [WikiWho Edit Persistence API](https://www.wikiwho.net/en/api_editor/v1.0.0-beta/)***

# In[ ]:


ww.api.edit_persistence(page_id=2161298)


# ## 6. Summary
# 
# Although in the [WikiWho API](https://api.wikiwho.net/en/api/v1.0.0-beta/), there are 9 types of requests, the wrapper reduces it to 5 functions (3 to 1 in the case of the [WikiWho Edit Persistence API](https://www.wikiwho.net/en/edit_persistence/v1.0.0-beta/)) by exploting the fact that a lot of these requests only vary in the type of the paramater for the page, i.e. id(`int`) or title(`str`):
# 
# Here is the complete list of functions fo the [WikiWho API](https://api.wikiwho.net/en/api/v1.0.0-beta/):
# 
# - `all_content()`
# - `rev_ids_of_article()`
# - `last_rev_content()`
# - `specific_rev_content_by_rev_id()`
# - `range_rev_content_by_article_title()`
# 
# And, for the [WikiWho Edit Persistence API](https://www.wikiwho.net/en/edit_persistence/v1.0.0-beta/), we only have one function
# 
# - `edit_persistence()`
# 
# Although, the JSON format of this request is useful for certain tasks that involves extracting detailed information, in many occasions you may prefer to work with a table representation of the date. The next part of the tutorial will show you that you can get the a pandas DataFrame instead, by using the DataView.
# 

# In[ ]:


from utils.notebooks import get_next_notebook
from IPython.display import HTML
try:
    display(HTML(f'<a href="{get_next_notebook()}" target="_blank">Go to next workbook</a>'))
except:
    HTML('<a href="2. Getting Dataframes (DataView).ipynb" target="_blank">Go to next workbook</a>')