slb-glossary¶

What is this?¶

The SLB Energy Glossary is a large, well maintained reference of oilfield and energy terms, but it's a JavaScript web application, not a page you can just download and read. There's no public API for it either. slb-glossary is a small, focused tool built to search it anyway: it drives a real browser in the background to load the site the way a person would, then parses the definitions out of the page.

It is not affiliated with or endorsed by SLB. The glossary content it searches belongs to SLB, under SLB's own terms of service. slb-glossary only searches and displays that content, and is intended for instructional and research use, not commercial use. If you enable the local cache, you are responsible for keeping its retention, refresh, and deletion in compliance with SLB's terms. See the FAQ for the full attribution.

Three ways in¶

You need take look at Installation first. After that, pick whichever of these matches what you are actually trying to do:

A quick look¶

Here's we have a simple search using the CLI. No code or coding knowledge needed at all. After installing:

slb search "water saturation"

This opens a background browser, searches the live glossary, and prints a table of matching definitions to your terminal.

Here's the same lookup from Python code, using the library directly. You can use this in a script, a notebook, or any other Python environment.:

import asyncio

import slb_glossary as slb


async def main() -> None:
    async with slb.live.session() as session:  # (1)!
        async for result in slb.live.search(session, "water saturation"):  # (2)!
            print(result.term, ":", result.definition)


asyncio.run(main())

1. Opens the background browser for the duration of this block, and closes it automatically on exit, even if search raises.
2. slb.live.search is an async generator. A search term can have more than one definition (one per topic it's filed under), so more than one SearchResult can come back for a single query.

Both do the same underlying work. The CLI is just a wrapper over what the library does.

How it works¶

slb-glossary has three major APIs, layered so each one is optional on its own:

• slb_glossary.live talks to the actual glossary website, through a Playwright-driven browser. This is the only way to reach terms slb-glossary does not already know about, and it's the slowest of the three, since it's a real network round trip through a real page load.
• slb_glossary.local keeps a SQLite database on your own disk. Once a term has been looked up once and saved there, reading it back is instant and needs no network or browser at all. It also supports semantic search over whatever you've stored, matching a paraphrase instead of an exact word.
• slb_glossary.query inteligently utilizes both the live and local APIs. Its search function reads from the local database first, and only reaches for a live fetch if the local result is not confident enough, optionally saving that live result back to the database as it goes (persist=True) so the next call for the same term does not need the network either.

You can use any one of these on its own, or all three in combination. The library tutorial walks you through them in that order.

Scope and limitations¶

slb-glossary is deliberately covers just one glossary. It is not a general web-scraping or knowledge-base tool. That scope comes with a few limits worth knowing up front:

• It depends on the glossary's own page structure. If SLB changes how the site is laid out, parsing can break until the library is updated to match.
• A live search opens a real browser. That's slower than an HTTP request to a JSON API, which is why the local cache and persist=True exist to make the slow path something you only pay for once per term.
• It reads two languages of the glossary, English and Spanish, because that's what the site itself publishes. See slb_glossary.Language in the API reference.

Ready to go?¶