Update docs to 4.0.0 changes

Author: mielvds

README.md

@@ -2,7 +2,8 @@
 
 [Documentation](https://digitalbazaar.github.io/pyld/) |
 [Installation](#installation) | [Usage](#usage) | [Advanced
-Topics](#advanced-topics) | [Contributing](./CONTRIBUTING.md) |
+Topics](#advanced-topics) | [What's new in version 4](#whats-new-in-version-4) |
+[Contributing](./CONTRIBUTING.md) |
 [Changelog](./CHANGELOG.md)
 
 ## Introduction
@@ -45,6 +46,27 @@ memory footprint in order to operate.
 * [Requests](http://docs.python-requests.org/) (optional)
 * [aiohttp](https://aiohttp.readthedocs.io/) (optional)
 
+## What's new in version 4
+
+PyLD 4 moves RDF handling to [RDFLib](https://rdflib.readthedocs.io/) and adds
+RDF Dataset Canonicalization 1.0 support.
+
+The main developer-facing changes are:
+
+* `jsonld.to_rdf()` returns an `rdflib.Dataset` by default when no output
+  `format` is requested.
+* `jsonld.to_rdf(doc, {'legacyMode': True})` returns the RDF.js-like dataset
+  `dict` used by PyLD versions lower than 4.
+* `jsonld.from_rdf()` accepts `rdflib.Dataset`, N-Quads strings, and the legacy
+  dataset `dict`.
+* `jsonld.normalize()` defaults to `RDFC10`; pass `{'algorithm': 'URDNA2015'}`
+  if older canonicalization output must remain stable.
+* The internal `pyld.nquads` parser/serializer module has been removed. Use the
+  JSON-LD APIs with `format: 'application/n-quads'` or RDFLib directly.
+
+See the full [version 4 upgrade notes](https://digitalbazaar.github.io/pyld/whats-new-version-4/)
+and the [`4.0.0` changelog entry](./CHANGELOG.md#400---unreleased).
+
 ## Installation
 
 PyLD can be installed with a [pip](http://www.pip-installer.org/)
@@ -121,10 +143,10 @@ flattened = jsonld.flatten(doc)
 framed = jsonld.frame(doc, frame)
 # document transformed into a particular tree structure per the given frame
 
-# normalize a document using the RDF Dataset Normalization Algorithm
-# (URDNA2015), see: https://www.w3.org/TR/rdf-canon/
+# normalize a document using RDF Dataset Canonicalization 1.0
+# (RDFC10), see: https://www.w3.org/TR/rdf-canon/
 normalized = jsonld.normalize(
-    doc, {'algorithm': 'URDNA2015', 'format': 'application/n-quads'})
+    doc, {'algorithm': 'RDFC10', 'format': 'application/n-quads'})
 # normalized is a string that is a canonical representation of the document
 # that can be used for hashing, comparison, etc.
 ```

docs/.pages

@@ -1,6 +1,7 @@
 nav:
   - Quickstart:
       - index.md
+      - whats-new-version-4.md
       - installation.md
       - conformance.md
   - Reference:

docs/examples/normalize.py

@@ -9,6 +9,15 @@
     },
 }
 
+# Normalize with RDFC10
+normalized = jsonld.normalize(
+    doc,
+    {"format": "application/n-quads"},
+)
+
+print(normalized)
+
+# Normalize with URDNA2015
 normalized = jsonld.normalize(
     doc,
     {"algorithm": "URDNA2015", "format": "application/n-quads"},

docs/index.md

@@ -15,6 +15,15 @@ applications add meaning to existing JSON documents with in-band or out-of-band
 contexts, while keeping the document shape practical for web APIs, JavaScript,
 and JSON document stores.
 
+## :material-new-box: What's new in version 4
+
+PyLD 4 uses [:material-library: RDFLib](https://rdflib.readthedocs.io/)
+`rdflib.Dataset` as the native RDF dataset representation, adds `RDFC10`
+canonicalization, and removes the internal `pyld.nquads` parser/serializer
+module.
+
+[Read the version 4 upgrade notes :octicons-arrow-right-24:](whats-new-version-4.md)
+
 ## :material-lightning-bolt: Quick Examples
 
 === "jsonld.compact()"

docs/reference/from_rdf.md

@@ -12,6 +12,16 @@
       show_bases: false
       heading_level: 3
 
+`jsonld.from_rdf()` accepts a
+[:material-library: RDFLib](https://rdflib.readthedocs.io/) `rdflib.Dataset`,
+an N-Quads string, or the RDF.js-like dataset `dict` returned by PyLD versions
+lower than 4. Prefer `rdflib.Dataset` for new in-memory RDF code.
+
+```python
+doc = jsonld.from_rdf(dataset)
+doc = jsonld.from_rdf(nquads, {"format": "application/n-quads"})
+```
+
 ## Example
 
 {{ example('from_rdf.py', 'json') }}

docs/reference/normalize.md

@@ -12,6 +12,17 @@
       show_bases: false
       heading_level: 3
 
+`RDFC10` is the default algorithm in PyLD 4. Use `URDNA2015` or `URGNA2012`
+explicitly when an integration requires the older canonicalization output.
+
+```python
+canonical = jsonld.normalize(
+    doc,
+    {"algorithm": "URDNA2015", "format": "application/n-quads"},
+)
+identifier_map = jsonld.normalize(doc, {"algorithm": "RDFC10", "outputMap": True})
+```
+
 ## Example
 
 {{ example('normalize.py') }}

docs/reference/to_rdf.md

@@ -12,9 +12,19 @@
       show_bases: false
       heading_level: 3
 
-When `format` is not set, `jsonld.to_rdf()` returns an
-[`rdflib.Dataset`](https://rdflib.readthedocs.io/). Set `legacyMode` to `True`
-to return the RDF.js-like dataset `dict` used by PyLD versions lower than 4.
+When `format` is not set, `jsonld.to_rdf()` returns a
+[:material-library: RDFLib](https://rdflib.readthedocs.io/) `rdflib.Dataset`.
+Set `legacyMode` to `True` to return the RDF.js-like dataset `dict` used by
+PyLD versions lower than 4.
+
+```python
+dataset = jsonld.to_rdf(doc)
+nquads = jsonld.to_rdf(doc, {"format": "application/n-quads"})
+legacy_dataset = jsonld.to_rdf(doc, {"legacyMode": True})
+```
+
+`legacyMode` only affects the unformatted return value. If `format` is set,
+`jsonld.to_rdf()` returns the requested serialization.
 
 ## Example
 

lib/pyld/options.py

@@ -149,12 +149,18 @@ class NormalizeOptions(ProcessingOptions, total=False):
     algorithm: Literal['URDNA2015', 'URGNA2012', 'RDFC10']
     """The algorithm to use (default: `RDFC10`)."""
 
+    hashAlgorithm: str
+    """The hashing algorithm for `RDFC10` (default: `SHA256`)."""
+
     inputFormat: Literal['application/n-quads']
     """The format if input is not JSON-LD: `application/n-quads` for N-Quads."""
 
     format: Literal['application/n-quads']
     """The format if output is a string: `application/n-quads` for N-Quads."""
 
+    outputMap: bool
+    """`True` to return a blank node identifier map instead of the normalized dataset (default: `False`)."""
+
 
 class ToRdfOptions(ProcessingOptions, total=False):
     documentLoader: DocumentLoader | DocumentLoaderCallable