gh-87027: Add prev_network function to ipaddress library (follow-up to GH-24180)

[777GE90]

Following the merge of #24180, it was previously raised that we should add a prev_network method for symmetry, I have now done this as part of this PR so hopefully this completes the entire feature.

FYI for:
@akulakov @merwok @Fidget-Spinner @orsenthil @AA-Turner

• Issue: ipaddress - add ability to get next closest network of any prefix size #87027

[python-cla-bot]

All commit authors signed the Contributor License Agreement.

[read-the-docs-community]

Documentation build overview

📚 cpython-previews | 🛠️ Build #33650720 | 📁 Comparing 7b79473 against main (c08c89a)

  🔍 Preview build  

3 files changed

± library/ipaddress.html
± whatsnew/3.16.html
± whatsnew/changelog.html

[fedonman]

_network_by_offset() bounds new_ip from above only in the prefix > self.prefixlen branch. The other branch falls through to except OverflowError, which only the IPv4 path raises, so on IPv6 the ValueError from _BaseV6._string_from_ip_int() escapes instead of error.

Against 7b79473:

IPv4Network('255.255.255.0/24').next_network()
    -> ValueError: out of address space, cannot make another /24 network
IPv6Network('ffff:ffff:ffff:ffff:ffff:ffff:ffff:0/112').next_network()
    -> ValueError: IPv6 address is too large
IPv6Network('ffff::/16').next_network()
    -> ValueError: IPv6 address is too large
IPv6Network('ffff:ffff:ffff:ffff:ffff:ffff:ffff:0/112').next_network(next_prefix=120)
    -> ValueError: out of address space, cannot make another /120 network

Checking new_ip > self._ALL_ONES next to the existing new_ip < 0 after the branch covers both cases and makes the try/except unnecessary.

Same defect as gh-156680; GH-156681 fixes it in next_network() on main.

[777GE90]

_network_by_offset() bounds new_ip from above only in the prefix > self.prefixlen branch. The other branch falls through to except OverflowError, which only the IPv4 path raises, so on IPv6 the ValueError from _BaseV6._string_from_ip_int() escapes instead of error.

Against 7b79473:

IPv4Network('255.255.255.0/24').next_network()
    -> ValueError: out of address space, cannot make another /24 network
IPv6Network('ffff:ffff:ffff:ffff:ffff:ffff:ffff:0/112').next_network()
    -> ValueError: IPv6 address is too large
IPv6Network('ffff::/16').next_network()
    -> ValueError: IPv6 address is too large
IPv6Network('ffff:ffff:ffff:ffff:ffff:ffff:ffff:0/112').next_network(next_prefix=120)
    -> ValueError: out of address space, cannot make another /120 network

Checking new_ip > self._ALL_ONES next to the existing new_ip < 0 after the branch covers both cases and makes the try/except unnecessary.

Same defect as gh-156680; GH-156681 fixes it in next_network() on main.

Thank you for raising this, I have taken a look and it seems whilst I did write tests for this I was not explicitly checking the error message so didn't notice this happy coincidence.

I have now updated the tests to explicitly check the reason/message and refactored the logic as suggested to handle this. It's nice to clean up that try/catch logic too.

See commit c6b1d1a