{"id":8521,"library":"pysnow","title":"pysnow: ServiceNow HTTP Client Library","description":"pysnow is a Python library for interacting with the ServiceNow REST API, emphasizing ease of use, simple code, and elegant syntax. It supports both Python 2 and 3. As of version 0.7.17, the library is in a stable maintenance mode, meaning essential fixes are applied, but new feature development has shifted to `aiosnow`, an asynchronous counterpart.","status":"maintenance","version":"0.7.17","language":"en","source_language":"en","source_url":"https://github.com/rbw/pysnow","tags":["ServiceNow","REST API","client","ITSM","automation"],"install":[{"cmd":"pip install pysnow","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core HTTP client for making API requests.","package":"requests","optional":false},{"reason":"Optional dependency for detecting content-type during file uploads.","package":"python-magic","optional":true}],"imports":[{"note":"The primary class for interacting with the ServiceNow API.","wrong":"import pysnow.Client","symbol":"Client","correct":"from pysnow import Client"},{"note":"Used for OAuth2-based authentication with ServiceNow instances.","symbol":"OAuthClient","correct":"from pysnow import OAuthClient"},{"note":"A utility for constructing complex ServiceNow queries with a fluent interface.","symbol":"QueryBuilder","correct":"from pysnow import QueryBuilder"}],"quickstart":{"code":"import os\nimport pysnow\n\n# Configure ServiceNow instance details from environment variables or provide directly\ninstance = os.environ.get('SNOW_INSTANCE', 'your_instance_name') # e.g., 'dev12345'\nuser = os.environ.get('SNOW_USER', 'your_username')\npassword = os.environ.get('SNOW_PASSWORD', 'your_password')\n\nif not all([instance, user, password]):\n    print(\"Please set SNOW_INSTANCE, SNOW_USER, and SNOW_PASSWORD environment variables or provide them directly.\")\nelse:\n    try:\n        # Create a client object\n        client = pysnow.Client(instance=instance, user=user, password=password)\n\n        # Define a resource, e.g., the incident table API\n        incident = client.resource(api_path='/table/incident')\n\n        # Query for incidents with state 1 (e.g., New) and print the first one\n        response = incident.get(query={'state': 1})\n        first_incident = response.first_or_none()\n\n        if first_incident:\n            print(f\"Found incident: {first_incident['number']} - {first_incident['short_description']}\")\n        else:\n            print(\"No incidents found with state 1.\")\n\n    except pysnow.exceptions.InvalidUsage as e:\n        print(f\"Client initialization error: {e}\")\n    except pysnow.exceptions.NoResults:\n        print(\"No results returned for the query (this is expected if raise_on_empty is True and no results).\")\n    except pysnow.exceptions.ResponseError as e:\n        print(f\"ServiceNow API error: {e.error['message']} - {e.error['detail']}\")\n    except Exception as e:\n        print(f\"An unexpected error occurred: {e}\")","lang":"python","description":"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."},"warnings":[{"fix":"Rely on the default behavior, or catch `pysnow.exceptions.NoResults` explicitly instead of setting `raise_on_empty=False`.","message":"The `raise_on_empty` argument in `pysnow.Client` is deprecated and will be removed in future releases. By default, `pysnow` raises `NoResults` on 404 (no matching records).","severity":"deprecated","affected_versions":">=0.7.17"},{"fix":"Pass a pre-configured `requests.Session` object to the `session` parameter of `pysnow.Client` for global request settings.","message":"The `request_params` argument in `pysnow.Client` is deprecated. Global request parameters should be handled by configuring the underlying `requests.Session` object directly and passing it to the client.","severity":"deprecated","affected_versions":">=0.7.17"},{"fix":"Provide either `instance` OR `host`, not both. Provide either `user`/`password` OR a `session` object, not both.","message":"When initializing `pysnow.Client`, the `instance` and `host` arguments are mutually exclusive. Providing both will raise an `InvalidUsage` exception. Similarly, providing both `user`/`password` and a `session` object is not allowed.","severity":"gotcha","affected_versions":"All"},{"fix":"Ensure exception handling for `UnexpectedResponseFormat` is in place if your code interacts with potentially malformed ServiceNow responses, especially after upgrading to 0.7.13 or newer from an intermediate version.","message":"The `UnexpectedResponseFormat` exception was re-added in version 0.7.13 for backward compatibility after being removed. Code that relied on its absence might need adjustments if upgrading from versions between its removal and re-addition.","severity":"breaking","affected_versions":"0.7.x"},{"fix":"Pass `stream=True` to `resource.get()` for large datasets: `response = resource.get(query=your_query, stream=True)`.","message":"For fetching large amounts of data, using `incident.get(stream=True)` returns a memory-friendly generator instead of buffering the entire result, which can prevent memory exhaustion. Iterating directly over `response.all()` is generally efficient.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure `Client(user='...', password='...')` or `Client(session=requests.Session())` is used. Do not provide both username/password and a session object.","cause":"The `pysnow.Client` constructor was called without both `user` and `password` or a valid `session` object.","error":"pysnow.exceptions.InvalidUsage: You must supply either username and password or a session object"},{"fix":"Specify either the ServiceNow `instance` name (e.g., 'dev12345') or the full `host` URL (e.g., 'https://dev12345.service-now.com'), but not both.","cause":"Both the `instance` and `host` parameters were provided to the `pysnow.Client` constructor.","error":"pysnow.exceptions.InvalidUsage: Arguments 'instance' and 'host' are mutually exclusive, you cannot use both."},{"fix":"Double-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.","cause":"Authentication credentials (username/password or OAuth token) are incorrect, missing, or the ServiceNow instance's IP whitelist is blocking the connection.","error":"pysnow.exceptions.ResponseError: {'message': 'Unauthorized', 'detail': 'Required to authenticate with login information'}"},{"fix":"Review the `QueryBuilder` method documentation and ensure the correct Python data types (e.g., `int`, `datetime`) are used for query criteria.","cause":"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`).","error":"pysnow.exceptions.QueryTypeError: 'SomeField' is of an unexpected type"},{"fix":"This 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.","cause":"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.","error":"Parameters on Resource.get() persist across requests leading to unexpected filtering."}]}