Merge pull request #148 from iolanta-tech/iri-type

Implement `URI` type

docs/types/uri.md

@@ -0,0 +1,5 @@
+---
+title: URI
+---
+
+::: yaml_ld.models.URI

docs/types/url.md

@@ -1,5 +1,5 @@
 ---
-title: urlpath.URL
+title: yarl.URL
 ---
 
-::: urlpath.URL
+::: yarl.URL

yaml_ld/document_loaders/base.py

@@ -3,7 +3,7 @@
 
 from typing_extensions import TypedDict
 
-from yaml_ld.models import JsonLdRecord
+from yaml_ld.models import JsonLdRecord, URI
 
 PyLDResponse = TypedDict(
     'PyLDResponse', {
@@ -26,7 +26,8 @@ class DocumentLoader(ABC):
     @abstractmethod
     def __call__(
         self,
-        source: str | Path,
+        source: URI,
         options: DocumentLoaderOptions,
     ) -> PyLDResponse:
+        """Load a document."""
         raise NotImplementedError()

yaml_ld/document_loaders/choice_by_scheme.py

@@ -11,6 +11,7 @@
     DocumentLoaderOptions,
     PyLDResponse,
 )
+from yaml_ld.models import URI
 
 
 @dataclass
@@ -44,9 +45,10 @@ def __init__(self, **loaders: DocumentLoader) -> None:
 
     def __call__(
         self,
-        source: str | Path,
+        source: URI,
         options: DocumentLoaderOptions,
     ) -> PyLDResponse:
+        """Choose by scheme."""
         url = URL(str(source))
 
         try:

yaml_ld/document_loaders/http.py

@@ -10,7 +10,7 @@
     PyLDResponse,
 )
 from yaml_ld.errors import LoadingDocumentFailed
-
+from yaml_ld.models import URI
 
 # Default `requests` timeout. Chosen arbitrarily.
 DEFAULT_TIMEOUT = 30
@@ -21,7 +21,7 @@ class HTTPDocumentLoader(DocumentLoader):
 
     def __call__(
         self,
-        source: str | Path,
+        source: URI,
         options: DocumentLoaderOptions,
     ) -> PyLDResponse:
         """Load documents from HTTP sources."""

yaml_ld/document_loaders/local_file.py

@@ -9,14 +9,15 @@
     PyLDResponse,
 )
 from yaml_ld.errors import LoadingDocumentFailed, NotFound
+from yaml_ld.models import URI
 
 
 class LocalFileDocumentLoader(DocumentLoader):
     """Load documents from a local file system."""
 
     def __call__(
         self,
-        source: str | Path,
+        source: URI,
         options: DocumentLoaderOptions,
     ) -> PyLDResponse:
         """Load documents from a local file system."""

yaml_ld/document_loaders/mock.py

@@ -6,6 +6,7 @@
     DocumentLoaderOptions,
     PyLDResponse,
 )
+from yaml_ld.models import URI
 
 
 @dataclass
@@ -14,7 +15,8 @@ class MockLoader(DocumentLoader):
 
     def __call__(
         self,
-        source: str | Path,
+        source: URI,
         options: DocumentLoaderOptions,
     ) -> PyLDResponse:
+        """Return the prepared response."""
         return self.response

yaml_ld/models.py

@@ -16,16 +16,24 @@ class RemoteDocument(TypedDict):
     profile: str
 
 
+URI = str | URL | Path
+"""
+A Universal Resource Identifier can be represented as a `Path` or as a `URL`.
+
+Or, it can be a `str`, and we will try to automatically identify what that is.
+"""
+
+
 JsonLdInput = (
-    JsonLdRecord | Sequence[JsonLdRecord] | str | Path | URL | RemoteDocument
+    JsonLdRecord | Sequence[JsonLdRecord] | URI | RemoteDocument
 )
 """
 Input for `expand()`, `compact()` and other functions.
 
 [Specification](https://w3c.github.io/json-ld-api/#dom-jsonldrecord)
 """
 
-JsonLdContext = JsonLdRecord | list[JsonLdRecord | str] | str
+JsonLdContext = JsonLdRecord | list[JsonLdRecord | URI] | URI
 """
 The `JsonLdContext` interface is used to refer to a value that may be a
 `JsonLdRecord`, a sequence of `JsonLdRecord`-s, or a string representing an IRI,
@@ -54,7 +62,7 @@ class ExtractAllScriptsOptions(BaseModel):    # type: ignore
 class ExpandContextOptions(BaseModel):    # type: ignore
     """Options flag to extract all scripts or not."""
 
-    expand_context: JsonLdRecord | str | Path | URL | None = None
+    expand_context: JsonLdRecord | URI | None = None
     """A context to expand with."""
 
     model_config = ConfigDict(arbitrary_types_allowed=True)
@@ -70,7 +78,7 @@ def _default_document_loader():
 class BaseOptions(BaseModel):   # type: ignore
     """Base options shared by all YAML-LD API methods."""
 
-    base: str | Path | None = None
+    base: URI | None = None
     """The base IRI to use."""
 
     document_loader: Annotated[  # type: ignore