From 45b89304d9745be1b87449805bf53d45bf740e90 Mon Sep 17 00:00:00 2001
From: Nejc Habjan <nejc.habjan@siemens.com>
Date: Thu, 12 Oct 2023 12:42:58 +0200
Subject: [PATCH] docs(advanced): document new netrc behavior

BREAKING CHANGE: python-gitlab now explicitly passes auth to requests, meaning
it will only read netrc credentials if no token is provided, fixing a bug where
netrc credentials took precedence over OAuth tokens. This also affects the CLI,
where all environment variables now take precedence over netrc files.
---
 docs/api-usage-advanced.rst    |  8 ++++----
 tests/unit/test_gitlab_auth.py | 34 ++++++++++++++++++++++++++++++++++
 2 files changed, 38 insertions(+), 4 deletions(-)

diff --git a/docs/api-usage-advanced.rst b/docs/api-usage-advanced.rst
index 90fbce4c4..ce18fd1e8 100644
--- a/docs/api-usage-advanced.rst
+++ b/docs/api-usage-advanced.rst
@@ -44,11 +44,11 @@ properly closed when you exit a ``with`` block:
 netrc authentication
 --------------------
 
-python-gitlab reads credentials from ``.netrc`` files via the ``requests`` backend by default,
-which may override authentication headers you set on your client.
+python-gitlab reads credentials from ``.netrc`` files via the ``requests`` backend
+only if you do not provide any other type of authentication yourself.
 
-For more granular control, you can disable this `Using a custom session`_
-and explicitly setting ``trust_env=False`` as described in the ``requests`` documentation.
+If you'd like to disable reading netrc files altogether, you can follow `Using a custom session`_
+and explicitly set ``trust_env=False`` as described in the ``requests`` documentation.
 
 .. code-block:: python
 
diff --git a/tests/unit/test_gitlab_auth.py b/tests/unit/test_gitlab_auth.py
index 8c3abc08d..0cf3715ed 100644
--- a/tests/unit/test_gitlab_auth.py
+++ b/tests/unit/test_gitlab_auth.py
@@ -1,5 +1,8 @@
+import pathlib
+
 import pytest
 import requests
+import responses
 from requests import PreparedRequest
 
 from gitlab import Gitlab
@@ -7,6 +10,13 @@
 from gitlab.config import GitlabConfigParser
 
 
+@pytest.fixture
+def netrc(monkeypatch: pytest.MonkeyPatch, tmp_path: pathlib.Path):
+    netrc_file = tmp_path / ".netrc"
+    netrc_file.write_text("machine localhost login test password test")
+    monkeypatch.setenv("NETRC", str(netrc_file))
+
+
 def test_invalid_auth_args():
     with pytest.raises(ValueError):
         Gitlab(
@@ -101,6 +111,30 @@ def test_http_auth():
     assert "JOB-TOKEN" not in p.headers
 
 
+@responses.activate
+def test_with_no_auth_uses_netrc_file(netrc):
+    responses.get(
+        url="http://localhost/api/v4/test",
+        match=[
+            responses.matchers.header_matcher({"Authorization": "Basic dGVzdDp0ZXN0"})
+        ],
+    )
+
+    gl = Gitlab("http://localhost")
+    gl.http_get("/test")
+
+
+@responses.activate
+def test_with_auth_ignores_netrc_file(netrc):
+    responses.get(
+        url="http://localhost/api/v4/test",
+        match=[responses.matchers.header_matcher({"Authorization": "Bearer test"})],
+    )
+
+    gl = Gitlab("http://localhost", oauth_token="test")
+    gl.http_get("/test")
+
+
 @pytest.mark.parametrize(
     "options,config,expected_private_token,expected_oauth_token,expected_job_token",
     [