jentic-openapi-common 1.0.0a10__tar.gz → 1.0.0a11__tar.gz

{jentic_openapi_common-1.0.0a10 → jentic_openapi_common-1.0.0a11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jentic-openapi-common
-Version: 1.0.0a10
+Version: 1.0.0a11
 Summary: Jentic OpenAPI Common
 Author: Jentic
 Author-email: Jentic <hello@jentic.com>

{jentic_openapi_common-1.0.0a10 → jentic_openapi_common-1.0.0a11}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "jentic-openapi-common"
-version = "1.0.0-alpha.10"
+version = "1.0.0-alpha.11"
 description = "Jentic OpenAPI Common"
 readme = "README.md"
 authors = [{ name = "Jentic", email = "hello@jentic.com" }]

{jentic_openapi_common-1.0.0a10 → jentic_openapi_common-1.0.0a11}/src/jentic/apitools/openapi/common/uri.py

@@ -1,8 +1,8 @@
 import os
 import re
-import urllib.request
 from pathlib import Path
 from urllib.parse import urljoin, urlparse, urlsplit, urlunsplit
+from urllib.request import url2pathname
 
 
 __all__ = [
@@ -10,8 +10,12 @@ __all__ = [
     "is_uri_like",
     "is_http_https_url",
     "is_file_uri",
+    "is_scheme_relative_uri",
+    "is_absolute_uri",
+    "is_fragment_only_uri",
     "is_path",
     "resolve_to_absolute",
+    "file_uri_to_path",
 ]
 
 
@@ -50,7 +54,7 @@ class URIResolutionError(ValueError):
     pass
 
 
-def is_uri_like(s: str | None) -> bool:
+def is_uri_like(uri: str | None) -> bool:
     r"""
     Heuristic check: is `s` a URI-like reference or absolute/relative path?
     - Accepts http(s)://, file://
@@ -59,13 +63,13 @@ def is_uri_like(s: str | None) -> bool:
     - Must be a single line (no '\\n' or '\\r').
     Leading/trailing whitespace is ignored.
     """
-    if not s:
+    if not uri:
         return False
-    s = s.strip()
+    uri = uri.strip()
     # Enforce single line
-    if "\n" in s or "\r" in s:
+    if "\n" in uri or "\r" in uri:
         return False
-    return bool(_URI_LIKE_RE.match(s))
+    return bool(_URI_LIKE_RE.match(uri))
 
 
 def is_path(s: str | None) -> bool:
@@ -109,6 +113,107 @@ def is_path(s: str | None) -> bool:
     return True
 
 
+def is_http_https_url(url: str) -> bool:
+    p = urlparse(url)
+    return p.scheme in ("http", "https") and bool(p.netloc)
+
+
+def is_file_uri(uri: str) -> bool:
+    return urlparse(uri).scheme == "file"
+
+
+def is_scheme_relative_uri(uri: str) -> bool:
+    """
+    Check if `uri` is a scheme-relative URI (also called protocol-relative URI).
+
+    A scheme-relative URI starts with "//" followed by an authority component (netloc),
+    inheriting the scheme from the context (e.g., "//cdn.example.com/path").
+
+    This is defined in RFC 3986 section 4.2 as a network-path reference.
+    Per RFC 3986, a valid network-path reference must have an authority component.
+
+    Examples:
+        - "//cdn.example.com/x.yaml" -> True
+        - "//example.com/api" -> True
+        - "http://example.com" -> False (has scheme)
+        - "/path/to/file" -> False (single slash)
+        - "./relative" -> False (relative path)
+        - "//" -> False (no authority component)
+        - "///path" -> False (no authority component)
+
+    Args:
+        uri: The string to check
+
+    Returns:
+        True if the string is a valid scheme-relative URI with authority, False otherwise
+    """
+    if not uri.startswith("//"):
+        return False
+    p = urlparse(uri)
+    return bool(p.netloc)
+
+
+def is_absolute_uri(uri: str) -> bool:
+    """
+    Check if `uri` is an absolute URI according to RFC 3986.
+
+    An absolute URI is defined as having a scheme (e.g., "http:", "https:", "ftp:", "file:").
+
+    Note: Scheme-relative URIs (starting with "//") are NOT considered absolute URIs.
+    According to RFC 3986 section 4.2, scheme-relative URIs are classified as
+    "relative references" (specifically, "network-path references").
+    Use `is_scheme_relative_uri()` to check for those separately.
+
+    Examples:
+        - "http://example.com" -> True
+        - "https://example.com/path" -> True
+        - "ftp://ftp.example.com" -> True
+        - "file:///path/to/file" -> True
+        - "//cdn.example.com/x.yaml" -> False (scheme-relative, use is_scheme_relative_uri)
+        - "/path/to/file" -> False (absolute path, not URI)
+        - "./relative" -> False
+        - "#fragment" -> False
+
+    Args:
+        uri: The string to check
+
+    Returns:
+        True if the string is an absolute URI (has a scheme), False otherwise
+    """
+    p = urlparse(uri)
+    return bool(p.scheme)
+
+
+def is_fragment_only_uri(uri: str) -> bool:
+    """
+    Check if `uri` is a fragment-only reference.
+
+    A fragment-only reference consists solely of a fragment identifier (starts with "#").
+    These are used in JSON References and OpenAPI to refer to parts within the same document.
+
+    Note: This checks if the ENTIRE string is a fragment reference, not whether
+    a URI contains a fragment. For example, "http://example.com#section" would
+    return False because it's a full URI with a fragment, not fragment-only.
+
+    Examples:
+        - "#/definitions/User" -> True
+        - "#fragment" -> True
+        - "#" -> True (empty fragment identifier)
+        - "##" -> True (fragment identifier is "#")
+        - "http://example.com#section" -> False (full URI with fragment)
+        - "/path/to/file" -> False
+        - "./relative" -> False
+        - "" -> False
+
+    Args:
+        uri: The string to check
+
+    Returns:
+        True if the string is a fragment-only reference, False otherwise
+    """
+    return uri.startswith("#")
+
+
 def resolve_to_absolute(value: str, base_uri: str | None = None) -> str:
     """
     Resolve `value` to either:
@@ -132,7 +237,7 @@ def resolve_to_absolute(value: str, base_uri: str | None = None) -> str:
         return _normalize_url(value)
 
     if is_file_uri(value):
-        return _file_uri_to_path(value)
+        return file_uri_to_path(value)
 
     if _looks_like_windows_path(value):
         return _resolve_path_like(value, base_uri)
@@ -167,6 +272,36 @@ def resolve_to_absolute(value: str, base_uri: str | None = None) -> str:
     return _resolve_path_like(value, None)
 
 
+def file_uri_to_path(file_uri: str) -> str:
+    """
+    Convert a file:// URI to an absolute filesystem path.
+
+    Args:
+        file_uri: A file:// URI string (e.g., "file:///path/to/file" or "file://server/share/path")
+
+    Returns:
+        Absolute filesystem path as a string
+
+    Raises:
+        URIResolutionError: If the input is not a valid file:// URI
+
+    Examples:
+        >>> file_uri_to_path("file:///home/user/doc.yaml")
+        '/home/user/doc.yaml'
+        >>> file_uri_to_path("file://localhost/etc/config.yaml")
+        '/etc/config.yaml'
+    """
+    parsed_uri = urlparse(file_uri)
+    if parsed_uri.scheme != "file":
+        raise URIResolutionError(f"Not a file URI: {file_uri!r}")
+    if parsed_uri.netloc and parsed_uri.netloc not in ("", "localhost"):
+        # UNC: \\server\share\path
+        unc = f"//{parsed_uri.netloc}{parsed_uri.path}"
+        return str(Path(url2pathname(unc)).resolve())
+    path = url2pathname(parsed_uri.path)
+    return str(Path(path).resolve())
+
+
 def _guard_single_line(s: str) -> None:
     if not isinstance(s, str) or ("\n" in s or "\r" in s):
         raise URIResolutionError("Input must be a single-line string.")
@@ -176,15 +311,6 @@ def _looks_like_windows_path(s: str) -> bool:
     return bool(_WINDOWS_DRIVE_RE.match(s) or _WINDOWS_UNC_RE.match(s))
 
 
-def is_http_https_url(s: str) -> bool:
-    p = urlparse(s)
-    return p.scheme in ("http", "https") and bool(p.netloc)
-
-
-def is_file_uri(s: str) -> bool:
-    return urlparse(s).scheme == "file"
-
-
 def _normalize_url(s: str) -> str:
     import posixpath
 
@@ -197,24 +323,12 @@ def _normalize_url(s: str) -> str:
     return urlunsplit((parts.scheme, parts.netloc, normalized_path, parts.query, parts.fragment))
 
 
-def _file_uri_to_path(file_uri: str) -> str:
-    p = urlparse(file_uri)
-    if p.scheme != "file":
-        raise URIResolutionError(f"Not a file URI: {file_uri!r}")
-    if p.netloc and p.netloc not in ("", "localhost"):
-        # UNC: \\server\share\path
-        unc = f"//{p.netloc}{p.path}"
-        return str(Path(urllib.request.url2pathname(unc)).resolve())
-    path = urllib.request.url2pathname(p.path)
-    return str(Path(path).resolve())
-
-
 def _resolve_path_like(value: str, base_uri: str | None) -> str:
     value = os.path.expandvars(os.path.expanduser(value))
 
     if base_uri:
         if is_file_uri(base_uri):
-            base_path = Path(urllib.request.url2pathname(urlparse(base_uri).path))
+            base_path = Path(url2pathname(urlparse(base_uri).path))
         elif is_http_https_url(base_uri):
             # Don't silently combine a local path with a URL base
             raise URIResolutionError("Cannot resolve a local path against an HTTP(S) base_uri.")