adds nice explicit way to override username.

Author: filiplajszczak

docs/reference/environment-variables.rst

@@ -32,24 +32,37 @@ API_TOKEN
 Optional Variables
 ------------------
 
-PYTHONANYWHERE_SITE
-~~~~~~~~~~~~~~~~~~~~
+PYTHONANYWHERE_CLIENT
+~~~~~~~~~~~~~~~~~~~~~~
 
 **Required:** No
 
-**Default:** ``www.pythonanywhere.com`` (or ``www.`` + ``PYTHONANYWHERE_DOMAIN`` if that is set)
+**Default:** Not set (library identifies itself without client information)
 
-**Description:** Override the hostname used for API requests. Useful for testing against different PythonAnywhere environments or when using EU servers.
+**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.
 
-.. note::
-   When running on PythonAnywhere, this variable is automatically set in the environment
-   to match your system location (e.g., ``www.pythonanywhere.com`` or ``eu.pythonanywhere.com``).
+**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:: bash
+.. code-block:: python
 
-    export PYTHONANYWHERE_SITE="eu.pythonanywhere.com"
+    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}"
 
 PYTHONANYWHERE_DOMAIN
 ~~~~~~~~~~~~~~~~~~~~~~
@@ -70,37 +83,39 @@ PYTHONANYWHERE_DOMAIN
 
     export PYTHONANYWHERE_DOMAIN="example.com"
 
-PYTHONANYWHERE_CLIENT
-~~~~~~~~~~~~~~~~~~~~~~
+PYTHONANYWHERE_SITE
+~~~~~~~~~~~~~~~~~~~~
 
 **Required:** No
 
-**Default:** Not set (library identifies itself without client information)
+**Default:** ``www.pythonanywhere.com`` (or ``www.`` + ``PYTHONANYWHERE_DOMAIN`` if that is set)
 
-**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.
+**Description:** Override the hostname used for API requests. Useful for testing against different PythonAnywhere environments or when using EU servers.
 
-**Format:** ``client-name/version`` (e.g., ``pa/1.0.0``, ``mcp-server/0.5.0``)
+.. note::
+   When running on PythonAnywhere, this variable is automatically set in the environment
+   to match your system location (e.g., ``www.pythonanywhere.com`` or ``eu.pythonanywhere.com``).
 
-**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``
+**Usage:**
 
-**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)``
+.. code-block:: bash
 
-**Usage:**
+    export PYTHONANYWHERE_SITE="eu.pythonanywhere.com"
 
-.. code-block:: python
+PYTHONANYWHERE_USERNAME
+~~~~~~~~~~~~~~~~~~~~~~~~
 
-    import os
-    from importlib.metadata import version
+**Required:** No
 
-    # Set at application startup
-    CLI_VERSION = version("my-cli-package")
-    os.environ["PYTHONANYWHERE_CLIENT"] = f"my-cli/{CLI_VERSION}"
+**Default:** The current system username (via :func:`getpass.getuser`)
+
+**Description:** Override the PythonAnywhere username used for constructing API endpoints. When running outside of PythonAnywhere (e.g., from a local machine), the system username often won't match your PythonAnywhere username, so this variable lets you specify the correct one.
+
+**Usage:**
+
+.. code-block:: bash
+
+    export PYTHONANYWHERE_USERNAME="your_pa_username"
 
 See Also
 --------

pythonanywhere_core/base.py

@@ -1,3 +1,4 @@
+import getpass
 import os
 import platform
 from typing import Dict
@@ -20,6 +21,13 @@
 }
 
 
