feat!: accept positional arguments when creating client (#231)

Modifies client creation to accept the server URL and API key as optional positional arguments.

BREAKING CHANGE: Swaps the api_key and url argument positions in Client init.

src/posit/connect/client.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 from requests import Response, Session
-from typing import Optional
+from typing import Optional, overload
 
 from . import hooks, me, urls
 
@@ -47,11 +47,114 @@ class Client:
         Server version.
     """
 
-    def __init__(
-        self,
-        api_key: Optional[str] = None,
-        url: Optional[str] = None,
-    ) -> None:
+    @overload
+    def __init__(self) -> None:
+        """Initialize a Client instance.
+
+        Creates a client instance using credentials read from the environment.
+
+        Environment Variables
+        ---------------------
+        CONNECT_SERVER - The Connect server URL.
+        CONNECT_API_KEY - The API key credential for client authentication.
+
+        Examples
+        --------
+        Client()
+        """
+        ...
+
+    @overload
+    def __init__(self, url: str) -> None:
+        """Initialize a Client instance.
+
+        Creates a client instance using a provided URL and API key credential read from the environment.
+
+        Environment Variables
+        ---------------------
+        CONNECT_API_KEY - The API key credential for client authentication.
+
+        Parameters
+        ----------
+        url : str
+            The Connect server URL.
+
+        Examples
+        --------
+        Client("https://connect.example.com)
+        """
+        ...
+
+    @overload
+    def __init__(self, url: str, api_key: str) -> None:
+        """Initialize a Client instance.
+
+        Parameters
+        ----------
+        url : str
+            The Connect server URL.
+        api_key : str
+            The API key credential for client authentication.
+
+        Examples
+        --------
+        >>> Client("https://connect.example.com", abcdefghijklmnopqrstuvwxyz012345")
+        """
+        ...
+
+    @overload
+    def __init__(self, *args, **kwargs) -> None:
+        """Initialize a Client instance."""
+        ...
+
+    def __init__(self, *args, **kwargs) -> None:
+        """Initialize a Client instance.
+
+        Environment Variables
+        ---------------------
+        CONNECT_SERVER - The Connect server URL.
+        CONNECT_API_KEY - The API key credential for client authentication.
+
+        Parameters
+        ----------
+        *args
+            Variable length argument list. Can accept:
+            - (url: str)
+                url: str
+                    The Connect server URL.
+            - (url: str, api_key: str)
+                url: str
+                    The Connect server URL.
+                api_key: str
+                    The API key credential for client authentication.
+
+        **kwargs
+            Keyword arguments. Can include 'url' and 'api_key'.
+
+        Examples
+        --------
+        >>> Client()
+        >>> Client("https://connect.example.com")
+        >>> Client("https://connect.example.com", abcdefghijklmnopqrstuvwxyz012345")
+        >>> Client(api_key=""abcdefghijklmnopqrstuvwxyz012345", url="https://connect.example.com")
+        """
+        api_key = None
+        url = None
+        if len(args) == 1 and isinstance(args[0], str):
+            url = args[0]
+        elif (
+            len(args) == 2
+            and isinstance(args[0], str)
+            and isinstance(args[1], str)
+        ):
+            url = args[0]
+            api_key = args[1]
+        else:
+            if "api_key" in kwargs and isinstance(kwargs["api_key"], str):
+                api_key = kwargs["api_key"]
+            if "url" in kwargs and isinstance(kwargs["url"], str):
+                url = kwargs["url"]
+
         self.config = Config(api_key=api_key, url=url)
         session = Session()
         session.auth = Auth(config=self.config)

tests/posit/connect/metrics/test_usage.py

@@ -165,7 +165,7 @@ def test(self):
         )
 
         # setup
-        c = connect.Client("12345", "https://connect.example")
+        c = connect.Client("https://connect.example", "12345")
 
         # invoke
         events = c.metrics.usage.find()
@@ -239,7 +239,7 @@ def test(self):
         )
 
         # setup
-        c = connect.Client("12345", "https://connect.example")
+        c = connect.Client("https://connect.example", "12345")
 
         # invoke
         view_event = c.metrics.usage.find_one()
@@ -275,7 +275,7 @@ def test_none(self):
         )
 
         # setup
-        c = connect.Client("12345", "https://connect.example")
+        c = connect.Client("https://connect.example", "12345")
 
         # invoke
         view_event = c.metrics.usage.find_one(content_guid="not-found")

tests/posit/connect/test_bundles.py

@@ -113,7 +113,7 @@ def test(self):
         )
 
         # setup
-        c = Client("12345", "https://connect.example")
+        c = Client("https://connect.example", "12345")
         bundle = c.content.get(content_guid).bundles.get(bundle_id)
 
         # invoke
@@ -157,7 +157,7 @@ def test(self):
         )
 
         # setup
-        c = Client("12345", "https://connect.example")
+        c = Client("https://connect.example", "12345")
         bundle = c.content.get(content_guid).bundles.get(bundle_id)
 
         # invoke
@@ -200,7 +200,7 @@ def test_output_as_str(self, mock_file: mock.MagicMock):
         )
 
         # setup
-        c = Client("12345", "https://connect.example")
+        c = Client("https://connect.example", "12345")
         bundle = c.content.get(content_guid).bundles.get(bundle_id)
 
         # invoke
@@ -239,7 +239,7 @@ def test_output_as_io(self):
         )
 
         # setup
-        c = Client("12345", "https://connect.example")
+        c = Client("https://connect.example", "12345")
         bundle = c.content.get(content_guid).bundles.get(bundle_id)
 
         # invoke
@@ -281,7 +281,7 @@ def test_invalid_arguments(self):
         )
 
         # setup
-        c = Client("12345", "https://connect.example")
+        c = Client("https://connect.example", "12345")
         bundle = c.content.get(content_guid).bundles.get(bundle_id)
 
         # invoke
@@ -316,7 +316,7 @@ def test(self):
         )
 
         # setup
-        c = Client("12345", "https://connect.example")
+        c = Client("https://connect.example", "12345")
         content = c.content.get(content_guid)
 
         # invoke
@@ -350,7 +350,7 @@ def test_kwargs_pathname(self):
         )
 
         # setup
-        c = Client("12345", "https://connect.example")
+        c = Client("https://connect.example", "12345")
         content = c.content.get(content_guid)
 
         # invoke
@@ -373,7 +373,7 @@ def test_invalid_arguments(self):
         )
 
         # setup
-        c = Client("12345", "https://connect.example")
+        c = Client("https://connect.example", "12345")
         content = c.content.get(content_guid)
 
         # invoke
@@ -398,7 +398,7 @@ def test(self):
         )
 
         # setup
-        c = Client("12345", "https://connect.example")
+        c = Client("https://connect.example", "12345")
 
         # invoke
         bundles = c.content.get(content_guid).bundles.find()
@@ -427,7 +427,7 @@ def test(self):
         )
 
         # setup
-        c = Client("12345", "https://connect.example")
+        c = Client("https://connect.example", "12345")
 
         # invoke
         bundle = c.content.get(content_guid).bundles.find_one()
@@ -458,7 +458,7 @@ def test(self):
         )
 
         # setup
-        c = Client("12345", "https://connect.example")
+        c = Client("https://connect.example", "12345")
 
         # invoke
         bundle = c.content.get(content_guid).bundles.get(bundle_id)