Improve docs

wikibaseintegrator/__init__.py

@@ -1,3 +1,20 @@
+"""
+Requests HTTP Library
+~~~~~~~~~~~~~~~~~~~~~
+
+WikibaseIntegrator is a Wikibase library, written in Python, for human beings.
+Basic read usage:
+
+   >>> from wikibaseintegrator import WikibaseIntegrator
+   >>> from wikibaseintegrator.wbi_config import config
+   >>> config['USER_AGENT'] = 'Item Get Notebook'
+   >>> wbi = WikibaseIntegrator()
+   >>> q42 = wbi.item.get('Q42')
+   >>> q42.labels.get('en').value
+   'Douglas Adams'
+
+Full documentation is available at <https://wikibaseintegrator.readthedocs.io/>.
+"""
 import pkg_resources
 
 from .wikibaseintegrator import WikibaseIntegrator

wikibaseintegrator/models/claims.py

@@ -123,6 +123,12 @@ class Claim(BaseModel):
     DTYPE = 'claim'
 
     def __init__(self, qualifiers: Qualifiers = None, rank: WikibaseRank = None, references: Union[References, List[Union[Claim, List[Claim]]]] = None) -> None:
+        """
+
+        :param qualifiers:
+        :param rank:
+        :param references: A References object, a list of Claim object or a list of list of Claim object
+        """
         self.mainsnak = Snak(datatype=self.DTYPE)
         self.type = 'statement'
         self.qualifiers = qualifiers or Qualifiers()
@@ -225,6 +231,10 @@ def remove(self, remove=True) -> None:
         self.removed = remove
 
     def from_json(self, json_data: Dict[str, Any]) -> Claim:
+        """
+
+        :param json_data: a JSON representation of a Claim
+        """
         self.mainsnak = Snak().from_json(json_data['mainsnak'])
         self.type = str(json_data['type'])
         if 'qualifiers' in json_data:

wikibaseintegrator/models/language_values.py

@@ -12,14 +12,23 @@ def __init__(self):
         self.values = {}
 
     @property
-    def values(self):
+    def values(self) -> Dict[str, LanguageValue]:
+        """
+        A dict of LanguageValue with the language as key.
+        """
         return self.__values
 
     @values.setter
     def values(self, value):
         self.__values = value
 
     def add(self, language_value: LanguageValue) -> LanguageValues:
+        """
+        Add a LanguageValue object to the list
+
+        :param language_value: A LanguageValue object
+        :return: The current LanguageValues object
+        """
         assert isinstance(language_value, LanguageValue)
 
         if language_value.value:
@@ -28,19 +37,35 @@ def add(self, language_value: LanguageValue) -> LanguageValues:
         return self
 
     def get(self, language: str = None) -> Optional[LanguageValue]:
+        """
+        Get a LanguageValue object with the specified language. Use the default language in wbi_config if none specified.
+
+        :param language: The requested language.
+        :return: The related LanguageValue object or None if none found.
+        """
         language = str(language or config['DEFAULT_LANGUAGE'])
         if language in self.values:
             return self.values[language]
 
         return None
 
     def set(self, language: str = None, value: str = None, action_if_exists: ActionIfExists = ActionIfExists.REPLACE) -> Optional[LanguageValue]:
+        """
+        Create or update the specified language with the valued passed in arguments.
+
+
+        :param language: The desired language.
+        :param value: The desired value of the LanguageValue object. Use None to delete an existing LanguageValue object from the list.
+        :param action_if_exists: The action if the LanguageValue object is already defined. Can be ActionIfExists.REPLACE (default) or ActionIfExists.KEEP.
+        :return: The created or updated LanguageValue. None if there's no LanguageValue object with this language.
+        """
         language = str(language or config['DEFAULT_LANGUAGE'])
         assert action_if_exists in [ActionIfExists.REPLACE, ActionIfExists.KEEP]
 
         # Remove value if None
-        if value is None and language in self.values:
-            self.values[language].remove()
+        if value is None:
+            if language in self.values:
+                self.values[language].remove()
             return None
 
         if action_if_exists == ActionIfExists.REPLACE or self.get(language=language) is None:
@@ -51,12 +76,23 @@ def set(self, language: str = None, value: str = None, action_if_exists: ActionI
         return self.get(language=language)
 
     def from_json(self, json_data: Dict[str, Dict]) -> LanguageValues:
+        """
+        Create a new LanguageValues object from a JSON/dict object.
+
+        :param json_data: A dict object who use the same format as Wikibase.
+        :return: The newly created or updated object.
+        """
         for language_value in json_data:
             self.add(language_value=LanguageValue(language=json_data[language_value]['language']).from_json(json_data=json_data[language_value]))
 
         return self
 
     def get_json(self) -> Dict[str, Dict]:
+        """
+        Get a formated dict who respect the Wikibase format.
+
+        :return: A dict using Wikibase format.
+        """
         json_data: Dict[str, Dict] = {}
         for language, language_value in self.values.items():
             json_data[language] = language_value.get_json()

wikibaseintegrator/wbi_backoff.py

@@ -1,3 +1,6 @@
+"""
+WikibaseIntegrator implementation of backoff python library.
+"""
 import sys
 from functools import partial
 from json import JSONDecodeError
@@ -8,19 +11,17 @@
 from wikibaseintegrator.wbi_config import config
 
 
-def wbi_backoff_backoff_hdlr(details):
+def wbi_backoff_backoff_hdlr(details) -> None:
     exc_type, exc_value, _ = sys.exc_info()
     if exc_type == JSONDecodeError:
         print(exc_value.doc)  # pragma: no cover
     print("Backing off {wait:0.1f} seconds afters {tries} tries calling function with args {args} and kwargs {kwargs}".format(**details))  # pylint: disable=consider-using-f-string
 
 
-def wbi_backoff_check_json_decode_error(e):
+def wbi_backoff_check_json_decode_error(e) -> bool:
     """
     Check if the error message is "Expecting value: line 1 column 1 (char 0)"
     if not, its a real error and we shouldn't retry
-    :param e:
-    :return:
     """
     return isinstance(e, JSONDecodeError) and str(e) != "Expecting value: line 1 column 1 (char 0)"
 

wikibaseintegrator/wbi_fastrun.py

@@ -110,6 +110,14 @@ def reconstruct_statements(self, qid: str) -> List[BaseDataType]:
         return reconstructed_statements
 
     def get_item(self, claims: Union[list, Claims], cqid: str = None) -> Optional[str]:
+        """
+        Load an item from the SPARQL endpoint.
+
+        :param claims:
+        :param cqid:
+        :return: the claim id
+        :exception: if there is more than one claim
+        """
         match_sets = []
         for claim in claims:
             # skip to next if statement has no value or no data type defined, e.g. for deletion objects
@@ -165,6 +173,14 @@ def get_item(self, claims: Union[list, Claims], cqid: str = None) -> Optional[st
         return matching_qids.pop()
 
     def write_required(self, data: List[BaseDataType], action_if_exists: ActionIfExists = ActionIfExists.REPLACE, cqid: str = None) -> bool:
+        """
+        Check if a write is required
+
+        :param data:
+        :param action_if_exists:
+        :param cqid:
+        :return: Return True if the write is required
+        """
         del_props = set()
         data_props = set()
         append_props = []
@@ -260,6 +276,7 @@ def write_required(self, data: List[BaseDataType], action_if_exists: ActionIfExi
     def init_language_data(self, lang: str, lang_data_type: str) -> None:
         """
         Initialize language data store
+
         :param lang: language code
         :param lang_data_type: 'label', 'description' or 'aliases'
         :return: None