PyLD 3.2.0__tar.gz → 3.3.0__tar.gz

{pyld-3.2.0 → pyld-3.3.0}/CHANGELOG.md

@@ -1,11 +1,31 @@
 # pyld ChangeLog
 
+## 3.3.0 - 2026-09-02
+
+### Added
+- `pyld.FileDocumentLoader`: a document loader for local `file:` URLs with optional root confinement.
+- `pyld.SchemeDirectedDocumentLoader`: a document loader that dispatches URL
+  strings to per-scheme loaders.
+- `pyld.TypeDirectedDocumentLoader`: a document loader that dispatches by Python
+  input type (e.g. `pathlib.Path` vs `str`).
+- `jsonld.flatten()`, `jsonld.frame()`, and `jsonld.to_rdf()` now accept an
+  `identifierIssuer` option with an `IdentifierIssuer` instance for blank node
+  identifiers. Defaults to `IdentifierIssuer('_:b')`, which preserves the
+  previous behaviour.
+- `pyld` command-line tool (`get`, `expand`, `compact`, `flatten`, `frame`,
+  `to-rdf`, `from-rdf`, and `cache clear`), installed via
+  `pip install "PyLD[cli]"`. Remote contexts are cached in a CLI-specific SQLite
+  file (overridable via `--cache-file` / `PYLD_CACHE_FILE`).
+
 ## 3.2.0 - 2026-08-17
 
 ### Added
 - `*Options` TypedDict types and a `Context` type alias in `pyld.options` for JSON-LD API option dicts (typing and documentation).
 - `pyld.SqliteCacheRequestsDocumentLoader`: a SQLite-backed HTTP cache document loader using `requests-cache`.
 
