Add NetRCAuth() class.

[tomchristie]

Closes #2532

Prompted by #2532 (comment)

We currently automatically handle netrc authentication, which is baked directly into the Client, and which is enabled unless the developer sets trust_env=False.

• Browsers, which do not use netrc authentication.
• The curl command line client, which only uses netrc authentication if explicitly enabled.

The suggest here is that we should make a behavioural change, and no longer bake netrc authentication directly into the client, in favor of providing an explicit NetRCAuth() class.

Some usage examples...

# Use default netrc file
auth = httpx.NetRCAuth()
client = httpx.Client(auth=auth)

# Use explicit netrc file
auth = httpx.NetRCAuth(file="/path/to/netrc")
client = httpx.Client(auth=auth)

# Optional environ override, fallback to default netrc file otherwise
auth = httpx.NetRCAuth(file=os.environ.get('NETRC'))
client = httpx.Client(auth=auth)

# Mandatory environ override
auth = httpx.NetRCAuth(file=os.environ['NETRC'])
client = httpx.Client(auth=auth)

# Optional netrc auth, depending on if the "~/.netrc" file exists
try:
    auth = httpx.NetRCAuth()
except FileNotFound:
    auth = None
client = httpx.Client(auth=auth)

This would be a behavioral change and need to be part of a 0.24.0 release, but I think it's obviously more consistent and neater than our existing "netrc is a special case" behaviour.

(I had also assumed that this change would resolve issue #2088, and added a test case for this, which showed me that my assumption there was incorrect. Failing test case for that now dropped in commits ebcf77a and 02120cc.)

TODO:

• Drop baked-in client netrc auth class.
• Implement NetRCAuth class.
• Tests.
• Update documentation.

Documentation link, for easier review... https://github.com/encode/httpx/blob/02120cccecf905a0f142b36a31cebf68974e9528/docs/advanced.md#netrc-support

[tomchristie]

What do we think @encode/maintainers?

[cdeler]

I'm sorry, may I ask you why you are checking the password for None?

[cdeler]

I'm asking since previously you were checking

if credentials is not None:
    ...

and python documentation says (link) that

If the netrc file did not contain an entry for the given host, return the tuple associated with the ‘default’ entry. If neither matching host nor default entry is available, return None.

[tomchristie]

Thanks @cdeler.

The simple version of "why" is because I was blindly following our previous implementation details here.

I've had a look into it, and I don't think the password can be None here, but I think it can be the empty string. It looks to me like Python 3.11+ will allow the empty string for a missing password field in the netrc file, and the previous versions will raise a parse error for missing passwords.

I think the robust thing to do here would be...

if auth_info is None or not auth_info[2]:

[tomchristie]

Demo'ing the behaviour of Python netrc with an empty password entry...

import netrc
import tempfile


with tempfile.NamedTemporaryFile(delete=False) as t:
    t.write(b"machine example.com\nlogin user\n")
    t.close()
    n = netrc.netrc(t.name)
    print(n.authenticators("example.com"))

Python 3.11:

$ python3.11 ./example.py 
('user', '', '')

Python 3.10:

$ python3.10 ./example.py 
Traceback (most recent call last):
  File "/Users/tomchristie/Temp/./example.py", line 8, in <module>
    n = netrc.netrc(t.name)
  File "/Library/Frameworks/Python.framework/Versions/3.10/lib/python3.10/netrc.py", line 31, in __init__
    self._parse(file, fp, default_netrc)
  File "/Library/Frameworks/Python.framework/Versions/3.10/lib/python3.10/netrc.py", line 82, in _parse
    raise NetrcParseError(
netrc.NetrcParseError: malformed machine entry example.com terminated by '' (/var/folders/8s/dk9369g11yzdnsfkvbtljcjm0000gn/T/tmpipnocc0x, line 3)

[tomchristie]

Great review, thanks @cdeler - I've updated the PR to be more robust to the empty password case.

[cdeler]

LGTM, but have 1 small nitpick:

Does it make sense to add a test + test fixture for the case when password is empty (it will add a test for the newly added check)?

[tomchristie]

Does it make sense to add a test + test fixture for the case when password is empty (it will add a test for the newly added check)?

Done.