Install & Compatibility
Where this runs
tested against v0.7.17 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.777s · 27.7MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 3.6s · import 0.721s · 28MB
25MB installed
● package 25MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Client
✓ from pysnow import Client
✗ import pysnow.Client
The primary class for interacting with the ServiceNow API.
OAuthClient
✓ from pysnow import OAuthClient
Used for OAuth2-based authentication with ServiceNow instances.
QueryBuilder
✓ from pysnow import QueryBuilder
A utility for constructing complex ServiceNow queries with a fluent interface.
This quickstart demonstrates how to initialize the `pysnow` client, create a resource for the incident table, and fetch the first record matching a specific query. It includes basic error handling for common `pysnow` exceptions.
import os
import pysnow
# Configure ServiceNow instance details from environment variables or provide directly
instance = os.environ.get('SNOW_INSTANCE', 'your_instance_name') # e.g., 'dev12345'
user = os.environ.get('SNOW_USER', 'your_username')
password = os.environ.get('SNOW_PASSWORD', 'your_password')
if not all([instance, user, password]):
print("Please set SNOW_INSTANCE, SNOW_USER, and SNOW_PASSWORD environment variables or provide them directly.")
else:
try:
# Create a client object
client = pysnow.Client(instance=instance, user=user, password=password)
# Define a resource, e.g., the incident table API
incident = client.resource(api_path='/table/incident')
# Query for incidents with state 1 (e.g., New) and print the first one
response = incident.get(query={'state': 1})
first_incident = response.first_or_none()
if first_incident:
print(f"Found incident: {first_incident['number']} - {first_incident['short_description']}")
else:
print("No incidents found with state 1.")
except pysnow.exceptions.InvalidUsage as e:
print(f"Client initialization error: {e}")
except pysnow.exceptions.NoResults:
print("No results returned for the query (this is expected if raise_on_empty is True and no results).")
except pysnow.exceptions.ResponseError as e:
print(f"ServiceNow API error: {e.error['message']} - {e.error['detail']}")
except Exception as e:
print(f"An unexpected error occurred: {e}")
Errors
Common errors & fixes
pysnow.exceptions.InvalidUsage: You must supply either username and password or a session object
The `pysnow.Client` constructor was called without both `user` and `password` or a valid `session` object.
fixEnsure `Client(user='...', password='...')` or `Client(session=requests.Session())` is used. Do not provide both username/password and a session object.
pysnow.exceptions.InvalidUsage: Arguments 'instance' and 'host' are mutually exclusive, you cannot use both.
Both the `instance` and `host` parameters were provided to the `pysnow.Client` constructor.
fixSpecify either the ServiceNow `instance` name (e.g., 'dev12345') or the full `host` URL (e.g., 'https://dev12345.service-now.com'), but not both.
pysnow.exceptions.ResponseError: {'message': 'Unauthorized', 'detail': 'Required to authenticate with login information'}
Authentication credentials (username/password or OAuth token) are incorrect, missing, or the ServiceNow instance's IP whitelist is blocking the connection.
fixDouble-check your `user` and `password`. If using SSO, consider `pysnow.OAuthClient` or generate an OAuth token. Verify if your server's IP needs to be whitelisted in ServiceNow.
pysnow.exceptions.QueryTypeError: 'SomeField' is of an unexpected type
An incorrect data type was passed to a `QueryBuilder` method (e.g., passing a string where an integer or datetime is expected for `between`, `less_than`, `greater_than`).
fixReview the `QueryBuilder` method documentation and ensure the correct Python data types (e.g., `int`, `datetime`) are used for query criteria.
Parameters on Resource.get() persist across requests leading to unexpected filtering.
Prior to 0.7.6, parameters set on `Resource.get()` could persist for subsequent requests on the same `Resource` object, causing unintended filtering or behavior.
fixThis was largely addressed in `pysnow` versions post-0.7.6. For older versions or persistent issues, create a new `Resource` object for each distinct query or explicitly clear parameters if your version allows it. Always re-evaluate query parameters per request.
Upgrade
Version history
0.7.17latest on PyPI · released Mar 6, 2021
Audit
Dependencies
requestsrequiredCore HTTP client for making API requests.
python-magicoptionalOptional dependency for detecting content-type during file uploads.