types(doc): Expose aliases at runtime for autodoc

why: sphinx-autodoc-typehints emitted forward reference warnings for aliases only defined under TYPE_CHECKING.

what:
- provide fallback DataclassInstance, move TypeAlias imports out of TYPE_CHECKING, and import StrPath/TypeGuard at runtime
- ensure sync/url/registry modules import shared aliases directly to make type hints resolvable during docs build
- tidy _internal types docstring wording to drop glossary term that caused warnings

Author: tony

src/libvcs/_internal/dataclasses.py

@@ -13,6 +13,8 @@
 
 if t.TYPE_CHECKING:
     from _typeshed import DataclassInstance
+else:
+    DataclassInstance = object
 
 
 class SkipDefaultFieldsReprMixin:

src/libvcs/_internal/shortcuts.py

@@ -8,17 +8,14 @@
 from __future__ import annotations
 
 import typing as t
+from typing import TypeGuard
 
 from libvcs import GitSync, HgSync, SvnSync, exc
+from libvcs._internal.run import ProgressCallbackProtocol
+from libvcs._internal.types import StrPath, VCSLiteral
 from libvcs.exc import InvalidVCS
 from libvcs.url import registry as url_tools
 
-if t.TYPE_CHECKING:
-    from typing import TypeGuard
-
-    from libvcs._internal.run import ProgressCallbackProtocol
-    from libvcs._internal.types import StrPath, VCSLiteral
-
 
 class VCSNoMatchFoundForUrl(exc.LibVCSException):
     def __init__(self, url: str, *args: object) -> None:

src/libvcs/_internal/types.py

@@ -1,4 +1,4 @@
-"""Internal :term:`type annotations <annotation>`.
+"""Internal type annotations.
 
 Notes
 -----
@@ -19,7 +19,7 @@
 """:class:`os.PathLike` or :class:`str`"""
 
 StrOrBytesPath: TypeAlias = str | bytes | PathLike[str] | PathLike[bytes]
-""":class:`os.PathLike`, :class:`str` or :term:`bytes-like object`"""
+""":class:`os.PathLike`, :class:`str` or bytes-like object"""
 
 
 VCSLiteral = t.Literal["git", "svn", "hg"]

src/libvcs/pytest_plugin.py

@@ -13,16 +13,11 @@
 import pytest
 
 from libvcs import exc
-from libvcs._internal.run import run
+from libvcs._internal.run import _ENV, run
 from libvcs.sync.git import GitRemote, GitSync
 from libvcs.sync.hg import HgSync
 from libvcs.sync.svn import SvnSync
 
-if t.TYPE_CHECKING:
-    from typing import TypeAlias
-
-    from libvcs._internal.run import _ENV
-
 
 class MaxUniqueRepoAttemptsExceeded(exc.LibVCSException):
     """Raised when exceeded threshold of attempts to find a unique repo destination."""

src/libvcs/sync/base.py

@@ -9,9 +9,7 @@
 from urllib import parse as urlparse
 
 from libvcs._internal.run import _CMD, CmdLoggingAdapter, ProgressCallbackProtocol, run
-
-if t.TYPE_CHECKING:
-    from libvcs._internal.types import StrPath
+from libvcs._internal.types import StrPath
 
 logger = logging.getLogger(__name__)
 

src/libvcs/sync/git.py

@@ -31,9 +31,7 @@
     VCSLocation,
     convert_pip_url as base_convert_pip_url,
 )
-
-if t.TYPE_CHECKING:
-    from libvcs._internal.types import StrPath
+from libvcs._internal.types import StrPath
 
 logger = logging.getLogger(__name__)
 

src/libvcs/sync/hg.py

@@ -15,13 +15,11 @@
 import pathlib
 import typing as t
 
+from libvcs._internal.types import StrPath
 from libvcs.cmd.hg import Hg
 
 from .base import BaseSync
 
-if t.TYPE_CHECKING:
-    from libvcs._internal.types import StrPath
-
 logger = logging.getLogger(__name__)
 
 

src/libvcs/sync/svn.py

@@ -21,13 +21,11 @@
 import re
 import typing as t
 
+from libvcs._internal.types import StrPath
 from libvcs.cmd.svn import Svn
 
 from .base import BaseSync
 
-if t.TYPE_CHECKING:
-    from libvcs._internal.types import StrPath
-
 logger = logging.getLogger(__name__)
 
 

src/libvcs/url/base.py

@@ -4,14 +4,12 @@
 
 import dataclasses
 import typing as t
+from _collections_abc import dict_values
+from collections.abc import Iterator
+from re import Pattern
 
 from libvcs._internal.dataclasses import SkipDefaultFieldsReprMixin
 
-if t.TYPE_CHECKING:
-    from _collections_abc import dict_values
-    from collections.abc import Iterator
-    from re import Pattern
-
 
 class URLProtocol(t.Protocol):
     """Common interface for VCS URL Parsers."""

src/libvcs/url/registry.py

@@ -3,16 +3,13 @@
 from __future__ import annotations
 
 import typing as t
+from typing import TypeAlias
 
 from libvcs._internal.module_loading import import_string
+from .base import URLProtocol
 
-if t.TYPE_CHECKING:
-    from typing import TypeAlias
-
-    from .base import URLProtocol
-
-    ParserLazyMap: TypeAlias = dict[str, type[URLProtocol] | str]
-    ParserMap: TypeAlias = dict[str, type[URLProtocol]]
+ParserLazyMap: TypeAlias = dict[str, type[URLProtocol] | str]
+ParserMap: TypeAlias = dict[str, type[URLProtocol]]
 
 DEFAULT_PARSERS: ParserLazyMap = {
     "git": "libvcs.url.git.GitURL",