{"id":3807,"library":"smartsheet-python-sdk","title":"Smartsheet Python SDK","description":"The Smartsheet Python SDK is a library for connecting Python applications to Smartsheet services using API 2.0. It provides a programmatic interface to manage sheets, rows, columns, users, and other Smartsheet resources. The library simplifies interaction with the Smartsheet API, handling authentication, request serialization, and response deserialization. It is actively maintained, with the current version being 3.7.2, and typically sees updates for API endpoint changes and new features.","status":"active","version":"3.7.2","language":"en","source_language":"en","source_url":"https://github.com/smartsheet/smartsheet-python-sdk","tags":["smartsheet","api","cloud","work management","sheets","data management"],"install":[{"cmd":"pip install smartsheet-python-sdk","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"note":"The primary client class for interacting with the Smartsheet API.","symbol":"Smartsheet","correct":"import smartsheet\nsmart = smartsheet.Smartsheet()"},{"note":"Model classes like Sheet, Column, Row, etc., are accessed through `smartsheet.Smartsheet.models`.","wrong":"import smartsheet.models.Sheet","symbol":"models","correct":"import smartsheet\nsheet_obj = smartsheet.Smartsheet.models.Sheet()"}],"quickstart":{"code":"import smartsheet\nimport os\n\n# Ensure SMARTSHEET_ACCESS_TOKEN is set in your environment variables\n# You can generate an access token in Smartsheet UI under Account > Personal Settings > API Access.\naccess_token = os.environ.get('SMARTSHEET_ACCESS_TOKEN', '')\n\nif not access_token:\n    print(\"Error: SMARTSHEET_ACCESS_TOKEN environment variable not set.\")\n    print(\"Please generate an access token from Smartsheet and set it.\")\nelse:\n    try:\n        # Create a Smartsheet client\n        smart = smartsheet.Smartsheet(access_token)\n\n        # Optional: Enable exceptions for API errors instead of returning Error objects\n        smart.errors_as_exceptions(True)\n\n        # List all sheets the authenticated user has access to\n        response = smart.Sheets.list_sheets()\n\n        if response.data:\n            first_sheet = response.data[0]\n            print(f\"Found sheet: {first_sheet.name} (ID: {first_sheet.id})\")\n            \n            # Get a specific sheet by ID\n            sheet = smart.Sheets.get_sheet(first_sheet.id)\n            print(f\"The sheet '{sheet.name}' has {sheet.total_row_count} rows.\")\n        else:\n            print(\"No sheets found for this user.\")\n\n    except smartsheet.exceptions.SmartsheetException as e:\n        print(f\"An error occurred: {e}\")\n    except Exception as e:\n        print(f\"An unexpected error occurred: {e}\")","lang":"python","description":"This quickstart initializes the Smartsheet client using an API access token from environment variables. It then lists the user's sheets and retrieves details for the first one found. It also demonstrates how to enable exceptions for API errors."},"warnings":[{"fix":"Generate an API access token from your Smartsheet personal settings and set it as the `SMARTSHEET_ACCESS_TOKEN` environment variable. For OAuth, follow the official Smartsheet API documentation.","message":"Authentication primarily relies on the `SMARTSHEET_ACCESS_TOKEN` environment variable for direct API access. For application development, OAuth 2.0 is supported but requires more setup. Misconfiguring or not setting the access token is a common source of 'Unauthorized' errors.","severity":"gotcha","affected_versions":"All"},{"fix":"Call `smartsheet_client.errors_as_exceptions(True)` after initializing your client to make the SDK raise `smartsheet.exceptions.SmartsheetException` instances for API errors, allowing for standard Python exception handling.","message":"By default, the SDK returns `Error` objects instead of raising exceptions for API errors. This can lead to silent failures if not handled correctly. Ensure you check the return type of API calls.","severity":"gotcha","affected_versions":"All"},{"fix":"Always keep the `smartsheet-python-sdk` up-to-date (`pip install --upgrade smartsheet-python-sdk`). Consult the `CHANGELOG.md` in the GitHub repository for breaking changes and new endpoint support.","message":"Smartsheet API endpoints are periodically updated or deprecated. Older SDK versions might not support new endpoints or parameters, leading to unexpected behavior or `AttributeError` if attempting to call non-existent methods.","severity":"breaking","affected_versions":"<3.x for some specific endpoints/parameters; ongoing for new API changes"},{"fix":"When calling list methods, review the documentation for pagination parameters. Use `include_all=True` for convenience, or loop through `page` and `page_size` for fine-grained control.","message":"Many list operations (e.g., listing sheets, rows, contacts) are paginated by default. If you need all results, you must either explicitly pass `include_all=True` to the list method or implement manual pagination using `page` and `page_size` parameters.","severity":"gotcha","affected_versions":"All"},{"fix":"When creating or manipulating objects, ensure you're using the correct methods on the client's service objects (e.g., `smart.Sheets.create_sheet()`) or correctly instantiating model classes with `smartsheet.Smartsheet.models.Sheet({'name': 'New Sheet'})` before passing them to service methods.","message":"Accessing model creation methods (e.g., for Sheet, Column, Row objects) directly from `smartsheet.Smartsheet.models.ClassName` instead of using the methods on the instantiated service objects (e.g., `smart.Sheets.add_sheet()`) or correctly creating model instances, can lead to `AttributeError`.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}