1 file changed
@@ -6,10 +6,23 @@ Using a custom session | |||
| 6 | 6 | ---------------------- | |
| 7 | 7 | ||
| 8 | 8 | python-gitlab relies on ``requests.Session`` objects to perform all the | |
| 9 | - HTTP requests to the Gitlab servers. | ||
| 9 | + HTTP requests to the GitLab servers. | ||
| 10 | 10 | ||
| 11 | - You can provide your own ``Session`` object with custom configuration when | ||
| 12 | - you create a ``Gitlab`` object. | ||
| 11 | + You can provide a custom session to create ``gitlab.Gitlab`` objects: | ||
| 12 | + | ||
| 13 | + .. code-block:: python | ||
| 14 | + | ||
| 15 | + import gitlab | ||
| 16 | + import requests | ||
| 17 | + | ||
| 18 | + session = requests.Session() | ||
| 19 | + gl = gitlab.Gitlab(session=session) | ||
| 20 | + | ||
| 21 | + # or when instantiating from configuration files | ||
| 22 | + gl = gitlab.Gitlab.from_config('somewhere', ['/tmp/gl.cfg'], session=session) | ||
| 23 | + | ||
| 24 | + Reference: | ||
| 25 | + https://requests.readthedocs.io/en/latest/user/advanced/#session-objects | ||
| 13 | 26 | ||
| 14 | 27 | Context manager | |
| 15 | 28 | --------------- | |
@@ -28,24 +41,34 @@ properly closed when you exit a ``with`` block: | |||
| 28 | 41 | The context manager will also close the custom ``Session`` object you might | |
| 29 | 42 | have used to build the ``Gitlab`` instance. | |
| 30 | 43 | ||
| 31 | - Proxy configuration | ||
| 32 | - ------------------- | ||
| 44 | + netrc authentication | ||
| 45 | + -------------------- | ||
| 33 | 46 | ||
| 34 | - The following sample illustrates how to define a proxy configuration when using | ||
| 35 | - python-gitlab: | ||
| 47 | + python-gitlab reads credentials from ``.netrc`` files via the ``requests`` backend by default, | ||
| 48 | + which may override authentication headers you set on your client. | ||
| 49 | + | ||
| 50 | + For more granular control, you can disable this `Using a custom session`_ | ||
| 51 | + and explicitly setting ``trust_env=False`` as described in the ``requests`` documentation. | ||
| 36 | 52 | ||
| 37 | 53 | .. code-block:: python | |
| 38 | 54 | ||
| 39 | - import os | ||
| 40 | 55 | import gitlab | |
| 41 | 56 | import requests | |
| 42 | 57 | ||
| 43 | - session = requests.Session() | ||
| 44 | - session.proxies = { | ||
| 45 | - 'https': os.environ.get('https_proxy'), | ||
| 46 | - 'http': os.environ.get('http_proxy'), | ||
| 47 | - } | ||
| 48 | - gl = gitlab.Gitlab(url, token, api_version=4, session=session) | ||
| 58 | + session = requests.Session(trust_env=False) | ||
| 59 | + gl = gitlab.Gitlab(session=session) | ||
| 60 | + | ||
| 61 | + Reference: | ||
| 62 | + https://requests.readthedocs.io/en/latest/user/authentication/#netrc-authentication | ||
| 63 | + | ||
| 64 | + Proxy configuration | ||
| 65 | + ------------------- | ||
| 66 | + | ||
| 67 | + python-gitlab accepts the standard ``http_proxy``, ``https_proxy`` and ``no_proxy`` | ||
| 68 | + environment variables via the ``requests`` backend. Uppercase variables are also supported. | ||
| 69 | + | ||
| 70 | + For more granular control, you can also explicitly set proxies by `Using a custom session`_ | ||
| 71 | + as described in the ``requests`` documentation. | ||
| 49 | 72 | ||
| 50 | 73 | Reference: | |
| 51 | 74 | https://requests.readthedocs.io/en/latest/user/advanced/#proxies | |
@@ -188,15 +211,3 @@ on your own, such as for nested API responses and ``Union`` return types. For ex | |||
| 188 | 211 | ||
| 189 | 212 | if TYPE_CHECKING: | |
| 190 | 213 | assert isinstance(license["plan"], str) | |
| 191 | - | ||
| 192 | - Custom session (Bring your own Session) | ||
| 193 | - --------------------------------------- | ||
| 194 | - | ||
| 195 | - You can use configuration files and a custom session to create | ||
| 196 | - ``gitlab.Gitlab`` objects: | ||
| 197 | - | ||
| 198 | - .. code-block:: python | ||
| 199 | - | ||
| 200 | - gl = gitlab.Gitlab.from_config('somewhere', ['/tmp/gl.cfg'], session=custom_session) | ||
| 201 | - | ||
| 202 | - | ||
0 commit comments