Merge pull request #67 from iolanta-tech/expand-docs-are-incorrect

Document `expand()`
iolanta-tech · Apr 30, 2024 · 353370a · 353370a
2 parents 61b30be + b1a07b4
commit 353370a
Show file tree

Hide file tree

Showing 4 changed files with 56 additions and 16 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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: