Caching remote contexts

Remote JSON-LD contexts are normal documents loaded through a DocumentLoader. Caching therefore belongs in two places:

1. PyLD's ContextResolver caches resolved contexts during processing.
2. The DocumentLoader can cache HTTP responses before PyLD sees them.

Use RequestsDocumentLoader when you want no HTTP cache. Use RequestsDocumentLoader with a requests_cache.CachedSession for in-memory HTTP caching. Use SqliteCacheRequestsDocumentLoader when the cache should survive process restarts.

For HTTP caching, install the necessary modules first by running:

pip install "PyLD[requests-cache]"

Choose a Cache Mode

Mode	Loader	Reused after process restart?
No HTTP cache	RequestsDocumentLoader()	No
In-memory HTTP cache	RequestsDocumentLoader(session=CachedSession(backend="memory"))	No
Persistent HTTP cache	SqliteCacheRequestsDocumentLoader()	Yes

SqliteCacheRequestsDocumentLoader uses SQLite through requests-cache. When sqlite_file_path is omitted, it stores the cache in the platform user cache directory.

Usage

This example configures all three modes and passes the persistent loader through documentLoader. The document uses an inline @context so the example is safe to run without network access; use the same options shape when the @context is a remote URL.

Example caching_modes.py

import json
import tempfile
from pathlib import Path
from uuid import uuid4

from requests_cache import CachedSession

from pyld import (
    RequestsDocumentLoader,
    SqliteCacheRequestsDocumentLoader,
    jsonld,
)

doc = {
    "@context": {"name": "https://schema.org/name"},
    "name": "Earth",
}

no_cache_loader = RequestsDocumentLoader()

memory_cache_loader = RequestsDocumentLoader(
    session=CachedSession(backend="memory", cache_control=True),
)

persistent_cache_loader = SqliteCacheRequestsDocumentLoader(
    sqlite_file_path=Path(tempfile.gettempdir()) / f"pyld-{uuid4()}.sqlite",
)

result = jsonld.expand(doc, options={"documentLoader": persistent_cache_loader})

print(json.dumps(result, indent=2))

Output

[
  {
    "https://schema.org/name": [
      {
        "@value": "Earth"
      }
    ]
  }
]

For application code, pass the selected loader in the operation options:

Example persistent_document_loader_cache.py

import json
import tempfile
from pathlib import Path
from uuid import uuid4

from pyld import SqliteCacheRequestsDocumentLoader, jsonld

cache_path = Path(tempfile.gettempdir()) / f"pyld-{uuid4()}.sqlite"
loader = SqliteCacheRequestsDocumentLoader(sqlite_file_path=cache_path)

doc = {
    "@context": {"name": "https://schema.org/name"},
    "name": "Earth",
}

expanded = jsonld.expand(doc, options={"documentLoader": loader})

print(json.dumps(expanded, indent=2))

Output

[
  {
    "https://schema.org/name": [
      {
        "@value": "Earth"
      }
    ]
  }
]

HTTP cache headers such as Cache-Control, Expires, and validators are handled by the cached session. PyLD still applies its normal JSON-LD processing rules after the remote document is loaded.

Related reference

See RequestsDocumentLoader, SqliteCacheRequestsDocumentLoader, and ContextResolver.