From b1a07b4f5daeb305a50fe4268f2562ece407076e Mon Sep 17 00:00:00 2001 From: Anatoly Scherbakov Date: Tue, 30 Apr 2024 23:04:09 +0400 Subject: [PATCH] Document `expand()` --- docs/expand.md | 53 ++++++++++++++++++++++++++++++++++++++++------ mkdocs.yml | 1 + yaml_ld/compact.py | 7 +++--- yaml_ld/expand.py | 11 +++++----- 4 files changed, 56 insertions(+), 16 deletions(-) diff --git a/docs/expand.md b/docs/expand.md index 181abad..942233e 100644 --- a/docs/expand.md +++ b/docs/expand.md @@ -4,19 +4,60 @@ hide: [toc] # :material-arrow-expand-all: `expand()` -!!! info "Specified by: [JSON-LD API]({{ yaml_ld.expand.specified_by }})" +!!! info "Specified by: [JSON-LD API]({{ yaml_ld.expand.__annotations__.return.__metadata__|first }})" ::: yaml_ld.expand.expand ## Input & output + | | Type | Default | Description | |-----------------------|---------------------------------------------|-------------|---| | `document` | [SerializedDocument](/types/serialized-document/) \| [Document](/types/document/) | | Document to expand. | -| `base` | `str | None` | | The base IRI to use. | -| `context` | [Document](/types/document/) \| `None` | | A context to expand with. | -| `extract_all_scripts` | `bool` | :x: `False` | Will we extract all scripts, or all documents in a YAML stream? | -| `mode` | [`ProcessingMode`](/types/processing-mode/) | JSON-LD 1.1 | JSON-LD version to use. | -| `document_loader` | `DocumentLoader` | `None` | Document Loader. | +| `options` | `ExpandOptions | ExpandOptionsDict` | | Options | | :material-arrow-right-bottom-bold: **Returns** | [Document](/types/document/) \| list[[Document](/types/document/)] | | Expanded document | +## `ExpandOptions` | `ExpandOptionsDict` + +| `ExpandOptions` | `ExpandOptionsDict` | Type | Default | Description | +|-----|------------------|---------------------------------------------|-------------|---| +| `context` | `context` | [Document](/types/document/) \| `None` | `None` | A context to expand with. | +| `extract_all_scripts` | `extractAllScripts` | `bool` | :x: `False` | Will we extract all scripts, or all documents in a YAML stream? | +| `document_loader` | `documentLoader` | `DocumentLoader` | `None` | Document Loader. | + +## Examples + +=== "`two-documents-in.yamlld`" + + ```yaml + --8<-- "specifications/yaml-ld/tests/cases/streams/two-documents-in.yamlld" + ``` + +=== "Call `yaml_ld.expand()`" + + ```python + from pathlib import Path + import pyyaml + import yaml_ld + + pyyaml.dumps( + yaml_ld.expand( + document=Path( + 'specifications/yaml-ld/tests/cases/streams/two-documents-in.yamlld' + ), + options=yaml_ld.ExpandOptions(extract_all_scripts=True), # (1) + ), + ) + ``` + + 1. Or, + ```python + options={'extractAllScripts': True}, + ``` + if you wish to be closer to the letter of the JSON-LD API Specification. + +=== "`two-documents-out.yamlld`" + + ```yaml + --8<-- "specifications/yaml-ld/tests/cases/streams/two-documents-out.yamlld" + ``` diff --git a/mkdocs.yml b/mkdocs.yml index b95bcf7..140aaf4 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -13,6 +13,7 @@ markdown_extensions: - md_in_html - pymdownx.superfences - pymdownx.details + - pymdownx.snippets - footnotes - pymdownx.tabbed: alternate_style: true diff --git a/yaml_ld/compact.py b/yaml_ld/compact.py index db0d011..9717842 100644 --- a/yaml_ld/compact.py +++ b/yaml_ld/compact.py @@ -3,12 +3,12 @@ from pydantic import Field from pyld import jsonld -from yaml_ld.annotations import specified_by, API -from yaml_ld.parse import parse # noqa: WPS347 +from yaml_ld.annotations import API from yaml_ld.errors import MappingKeyError, CycleDetected from yaml_ld.models import ( Document, ProcessingMode, DocumentLoader, BaseOptions, ExtractAllScripts, ) +from yaml_ld.parse import parse # noqa: WPS347 class CompactOptions(BaseOptions): @@ -20,7 +20,6 @@ class CompactOptions(BaseOptions): skip_expansion: bool = Field(default=False, alias='skipExpansion') -@specified_by(API / '#dom-jsonldprocessor-compact') def compact( # noqa: WPS211 document: str | bytes | Document, context: Annotated[Document | None, 'Context to compact with.'], @@ -44,7 +43,7 @@ def compact( # noqa: WPS211 bool, 'Treat the input as already expanded, and do not expand it again.', ] = False, -): +) -> Annotated[Document | list[Document], API / '#dom-jsonldprocessor-compact']: """Compact a JSON-LD document.""" if isinstance(document, (str, bytes)): document = parse(document) diff --git a/yaml_ld/expand.py b/yaml_ld/expand.py index f94be52..5264c52 100644 --- a/yaml_ld/expand.py +++ b/yaml_ld/expand.py @@ -5,14 +5,14 @@ from pyld import jsonld from urlpath import URL -from yaml_ld.annotations import Help, specified_by, API +from yaml_ld.annotations import API from yaml_ld.errors import ( CycleDetected, MappingKeyError, - LoadingRemoteContextFailed, YAMLLDError, PyLDError, + LoadingRemoteContextFailed, PyLDError, ) from yaml_ld.models import ( - Document, ProcessingMode, - DocumentLoader, BaseOptions, ExtractAllScripts, SerializedDocument, + Document, DocumentLoader, BaseOptions, ExtractAllScripts, + SerializedDocument, ) from yaml_ld.parse import parse # noqa: WPS347 @@ -30,12 +30,11 @@ class ExpandOptionsDict(TypedDict): document_loader: DocumentLoader | None -@specified_by(API / '#dom-jsonldprocessor-expand') @validate_call(config=dict(arbitrary_types_allowed=True)) def expand( # noqa: C901, WPS211 document: SerializedDocument | Document, options: ExpandOptions = ExpandOptions(), -) -> Document | list[Document]: +) -> Annotated[Document | list[Document], API / '#dom-jsonldprocessor-expand']: """Expand a YAML-LD document.""" if isinstance(document, (str, bytes, Path, URL)): if isinstance(document, Path) and options.base is None: