feat(api): default to gitlab.com if no URL given

nejch · nejch · commit 2edd69c55fc7 · 2021-02-04T22:54:46.000+01:00
diff --git a/docs/api-usage.rst b/docs/api-usage.rst
@@ -7,13 +7,22 @@ python-gitlab only supports GitLab APIs v4.
 ``gitlab.Gitlab`` class
 =======================
 
-To connect to a GitLab server, create a ``gitlab.Gitlab`` object:
+To connect to GitLab.com or another GitLab server, create a ``gitlab.Gitlab`` object:
 
 .. code-block:: python
 
    import gitlab
 
-   # private token or personal token authentication
+   # anonymous read-only access for public resources (GitLab.com)
+   gl = gitlab.Gitlab()
+
+   # anonymous read-only access for public resources (self-hosted GitLab instance)
+   gl = gitlab.Gitlab('http://10.0.0.1')
+
+   # private token or personal token authentication (GitLab.com)
+   gl = gitlab.Gitlab(private_token='JVNSESs8EwWRx5yDxM5q')
+
+   # private token or personal token authentication (self-hosted GitLab instance)
    gl = gitlab.Gitlab('http://10.0.0.1', private_token='JVNSESs8EwWRx5yDxM5q')
 
    # oauth token authentication
@@ -23,12 +32,6 @@ To connect to a GitLab server, create a ``gitlab.Gitlab`` object:
    import os
    gl = gitlab.Gitlab('http://10.0.0.1', job_token=os.environ['CI_JOB_TOKEN'])
 
-   # anonymous gitlab instance, read-only for public resources
-   gl = gitlab.Gitlab('http://10.0.0.1')
-
-   # Define your own custom user agent for requests
-   gl = gitlab.Gitlab('http://10.0.0.1', user_agent='my-package/1.0.0')
-
    # make an API request to create the gl.user object. This is mandatory if you
    # use the username/password authentication.
    gl.auth()
diff --git a/gitlab/__init__.py b/gitlab/__init__.py
@@ -52,7 +52,7 @@ class Gitlab(object):
     """Represents a GitLab server connection.
 
     Args:
-        url (str): The URL of the GitLab server.
+        url (str): The URL of the GitLab server (defaults to https://gitlab.com).
         private_token (str): The user private token
         oauth_token (str): An oauth token
         job_token (str): A CI job token
@@ -70,7 +70,7 @@ class Gitlab(object):
 
     def __init__(
         self,
-        url,
+        url=DEFAULT_URL,
         private_token=None,
         oauth_token=None,
         job_token=None,
diff --git a/gitlab/const.py b/gitlab/const.py
@@ -18,6 +18,8 @@
 from gitlab.__version__ import __title__, __version__
 
 
+DEFAULT_URL = "https://gitlab.com"
+
 NO_ACCESS = 0
 MINIMAL_ACCESS = 5
 GUEST_ACCESS = 10
diff --git a/gitlab/tests/test_gitlab.py b/gitlab/tests/test_gitlab.py
@@ -21,7 +21,7 @@
 import pytest
 from httmock import HTTMock, response, urlmatch, with_httmock  # noqa
 
-from gitlab import Gitlab, GitlabList, USER_AGENT
+from gitlab import Gitlab, GitlabList, DEFAULT_URL, USER_AGENT
 from gitlab.v4.objects import CurrentUser
 
 
@@ -128,6 +128,11 @@ def test_gitlab_token_auth(gl, callback=None):
     assert isinstance(gl.user, CurrentUser)
 
 
+def test_gitlab_default_url():
+    gl = Gitlab()
+    assert gl.url == DEFAULT_URL
+
+
 def test_gitlab_from_config(default_config):
     config_path = default_config
     Gitlab.from_config("one", [config_path])
