wordlift-sdk 2.7.1__py3-none-any.whl

wordlift_sdk-2.7.1.dist-info/METADATA

@@ -0,0 +1,125 @@
+Metadata-Version: 2.3
+Name: wordlift-sdk
+Version: 2.7.1
+Summary: 
+Author: David Riccitelli
+Author-email: david@wordlift.io
+Requires-Python: >=3.10,<3.14
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: advertools (>=0.16.6,<0.17.0)
+Requires-Dist: aiohttp (>=3.10.5,<4.0.0)
+Requires-Dist: google-auth (>=2.35.0,<3.0.0)
+Requires-Dist: gql[aiohttp] (>=3.5.2,<4.0.0)
+Requires-Dist: gspread (>=6.1.2,<7.0.0)
+Requires-Dist: pandas (>=2.1.4,<2.3.0)
+Requires-Dist: pycountry (>=24.6.1,<25.0.0)
+Requires-Dist: python-liquid (>=2.0.1,<3.0.0)
+Requires-Dist: rdflib (>=7.0.0,<8.0.0)
+Requires-Dist: tenacity (>=9.0.0,<10.0.0)
+Requires-Dist: tqdm (>=4.67.1,<5.0.0)
+Requires-Dist: wordlift-client (>=1.117.0,<2.0.0)
+Description-Content-Type: text/markdown
+
+ # WordLift Python SDK
+
+A Python toolkit for orchestrating WordLift imports: fetch URLs from sitemaps, Google Sheets, or explicit lists, filter out already imported pages, enqueue search console jobs, push RDF graphs, and call the WordLift APIs to import web pages.
+
+## Features
+- URL sources: XML sitemaps (with optional regex filtering), Google Sheets (`url` column), or Python lists.
+- Change detection: skips URLs that are already imported unless `OVERWRITE` is enabled; re-imports when `lastmod` is newer.
+- Web page imports: sends URLs to WordLift with embedding requests, output types, retry logic, and pluggable callbacks.
+- Search Console refresh: triggers analytics imports when top queries are stale.
+- Graph templates: renders `.ttl.liquid` templates under `data/templates` with account data and uploads the resulting RDF graphs.
+- Extensible: override protocols via `WORDLIFT_OVERRIDE_DIR` without changing the library code.
+
+## Installation
+
+```bash
+pip install wordlift-sdk
+# or
+poetry add wordlift-sdk
+```
+
+Requires Python 3.10–3.13.
+
+## Configuration
+
+Settings are read in order: `config/default.py` (or a custom path you pass to `ConfigurationProvider.create`), environment variables, then (when available) Google Colab `userdata`.
+
+Common options:
+- `WORDLIFT_KEY` (required): WordLift API key.
+- `API_URL`: WordLift API base URL, defaults to `https://api.wordlift.io`.
+- `SITEMAP_URL`: XML sitemap to crawl; `SITEMAP_URL_PATTERN` optional regex to filter URLs.
+- `SHEETS_URL`, `SHEETS_NAME`, `SHEETS_SERVICE_ACCOUNT`: use a Google Sheet as source; service account points to credentials file.
+- `URLS`: list of URLs (e.g., `["https://example.com/a", "https://example.com/b"]`).
+- `OVERWRITE`: re-import URLs even if already present (default `False`).
+- `WEB_PAGE_IMPORT_WRITE_STRATEGY`: WordLift write strategy (default `createOrUpdateModel`).
+- `EMBEDDING_PROPERTIES`: list of schema properties to embed.
+- `WEB_PAGE_TYPES`: output schema types, defaults to `["http://schema.org/Article"]`.
+- `GOOGLE_SEARCH_CONSOLE`: enable/disable Search Console handler (default `True`).
+- `CONCURRENCY`: max concurrent handlers, defaults to `min(cpu_count(), 4)`.
+- `WORDLIFT_OVERRIDE_DIR`: folder containing protocol overrides (default `app/overrides`).
+
+Example `config/default.py`:
+
+```python
+WORDLIFT_KEY = "your-api-key"
+SITEMAP_URL = "https://example.com/sitemap.xml"
+SITEMAP_URL_PATTERN = r"^https://example.com/article/.*$"
+GOOGLE_SEARCH_CONSOLE = True
+WEB_PAGE_TYPES = ["http://schema.org/Article"]
+EMBEDDING_PROPERTIES = [
+    "http://schema.org/headline",
+    "http://schema.org/abstract",
+    "http://schema.org/text",
+]
+```
+
+## Running the import workflow
+
+```python
+import asyncio
+from wordlift_sdk import run_kg_import_workflow
+
+if __name__ == "__main__":
+    asyncio.run(run_kg_import_workflow())
+```
+
+The workflow:
+1. Renders and uploads RDF graphs from `data/templates/*.ttl.liquid` using account info.
+2. Builds the configured URL source and filters out unchanged URLs (unless `OVERWRITE`).
+3. Sends each URL to WordLift for import with retries and optional Search Console refresh.
+
+You can build components yourself when you need more control:
+
+```python
+import asyncio
+from wordlift_sdk.container.application_container import ApplicationContainer
+
+async def main():
+    container = ApplicationContainer()
+    workflow = await container.create_kg_import_workflow()
+    await workflow.run()
+
+asyncio.run(main())
+```
+
+## Custom callbacks and overrides
+
+Override the web page import callback by placing `web_page_import_protocol.py` with a `WebPageImportProtocol` class under `WORDLIFT_OVERRIDE_DIR` (default `app/overrides`). The callback receives a `WebPageImportResponse` and can push to `graph_queue` or `entity_patch_queue`.
+
+## Templates
+
+Add `.ttl.liquid` files under `data/templates`. Templates render with `account` fields available (e.g., `{{ account.dataset_uri }}`) and are uploaded before URL handling begins.
+
+## Testing
+
+```bash
+poetry install --with dev
+poetry run pytest
+```
+

