Adds client identification.

Adds custom User-Agent header to API calls to enable analytics on how the library is being used by different clients (CLI, MCP server, direct usage, etc.).

Author: filiplajszczak

README.rst

@@ -1,6 +1,10 @@
-API wrapper for programmatic management of PythonAnywhere services.
+pythonanywhere-core
+===================
 
-It's a core code behind `PythonAnywhere cli tool`_.
+Python SDK for PythonAnywhere API - programmatic management of PythonAnywhere
+services including webapps, files, scheduled tasks, students, and websites.
+
+Core library behind the `PythonAnywhere cli tool`_.
 
 .. _PythonAnywhere cli tool: https://pypi.org/project/pythonanywhere/
 
@@ -9,7 +13,6 @@ Documentation
 
 Full documentation is available at https://core.pythonanywhere.com/
 
-
 Development
 ===========
 

docs/reference/environment-variables.rst

@@ -70,6 +70,38 @@ PYTHONANYWHERE_DOMAIN
 
     export PYTHONANYWHERE_DOMAIN="example.com"
 
+PYTHONANYWHERE_CLIENT
+~~~~~~~~~~~~~~~~~~~~~~
+
+**Required:** No
+
+**Default:** Not set (library identifies itself without client information)
+
+**Description:** Identifies the client application using ``pythonanywhere-core`` in API requests. This information is included in the User-Agent header and helps PythonAnywhere understand API usage patterns and improve service analytics.
+
+**Format:** ``client-name/version`` (e.g., ``pa/1.0.0``, ``mcp-server/0.5.0``)
+
+**When to use:**
+  - Building a CLI tool that uses this library
+  - Creating an MCP server
+  - Developing automation scripts or custom applications
+  - Any downstream tool that wraps ``pythonanywhere-core``
+
+**User-Agent format:**
+  - Without ``PYTHONANYWHERE_CLIENT``: ``pythonanywhere-core/0.2.8 (Python/3.13.7)``
+  - With ``PYTHONANYWHERE_CLIENT``: ``pythonanywhere-core/0.2.8 (pa/1.0.0; Python/3.13.7)``
+
+**Usage:**
+
+.. code-block:: python
+
+    import os
+    from importlib.metadata import version
+
+    # Set at application startup
+    CLI_VERSION = version("my-cli-package")
+    os.environ["PYTHONANYWHERE_CLIENT"] = f"my-cli/{CLI_VERSION}"
+
 See Also
 --------
 

pythonanywhere_core/base.py

@@ -1,8 +1,10 @@
 import os
+import platform
 from typing import Dict
 
 import requests
 
+from pythonanywhere_core import __version__
 from pythonanywhere_core.exceptions import AuthenticationError, NoTokenError
 
 PYTHON_VERSIONS: Dict[str, str] = {
@@ -54,15 +56,35 @@ def call_api(url: str, method: str, **kwargs) -> requests.Response:
     :returns: requests.Response object
 
     :raises AuthenticationError: if API returns 401
-    :raises NoTokenError: if API_TOKEN environment variable is not set"""
+    :raises NoTokenError: if API_TOKEN environment variable is not set
+
+    Client identification can be provided via PYTHONANYWHERE_CLIENT environment
+    variable (e.g., "pa/1.0.0" or "mcp-server/0.5.0") to help with usage analytics.
+    """
 
     token = os.environ.get("API_TOKEN")
     if token is None:
         raise NoTokenError(helpful_token_error_message())
+
+    base_user_agent = f"pythonanywhere-core/{__version__}"
+    client_info = os.environ.get("PYTHONANYWHERE_CLIENT")
+
+    if client_info:
+        user_agent = f"{base_user_agent} ({client_info}; Python/{platform.python_version()})"
+    else:
+        user_agent = f"{base_user_agent} (Python/{platform.python_version()})"
+
+    headers = {
+        "Authorization": f"Token {token}",
+        "User-Agent": user_agent
+    }
+    if "headers" in kwargs:
+        headers.update(kwargs.pop("headers"))
+
     response = requests.request(
         method=method,
         url=url,
-        headers={"Authorization": f"Token {token}"},
+        headers=headers,
         **kwargs,
     )
     if response.status_code == 401:

tests/test_base.py

@@ -1,3 +1,6 @@
+import platform
+from pythonanywhere_core import __version__
+
 import pytest
 import responses
 
@@ -9,11 +12,6 @@
 from pythonanywhere_core.exceptions import AuthenticationError, NoTokenError
 
 
-@pytest.fixture
-def mock_requests(mocker):
-    return mocker.patch("pythonanywhere_core.base.requests")
-
-
 def test_get_api_endpoint_defaults_to_pythonanywhere_dot_com_if_no_environment_variables():
     result = get_api_endpoint(username="bill", flavor="webapp")
 
@@ -90,3 +88,50 @@ def test_helpful_message_outside_pythonanywhere(monkeypatch):
     monkeypatch.delenv("PYTHONANYWHERE_SITE", raising=False)
 
     assert "Oops, you don't seem to have an API_TOKEN environment variable set." in helpful_token_error_message()
+
+
+def test_call_api_includes_user_agent_without_client_info(api_token, api_responses, monkeypatch):
+    monkeypatch.delenv("PYTHONANYWHERE_CLIENT", raising=False)
+
+    url = "https://www.pythonanywhere.com/api/v0/test"
+    api_responses.add(responses.GET, url, json={"status": "ok"}, status=200)
+
+    response = call_api(url, "GET")
+
+    assert response.status_code == 200
+    expected_ua = f"pythonanywhere-core/{__version__} (Python/{platform.python_version()})"
+    assert api_responses.calls[0].request.headers["User-Agent"] == expected_ua
+
+
+def test_call_api_includes_user_agent_with_client_info(api_token, api_responses, monkeypatch):
+    monkeypatch.setenv("PYTHONANYWHERE_CLIENT", "pa/1.0.0")
+
+    url = "https://www.pythonanywhere.com/api/v0/test"
+    api_responses.add(responses.GET, url, json={"status": "ok"}, status=200)
+
+    response = call_api(url, "GET")
+
+    assert response.status_code == 200
+    expected_ua = f"pythonanywhere-core/{__version__} (pa/1.0.0; Python/{platform.python_version()})"
+    assert api_responses.calls[0].request.headers["User-Agent"] == expected_ua
+
+
+def test_call_api_custom_headers_can_override_user_agent(api_token, api_responses):
+    url = "https://www.pythonanywhere.com/api/v0/test"
+    api_responses.add(responses.GET, url, json={"status": "ok"}, status=200)
+
+    response = call_api(url, "GET", headers={"User-Agent": "custom/1.0.0"})
+
+    assert response.status_code == 200
+    assert api_responses.calls[0].request.headers["User-Agent"] == "custom/1.0.0"
+
+
+def test_call_api_preserves_authorization_with_custom_headers(api_token, api_responses):
+    url = "https://www.pythonanywhere.com/api/v0/test"
+    api_responses.add(responses.POST, url, json={"status": "ok"}, status=200)
+
+    response = call_api(url, "POST", headers={"X-Custom": "value"})
+
+    assert response.status_code == 200
+    assert api_responses.calls[0].request.headers["Authorization"] == f"Token {api_token}"
+    assert api_responses.calls[0].request.headers["X-Custom"] == "value"