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

4 files changed, 21 insertions, 11 deletions

diff --git a/docs/api-usage.rst b/docs/api-usage.rst
index 2a40cfa..e205cb4 100644
--- 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
index a9cbf89..e1b8bb8 100644
--- 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
index 36e3c1a..f944e99 100644
--- 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
index 4a82207..202a101 100644
--- a/gitlab/tests/test_gitlab.py
+++ b/gitlab/tests/test_gitlab.py
@@ -21,7 +21,7 @@ import pickle
 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])