wordlift_sdk-2.7.1.dist-info/RECORD

@@ -0,0 +1,100 @@
+wordlift_sdk/__init__.py,sha256=Xv7okTmyNmt6hgCUhFeFzh-Phw3LChdw89EuRt8kq_4,79
+wordlift_sdk/client/__init__.py,sha256=-lCMSH8UmtjETZHaXwwjkk6ID3uVa64ryUZ-wlBVR9w,111
+wordlift_sdk/client/client_configuration_factory.py,sha256=aDhiEYsxzKQUun3kFN_W7RJcfSbhGX9XeeKZPGeLfHo,799
+wordlift_sdk/configuration/__init__.py,sha256=MOrZCRQCeeCae2rVcR9THy9yxK8n_Gpx1BobsDptbgQ,162
+wordlift_sdk/configuration/configuration_provider.py,sha256=Fz1iZHvbpdxh92sKucDFmhJDBEwYZEB6iYm646Deixk,1324
+wordlift_sdk/configuration/get_config_value.py,sha256=nULkIY9hISEytArZVHrt2Ju8QNGQR4pAhJ388kG2Tu8,1050
+wordlift_sdk/container/__init__.py,sha256=_lFoxsP0acwODKryIVo0n4FuagUdyZ30LjFaXM4jfy4,92
+wordlift_sdk/container/application_container.py,sha256=Kk3TiCgLAPxM0cix_gUM3-Tf_vUXYhSnkxDVbBYpi5g,9053
+wordlift_sdk/deprecated/__init__.py,sha256=vQacTb6XoS2wO1ccBfSCyQmUNBKnJKl59iyR7dH_Ghk,160
+wordlift_sdk/deprecated/create_entities_with_top_query_dataframe.py,sha256=KhJ0P99cnoMqMV7D4Ox5DtGApEbptJSrV9X4Ho_tjNQ,921
+wordlift_sdk/entity/__init__.py,sha256=v1CYhRguuoVBaDkbysRP5D1uTDUvm0tdF9MVDa4qAAQ,123
+wordlift_sdk/entity/enrich.py,sha256=agXDLJhE8oJyiM8aV70bFyFjRc1tHUbdLIcIrL02J7U,1982
+wordlift_sdk/entity/patch.py,sha256=CP2H2nrrli4A_zu1D00Egye1I784ZQ6MxL_jS9ZsW9k,523
+wordlift_sdk/google_search_console/__init__.py,sha256=-PmsnNYsGs4Utb9l7AXz0qAzcWhJeD-eZyFNfOHM5ow,384
+wordlift_sdk/google_search_console/create_google_search_console_data_import.py,sha256=xP_koUaaXYnnNVyw2ld4jbqc_d7yFkYXLe2dC2vLpm0,2223
+wordlift_sdk/google_search_console/raise_error_if_account_analytics_not_configured.py,sha256=pXcRlaVAODSbSgxI3KTtsHp37qiIaWCu9ISDKtDw6qM,830
+wordlift_sdk/graph/graph_bag.py,sha256=Gp0ufstKY5xCx6dZNohcTmaEhoEYef891eaLuESUJpM,105
+wordlift_sdk/graph/ttl_liquid/__init__.py,sha256=2AmJpsFFkJxv6FyO7J3XFUfX1nSPDoY31tRom-K5C_w,97
+wordlift_sdk/graph/ttl_liquid/ttl_liquid_graph_factory.py,sha256=CSzO36YZ-XQrV7xRi99LhmYfQgMxjBkKdfEGeD0Zt9M,1242
+wordlift_sdk/graphql/__init__.py,sha256=QuI1slWTN_ULF8W2goCkRstC9uTytVOBqIx2MMcXfJ4,46
+wordlift_sdk/graphql/client/__init__.py,sha256=1AatJnAUtWMAH2yRn8doSVxUnQIeyzPdnOFakmyxNZU,201
+wordlift_sdk/graphql/client/client.py,sha256=2JKj10JdAwCGEx8cO5cOpN8pi0JsnVcKOB9YIWbbH4U,2147
+wordlift_sdk/graphql/client/factory.py,sha256=X5ig85_sDxeFDERN7hBgZOMvoHRYaiUcpiEOpkZObYk,1143
+wordlift_sdk/graphql/client/gql_client_provider.py,sha256=e8haJEUUqgmtiT6TZyHU7B8eOLNAX5KRlbK4qzwNmGc,766
+wordlift_sdk/graphql/data/entities_by_type.graphql,sha256=-SItjZE9S-sxviVG8jTF3QQWP8wSupjuH1O93sZfbNg,226
+wordlift_sdk/graphql/data/entities_embedding_value.graphql,sha256=K_abFr_MKpPt2S-veFCx1Wn9z7DpRrvnTZfCsAA8_4Y,370
+wordlift_sdk/graphql/data/entities_top_query.graphql,sha256=PboyUgRGtdPzQafaxqLZCK3SyhGIQjnrN15fd6Ymrwg,713
+wordlift_sdk/graphql/data/entities_url_id.graphql,sha256=1Vzk0gWqcsA6FuzLmjSqm5EaKf8QqBMTd3ZiYMs_H0c,162
+wordlift_sdk/graphql/data/entities_url_iri.graphql,sha256=rtwnV-rycoKXgYdR5kJrkr0DCnr6jVIfiIPrCEVdDfI,220
+wordlift_sdk/graphql/data/entities_url_iri_with_source_equal_to_web_page_import.graphql,sha256=f7DRiFSmqIG0aaqcT2_8YVVTvYax1ITrUsjRtHrJwGE,349
+wordlift_sdk/graphql/query.py,sha256=uu-2_yxmizNPsFWDZRw9wTyLzbcCc0YCwZPrAuPVEP4,729
+wordlift_sdk/graphql/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+wordlift_sdk/graphql/utils/query/__init__.py,sha256=ZYHHfPT6r3AknTqx-OOuoJfj54WeibpvnHTKLIN-vbs,173
+wordlift_sdk/graphql/utils/query/entity_top_query.py,sha256=XViljOJ3KUQMopNO94k4Vo_0DtD9mB_cvy4_yigxSvM,2263
+wordlift_sdk/graphql/utils/query/entity_with_top_query.py,sha256=rP_C6h1F09WErXzsYU8jgQov1T-AI3CRzavoMu0mdek,1902
+wordlift_sdk/id_generator/__init__.py,sha256=O04jGKqZmW3nLX5ooKrbQZAKccJAn1HUUA7ZXonWHD4,65
+wordlift_sdk/id_generator/id_generator.py,sha256=Lbv50D5NXDHcID1FEuCyydNhasul9ahgSp-6NT6MJwY,1371
+wordlift_sdk/id_generator/id_generator_interface.py,sha256=LJLTWfuDtt5tT6Nb7aGnsCx__L7rTlqRL92EQTYFigQ,134
+wordlift_sdk/internal_link/__init__.py,sha256=iw-22JYFeKSz3XOHis_IL0PJPskooZXsQPIdiQJcvJQ,92
+wordlift_sdk/internal_link/utils.py,sha256=Zz0T8zYnq-QQHStn2aj2gTWINFuNmZUGwm92TSkXVfg,9056
+wordlift_sdk/kg/__init__.py,sha256=dGz47CSM0aW3AskpKR9jQpDDJTp2CKNQsZ9wB5irEQY,177
+wordlift_sdk/kg/entity.py,sha256=TiKkNlXDPnz-NAIs9rMPGut1jlzaKi8wb4hXsnAEjdM,359
+wordlift_sdk/kg/entity_store.py,sha256=uFfjCT_SyGhEMPxg9WYsoGLmb7omdpTBeF0z8VyoydA,3297
+wordlift_sdk/kg/entity_store_factory.py,sha256=KTLEfDhJqt_-IiK485-WA19mOpwI5yaJOGMa5X7TonQ,267
+wordlift_sdk/kg/relation/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+wordlift_sdk/kg/relation/relation_service.py,sha256=vo71xQxSqN27EeUGobQoTIAvi6c6Ou6Aue53I0_jBQ4,3513
+wordlift_sdk/main.py,sha256=Bleo_MPMHWSSrpuo7BaFgmB558B-ImI7ROviSdxWJUU,251
+wordlift_sdk/namespace/SDO.py,sha256=jrQ4HoDLG_sK6LQcTS06jy0XHDh4Afr4jqr71Utbaf8,424482
+wordlift_sdk/namespace/__init__.py,sha256=MSahDRm3mm_zWi9zkIo32U6qWT49NVhAhgWNpbirMFs,40
+wordlift_sdk/notebook/__init__.py,sha256=RQC28cZE7qBV9XX3PWWjIbdXjG7-FOPu9qrq3u0h__I,85
+wordlift_sdk/notebook/install_if_missing.py,sha256=JdAqE6T3X5VDFpErf0L4APFrL95svxL9yMrr8rtzOTY,372
+wordlift_sdk/protocol/__init__.py,sha256=mpRdjY13DnPu6iCZIlxP2S3QewMV3snA_QOe9Jv1bOQ,293
+wordlift_sdk/protocol/context.py,sha256=Csf9rGuBxkwuDuRQkjIJgbLWk2i4wNMRCmaDE3VYerg,568
+wordlift_sdk/protocol/entity_patch/__init__.py,sha256=-4UeFAaJkK5v6HK4_t-62UKA1jVwww3q5dfbRRY7SJg,134
+wordlift_sdk/protocol/entity_patch/entity_patch.py,sha256=o6Dc2Fp51zac95IAbutnl_a3CN_jaTPnhiS7EL4JpDk,165
+wordlift_sdk/protocol/entity_patch/entity_patch_queue.py,sha256=k7B9JooK3SqzcM5XmtdoXCyq909XVvmYGeUY9zCl9Gk,1793
+wordlift_sdk/protocol/graph/__init__.py,sha256=A1MUTCRR5o84pYvlPMZFXNxf5396SurHhmBhIW7eOyw,62
+wordlift_sdk/protocol/graph/graph_queue.py,sha256=4q_uBSSC0Wv5bqOL-irQCPHIR4xm8HM2Z5ki1AKY8L4,2270
+wordlift_sdk/protocol/load_override_class.py,sha256=mHsOL8u_uQpQ4GvK_Bvr1dtTY4t7IUZ7PjoUYT90GJA,866
+wordlift_sdk/protocol/web_page_import_protocol.py,sha256=P5WU06fcUFvXO7Z2roU6A06e4r7LlerSVkHW7sQxMwY,577
+wordlift_sdk/url_source/__init__.py,sha256=RmHbF2tY6yCYXeJYq4SnqUVU3R0I5yuRAFWqIWWNIBY,285
+wordlift_sdk/url_source/google_sheets_url_source.py,sha256=tfBrPztpNi_J-i-akM6AFRiKyUw3SJHgloq759nIsVw,2020
+wordlift_sdk/url_source/list_url_source.py,sha256=uhWFI_zF_id80JiEv_JbqC7HphkiXPDh0WgBNCid-v0,808
+wordlift_sdk/url_source/new_or_changed_url_source.py,sha256=KY4BClYkXiKwYWO5O33IYsJfwqr36zEA420OljqIhTo,2000
+wordlift_sdk/url_source/sitemap_url_source.py,sha256=JMIteakIFIWcHoQ3Uf0fyMh8pYz4YM_rnJvdm7NXYak,1198
+wordlift_sdk/url_source/url_source.py,sha256=ZmGOiDlPVzoOTt2Qz69onpnFzQYZlrwWaogOkZMEqGc,403
+wordlift_sdk/url_source/url_source_input.py,sha256=GvRAjBb103DS--rR7M8oIxIjWhQbYUTldwbPx2BctaU,152
+wordlift_sdk/utils/__init__.py,sha256=_BB9cgIXFY5JUDowedu2tZeQmLhtGElUTh6qzVQ-Xoc,759
+wordlift_sdk/utils/create_dataframe_from_google_sheets.py,sha256=7j0oCwUwSqoo2505_QfcUCx4XNqhw94Y_UTL5tyIk5U,1117
+wordlift_sdk/utils/create_dataframe_of_entities_by_types.py,sha256=5U5k_OheifPJyod4PB0HEdYCGwZEMgkdiwckAR8LFJY,770
+wordlift_sdk/utils/create_dataframe_of_entities_with_embedding_vectors.py,sha256=A_JMVoYS4pcWCsKYGH_sHyc9MJvg5EuoKELp1BCI2Ko,679
+wordlift_sdk/utils/create_dataframe_of_url_iri.py,sha256=xTxNyHb1Vo7YdfoYoaiCqp6-4lD0PoLppcxlyAYBTEg,530
+wordlift_sdk/utils/create_entity_patch_request.py,sha256=-fEZrflVpTBtk7c7ME8-BWn6-r86cQJp7fvQJznj_aU,497
+wordlift_sdk/utils/delayed.py,sha256=uy-cQsLMprakx8CiQl6ZLL49bfYB1C6oQt4UObr5TwU,323
+wordlift_sdk/utils/get_me.py,sha256=-mr0DscVWEDFvgBYtmgND3_gIuh2q7kfD-OiqrYwLJU,297
+wordlift_sdk/utils/import_url.py,sha256=KiUFkU4mRfd7YWFlLoz5bB13AgPURV8Km8H05LxevCI,1299
+wordlift_sdk/wordlift/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+wordlift_sdk/wordlift/entity_gaps/__init__.py,sha256=PMtdyBoUD-oiTE-7Izr6fuod7OxGOQIhFSasZG_SafM,109
+wordlift_sdk/wordlift/entity_gaps/create_entity_gaps_factory.py,sha256=LfU8ebaN14vXiwDcLEpJQnrZaxJj7EUWC0zs-qDvj2g,1841
+wordlift_sdk/wordlift/entity_gaps/entity_gaps_callback.py,sha256=w2gBVzIsb4QMFESLidcSKyGM-SGYaWbV5Kb0kFdb534,1119
+wordlift_sdk/wordlift/sitemap_import/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+wordlift_sdk/wordlift/sitemap_import/protocol/__init__.py,sha256=OupEkZdO0-7V0kjvL_S7EQv23ZY27dxaV4iv5cwClJc,504
+wordlift_sdk/wordlift/sitemap_import/protocol/default/__init__.py,sha256=iQhyw4Tcrh7YdLwq3H3RkZDS-cLJwA71_G9pzgmY4CE,200
+wordlift_sdk/wordlift/sitemap_import/protocol/default/default_import_url_protocol.py,sha256=AQZPxquQQlB2BPXUh_5fHmLpEhbZHpgLa0vRvpIvTjk,1428
+wordlift_sdk/wordlift/sitemap_import/protocol/default/default_parse_html_protocol.py,sha256=HjXbsWSbM8UkxKBEu38imRl_dhzQnUtkPYcZ2ELV8K0,1614
+wordlift_sdk/wordlift/sitemap_import/protocol/import_url_protocol_interface.py,sha256=SpGaIwyf1G459Geu50aAZuYl2KZStv9faLdVKKqdaig,463
+wordlift_sdk/wordlift/sitemap_import/protocol/parse_html_protocol_interface.py,sha256=CwLxHTjPz1Zd08WoSIG0y6CS6WZkr0QIcI2BhHfPoUc,602
+wordlift_sdk/wordlift/sitemap_import/protocol/protocol_context.py,sha256=HqjptNxEIge7Ds2VqXVpDqdeRpJsLe0VitZT_5_dcoE,415
+wordlift_sdk/workflow/__init__.py,sha256=n3zp6pkRbimeaDgr3g5fVbKDRZEPbLpry-H599j6YQ8,81
+wordlift_sdk/workflow/create_or_update_entities_factory.py,sha256=fKnxrxqAgRo9vGbsKUEF6I8OUj2Fva0RoRasURoAUR8,586
+wordlift_sdk/workflow/kg_import_workflow.py,sha256=P0SZNq6nP-RduzT0-lK-MT8FZD7QyVVga9-po5k-Peg,1291
+wordlift_sdk/workflow/patch_entities_factory.py,sha256=QwA4EUEYBB2s64mi9YxN_PfcyAZ8_-yzwN9BJYsW1Dk,572
+wordlift_sdk/workflow/url_handler/__init__.py,sha256=2S3ez5C2Xw8FZCJ2Bf0zkASpPqmLWaVapyi8xFFj3tM,104
+wordlift_sdk/workflow/url_handler/default_url_handler.py,sha256=irMoJftx9Gyq-8HQd4Y8HhKvPlHvVXxqyj4b1__m4mw,706
+wordlift_sdk/workflow/url_handler/search_console_url_handler.py,sha256=uOwD4t009-cA9JI7ZtbYhCGRwjhLzDpBNTWHERPnNqI,2698
+wordlift_sdk/workflow/url_handler/url_handler.py,sha256=meyOpWVhLk2NcbtUOO_V0z6_T9q-D3pD7kWQCRioYh0,129
+wordlift_sdk/workflow/url_handler/web_page_import_url_handler.py,sha256=xQiy-fgFj_dWKFFBNWeodAGhIMJQereSPdgnjK-Crmo,3529
+wordlift_sdk-2.7.1.dist-info/METADATA,sha256=04londwmxAjfkUd7cHxoJsUbYxb0QBhcJoFjuJaNkx8,4979
+wordlift_sdk-2.7.1.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
+wordlift_sdk-2.7.1.dist-info/RECORD,,

wordlift_sdk-2.7.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 2.1.3
+Root-Is-Purelib: true
+Tag: py3-none-any