Ensure portfoward's local_port keyword follows kubectl behavior

[jacobtomlinson]

Closes #505

Currently setting local_port=None (the default behaviour) when port forwarding chooses a random high port. However this does not match the default behaviour of kubectl. As pointed out in #505 there are three different things that local_port can be set to in kubectl.

If it is completely omitted it will match the remote_port.

# This binds remote port 80 to port 80 locally
kubectl port-forward po/nginx 80

If it is left empty it will choose a random high port.

# This binds to a random port locally
kubectl port-forward po/nginx :80

And finally if it is set then it will be explicitly set.

# This binds to port 8080 locally
kubectl port-forward po/nginx 8080:80

This is a little trickier to implement in a Pythonic way because we usually use None or 0 for choosing a random high port. To resolve this in this PR I've added a new optional union type that is either a literal string of "match" or "auto" or an int. If the value is set to None it will follow the behaviour or "auto" which provides backward compatibility for folks who may explicitly be setting the value to None.

BREAKING: The default value has been changed to "match" to mimic the default behaviour of kubectl.

So the kr8s Python API now follows the kubectl behaviour:

If it is completely omitted it will match the remote_port.

from kr8s.objects import Pod

# This binds remote port 80 to port 80 locally
Pod("nginx").portforward(remote_port=80).run_forever()

If it is set to "auto" or None it will choose a random high port.

from kr8s.objects import Pod

# This binds to a random port locally
Pod("nginx").portforward(remote_port=80, local_port="auto").run_forever()

# This is equivalent for backward compatibility
Pod("nginx").portforward(remote_port=80, local_port=None).run_forever()

# This is also equivalent
Pod("nginx").portforward(remote_port=80, local_port=0).run_forever()

And finally if it is set then it will be explicitly set.

from kr8s.objects import Pod

# This binds to port 8080 locally
Pod("nginx").portforward(remote_port=80, local_port=8080).run_forever()

[codecov]

Codecov Report

Attention: Patch coverage is 80.00000% with 4 lines in your changes missing coverage. Please review.

Project coverage is 95.08%. Comparing base (87063fc) to head (530aa66).
Report is 124 commits behind head on main.

Files with missing lines	Patch %	Lines
kr8s/_portforward.py	55.55%	4 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #506      +/-   ##
==========================================
+ Coverage   94.61%   95.08%   +0.46%     
==========================================
  Files          29       30       +1     
  Lines        3141     3989     +848     
==========================================
+ Hits         2972     3793     +821     
- Misses        169      196      +27     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.