+def get_username() -> str:
+    """Returns PythonAnywhere username from ``PYTHONANYWHERE_USERNAME``
+    environment variable, falling back to :func:`getpass.getuser`."""
+
+    return os.environ.get("PYTHONANYWHERE_USERNAME", getpass.getuser())
+
+
 def get_api_endpoint(username: str, flavor: str) -> str:
     hostname = os.environ.get(
         "PYTHONANYWHERE_SITE",

pythonanywhere_core/files.py

@@ -1,11 +1,10 @@
-import getpass
 from pathlib import Path
 from typing import Tuple, Union
 from urllib.parse import urljoin
 
 from requests.models import Response
 
-from pythonanywhere_core.base import call_api, get_api_endpoint
+from pythonanywhere_core.base import call_api, get_api_endpoint, get_username
 from pythonanywhere_core.exceptions import PythonAnywhereApiException
 
 
@@ -39,7 +38,7 @@ class Files:
     """
 
 
-    base_url = get_api_endpoint(username=getpass.getuser(), flavor="files")
+    base_url = get_api_endpoint(username=get_username(), flavor="files")
     path_endpoint = urljoin(base_url, "path")
     sharing_endpoint = urljoin(base_url, "sharing/")
     tree_endpoint = urljoin(base_url, "tree/")

pythonanywhere_core/resources.py

@@ -1,6 +1,4 @@
-import getpass
-
-from pythonanywhere_core.base import call_api, get_api_endpoint
+from pythonanywhere_core.base import call_api, get_api_endpoint, get_username
 from pythonanywhere_core.exceptions import PythonAnywhereApiException
 
 
@@ -17,7 +15,7 @@ class CPU:
     """
 
     def __init__(self):
-        self.base_url = get_api_endpoint(username=getpass.getuser(), flavor="cpu")
+        self.base_url = get_api_endpoint(username=get_username(), flavor="cpu")
 
     def get_cpu_usage(self):
         """Get current CPU usage information.

pythonanywhere_core/schedule.py

@@ -1,9 +1,8 @@
-import getpass
 from typing import List, Optional
 
 from typing_extensions import Literal
 
-from pythonanywhere_core.base import call_api, get_api_endpoint
+from pythonanywhere_core.base import call_api, get_api_endpoint, get_username
 from pythonanywhere_core.exceptions import PythonAnywhereApiException
 
 
@@ -28,7 +27,7 @@ class Schedule:
         - :meth:`Schedule.update`: Update an existing task.
     """
 
-    base_url: str = get_api_endpoint(username=getpass.getuser(), flavor="schedule")
+    base_url: str = get_api_endpoint(username=get_username(), flavor="schedule")
 
     def create(self, params: dict) -> Optional[dict]:
         """Creates new scheduled task using `params`.

pythonanywhere_core/students.py

@@ -1,7 +1,6 @@
-import getpass
 from typing import Optional
 
-from pythonanywhere_core.base import call_api, get_api_endpoint
+from pythonanywhere_core.base import call_api, get_api_endpoint, get_username
 
 
 class StudentsAPI:
@@ -22,7 +21,7 @@ class StudentsAPI:
         - :meth:`StudentsAPI.delete`: Remove a student.
     """
 
-    base_url: str = get_api_endpoint(username=getpass.getuser(), flavor="students")
+    base_url: str = get_api_endpoint(username=get_username(), flavor="students")
 
     def get(self) -> Optional[dict]:
         """Returns list of PythonAnywhere students related with user's account.

pythonanywhere_core/webapp.py

@@ -1,14 +1,13 @@
 from __future__ import annotations
 
 import os
-import getpass
 from pathlib import Path
 from textwrap import dedent
 from typing import Any
 
 from dateutil.parser import parse
 
-from pythonanywhere_core.base import call_api, get_api_endpoint, PYTHON_VERSIONS
+from pythonanywhere_core.base import call_api, get_api_endpoint, get_username, PYTHON_VERSIONS
 from pythonanywhere_core.exceptions import SanityException, PythonAnywhereApiException, MissingCNAMEException
 
 
@@ -35,7 +34,7 @@ class Webapp:
     Class Methods:
         - :meth:`Webapp.list_webapps`: List all webapps for the current user.
     """
-    username = getpass.getuser()
+    username = get_username()
     files_url = get_api_endpoint(username=username, flavor="files")
     webapps_url = get_api_endpoint(username=username, flavor="webapps")
 

pythonanywhere_core/website.py

@@ -1,7 +1,4 @@
-import getpass
-
-
-from pythonanywhere_core.base import call_api, get_api_endpoint
+from pythonanywhere_core.base import call_api, get_api_endpoint, get_username
 from pythonanywhere_core.exceptions import DomainAlreadyExistsException, PythonAnywhereApiException
 
 
@@ -24,8 +21,8 @@ class Website:
     """
 
     def __init__(self) -> None:
-        self.websites_base_url = get_api_endpoint(username=getpass.getuser(), flavor="websites")
-        self.domains_base_url = get_api_endpoint(username=getpass.getuser(), flavor="domains")
+        self.websites_base_url = get_api_endpoint(username=get_username(), flavor="websites")
+        self.domains_base_url = get_api_endpoint(username=get_username(), flavor="domains")
 
 
     def create(self, domain_name: str, command: str) -> dict:

tests/test_base.py

@@ -1,3 +1,4 @@
+import getpass
 import platform
 from pythonanywhere_core import __version__
 
@@ -7,11 +8,24 @@
 from pythonanywhere_core.base import (
     call_api,
     get_api_endpoint,
+    get_username,
     helpful_token_error_message,
 )
 from pythonanywhere_core.exceptions import AuthenticationError, NoTokenError
 
 
+def test_get_username_returns_env_var_when_set(monkeypatch):
+    monkeypatch.setenv("PYTHONANYWHERE_USERNAME", "bill")
+
+    assert get_username() == "bill"
+
+
+def test_get_username_falls_back_to_getpass(monkeypatch):
+    monkeypatch.delenv("PYTHONANYWHERE_USERNAME", raising=False)
+
+    assert get_username() == getpass.getuser()
+
+
 def test_get_api_endpoint_defaults_to_pythonanywhere_dot_com_if_no_environment_variables():
     result = get_api_endpoint(username="bill", flavor="webapp")