get_client#

teamworksams.utils.get_client(url: str, username: str | None = None, password: str | None = None, cache: bool = True, interactive_mode: bool = False) → AMSClient[source]#

Create or retrieve an authenticated AMSClient instance.

Creates a new AMSClient instance with the provided credentials or reuses an existing authenticated client if caching is enabled. The client is used for all AMS API interactions, handling authentication and session management. Provides interactive feedback on login success if enabled. This function is typically called internally by other public-facing functions but can be used directly to initialize a client. Use this function for custom API calls or batch operations requiring an authenticated client.

Parameters:

  • url (str) – The AMS instance URL (e.g., ‘https://example.smartabase.com/site’). Must include a valid site name (e.g., ‘/site’).

  • username (Optional[str]) – Username for authentication. If None, uses AMS_USERNAME or keyring credentials. Defaults to None.

  • password (Optional[str]) – Password for authentication. If None, uses AMS_PASSWORD or keyring credentials. Defaults to None.

  • cache (bool) – Reuse an existing authenticated client if available. Set to False for independent sessions (e.g., parallel scripts). Defaults to True.

  • interactive_mode (bool) – Print status messages (e.g., login success). Useful for interactive workflows. Defaults to False.

Returns:

An authenticated client ready for API interactions.

Return type:

AMSClient

Raises:

AMSError – If the URL is invalid, credentials are missing, or authentication fails.

Examples

>>> from teamworksams import get_client
>>> client = get_client(
...     url="https://example.smartabase.com/site",
...     username = "user",
...     password = "pass",
...     cache = True,
...     interactive_mode = True
... )
✔ Successfully logged user into https://example.smartabase.com/site.
>>> print(client.authenticated)
True

Additional Notes#

  • The cache parameter is recommended for workflows with multiple API calls (e.g., fetching users then groups), as it reuses a single AMSClient() instance, reducing authentication overhead.

  • Set interactive_mode=True for real-time feedback in interactive environments like Jupyter notebooks, showing messages like “Successfully logged in.”

  • If credentials are not provided via username and password, the function falls back to AMS_USERNAME, AMS_PASSWORD, or keyring credentials (service name ‘smartabasepy’).

See Also#