servicepytan.utils module

Utility Functions for Supporting Other Modules

servicepytan.utils.request_json(url, options={}, payload={}, conn=None, request_type='GET', json_payload={})[source]

Makes the request to the API and returns JSON.

Sends HTTP requests to the ServiceTitan API with proper authentication headers and handles various request types including GET, POST, PUT, PATCH, and DELETE.

Parameters:

url – The complete URL for the API request
options – Dictionary of query parameters to add to the URL for filtering
payload – Dictionary containing form data for the request body
conn – Dictionary containing the credential configuration
request_type – HTTP method type (“GET”, “POST”, “PUT”, “PATCH”, “DEL”)
json_payload – Dictionary containing JSON data for the request body

Returns:

JSON response from the API

Return type:

dict

Raises:

requests.HTTPError – If the API request fails

Examples

>>> response = request_json(
...     "https://api.servicetitan.io/jpm/v2/tenant/123/jobs",
...     options={"pageSize": 100},
...     conn=connection_config
... )

servicepytan.utils.check_default_options(options)[source]

Add sensible defaults to options when not defined.

Ensures that API request options have reasonable defaults to prevent issues with pagination and data retrieval.

Parameters:: options – Dictionary of request options/parameters
Returns:: Options dictionary with defaults applied
Return type:: dict

Examples

>>> options = check_default_options({})
>>> # Returns: {"pageSize": 100}
>>> options = check_default_options({"pageSize": 50})
>>> # Returns: {"pageSize": 50} (unchanged)

servicepytan.utils.endpoint_url(folder, endpoint, id='', modifier='', conn=None, tenant_id='')[source]

Constructs API request URL based on key parameters.

Builds the complete ServiceTitan API URL using the standard URL structure and allows for various endpoint configurations including specific IDs and modifiers.

Parameters:

folder – The API endpoint category/folder (e.g., “jpm”, “sales”, “inventory”)
endpoint – The specific endpoint within the folder (e.g., “jobs”, “estimates”)
id – Optional specific record ID to append to the URL
modifier – Optional additional path segment for specialized endpoints
conn – Dictionary containing the credential configuration
tenant_id – Optional manual override for the tenant ID

Returns:

Complete API URL ready for requests

Return type:

str

Raises:

KeyError – If required connection information is missing

Examples

>>> url = endpoint_url("jpm", "jobs", conn=conn)
>>> # Returns: "https://api.servicetitan.io/jpm/v2/tenant/12345/jobs"

>>> url = endpoint_url("jpm", "jobs", id="67890", modifier="notes", conn=conn)
>>> # Returns: "https://api.servicetitan.io/jpm/v2/tenant/12345/jobs/67890/notes"

servicepytan.utils.create_credential_file(name='servicepytan_config.json')[source]

Creates and saves an unfilled configuration file template.

Generates a JSON configuration file with empty credential fields that can be filled in with actual ServiceTitan API credentials.

Parameters:: name – Filename for the configuration file
Returns:: Path to the created configuration file
Return type:: str

Examples

>>> filepath = create_credential_file("my_config.json")
>>> # Creates a file with empty credential template

servicepytan.utils.get_timezone_by_file(conn=None)[source]

Retrieves timezone from the connection configuration.

Extracts the timezone setting from the connection configuration object, defaulting to “UTC” if no timezone is specified.

Parameters:: conn – Dictionary containing the credential configuration
Returns:: Timezone string (e.g., “America/New_York”, “UTC”)
Return type:: str

Examples

>>> tz = get_timezone_by_file(conn)
>>> # Returns: "America/New_York" or "UTC" if not specified

servicepytan.utils.sleep_with_countdown(sleep_time)[source]

Sleeps for a given amount of time with a countdown display.

Provides a visual countdown timer during sleep periods, typically used when handling rate limiting or waiting between API requests.

Parameters:: sleep_time – Number of seconds to sleep

Examples

>>> sleep_with_countdown(30)
>>> # Displays: "Trying again in 30 seconds...", "29 seconds...", etc.

servicepytan.utils.request_json_with_retry(url, options={}, payload='', conn=None, request_type='GET', json_payload='')[source]

Makes the request to the API and returns JSON with automatic retry for rate limits.

Enhanced version of request_json that automatically handles rate limiting by detecting 429 status codes and retrying after the specified wait time.

Parameters:

url – The complete URL for the API request
options – Dictionary of query parameters to add to the URL for filtering
payload – Dictionary containing form data for the request body
conn – Dictionary containing the credential configuration
request_type – HTTP method type (“GET”, “POST”, “PUT”, “PATCH”, “DEL”)
json_payload – Dictionary containing JSON data for the request body

Returns:

JSON response from the API

Return type:

dict

Raises:

requests.HTTPError – If the API request fails (non-rate-limit errors)

Examples

>>> response = request_json_with_retry(
...     "https://api.servicetitan.io/jpm/v2/tenant/123/jobs",
...     options={"pageSize": 100},
...     conn=connection_config
... )
>>> # Automatically retries if rate limited

servicepytan.utils.request_contents(url, options={}, conn=None)[source]

Fetches the contents of a URL with optional query parameters.

Parameters:

url – The complete URL for the API request
options – Dictionary of query parameters to add to the URL
conn – Dictionary containing the credential configuration

Returns:

JSON response from the API

Return type:

dict

Raises:

requests.HTTPError – If the API request fails