feat(proxy): add ProxySettings model and Requests-compatible proxies mapping

- Introduces typed ProxySettings with fields: address, port (optional), username (optional), password (optional)
- Adds to_proxies() that returns {"http": "...", "https": "..."} usable by requests
- Ensures clean output when port is omitted (no trailing colon)
- Adds parameterized pytest coverage for typical usage
- Updates docs (Proxy configuration) and changelog

Author: sufyankhanrao

apimatic_core/http/configurations/__init__.py

@@ -1,3 +1,4 @@
 __all__ = [
-    'http_client_configuration'
+    'http_client_configuration',
+    'proxy_settings'
 ]

apimatic_core/http/configurations/proxy_settings.py

@@ -0,0 +1,22 @@
+from typing import Dict, Optional
+from urllib.parse import quote
+
+
+class ProxySettings:
+    address: str
+    port: Optional[int] = None
+    username: Optional[str] = None
+    password: Optional[str] = None
+
+    def to_proxies(self) -> Dict[str, str]:
+        auth = ""
+        if self.username is not None:
+            # URL-encode in case of special chars
+            u = quote(self.username, safe="")
+            p = quote(self.password or "", safe="")
+            auth = f"{u}:{p}@"
+        port = f":{self.port}" if self.port is not None else ""
+        return {
+            "http": f"http://{auth}{self.address}{port}",
+            "https": f"https://{auth}{self.address}{port}",
+        }

setup.py

@@ -12,7 +12,7 @@
 
 setup(
     name='apimatic-core',
-    version='0.2.21',
+    version='0.2.22',
     description='A library that contains core logic and utilities for '
                 'consuming REST APIs using Python SDKs generated by APIMatic.',
     long_description=long_description,

tests/apimatic_core/configuration/__init__.py

@@ -0,0 +1,118 @@
+from typing import Optional
+
+import pytest
+
+from apimatic_core.http.configurations.proxy_settings import ProxySettings
+
+
+class TestProxySettings:
+    @pytest.mark.parametrize(
+        "address, port, username, password, exp_http, exp_https",
+        [
+            pytest.param(
+                "proxy.local", None, None, None,
+                "http://proxy.local",
+                "https://proxy.local",
+                id="no-auth-no-port",
+            ),
+            pytest.param(
+                "proxy.local", 8080, None, None,
+                "http://proxy.local:8080",
+                "https://proxy.local:8080",
+                id="no-auth-with-port",
+            ),
+            pytest.param(
+                "proxy.local", 8080, "user", "pass",
+                "http://user:pass@proxy.local:8080",
+                "https://user:pass@proxy.local:8080",
+                id="auth-with-port",
+            ),
+            pytest.param(
+                "proxy.local", None, "user", None,
+                # password None -> empty string: "user:@"
+                "http://user:@proxy.local",
+                "https://user:@proxy.local",
+                id="auth-username-only-password-none",
+            ),
+            pytest.param(
+                "proxy.local", None, "a b", "p@ss#",
+                # URL-encoding of space/@/#
+                "http://a%20b:p%40ss%23@proxy.local",
+                "https://a%20b:p%40ss%23@proxy.local",
+                id="auth-with-url-encoding",
+            ),
+            pytest.param(
+                "localhost", None, "", "",
+                # empty username triggers auth block (since not None) -> ':@'
+                "http://:@localhost",
+                "https://:@localhost",
+                id="empty-username-and-password",
+            ),
+        ],
+    )
+    def test_to_proxies_formats_urls_correctly(
+        self, address: str, port: Optional[int], username: Optional[str], password: Optional[str], exp_http, exp_https
+    ):
+        ps = ProxySettings()
+        ps.address = address
+        ps.port = port
+        ps.username = username
+        ps.password = password
+
+        proxies = ps.to_proxies()
+
+        assert isinstance(proxies, dict)
+        assert proxies["http"] == exp_http
+        assert proxies["https"] == exp_https
+
+    def test_to_proxies_has_expected_keys(self):
+        ps = ProxySettings()
+        ps.address = "proxy.local"
+        proxies = ps.to_proxies()
+        assert set(proxies.keys()) == {"http", "https"}
+
+    @pytest.mark.parametrize("address", ["proxy.local", "localhost"])
+    def test_no_trailing_colon_when_no_port(self, address):
+        ps = ProxySettings()
+        ps.address = address
+        ps.port = None
+        proxies = ps.to_proxies()
+
+        # Ensure clean host without trailing colon or accidental double-colon
+        assert not proxies["http"].endswith(":")
+        assert not proxies["https"].endswith(":")
+        assert "::" not in proxies["http"]
+        assert "::" not in proxies["https"]
+
+    @pytest.mark.parametrize(
+        "username,password,expected_auth_fragment",
+        [
+            ("user", "pass", "user:pass@"),
+            ("a b", "p@ss#", "a%20b:p%40ss%23@"),   # URL-encoded creds
+            ("user", None, "user:@"),               # empty password encoded as ""
+            ("", "", ":@"),                         # empty user & pass still builds auth
+        ],
+    )
+    def test_auth_fragment_is_correctly_encoded_and_included(
+        self, username, password, expected_auth_fragment
+    ):
+        ps = ProxySettings()
+        ps.address = "proxy.local"
+        ps.username = username
+        ps.password = password
+
+        proxies = ps.to_proxies()
+        assert expected_auth_fragment in proxies["http"]
+        assert expected_auth_fragment in proxies["https"]
+
+    def test_with_port_has_single_colon_before_port(self):
+        ps = ProxySettings()
+        ps.address = "proxy.local"
+        ps.port = 3128
+        proxies = ps.to_proxies()
+
+        # Only one colon should precede the port, e.g., "...proxy.local:3128"
+        assert proxies["http"].endswith(":3128")
+        assert proxies["https"].endswith(":3128")
+        assert "proxy.local::3128" not in proxies["http"]
+        assert "proxy.local::3128" not in proxies["https"]