+### Changed
+- `SqliteCacheRequestsDocumentLoader` creates the SQLite cache file on first document load, not at construction time.
+
 ### Fixed
 - If value objects contain array values for `@type` during expansion, an error is now raised. Fixes [expand#ter54](https://w3c.github.io/json-ld-api/tests/expand-manifest.html#ter54) and [toRdf#ter54](https://w3c.github.io/json-ld-api/tests/toRdf-manifest.html#ter54).
 - Inline contexts that try to redefine @context now raise an error. Fixes [expand#ter56](https://w3c.github.io/json-ld-api/tests/expand-manifest.html#ter56) and [toRdf#ter56](https://w3c.github.io/json-ld-api/tests/toRdf-manifest.html#ter56).

{pyld-3.2.0/lib/PyLD.egg-info → pyld-3.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyLD
-Version: 3.2.0
+Version: 3.3.0
 Summary: Python implementation of the JSON-LD API
 Home-page: https://github.com/digitalbazaar/pyld
 Author: Digital Bazaar
@@ -30,6 +30,9 @@ Provides-Extra: cachetools
 Requires-Dist: cachetools; extra == "cachetools"
 Provides-Extra: frozendict
 Requires-Dist: frozendict; extra == "frozendict"
+Provides-Extra: cli
+Requires-Dist: typer>=0.27; extra == "cli"
+Requires-Dist: requests-cache>=1.3; extra == "cli"
 Dynamic: author
 Dynamic: author-email
 Dynamic: classifier
@@ -103,12 +106,30 @@ Defining a dependency on pyld will not pull in
 [Document Loader](#document-loader) then either depend on the desired external library directly
 or define the requirement as `PyLD[requests]` or `PyLD[aiohttp]`.
 
+## Command line
+
+Install the optional CLI extra to get a JSON-LD 1.1 `pyld` console script:
+
+```bash
+pip install "PyLD[cli]"
+pyld expand document.jsonld
+pyld compact document.jsonld context.jsonld
+pyld frame document.jsonld frame.jsonld
+pyld to-rdf document.jsonld
+pyld from-rdf document.nq
+```
+
+The CLI also provides `get`, `flatten`, and HTTP cache management. See the
+[CLI documentation](https://digitalbazaar.github.io/pyld/cli/) for all commands,
+options, and stdin support.
+
 ## Usage
 
 Here are some quick examples to get started:
 
 ```python
 from pyld import jsonld
+from pyld.identifier_issuer import IdentifierIssuer
 import json
 
 doc = {
@@ -170,6 +191,13 @@ normalized = jsonld.normalize(
     doc, {'algorithm': 'URDNA2015', 'format': 'application/n-quads'})
 # normalized is a string that is a canonical representation of the document
 # that can be used for hashing, comparison, etc.
+
+# convert a document to RDF with a custom blank node issuer
+issuer = IdentifierIssuer('_:doc')
+rdf = jsonld.to_rdf(
+    doc,
+    {'identifierIssuer': issuer, 'format': 'application/n-quads'})
+# flatten() and frame() accept the same identifierIssuer option
 ```
 
 ## Features & conformance

{pyld-3.2.0 → pyld-3.3.0}/README.md

@@ -59,12 +59,30 @@ Defining a dependency on pyld will not pull in
 [Document Loader](#document-loader) then either depend on the desired external library directly
 or define the requirement as `PyLD[requests]` or `PyLD[aiohttp]`.
 
+## Command line
+
+Install the optional CLI extra to get a JSON-LD 1.1 `pyld` console script:
+
+```bash
+pip install "PyLD[cli]"
+pyld expand document.jsonld
+pyld compact document.jsonld context.jsonld
+pyld frame document.jsonld frame.jsonld
+pyld to-rdf document.jsonld
+pyld from-rdf document.nq
+```
+
+The CLI also provides `get`, `flatten`, and HTTP cache management. See the
+[CLI documentation](https://digitalbazaar.github.io/pyld/cli/) for all commands,
+options, and stdin support.
+
 ## Usage
 
 Here are some quick examples to get started:
 
 ```python
 from pyld import jsonld
+from pyld.identifier_issuer import IdentifierIssuer
 import json
 
 doc = {
@@ -126,6 +144,13 @@ normalized = jsonld.normalize(
     doc, {'algorithm': 'URDNA2015', 'format': 'application/n-quads'})
 # normalized is a string that is a canonical representation of the document
 # that can be used for hashing, comparison, etc.
+
+# convert a document to RDF with a custom blank node issuer
+issuer = IdentifierIssuer('_:doc')
+rdf = jsonld.to_rdf(
+    doc,
+    {'identifierIssuer': issuer, 'format': 'application/n-quads'})
+# flatten() and frame() accept the same identifierIssuer option
 ```
 
 ## Features & conformance
@@ -421,4 +446,4 @@ See [`LICENSE`](./LICENSE) file for details.
 The PyLD library is maintained by [Miel Vander
 Sande](https://github.com/mielvds), [Anatoly
 Scherbakov](https://github.com/anatoly-scherbakov) and [Digital
-Bazaar](https://github.com/digitalbazaar) (Original authors of `PyLD`).
+Bazaar](https://github.com/digitalbazaar) (Original authors of `PyLD`).

{pyld-3.2.0 → pyld-3.3.0}/README.txt

@@ -59,12 +59,30 @@ Defining a dependency on pyld will not pull in
 [Document Loader](#document-loader) then either depend on the desired external library directly
 or define the requirement as `PyLD[requests]` or `PyLD[aiohttp]`.
 
+## Command line
+
+Install the optional CLI extra to get a JSON-LD 1.1 `pyld` console script:
+
+```bash
+pip install "PyLD[cli]"
+pyld expand document.jsonld
+pyld compact document.jsonld context.jsonld
+pyld frame document.jsonld frame.jsonld
+pyld to-rdf document.jsonld
+pyld from-rdf document.nq
+```
+
+The CLI also provides `get`, `flatten`, and HTTP cache management. See the
+[CLI documentation](https://digitalbazaar.github.io/pyld/cli/) for all commands,
+options, and stdin support.
+
 ## Usage
 
 Here are some quick examples to get started:
 
 ```python
 from pyld import jsonld
+from pyld.identifier_issuer import IdentifierIssuer
 import json
 
 doc = {
@@ -126,6 +144,13 @@ normalized = jsonld.normalize(
     doc, {'algorithm': 'URDNA2015', 'format': 'application/n-quads'})
 # normalized is a string that is a canonical representation of the document
 # that can be used for hashing, comparison, etc.
+
+# convert a document to RDF with a custom blank node issuer
+issuer = IdentifierIssuer('_:doc')
+rdf = jsonld.to_rdf(
+    doc,
+    {'identifierIssuer': issuer, 'format': 'application/n-quads'})
+# flatten() and frame() accept the same identifierIssuer option
 ```
 
 ## Features & conformance
@@ -421,4 +446,4 @@ See [`LICENSE`](./LICENSE) file for details.
 The PyLD library is maintained by [Miel Vander
 Sande](https://github.com/mielvds), [Anatoly
 Scherbakov](https://github.com/anatoly-scherbakov) and [Digital
-Bazaar](https://github.com/digitalbazaar) (Original authors of `PyLD`).
+Bazaar](https://github.com/digitalbazaar) (Original authors of `PyLD`).

{pyld-3.2.0 → pyld-3.3.0/lib/PyLD.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyLD
-Version: 3.2.0
+Version: 3.3.0
 Summary: Python implementation of the JSON-LD API
 Home-page: https://github.com/digitalbazaar/pyld
 Author: Digital Bazaar
@@ -30,6 +30,9 @@ Provides-Extra: cachetools
 Requires-Dist: cachetools; extra == "cachetools"
 Provides-Extra: frozendict
 Requires-Dist: frozendict; extra == "frozendict"
+Provides-Extra: cli
+Requires-Dist: typer>=0.27; extra == "cli"
+Requires-Dist: requests-cache>=1.3; extra == "cli"
 Dynamic: author
 Dynamic: author-email
 Dynamic: classifier
@@ -103,12 +106,30 @@ Defining a dependency on pyld will not pull in
 [Document Loader](#document-loader) then either depend on the desired external library directly
 or define the requirement as `PyLD[requests]` or `PyLD[aiohttp]`.
 
+## Command line
+
+Install the optional CLI extra to get a JSON-LD 1.1 `pyld` console script:
+
+```bash
+pip install "PyLD[cli]"
+pyld expand document.jsonld
+pyld compact document.jsonld context.jsonld
+pyld frame document.jsonld frame.jsonld
+pyld to-rdf document.jsonld
+pyld from-rdf document.nq
+```
+
+The CLI also provides `get`, `flatten`, and HTTP cache management. See the
+[CLI documentation](https://digitalbazaar.github.io/pyld/cli/) for all commands,
+options, and stdin support.
+
 ## Usage
 
 Here are some quick examples to get started:
 
 ```python
 from pyld import jsonld
+from pyld.identifier_issuer import IdentifierIssuer
 import json
 
 doc = {
@@ -170,6 +191,13 @@ normalized = jsonld.normalize(
     doc, {'algorithm': 'URDNA2015', 'format': 'application/n-quads'})
 # normalized is a string that is a canonical representation of the document
 # that can be used for hashing, comparison, etc.
+
+# convert a document to RDF with a custom blank node issuer
+issuer = IdentifierIssuer('_:doc')
+rdf = jsonld.to_rdf(
+    doc,
+    {'identifierIssuer': issuer, 'format': 'application/n-quads'})
+# flatten() and frame() accept the same identifierIssuer option
 ```
 
 ## Features & conformance

{pyld-3.2.0 → pyld-3.3.0}/lib/PyLD.egg-info/SOURCES.txt

@@ -8,6 +8,7 @@ setup.py
 lib/PyLD.egg-info/PKG-INFO
 lib/PyLD.egg-info/SOURCES.txt
 lib/PyLD.egg-info/dependency_links.txt
+lib/PyLD.egg-info/entry_points.txt
 lib/PyLD.egg-info/requires.txt
 lib/PyLD.egg-info/top_level.txt
 lib/c14n/Canonicalize.py
@@ -23,11 +24,31 @@ lib/pyld/jsonld.py
 lib/pyld/nquads.py
 lib/pyld/options.py
 lib/pyld/resolved_context.py
+lib/pyld/cli/__init__.py
+lib/pyld/cli/app.py
+lib/pyld/cli/entry.py
+lib/pyld/cli/errors.py
+lib/pyld/cli/input.py
+lib/pyld/cli/options.py
+lib/pyld/cli/output.py
+lib/pyld/cli/state.py
+lib/pyld/cli/commands/__init__.py
+lib/pyld/cli/commands/cache.py
+lib/pyld/cli/commands/compact.py
+lib/pyld/cli/commands/expand.py
+lib/pyld/cli/commands/flatten.py
+lib/pyld/cli/commands/frame.py
+lib/pyld/cli/commands/from_rdf.py
+lib/pyld/cli/commands/get.py
+lib/pyld/cli/commands/to_rdf.py
 lib/pyld/documentloader/__init__.py
 lib/pyld/documentloader/aiohttp.py
 lib/pyld/documentloader/base.py
+lib/pyld/documentloader/file.py
 lib/pyld/documentloader/requests.py
 lib/pyld/documentloader/requests_sqlite_cache.py
+lib/pyld/documentloader/scheme_directed.py
+lib/pyld/documentloader/type_directed.py
 lib/pyld/documentloader/frozen/__init__.py
 lib/pyld/documentloader/frozen/bundled/activitystreams.jsonld
 lib/pyld/documentloader/frozen/bundled/credentials-v1.jsonld
@@ -37,9 +58,13 @@ lib/pyld/documentloader/frozen/bundled/security-ed25519-2020-v1.jsonld
 lib/pyld/documentloader/frozen/bundled/security-jws-2020-v1.jsonld
 lib/pyld/documentloader/frozen/bundled/security-v1.jsonld
 lib/pyld/documentloader/frozen/bundled/security-v2.jsonld
+tests/test_cli.py
 tests/test_document_loader.py
+tests/test_file_document_loader.py
 tests/test_frozen_document_loader.py
 tests/test_iri_resolver.py
 tests/test_jsonld.py
 tests/test_manifests.py
-tests/test_sqlite_cache_requests_document_loader.py
+tests/test_scheme_directed_document_loader.py
+tests/test_sqlite_cache_requests_document_loader.py
+tests/test_type_directed_document_loader.py

pyld-3.3.0/lib/PyLD.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pyld = pyld.cli.entry:main

{pyld-3.2.0 → pyld-3.3.0}/lib/PyLD.egg-info/requires.txt

@@ -8,6 +8,10 @@ aiohttp
 [cachetools]
 cachetools
 
+[cli]
+typer>=0.27
+requests-cache>=1.3
+
 [frozendict]
 frozendict
 

{pyld-3.2.0 → pyld-3.3.0}/lib/pyld/__about__.py

@@ -4,4 +4,4 @@ __all__ = ['__copyright__', '__license__', '__version__']
 
 __copyright__ = 'Copyright (c) 2011-2024 Digital Bazaar, Inc.'
 __license__ = 'BSD 3-Clause "New" or "Revised" License'
-__version__ = '3.2.0'
+__version__ = '3.3.0'

{pyld-3.2.0 → pyld-3.3.0}/lib/pyld/__init__.py

@@ -4,15 +4,21 @@ from . import jsonld
 from .context_resolver import ContextResolver
 from .documentloader.aiohttp import AioHttpDocumentLoader
 from .documentloader.base import DocumentLoader, RemoteDocument
+from .documentloader.file import FileDocumentLoader
 from .documentloader.frozen import BUNDLED_CONTEXTS, FrozenDocumentLoader
 from .documentloader.requests import RequestsDocumentLoader
 from .documentloader.requests_sqlite_cache import SqliteCacheRequestsDocumentLoader
+from .documentloader.scheme_directed import SchemeDirectedDocumentLoader
+from .documentloader.type_directed import TypeDirectedDocumentLoader
 
 __all__ = [
     'AioHttpDocumentLoader',
     'BUNDLED_CONTEXTS',
+    'SchemeDirectedDocumentLoader',
+    'TypeDirectedDocumentLoader',
     'ContextResolver',
     'DocumentLoader',
+    'FileDocumentLoader',
     'FrozenDocumentLoader',
     'RequestsDocumentLoader',
     'RemoteDocument',

pyld-3.3.0/lib/pyld/cli/__init__.py

@@ -0,0 +1,5 @@
+"""Command-line interface for PyLD."""
+
+from pyld.cli.app import main, pyld
+
+__all__ = ['main', 'pyld']

pyld-3.3.0/lib/pyld/cli/app.py

@@ -0,0 +1,82 @@
+"""Typer application assembly for the PyLD CLI."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Annotated
+
+try:
+    import typer
+except ImportError as cause:  # pragma: no cover
+    raise ImportError(
+        'The pyld command-line interface requires Typer. '
+        'Install it with: pip install "PyLD[cli]"'
+    ) from cause
+
+from typer import Option
+
+from pyld.cli import state as cli_state
+from pyld.cli.commands.cache import cache_clear
+from pyld.cli.commands.compact import compact_command
+from pyld.cli.commands.expand import expand_command
+from pyld.cli.commands.flatten import flatten_command
+from pyld.cli.commands.frame import frame_command
+from pyld.cli.commands.from_rdf import from_rdf_command
+from pyld.cli.commands.get import get_command
+from pyld.cli.commands.to_rdf import to_rdf_command
+from pyld.cli.errors import print_error
+from pyld.cli.state import State
+
+pyld = typer.Typer(
+    help='Command-line tool for JSON-LD transformations.',
+    no_args_is_help=True,
+)
+
+
+@pyld.callback()
+def root(
+    ctx: typer.Context,
+    traceback: Annotated[
+        bool,
+        Option('--traceback', help='Show the Python traceback on errors.'),
+    ] = False,
+    cache_file: Annotated[
+        Path | None,
+        Option(
+            '--cache-file',
+            envvar='PYLD_CACHE_FILE',
+            help='SQLite file for the CLI HTTP cache.',
+        ),
+    ] = None,
+) -> None:
+    state = State(traceback=traceback, cache_file=cache_file)
+    ctx.obj = state
+    # ``main`` reads this after Click has torn down the context.
+    cli_state.current = state
+
+
+pyld.command('get')(get_command)
+pyld.command('expand')(expand_command)
+pyld.command('compact')(compact_command)
+pyld.command('flatten')(flatten_command)
+pyld.command('frame')(frame_command)
+pyld.command('to-rdf')(to_rdf_command)
+pyld.command('from-rdf')(from_rdf_command)
+
+cache_app = typer.Typer(help='Cache management.', no_args_is_help=True)
+cache_app.command('clear')(cache_clear)
+pyld.add_typer(cache_app, name='cache')
+
+
+def main(args: list[str] | None = None) -> None:
+    """Entry point for the ``pyld`` console script."""
+    try:
+        pyld(args=args, prog_name='pyld')
+    except (SystemExit, KeyboardInterrupt):
+        raise
+    except Exception as err:
+        if cli_state.current.traceback:
+            raise
+        print_error(err, sys.argv[1:] if args is None else args)
+        raise SystemExit(1) from None

pyld-3.3.0/lib/pyld/cli/commands/__init__.py

@@ -0,0 +1 @@
+"""Command implementations for the PyLD CLI."""

pyld-3.3.0/lib/pyld/cli/commands/cache.py

@@ -0,0 +1,14 @@
+"""The ``pyld cache`` commands."""
+
+from __future__ import annotations
+
+from pyld.cli.input import configured_cache_file
+from pyld.cli.output import console
+
+
+def cache_clear() -> None:
+    """Clear the CLI HTTP cache."""
+    path = configured_cache_file()
+    if path.exists():
+        path.unlink()
+    console.print('Cache cleared.', style='green')

pyld-3.3.0/lib/pyld/cli/commands/compact.py

@@ -0,0 +1,62 @@
+"""The ``pyld compact`` command."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from typer import Option
+
+from pyld import jsonld
+from pyld.cli.input import (
+    ContextArgument,
+    Input,
+    document_value,
+    ensure_single_stdin,
+)
+from pyld.cli.options import (
+    Base,
+    ExpandContext,
+    ExtractAllScripts,
+    optional_options,
+    processing_options,
+)
+from pyld.cli.output import print_json
+
+
+def compact_command(
+    input_: Input,
+    context: ContextArgument,
+    expand_context: ExpandContext = None,
+    base: Base = None,
+    extract_all_scripts: ExtractAllScripts = None,
+    compact_arrays: Annotated[
+        bool | None,
+        Option(
+            '--compact-arrays/--no-compact-arrays',
+            help='Compact single-value arrays when appropriate.',
+        ),
+    ] = None,
+    graph: Annotated[
+        bool | None,
+        Option(
+            '--graph/--no-graph',
+            help='Always emit a top-level graph.',
+        ),
+    ] = None,
+) -> None:
+    """Compact a JSON-LD document using a context."""
+    ensure_single_stdin(input_, context, expand_context)
+    options = {
+        **processing_options(
+            base=base,
+            extract_all_scripts=extract_all_scripts,
+            expand_context=expand_context,
+        ),
+        **optional_options(compactArrays=compact_arrays, graph=graph),
+    }
+    result = jsonld.compact(
+        document_value(input_),
+        document_value(context),
+        options=options,
+    )
+    print_json(result)

pyld-3.3.0/lib/pyld/cli/commands/expand.py

@@ -0,0 +1,42 @@
+"""The ``pyld expand`` command."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from typer import Option
+
+from pyld import jsonld
+from pyld.cli.input import (
+    Input,
+    document_value,
+    ensure_single_stdin,
+)
+from pyld.cli.options import Base, ExtractAllScripts, MaybeStr, processing_options
+from pyld.cli.output import print_json
+
+
+def expand_command(
+    input_: Input,
+    context: Annotated[
+        MaybeStr,
+        Option(
+            '--context',
+            '-c',
+            help='Context path or URL. Pass - to read JSON from standard input.',
+        ),
+    ] = None,
+    base: Base = None,
+    extract_all_scripts: ExtractAllScripts = None,
+) -> None:
+    """Expand a JSON-LD document."""
+    ensure_single_stdin(input_, context)
+    options = processing_options(
+        base=base,
+        extract_all_scripts=extract_all_scripts,
+    )
+    if context is not None:
+        options = {**options, 'expandContext': document_value(context)}
+
+    result = jsonld.expand(document_value(input_), options=options)
+    print_json(result)

pyld-3.3.0/lib/pyld/cli/commands/flatten.py

@@ -0,0 +1,48 @@
+"""The ``pyld flatten`` command."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from typer import Option
+
+from pyld import jsonld
+from pyld.cli.input import (
+    Input,
+    document_value,
+    ensure_single_stdin,
+)
+from pyld.cli.options import (
+    Base,
+    ExpandContext,
+    ExtractAllScripts,
+    MaybeStr,
+    processing_options,
+)
+from pyld.cli.output import print_json
+
+
+def flatten_command(
+    input_: Input,
+    context: Annotated[
+        MaybeStr,
+        Option(
+            '--context',
+            '-c',
+            help='Output context path or URL. Pass - to read JSON from standard input.',
+        ),
+    ] = None,
+    expand_context: ExpandContext = None,
+    base: Base = None,
+    extract_all_scripts: ExtractAllScripts = None,
+) -> None:
+    """Flatten a JSON-LD document."""
+    ensure_single_stdin(input_, context, expand_context)
+    options = processing_options(
+        base=base,
+        extract_all_scripts=extract_all_scripts,
+        expand_context=expand_context,
+    )
+    output_context = document_value(context) if context is not None else None
+    result = jsonld.flatten(document_value(input_), output_context, options=options)
+    print_json(result)