Determined proper use of conditional import; revert type annotations to classes from module addresses

Update tox.ini

Build docs on 3.9

via readthedocs/readthedocs.org#7554 (comment)

Update __init__.py

Give intersphinx internal package name (ranges)

Use intersphinx to link to external package

typo

Remove non-functional intersphinx aliases

Revert to working python-ranges link

Author: lmmx

.readthedocs.yml

@@ -3,8 +3,10 @@
 version: 2
 sphinx:
   configuration: docs/conf.py
+build:
+  image: testing
 python:
-  version: 3.8
+  version: 3.9
 
   install:
     - method: pip

docs/conf.py

@@ -44,8 +44,7 @@
 
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3/", None),
-    "python-ranges": ("https://python-ranges.readthedocs.io/en/latest/", None),
-    # "httpx": ("https://www.python-httpx.org/", None),
+    "ranges": ("https://python-ranges.readthedocs.io/en/latest/", None),
 }
 
 suppress_warnings = [

src/range_streams/__init__.py

@@ -1,10 +1,11 @@
 r"""
 :mod:`range_streams` provides file-like object handling through
 an API familiar to users of the standard library
-:mod:`io` module.  It uses Range, RangeSet, and RangeDict classes
+:mod:`io` module.  It uses :class:`ranges.Range`, :class:`ranges.RangeSet`,
+and :class:`ranges.RangeDict` classes (from the externally maintained
+`python-ranges <https://python-ranges.readthedocs.io/en/latest/>`_ library)
 to represent and look up range operations in an efficient linked
-list data structure from the externally maintained python-ranges
-library.
+list data structure.
 
 Servers with support for `HTTP range requests
 <https://developer.mozilla.org/en-US/docs/Web/HTTP/Range_requests>`_

src/range_streams/http_utils.py

@@ -1,13 +1,18 @@
 from __future__ import annotations
 
-import ranges
+from typing import TYPE_CHECKING
+
+from ranges import Range
+
+if TYPE_CHECKING:
+    import ranges
 
 from .range_utils import range_termini
 
 __all__ = ["byte_range_from_range_obj", "range_header"]
 
 
-def byte_range_from_range_obj(rng: ranges.Range) -> str:
+def byte_range_from_range_obj(rng: Range) -> str:
     """Prepare the byte range substring for a HTTP `range request
     <https://developer.mozilla.org/en-US/docs/Web/HTTP/Range_requests>`_.
 
@@ -22,7 +27,7 @@ def byte_range_from_range_obj(rng: ranges.Range) -> str:
     return byte_range
 
 
-def range_header(rng: ranges.Range) -> dict[str, str]:
+def range_header(rng: Range) -> dict[str, str]:
     """Prepare a :class:`dict` to pass as a :mod:`httpx` request header
     with a single key ``ranges`` whose value is the byte range.
 

src/range_streams/overlaps.py

@@ -3,7 +3,7 @@
 from typing import TYPE_CHECKING
 
 import ranges
-from ranges import Range
+from ranges import Range, RangeDict
 
 # due to https://github.com/agronholm/sphinx-autodoc-typehints/issues/72
 import range_streams  # for RangeStream
@@ -19,7 +19,7 @@
 
 # This could be written more clearly by using a range_utils helper function shared with
 # most_recent_range
-def get_range_containing(rng_dict: ranges.RangeDict, position: int) -> ranges.Range:
+def get_range_containing(rng_dict: RangeDict, position: int) -> Range:
     """Get a :class:`ranges.Range` from ``rng_dict`` by looking up the ``position`` it
     contains, where ``rng_dict`` is either the internal :obj:`RangeStream._ranges`
     or the external :obj:`RangeStream.ranges`.
@@ -42,7 +42,7 @@ def get_range_containing(rng_dict: ranges.RangeDict, position: int) -> ranges.Ra
 
 
 def burn_range(
-    stream: range_streams.range_stream.RangeStream, overlapped_ext_rng: ranges.Range
+    stream: range_streams.range_stream.RangeStream, overlapped_ext_rng: Range
 ):
     internal_rng = ext2int(stream=stream, ext_rng=overlapped_ext_rng)
     stream._ranges.remove(internal_rng)
@@ -52,7 +52,7 @@ def burn_range(
 
 def handle_overlap(
     stream: range_streams.range_stream.RangeStream,
-    rng: ranges.Range,
+    rng: Range,
     internal: bool = False,
 ) -> None:
     """
@@ -118,7 +118,7 @@ def handle_overlap(
 
 def overlap_whence(
     stream: range_streams.range_stream.RangeStream,
-    rng: ranges.Range,
+    rng: Range,
     internal: bool = False,
 ) -> int | None:
     """

src/range_streams/range_request.py

@@ -3,7 +3,10 @@
 from typing import TYPE_CHECKING, Iterator
 
 import httpx
-import ranges
+from ranges import Range
+
+if TYPE_CHECKING:
+    import ranges
 
 from .http_utils import range_header
 
@@ -18,7 +21,7 @@ class RangeRequest:
     suitable for `RangeResponse` to wrap in a `io.BytesIO` buffered stream.
     """
 
-    def __init__(self, byte_range: ranges.Range, url: str, client: httpx.Client):
+    def __init__(self, byte_range: Range, url: str, client: httpx.Client):
         self.range = byte_range
         self.url = url
         self.client = client

src/range_streams/range_utils.py

@@ -12,25 +12,26 @@
 
 from typing import TYPE_CHECKING
 
-import ranges
-from ranges import Range
+if TYPE_CHECKING:
+    import ranges
+from ranges import Range, RangeDict
 
 import range_streams
 
 
-def ranges_in_reg_order(ranges: ranges.RangeDict) -> list[Range]:
+def ranges_in_reg_order(ranges: RangeDict) -> list[Range]:
     "Presumes integrity is already checked: ranges in order of registration"
     return [k[0].ranges()[0] for k, v in ranges.items()]
 
 
-def response_ranges_in_reg_order(ranges: ranges.RangeDict) -> list[Range]:
+def response_ranges_in_reg_order(ranges: RangeDict) -> list[Range]:
     "RangeResponse requested ranges in order of registration"
     return [v.request.range for k, v in ranges.items()]
 
 
 def most_recent_range(
     stream: range_streams.range_stream.RangeStream, internal: bool = True
-) -> ranges.Range | None:
+) -> Range | None:
     if stream._ranges.isempty():
         rng = None  # type: Range | None
     else:
@@ -39,7 +40,7 @@ def most_recent_range(
     return rng
 
 
-def range_termini(rng: ranges.Range) -> tuple[int, int]:
+def range_termini(rng: Range) -> tuple[int, int]:
     """
     Get the inclusive start and end positions `[start,end]` from a `ranges.Range`.
     These are referred to as the 'termini'. Ranges are always ascending.
@@ -52,26 +53,26 @@ def range_termini(rng: ranges.Range) -> tuple[int, int]:
     return start, end
 
 
-def range_len(rng: ranges.Range) -> int:
+def range_len(rng: Range) -> int:
     rmin, rmax = range_termini(rng)
     return rmax - rmin
 
 
-def range_min(rng: ranges.Range) -> int:
+def range_min(rng: Range) -> int:
     if rng.isempty():
         raise ValueError("Empty range has no minimum")
     return range_termini(rng)[0]
 
 
-def range_max(rng: ranges.Range) -> int:
+def range_max(rng: Range) -> int:
     if rng.isempty():
         raise ValueError("Empty range has no maximum")
     return range_termini(rng)[1]
 
 
 def validate_range(
-    byte_range: ranges.Range | tuple[int, int], allow_empty: bool = True
-) -> ranges.Range:
+    byte_range: Range | tuple[int, int], allow_empty: bool = True
+) -> Range:
     """
     Validate byte_range and convert to `[a,b)` :class:`ranges.Range` if given as integer
     tuple.
@@ -95,7 +96,7 @@ def validate_range(
     return byte_range
 
 
-def range_span(ranges: list[ranges.Range]) -> ranges.Range:
+def range_span(ranges: list[Range]) -> Range:
     """
     Assumes input list of :class:`RangeSets` are in ascending order, switches if not
     """
@@ -109,7 +110,7 @@ def range_span(ranges: list[ranges.Range]) -> ranges.Range:
 
 
 def ext2int(
-    stream: range_streams.range_stream.RangeStream, ext_rng: ranges.Range
+    stream: range_streams.range_stream.RangeStream, ext_rng: Range
 ) -> range_streams.range_stream.RangeResponse:
     """
     Given the external range `ext_rng` and the :class:`RangeStream` ``stream`` on which it is

tox.ini

@@ -4,8 +4,8 @@ testpaths = tests
 
 [gh-actions]
 python =
-    3.8: py38, mypy, lint, docs
-    3.9: py39
+    3.8: py38, mypy, lint
+    3.9: py39, docs
 
 [tox]
 envlist = lint, mypy, {py38,py39}, docs, coverage-report
@@ -35,7 +35,7 @@ commands = mypy src
 
 [testenv:docs]
 description = Build docs and run doctests.
-basepython = python3.8
+basepython = python3.9
 extras = docs
 changedir = docs
 commands =