smartsheet-python-sdk 3.5.5__tar.gz → 3.5.6__tar.gz

{smartsheet_python_sdk-3.5.5 → smartsheet_python_sdk-3.5.6}/.github/pull_request_template.md

@@ -35,6 +35,7 @@
 - [ ] I have performed a self-review of my own code
 - [ ] I have commented my code, particularly in hard-to-understand areas
 - [ ] I have made corresponding changes to the documentation
+- [ ] I have updated the relevant files in `docs-source/` (see [Documentation guidelines](../../../CONTRIBUTING.md#documentation))
 - [ ] My changes generate no new warnings
 - [ ] I have added tests that prove my fix is effective or that my feature works
 - [ ] New and existing unit tests pass locally with my changes

{smartsheet_python_sdk-3.5.5 → smartsheet_python_sdk-3.5.6}/.github/workflows/test-build.yaml

@@ -25,7 +25,7 @@ jobs:
         run: |
           pylint smartsheet
 
-  mock-api-test:
+  test:
     needs: lint
     runs-on: ubuntu-latest
     strategy:
@@ -53,9 +53,9 @@ jobs:
       - name: Setup Mock API
         run: |
           docker compose -f smartsheet-sdk-tests/docker-compose.yml up -d --wait
-      - name: Run mock API tests
+      - name: Run tests
         run: |
-          coverage run --source=smartsheet -m pytest tests/mock_api/
+          coverage run --source=smartsheet -m pytest
           coverage lcov
       - name: Coveralls Parallel
         uses: coverallsapp/github-action@master
@@ -67,7 +67,7 @@ jobs:
 
   build-packages-test:
     runs-on: ubuntu-latest
-    needs: [mock-api-test]
+    needs: [test]
     steps:
       - uses: actions/checkout@v4
       - name: Set up Python

{smartsheet_python_sdk-3.5.5 → smartsheet_python_sdk-3.5.6}/.gitignore

@@ -12,8 +12,7 @@ smartsheet*.egg-info/
 # Ignore SDK reference docs artifacts
 gh-pages/
 docs-source/_build/
-docs-source/modules.rst
-docs-source/smartsheet*.rst
+docs-source/_static/
 
 # Ignore the test cases log files
 *.log

{smartsheet_python_sdk-3.5.5 → smartsheet_python_sdk-3.5.6}/ADVANCED.md

@@ -4,9 +4,9 @@
 
 The following packages are required.
 
-* [setuptools](https://pypi.org/project/setuptools/)
-* [six](https://pypi.python.org/pypi/six)
-* [requests](https://pypi.python.org/pypi/requests)
+- [setuptools](https://pypi.org/project/setuptools/)
+- [six](https://pypi.python.org/pypi/six)
+- [requests](https://pypi.python.org/pypi/requests)
 
 To install this SDK manually:
 
@@ -55,9 +55,9 @@ To invoke the passthrough, your code can call one of the following four methods:
 
 `response = client.Passthrough.delete(endpoint)`
 
-* `endpoint`: The specific API endpoint you wish to invoke. The client object base URL gets prepended to the caller’s endpoint URL argument, so in the above `get` example, if endpoint is `'/sheets'` an HTTP GET is requested from the URL `https://api.smartsheet.com/2.0/sheets`
-* `payload`: The data to be passed through, can be either a dictionary or string.
-* `query_params`: An optional dictionary of query parameters.
+- `endpoint`: The specific API endpoint you wish to invoke. The client object base URL gets prepended to the caller’s endpoint URL argument, so in the above `get` example, if endpoint is `'/sheets'` an HTTP GET is requested from the URL `https://api.smartsheet.com/2.0/sheets`
+- `payload`: The data to be passed through, can be either a dictionary or string.
+- `query_params`: An optional dictionary of query parameters.
 
 All calls to passthrough methods return a JSON result. The `data` attribute contains the JSON result as a dictionary. For example, after a PUT operation the API's result message will be contained in `response.data['message']`. If you prefer raw JSON instead of a dictionary, you can use the `to_json()` method, for example `response.to_json()`.
 
@@ -78,17 +78,91 @@ response = client.Passthrough.post('/sheets', payload)
 
 ## Testing
 
-### Integration Tests
+### Mock API Tests
 
-1. Follow the [Integration test instructions](tests/integration/README.md)
-2. Run `pytest tests/integration`
+We use WireMock for API contract testing. This allows us to simulate Smartsheet API responses and run tests without relying on the live API.
+The [smartsheet-sdk-tests](https://github.com/smartsheet/smartsheet-sdk-tests) repo provides a standalone WireMock server with JSON mappings that simulate the Smartsheet API.
+Each mapping defines a request to match and a response to return.
+
+Common test cases use catch-all path patterns (e.g., /errors/500-response).
+
+We use two custom headers:
+
+- x-test-name: Used for exact mapping match, allowing different mock responses for the same HTTP method and endpoint.
+- x-request-id: A UUID generated for each request, used to verify request URLs and search for requests in WireMock admin history.
+
+To run the mock API tests:
+
+1. Clone the [smartsheet-sdk-tests](https://github.com/smartsheet/smartsheet-sdk-tests) repo and follow the instructions from the readme to start the mock server.
+
+2. `pytest tests/mock_api`
+
+To add new mock API tests:
+
+1. Add a WireMock Mapping (JSON) in the [smartsheet-sdk-tests](https://github.com/smartsheet/smartsheet-sdk-tests):
+
+```json
+{
+  "request": {
+    "urlPathTemplate": "/2.0/users/{userId}/plans",
+    "method": "GET",
+    "headers": {
+      "Authorization": {
+        "matches": "Bearer .*"
+      },
+      "x-test-name": {
+        "equalTo": "/users/list-user-plans/all-response-body-properties"
+      },
+      "x-request-id": {
+        "matches": ".*"
+      }
+    }
+  },
+  "response": {
+    "statusMessage": "OK",
+    "status": 200,
+    "jsonBody": {
+      "lastKey": "12345678901234569",
+      "data": [
+        {
+          "planId": 1234567890123456,
+          "seatType": "MEMBER",
+          "seatTypeLastChangedAt": "2025-01-01T00:00:00.123456789Z",
+          "provisionalExpirationDate": "2026-12-13T12:17:52.525696Z",
+          "isInternal": false
+        }
+      ]
+    },
+    "headers": {
+      "Content-Type": "application/json"
+    }
+  }
+}
+```
 
-### Mock API Tests
+<!-- markdownlint-disable MD029 -->
+2. Write a Test in the SDK:
+<!-- markdownlint-enable MD029 -->
 
-**NOTE:** the mock API tests will fail unless the mock server is running.
+- Always use x-test-name to target specific mock responses.
+- Use x-request-id for traceability in WireMock admin.
+- Keep mappings in the smartsheet-sdk-tests repository organized and descriptive
 
-1. Clone the [Smartsheet SDK tests](https://github.com/smartsheet-platform/smartsheet-sdk-tests) repo and follow the instructions from the README to start the mock server
-2. Run `pytest tests/mock_api`
+```python
+    def test_list_user_plans_all_response_properties():
+    request_id = uuid.uuid4().hex
+    client = get_mock_api_client(
+        "/users/list-user-plans/all-response-body-properties", request_id
+    )
+
+    response = client.Users.list_user_plans(
+        user_id=TEST_USER_ID,
+        last_key=TEST_LAST_KEY,
+        max_items=TEST_MAX_ITEMS
+    )
+
+    assert isinstance(response, TokenPaginatedResult)
+```
 
 ## HTTP Proxy
 

{smartsheet_python_sdk-3.5.5 → smartsheet_python_sdk-3.5.6}/CHANGELOG.md

@@ -5,6 +5,21 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
+## [3.5.6] - 2025-11-18
+
+### Removed
+
+- Remove integration tests from the sdk test suite
+
+### Added
+
+- Add support for code completion. Now code editors will be able to recognize and complete expressions like `smart.Users` and `smart.Users.list_users`.
+
+### Updated
+
+- Improved the generated reference documentation.
+- ADVANCED.md integration and mock api testing documentation
+
 ## [3.5.5] - 2025-11-11
 
 ### Fixed

{smartsheet_python_sdk-3.5.5 → smartsheet_python_sdk-3.5.6}/CONTRIBUTING.md

@@ -36,6 +36,27 @@ Changes that are cosmetic in nature and do not add anything substantial to the s
 
 - Write unit tests for new features and bug fixes. All tests should pass before submitting a PR.
 
+## Documentation
+
+- If your changes affect the public API, you must update the corresponding Sphinx documentation files in `docs-source/`:
+  - **API Resources** (modules in `smartsheet/`): Update `docs-source/smartsheet_api.rst`
+  - **Models** (classes in `smartsheet/models/`): Update `docs-source/smartsheet_models.rst`
+  - **Enums** (enums in `smartsheet/models/enums/`): Update `docs-source/smartsheet_enums.rst`
+  - **Types** (type definitions in `smartsheet/types.py`): Update `docs-source/smartsheet_types.rst`
+  - **Exceptions** (exceptions in `smartsheet/exceptions.py`): Update `docs-source/smartsheet_exceptions.rst`
+  - **General documentation** (installation, quickstart, examples): Update `docs-source/index.rst`
+
+- The documentation uses Sphinx with autodoc to generate API documentation from docstrings. Ensure your docstrings follow Google-style format as configured in `docs-source/conf.py`.
+
+- After making changes to `docs-source/`, you can build the documentation locally to verify your changes:
+
+  ```bash
+  cd docs-source
+  make html
+  ```
+
+- The built documentation will be in `docs-source/_build/html/`. Open `index.html` in a browser to review your changes.
+
 ## Running Tests
 
 - To run the test suite, use the following command:

{smartsheet_python_sdk-3.5.5 → smartsheet_python_sdk-3.5.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: smartsheet-python-sdk
-Version: 3.5.5
+Version: 3.5.6
 Summary: Library that uses Python to connect to Smartsheet services (using API 2.0).
 License-Expression: Apache-2.0
 Classifier: Development Status :: 5 - Production/Stable

smartsheet_python_sdk-3.5.6/docs-source/index.rst

@@ -0,0 +1,141 @@
+.. toctree::
+    :maxdepth: 2
+    :hidden:
+
+    smartsheet_api
+    smartsheet_models
+    smartsheet_enums
+    smartsheet_types
+    smartsheet_exceptions
+
+Smartsheet Python SDK Documentation
+===================================
+
+* Release v\ |version|
+
+* `GitHub repository <https://github.com/smartsheet/smartsheet-python-sdk>`_
+
+* `Changelog <https://github.com/smartsheet/smartsheet-python-sdk/blob/mainline/CHANGELOG.md>`_
+
+Installation
+------------
+
+To install using pip::
+
+    pip install smartsheet-python-sdk
+
+Quickstart
+----------
+
+Getting started is easy:
+
+#.  Get your Smartsheet API access token. Find out more about getting
+    `direct API access <https://developers.smartsheet.com/api/smartsheet/guides/getting-started>`_ in the Smartsheet API Documentation.
+    You can generate an access token in Smartsheet UI under Account > Personal Settings > API Access.
+
+#.  Install the Smartsheet Python SDK from the `Python Package Index <http://pypi.python.org/pypi/smartsheet-python-sdk>`_,
+    or by using "pip install smartsheet-python-sdk".
+
+#.  Import the smartsheet module and start using the SDK (see examples below).
+
+Authentication
+--------------
+
+You can authenticate with the Smartsheet API in two ways:
+
+**Option 1: Environment Variable (Recommended)**
+
+Set the **SMARTSHEET_ACCESS_TOKEN** environment variable::
+
+    export SMARTSHEET_ACCESS_TOKEN="your_token_here"
+
+Then create the client without parameters::
+
+    import smartsheet
+    smart = smartsheet.Smartsheet()
+
+**Option 2: Direct Token**
+
+Pass the access token directly to the Smartsheet constructor::
+
+    import smartsheet
+    smart = smartsheet.Smartsheet(access_token='your_token_here')
+
+Example Usage
+-------------
+
+Basic Example
+~~~~~~~~~~~~~
+
+The following example shows how to create a Smartsheet client and perform some basic operations::
+
+    import smartsheet
+
+    # Create a Smartsheet client (uses SMARTSHEET_ACCESS_TOKEN environment variable)
+    smart = smartsheet.Smartsheet()
+
+    # Or create with explicit token:
+    # smart = smartsheet.Smartsheet(access_token='your_token_here')
+
+    # List all sheets
+    response = smart.Sheets.list_sheets()
+
+    # Get the ID of the first sheet
+    sheet_id = response.data[0].id
+
+    # Load the sheet by using its ID
+    sheet = smart.Sheets.get_sheet(sheet_id)
+
+    # Print information about the sheet
+    print(f"The sheet {sheet.name} has {sheet.total_row_count} rows")
+
+Working with Rows
+~~~~~~~~~~~~~~~~~
+
+Add rows to a sheet::
+
+    import smartsheet
+
+    smart = smartsheet.Smartsheet()
+
+    # Build new row
+    new_row = smart.models.Row()
+    new_row.to_top = True
+    new_row.cells.append({
+        'column_id': 123456789,
+        'value': 'New Value'
+    })
+
+    # Add rows to sheet
+    response = smart.Sheets.add_rows(sheet_id, [new_row])
+
+Working with Cells
+~~~~~~~~~~~~~~~~~~
+
+Update cell values::
+
+    import smartsheet
+
+    smart = smartsheet.Smartsheet()
+
+    # Build new cell value
+    new_cell = smart.models.Cell()
+    new_cell.column_id = 123456789
+    new_cell.value = 'Updated Value'
+    new_cell.strict = False
+
+    # Build the row to update
+    new_row = smart.models.Row()
+    new_row.id = 987654321
+    new_row.cells.append(new_cell)
+
+    # Update rows
+    response = smart.Sheets.update_rows(sheet_id, [new_row])
+
+Additional Resources
+--------------------
+
+For more examples and detailed documentation:
+
+* `Smartsheet Python SDK sample project <https://github.com/smartsheet-samples/python-read-write-sheet>`_
+* `Smartsheet API Documentation <https://developers.smartsheet.com/api/smartsheet/introduction>`_ for dozens of Python SDK usage examples

smartsheet_python_sdk-3.5.6/docs-source/smartsheet_api.rst

@@ -0,0 +1,186 @@
+API Resources
+==================
+
+Attachments
+-----------------------------
+
+.. automodule:: smartsheet.attachments
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Cells
+-----------------------
+
+.. automodule:: smartsheet.cells
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Contacts
+--------------------------
+
+.. automodule:: smartsheet.contacts
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Discussions
+-----------------------------
+
+.. automodule:: smartsheet.discussions
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Events
+------------------------
+
+.. automodule:: smartsheet.events
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Favorites
+---------------------------
+
+.. automodule:: smartsheet.favorites
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Folders
+-------------------------
+
+.. automodule:: smartsheet.folders
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Groups
+------------------------
+
+.. automodule:: smartsheet.groups
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Home
+----------------------
+
+.. automodule:: smartsheet.home
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Images
+------------------------
+
+.. automodule:: smartsheet.images
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Passthrough Mode
+-----------------------------
+
+.. automodule:: smartsheet.passthrough
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Reports
+-------------------------
+
+.. automodule:: smartsheet.reports
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Search
+------------------------
+
+.. automodule:: smartsheet.search
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Server
+------------------------
+
+.. automodule:: smartsheet.server
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Sharing
+-------------------------
+
+.. automodule:: smartsheet.sharing
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Sheets
+------------------------
+
+.. automodule:: smartsheet.sheets
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Dashboards (sights)
+------------------------
+
+.. automodule:: smartsheet.sights
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Smartsheet
+----------------------------
+
+.. automodule:: smartsheet.smartsheet
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Templates
+---------------------------
+
+.. automodule:: smartsheet.templates
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Token
+-----------------------
+
+.. automodule:: smartsheet.token
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Users
+-----------------------
+
+.. automodule:: smartsheet.users
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Webhooks
+--------------------------
+
+.. automodule:: smartsheet.webhooks
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Workspaces
+----------------------------
+
+.. automodule:: smartsheet.workspaces
+   :members:
+   :undoc-members:
+   :show-inheritance: