personal_knowledge_library 3.0.0__py3-none-any.whl

knowledge/utils/graph.py

@@ -0,0 +1,417 @@
+# -*- coding: utf-8 -*-
+# Copyright © 2024-present Wacom. All rights reserved.
+from typing import Optional, Iterator, Tuple, AsyncIterator
+
+from knowledge.base.language import LocaleCode
+from knowledge.base.ontology import OntologyClassReference, ThingObject
+from knowledge.services.asyncio.graph import AsyncWacomKnowledgeService
+from knowledge.services.graph import WacomKnowledgeService, Visibility
+
+
+def count_things(
+    wacom_client: WacomKnowledgeService,
+    user_token: str,
+    concept_type: OntologyClassReference,
+    locale: Optional[LocaleCode] = None,
+    visibility: Optional[Visibility] = None,
+    only_own: Optional[bool] = None,
+) -> int:
+    """
+    Counts the number of things.
+
+    Parameters
+    ----------
+    wacom_client: WacomKnowledgeService
+        The Wacom Knowledge Service
+    user_token: str
+        The user token
+    concept_type: OntologyClassReference
+        The concept type
+    locale: Optional[LocaleCode]
+        The locale
+    visibility: Optional[Visibility]
+        The visibility
+    only_own: Optional[bool]
+        Only own things
+    Returns
+    -------
+    int
+        The number of things
+    """
+    _, total, _ = wacom_client.listing(
+        concept_type,
+        visibility=visibility,
+        locale=locale,
+        is_owner=only_own,
+        limit=1,
+        estimate_count=True,
+        auth_key=user_token,
+    )
+    return total
+
+
+def count_things_session(
+    wacom_client: WacomKnowledgeService,
+    concept_type: OntologyClassReference,
+    locale: Optional[LocaleCode] = None,
+    visibility: Optional[Visibility] = None,
+    only_own: Optional[bool] = None,
+) -> int:
+    """
+    Counts the number of things.
+
+    Parameters
+    ----------
+    wacom_client: WacomKnowledgeService
+        The Wacom Knowledge Service
+    concept_type: OntologyClassReference
+        The concept type
+    locale: Optional[LocaleCode]
+        The locale
+    visibility: Optional[Visibility]
+        The visibility
+    only_own: Optional[bool]
+        Only own things
+    Returns
+    -------
+    int
+        The number of things
+    """
+    _, total, _ = wacom_client.listing(
+        concept_type, visibility=visibility, locale=locale, is_owner=only_own, limit=1, estimate_count=True
+    )
+    return total
+
+
+def things_session_iter(
+    wacom_client: WacomKnowledgeService,
+    concept_type: OntologyClassReference,
+    visibility: Optional[Visibility] = None,
+    locale: Optional[LocaleCode] = None,
+    only_own: bool = False,
+    fetch_size: int = 100,
+    force_refresh_timeout: int = 360,
+) -> Iterator[ThingObject]:
+    """
+    Iterates over all things using the current session configured for client.
+
+    Parameters
+    ----------
+    wacom_client: WacomKnowledgeService
+        The Wacom Knowledge Service
+    concept_type: OntologyClassReference
+        The class type
+    visibility: Optional[Visibility] [default:= None]
+        The visibility
+    locale: Optional[LocaleCode] [default:= None]
+        Only entities with this labels having a given locale
+    only_own: bool [default:= False]
+        Only own things
+    fetch_size: int [default:= 100]
+        Fetch size.
+    force_refresh_timeout: int [default:= 360]
+        Force refresh timeout
+
+    Returns
+    -------
+    Iterator[ThingObject]
+        Iterator of things
+
+    Raises
+    ------
+    ValueError
+        If no session is configured for client
+    """
+    next_page_id: Optional[str] = None
+    if wacom_client.current_session is None:
+        raise ValueError("No session configured for client")
+    while True:
+        # Refresh token if needed
+        things, _, next_page_id = wacom_client.listing(
+            concept_type,
+            visibility=visibility,
+            locale=locale,
+            is_owner=only_own,
+            limit=fetch_size,
+            page_id=next_page_id,
+        )
+        if len(things) == 0:
+            return
+        for obj in things:
+            # Refresh token if needed
+            wacom_client.handle_token(force_refresh_timeout=force_refresh_timeout)
+            yield obj
+
+
+def things_iter(
+    wacom_client: WacomKnowledgeService,
+    user_token: str,
+    refresh_token: str,
+    concept_type: OntologyClassReference,
+    visibility: Optional[Visibility] = None,
+    locale: Optional[LocaleCode] = None,
+    only_own: bool = False,
+    fetch_size: int = 100,
+    force_refresh_timeout: int = 360,
+    tenant_api_key: Optional[str] = None,
+    external_user_id: Optional[str] = None,
+) -> Iterator[Tuple[ThingObject, str, str]]:
+    """
+    Iterates over all things.
+
+    Parameters
+    ----------
+    wacom_client: WacomKnowledgeService
+        The Wacom Knowledge Service
+    user_token: str
+        The user token
+    refresh_token: str
+        The refresh token
+    concept_type: OntologyClassReference
+        The class type
+    visibility: Optional[Visibility] [default:= None]
+        The visibility
+    locale: Optional[LocaleCode] [default:= None]
+        Only entities with this labels having a given locale
+    only_own: bool [default:= False]
+        Only own things
+    fetch_size: int [default:= 100]
+        Fetch size.
+    force_refresh_timeout: int [default:= 360]
+        Force refresh timeout
+    tenant_api_key: Optional[str] [default:= None]
+        The tenant API key
+    external_user_id: Optional[str] [default:= None]
+        The external user ID
+
+    Yields
+    -------
+    obj: ThingObject
+        Current thing
+    user_token: str
+        The user token
+    refresh_token: str
+        The refresh token
+    """
+    next_page_id: Optional[str] = None
+    if tenant_api_key is not None and external_user_id is not None:
+        # First login
+        wacom_client.login(tenant_api_key=tenant_api_key, external_user_id=external_user_id)
+    else:
+        wacom_client.register_token(user_token, refresh_token)
+    while True:
+        # Refresh token if needed
+        things, _, next_page_id = wacom_client.listing(
+            concept_type,
+            visibility=visibility,
+            locale=locale,
+            is_owner=only_own,
+            limit=fetch_size,
+            page_id=next_page_id,
+        )
+        if len(things) == 0:
+            return
+        for obj in things:
+            # Refresh token if needed
+            wacom_client.handle_token(force_refresh_timeout=force_refresh_timeout)
+            yield obj, user_token, refresh_token
+
+
+async def async_count_things(
+    async_client: AsyncWacomKnowledgeService,
+    user_token: str,
+    concept_type: OntologyClassReference,
+    locale: Optional[LocaleCode] = None,
+    visibility: Optional[Visibility] = None,
+    only_own: Optional[bool] = None,
+) -> int:
+    """
+    Async counting of things given a concept type.
+
+    Parameters
+    ----------
+    async_client: AsyncWacomKnowledgeService
+        The Wacom Knowledge Service
+    user_token: str
+        The user token
+    concept_type: OntologyClassReference
+        The concept type
+    locale: Optional[LocaleCode]
+        The locale
+    visibility: Optional[Visibility]
+        The visibility
+    only_own: Optional[bool]
+        Only own things
+
+    Returns
+    -------
+    int
+        The number of things
+    """
+    _, total, _ = await async_client.listing(
+        concept_type,
+        visibility=visibility,
+        locale=locale,
+        limit=1,
+        estimate_count=True,
+        is_owner=only_own,
+        auth_key=user_token,
+    )
+    return total
+
+
+async def async_count_things_session(
+    async_client: AsyncWacomKnowledgeService,
+    concept_type: OntologyClassReference,
+    locale: Optional[LocaleCode] = None,
+    visibility: Optional[Visibility] = None,
+    only_own: Optional[bool] = None,
+) -> int:
+    """
+    Async counting of things given a concept type using session.
+
+    Parameters
+    ----------
+    async_client: AsyncWacomKnowledgeService
+        The Wacom Knowledge Service
+    concept_type: OntologyClassReference
+        The concept type
+    locale: Optional[LocaleCode]
+        The locale
+    visibility: Optional[Visibility]
+        The visibility
+    only_own: Optional[bool]
+        Only own things
+
+    Returns
+    -------
+    int
+        The number of things
+    """
+    _, total, _ = await async_client.listing(
+        concept_type, visibility=visibility, is_owner=only_own, locale=locale, limit=1, estimate_count=True
+    )
+    return total
+
+
+async def async_things_iter(
+    async_client: AsyncWacomKnowledgeService,
+    user_token: str,
+    refresh_token: str,
+    concept_type: OntologyClassReference,
+    visibility: Optional[Visibility] = None,
+    locale: Optional[LocaleCode] = None,
+    only_own: Optional[bool] = None,
+    fetch_size: int = 100,
+    force_refresh_timeout: int = 360,
+    tenant_api_key: Optional[str] = None,
+    external_user_id: Optional[str] = None,
+) -> AsyncIterator[Tuple[ThingObject, str, str]]:
+    """
+    Asynchronous iterator over all things of a given type.
+
+    Parameters
+    ----------
+    async_client: AsyncWacomKnowledgeService
+        The Wacom Knowledge Service
+    user_token: str
+        The user token
+    refresh_token: str
+        The refresh token
+    concept_type: OntologyClassReference
+        The class type
+    visibility: Optional[Visibility] [default:= None]
+        The visibility
+    locale: Optional[LocaleCode] [default:= None]
+        Only entities with this labels having a given locale
+    only_own: Optional[bool] = [default:= None]
+        Only own things
+    fetch_size: int [default:= 100]
+        Fetch size.
+    force_refresh_timeout: int [default:= 360]
+        Force refresh timeout
+    tenant_api_key: Optional[str] [default:= None]
+        The tenant API key
+    external_user_id: Optional[str] [default:= None]
+        The external user ID
+
+    Returns
+    -------
+    AsyncIterator[ThingObject]
+        Asynchronous Iterator of things
+    """
+    next_page_id: Optional[str] = None
+    if tenant_api_key is not None and external_user_id is not None:
+        # First login
+        await async_client.login(tenant_api_key=tenant_api_key, external_user_id=external_user_id)
+    else:
+        await async_client.register_token(user_token, refresh_token)
+    while True:
+        things, _, next_page_id = await async_client.listing(
+            concept_type,
+            visibility=visibility,
+            locale=locale,
+            is_owner=only_own,
+            limit=fetch_size,
+            page_id=next_page_id,
+        )
+        if len(things) == 0:
+            return
+        for obj in things:
+            user_token, refresh_token = await async_client.handle_token(force_refresh_timeout=force_refresh_timeout)
+            yield obj, user_token, refresh_token
+
+
+async def async_things_session_iter(
+    async_client: AsyncWacomKnowledgeService,
+    concept_type: OntologyClassReference,
+    visibility: Optional[Visibility] = None,
+    locale: Optional[LocaleCode] = None,
+    only_own: Optional[bool] = None,
+    fetch_size: int = 100,
+    force_refresh_timeout: int = 360,
+) -> AsyncIterator[ThingObject]:
+    """
+    Asynchronous iterator over all things of a given type using session.
+
+    Parameters
+    ----------
+    async_client: AsyncWacomKnowledgeService
+        The Wacom Knowledge Service
+    concept_type: OntologyClassReference
+        The class type
+    visibility: Optional[Visibility] [default:= None]
+        The visibility
+    locale: Optional[LocaleCode] [default:= None]
+        Only entities with this labels having a given locale
+    only_own: Optional[bool] = [default:= None]
+        Only own things
+    fetch_size: int [default:= 100]
+        Fetch size.
+    force_refresh_timeout: int [default:= 360]
+        Force refresh timeout
+
+    Returns
+    -------
+    AsyncIterator[ThingObject]
+        Asynchronous Iterator of things
+    """
+    next_page_id: Optional[str] = None
+    if async_client.current_session is None:
+        raise ValueError("No session configured for client")
+
+    while True:
+        things, _, next_page_id = await async_client.listing(
+            concept_type,
+            visibility=visibility,
+            is_owner=only_own,
+            locale=locale,
+            limit=fetch_size,
+            page_id=next_page_id,
+        )
+        if len(things) == 0:
+            return
+        for obj in things:
+            await async_client.handle_token(force_refresh_timeout=force_refresh_timeout)
+            if obj.owner or not only_own:
+                yield obj

knowledge/utils/wikidata.py

@@ -0,0 +1,197 @@
+# -*- coding: utf-8 -*-
+# Copyright © 2024-present Wacom. All rights reserved.
+from typing import Any, Dict, List
+
+from knowledge import logger
+from knowledge.base.entity import LanguageCode, IMAGE_TAG, STATUS_FLAG_TAG, Description, Label
+from knowledge.base.language import LANGUAGE_LOCALE_MAPPING, LocaleCode
+from knowledge.base.ontology import ThingObject, OntologyClassReference
+
+
+# ----------------------------------------------- Helper functions -----------------------------------------------------
+def update_language_code(lang: LanguageCode) -> LocaleCode:
+    """Update the language_code code to a default language_code / country code
+    Parameters
+    ----------
+    lang: LanguageCode
+        Language code.
+
+    Returns
+    -------
+    language_code: LocaleCode
+        Language code.
+
+    Raises
+    ------
+    ValueError
+        If the language_code code is not supported.
+    """
+    if lang not in LANGUAGE_LOCALE_MAPPING:
+        raise ValueError(f"Language code {lang} not supported.")
+    return LANGUAGE_LOCALE_MAPPING[lang]
+
+
+def localized_list_description(entity_dict: Dict[str, str]) -> List[Description]:
+    """
+    Creates a list of descriptions for the given entity dictionary.
+    Parameters
+    ----------
+    entity_dict: Dict[str, str]
+        Entities dictionary.
+
+    Returns
+    -------
+    descriptions: List[Description]
+        List of descriptions.
+    """
+    return [Description(cont, update_language_code(LanguageCode(lang))) for lang, cont in entity_dict.items()]
+
+
+def localized_list_label(entity_dict: Dict[str, str]) -> List[Label]:
+    """
+    Creates a list of labels for the given entity dictionary.
+
+    Parameters
+    ----------
+    entity_dict: Dict[str, str]
+        Entities dictionary.
+
+    Returns
+    -------
+    labels: List[Label]
+        List of labels.
+    """
+    return [
+        Label(cont, update_language_code(LanguageCode(lang)), main=True)
+        for lang, cont in entity_dict.items()
+        if cont != ""
+    ]
+
+
+def localized_flatten_alias_list(entity_dict: Dict[str, List[str]]) -> List[Label]:
+    """
+    Flattens the alias list.
+    Parameters
+    ----------
+    entity_dict: Dict[str, List[str]]
+        Entities dictionary.
+
+    Returns
+    -------
+    flatten: List[Label]
+        Flattened list of labels.
+    """
+    flatten: List[Label] = []
+    for language, items in entity_dict.items():
+        for i in items:
+            if i != "":
+                flatten.append(Label(i, update_language_code(LanguageCode(language)), main=False))
+    return flatten
+
+
+def from_dict(entity: Dict[str, Any], concept_type: OntologyClassReference) -> ThingObject:
+    """
+    Create a thing object from a dictionary.
+    Parameters
+    ----------
+    entity: Dict[str, Any]
+        Entities dictionary.
+    concept_type: OntologyClassReference
+        Concept type.
+
+    Returns
+    -------
+    thing: ThingObject
+        Thing object.
+    """
+    labels: List[Label] = localized_list_label(entity["label"])
+    description: List[Description] = localized_list_description(entity["description"])
+    alias: List[Label] = localized_flatten_alias_list(entity["alias"])
+    if IMAGE_TAG in entity:
+        icon: str = entity[IMAGE_TAG]
+    else:
+        logger.warning(f"Entity has no image: {entity}")
+        icon: str = ""
+    # Create the entity
+    thing: ThingObject = ThingObject(label=labels, concept_type=concept_type, description=description, icon=icon)
+    thing.alias = alias
+    if STATUS_FLAG_TAG in entity:
+        thing.status_flag = entity[STATUS_FLAG_TAG]
+    return thing
+
+
+# --------------------------------------------------- Utilities --------------------------------------------------------
+
+
+def strip(url: str) -> str:
+    """Strip qid from url.
+    Parameters
+    ----------
+    url: str
+        URL
+    Returns
+    -------
+    result: str
+        Stripped URL
+    """
+    parts = url.split("/")
+    return parts[-1]
+
+
+def build_query(params: Dict[str, Any]) -> List[str]:
+    """
+    Build of query.
+
+    Parameters
+    ----------
+    params:
+        Parameters for query
+
+    Returns
+    -------
+    queries: List[str]
+        SPARQL query string
+    """
+    filters: List[Dict[str, Any]] = params.get("filters")
+    dynamics: Dict[str, Any] = params.get("dynamic-filters")
+    limit: int = params.get("limit", 1000)
+    lang_code: str = params.get("language_code", "en")
+    filter_string: str = ""
+    queries: List[str] = []
+    for f in filters:
+        filter_string += f"?item wdt:{f['property']}  wd:{f['target']}.\n"
+    if dynamics:
+        property_str: str = dynamics["property"]
+        for v in dynamics["targets"]:
+            dyn: str = filter_string + f"?item wdt:{property_str}  wd:{v}.\n"
+            query: str = f"""SELECT DISTINCT ?item ?itemLabel WHERE {{
+              {dyn}SERVICE wikibase:label {{ bd:serviceParam wikibase:language \"[AUTO_LANGUAGE],{lang_code}\". }}
+            }}
+            LIMIT {limit}
+            """
+            queries.append(query)
+    else:
+        query: str = f"""SELECT DISTINCT ?item ?itemLabel WHERE {{
+          {filter_string}SERVICE wikibase:label {{ bd:serviceParam wikibase:language \"[AUTO_LANGUAGE],{lang_code}\". }}
+        }}
+        LIMIT {limit}
+        """
+        queries.append(query)
+    return queries
+
+
+def extract_qid(url: str) -> str:
+    """
+    Extract qid from url.
+    Parameters
+    ----------
+    url: str
+        URL
+
+    Returns
+    -------
+    qid: str
+        QID
+    """
+    parts: List[str] = url.split("/")
+    return parts[-1]