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

{smartsheet_python_sdk-3.5.5 → smartsheet_python_sdk-3.6.0}/.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.6.0}/.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.6.0}/.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.6.0/.roo/roomotes.yml

@@ -0,0 +1,25 @@
+version: "1.0"
+
+commands:
+    - name: Pull latest changes
+      run: git pull
+      timeout: 60
+      execution_phase: task_run
+    - name: Install dependencies
+      run: pip install -e .[test,develop]
+      timeout: 60
+      execution_phase: task_run
+
+github_events:
+    - event: issues.opened
+      action:
+          name: github.issue.fix
+    - event: issue_comment.created
+      action:
+          name: github.issue.comment.respond
+    - event: pull_request.opened
+      action:
+          name: github.pr.review
+    - event: pull_request_review_comment.created
+      action:
+          name: github.pr.comment.respond

{smartsheet_python_sdk-3.5.5 → smartsheet_python_sdk-3.6.0}/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.6.0}/CHANGELOG.md

@@ -5,6 +5,30 @@ 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).
 
+## [x.x.x] - Unreleased
+
+## [3.6.0] - 2025-12-04
+
+### Added
+
+- Support for POST /2.0/users/{userId}/reactivate endpoint
+- Support for POST /2.0/users/{userId}/deactivate endpoint
+
+## [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.6.0}/CONTRIBUTING.md

@@ -1,5 +1,11 @@
 # Contributing to Smartsheet Python SDK
 
+## Issue First Approach
+
+**All contributions to the Smartsheet Python SDK must begin with a GitHub Issue.** This includes bug fixes, new features, and documentation improvements.
+
+For detailed guidance on creating effective issues that work well with both human reviewers and AI-powered Cloud Agents, see our [Issue First documentation](ISSUE-FIRST.md).
+
 ## Did you find a bug?
 
 - **Send all security related bugs to our maintainer email, <sdk-python@smartsheet.com>**.
@@ -10,19 +16,23 @@
 
 ## Did you write a patch that fixes a bug?
 
-- Open a new GitHub pull request with the patch.
+- **First, ensure there is a GitHub issue** describing the bug (see above).
+
+- Open a new GitHub pull request with the patch, referencing the issue number.
 
-- Ensure the PR description clearly describes the problem and solution. Include the relevant issue number if applicable.
+- Ensure the PR description clearly describes the problem and solution. Include the relevant issue number.
 
 - A maintainer should review your PR within the next few days. If the PR has been dormant for more than a week, consider sending an email to <sdk-python@smartsheet.com>
 
 ## Did you fix whitespace, format code, or make a purely cosmetic patch?
 
-Changes that are cosmetic in nature and do not add anything substantial to the stability, functionality, or testability may take longer to review, but are still welcome.
+Changes that are cosmetic in nature and do not add anything substantial to the stability, functionality, or testability may take longer to review, but are still welcome. Please create an issue first describing the cosmetic changes you'd like to make.
 
 ## Do you intend to add a new feature or change an existing one?
 
-- Suggest your change as an issue with the label #enhancement. Make sure that your new feature description outlines why this would be helpful for users, and how difficult a change it would be to make.
+- **First, create an issue** with the label #enhancement. Make sure that your new feature description outlines why this would be helpful for users, and how difficult a change it would be to make.
+
+- Once the feature is discussed and approved in the issue, you can submit a pull request implementing it.
 
 ## Code Style and Quality
 
@@ -36,6 +46,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.6.0/ISSUE-FIRST.md

@@ -0,0 +1,306 @@
+# Issue First Approach for Smartsheet Python SDK
+
+## What is "Issue First"?
+
+The "Issue First" approach is a collaborative development methodology where **all contributions to the Smartsheet Python SDK must begin with a GitHub Issue** before any code changes are made. This means that whether you're fixing a bug, adding a new feature, or improving documentation, you first create or identify an existing issue that describes what needs to be done.
+
+## Why Issue First Matters for Cloud Agents
+
+With the integration of Roo Code Cloud Agents in the Smartsheet Python SDK repository, the Issue First approach becomes even more critical. Here's why:
+
+### 1. **Clear Communication with AI Agents**
+
+Cloud Agents are AI-powered assistants that can understand natural language and translate it into code changes. A well-written GitHub Issue serves as a **high-quality prompt** that gives the Cloud Agent all the context it needs to:
+
+- Understand the problem or feature request
+- Identify which parts of the Smartsheet Python SDK codebase need to be modified
+- Generate appropriate Python code that follows the SDK's patterns and conventions
+- Create comprehensive tests and documentation
+
+### 2. **Structured Problem Definition**
+
+Issues provide a structured format that helps both humans and AI agents understand:
+
+- **What** needs to change (the goal)
+- **Why** it needs to change (the motivation)
+- **How** it should work (expected behavior)
+- **Context** about the Smartsheet Python SDK codebase
+
+### 3. **Trackable Progress**
+
+Issues create a clear audit trail of:
+
+- What work was requested
+- Who is working on it (human or Cloud Agent)
+- The discussion and decisions made
+- The resulting code changes via linked Pull Requests
+
+### 4. **Quality Control**
+
+By requiring an issue first, we ensure that:
+
+- The proposed change aligns with the SDK's goals and architecture
+- Duplicate work is avoided
+- The community can provide input before code is written
+- Cloud Agents have sufficient context to generate high-quality code
+
+## How to Use Issue First with Roo Cloud Agents
+
+### Step 1: Create a Quality Issue
+
+When creating an issue that will be used by a Roo Cloud Agent, provide comprehensive details:
+
+#### For Bug Reports
+
+```markdown
+**Description**: Clear description of the bug in the Smartsheet Python SDK
+
+**Steps to Reproduce**:
+1. Import the SDK: `import smartsheet`
+2. Call the specific method: `client.Sheets.get_sheet(sheet_id)`
+3. Observe the error
+
+**Expected Behavior**: What should happen when using the SDK
+
+**Actual Behavior**: What actually happens
+
+**Environment**:
+- SDK Version: (e.g., 3.0.0)
+- Python Version: (e.g., 3.9.0)
+- Operating System: (e.g., Ubuntu 22.04)
+
+**Code Sample** (if applicable):
+```python
+import smartsheet
+client = smartsheet.Smartsheet('your_token')
+# Your code that demonstrates the issue
+\`\`\`
+
+**Additional Context**: Any relevant details about the Smartsheet API, error messages, or stack traces
+\`\`\`
+
+#### For Feature Requests
+
+```markdown
+**Feature Description**: Clear description of the new functionality needed in the Smartsheet Python SDK
+
+**Use Case**: Why this feature is needed and how it will be used
+
+**Proposed API**:
+```python
+# Example of how the feature would be used
+client.Sheets.new_method(parameters)
+```
+
+**Smartsheet API Reference**: Link to relevant Smartsheet API documentation if applicable
+
+**Implementation Considerations**:
+
+- Which SDK modules would be affected (e.g., `smartsheet/sheets.py`, `smartsheet/models/`)
+- Any dependencies or related features
+- Backwards compatibility concerns
+
+**Alternatives Considered**: Other approaches that were considered
+\`\`\`
+
+#### For Documentation Improvements
+
+```markdown
+**Documentation Issue**: What documentation is missing, unclear, or incorrect
+
+**Location**: Which file or section needs improvement (e.g., `README.md`, `ADVANCED.md`)
+
+**Suggested Improvement**: What should be added or changed
+
+**Context**: Why this documentation is important for SDK users
+\`\`\`
+
+### Step 2: Let the Cloud Agent Work
+
+Once your issue is well-defined:
+
+1. **The Cloud Agent reads your issue** as its primary prompt
+2. **It analyzes the Smartsheet Python SDK codebase** to understand:
+   - Existing patterns and conventions
+   - Related code that may need updates
+   - Test files that need modifications
+   - Documentation that should be updated
+
+3. **It generates the necessary changes**:
+   - Python code following the SDK's style
+   - Unit tests using the project's testing framework
+   - Updated documentation
+   - Appropriate error handling
+
+4. **It creates a Pull Request** linked to your issue with all the changes
+
+### Step 3: Review and Iterate
+
+After the Cloud Agent creates a PR:
+
+1. Review the generated code for correctness and quality
+2. Test the changes locally with the Smartsheet API
+3. Provide feedback in the PR comments
+4. The Cloud Agent can iterate based on your feedback
+5. Once approved, the changes are merged
+
+## Best Practices for Writing Issues
+
+### Be Specific and Detailed
+
+**Poor Issue**: "Fix the sheet method"
+
+**Good Issue**: "Fix TypeError in `Sheets.get_sheet()` when sheet contains cell links - occurs when a sheet has cells with links to other sheets, the SDK raises a TypeError during deserialization of the Cell model"
+
+### Include Code Examples
+
+Show how the SDK is being used and what's not working:
+
+```python
+import smartsheet
+
+client = smartsheet.Smartsheet(access_token='your_token')
+
+# This raises an error
+sheet = client.Sheets.get_sheet(1234567890)
+print(sheet.rows[0].cells[0].value)  # TypeError here
+```
+
+### Reference Smartsheet API Documentation
+
+Link to relevant Smartsheet API documentation to help the Cloud Agent understand the expected behavior:
+
+```markdown
+According to the [Smartsheet API documentation for Get Sheet](https://developers.smartsheet.com/api/smartsheet/openapi/sheets/get-sheet),
+the response should include...
+```
+
+### Specify the Scope
+
+Be clear about what should and shouldn't be changed:
+
+```markdown
+**In Scope**:
+- Update the `Cell` model in `smartsheet/models/cell.py`
+- Add handling for cell link objects
+- Update tests in `tests/mock_api/test_mock_api_sheets.py`
+
+**Out of Scope**:
+- Changes to other models
+- API authentication changes
+```
+
+### Tag Appropriately
+
+Use GitHub labels to help categorize your issue:
+
+- `bug` - Something isn't working correctly
+- `enhancement` - New feature or improvement
+- `documentation` - Documentation improvements
+- `good first issue` - Good for newcomers
+- `help wanted` - Extra attention needed
+
+## Examples of Well-Written Issues
+
+### Example 1: Bug Report
+
+```markdown
+**Title**: Cell deserialization fails when cell contains hyperlink with null url
+
+**Description**:
+When using the Smartsheet Python SDK to retrieve a sheet that contains cells with hyperlinks
+where the url property is null, the SDK raises an AttributeError during deserialization.
+
+**Steps to Reproduce**:
+
+1. Create a sheet in Smartsheet with a cell containing a hyperlink with no URL
+2. Use the SDK to get the sheet:
+
+\`\`\`python
+import smartsheet
+client = smartsheet.Smartsheet('token')
+sheet = client.Sheets.get_sheet(sheet_id)
+\`\`\`
+
+3. Observe the AttributeError
+
+**Expected Behavior**:
+The SDK should handle null hyperlink URLs gracefully, either by setting the url to None
+or providing a default value.
+
+**Actual Behavior**:
+
+\`\`\`text
+AttributeError: 'NoneType' object has no attribute 'strip'
+  File "smartsheet/models/hyperlink.py", line 45, in __init__
+\`\`\`
+
+**Environment**:
+
+- SDK Version: 2.105.1
+- Python Version: 3.9.7
+- OS: macOS 12.6
+
+**Smartsheet API Reference**:
+<https://developers.smartsheet.com/api/smartsheet/openapi/sheets/get-sheet>
+
+\`\`\`
+
+### Example 2: Feature Request
+
+```markdown
+**Title**: Add support for Sheet Summary Fields API
+
+**Description**:
+The Smartsheet Python SDK currently does not support the Sheet Summary Fields API endpoints.
+This feature would allow users to programmatically read and update sheet summary fields.
+
+**Use Case**:
+Users need to automate updating project metadata stored in sheet summaries, such as
+project status, start dates, and custom KPIs.
+
+**Proposed API**:
+
+\`\`\`python
+# Get summary fields
+summary = client.Sheets.get_sheet_summary(sheet_id)
+for field in summary.fields:
+    print(f"{field.title}: {field.value}")
+
+# Update a summary field
+client.Sheets.update_summary_field(
+    sheet_id=sheet_id,
+    field_id=field_id,
+    value="Updated value"
+)
+\`\`\`
+
+**Smartsheet API Reference**:
+
+- <https://developers.smartsheet.com/api/smartsheet/openapi/sheetsummary/list-summary-fields>
+- <https://developers.smartsheet.com/api/smartsheet/openapi/sheetsummary/get-sheet-summary>
+
+**Implementation Considerations**:
+
+- Add new methods to `smartsheet/sheets.py`
+- Create `SummaryField` model in `smartsheet/models/`
+- Add tests to verify API integration
+- Update documentation in `README.md` or `ADVANCED.md`
+
+**Related Issues**: None
+
+**Alternatives Considered**:
+Using direct API calls with the `Passthrough` module, but a native SDK implementation
+would provide better type hints and error handling.
+\`\`\`
+
+## Conclusion
+
+The Issue First approach, combined with Roo Code Cloud Agents, creates a powerful workflow for contributing to the Smartsheet Python SDK. By writing clear, detailed issues, you provide Cloud Agents with the context they need to generate high-quality code changes. This approach ensures that:
+
+- All changes are well-documented and justified
+- The community can provide input and avoid duplicate work
+- Cloud Agents have the information they need to be effective
+- The SDK maintains high quality and consistency
+
+Remember: **A well-written issue is the foundation for successful automation with Cloud Agents.**

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: smartsheet-python-sdk
-Version: 3.5.5
+Version: 3.6.0
 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
@@ -100,6 +100,10 @@ Use the following resources to learn more about the SDK capabilities:
 2. [Python SDK documentation](https://smartsheet.github.io/smartsheet-python-sdk/)
 3. [Smartsheet API Documentation](https://developers.smartsheet.com/api/smartsheet/)
 
+## Contributing
+
+We welcome contributions! Before submitting code changes, please review our [Issue First approach](ISSUE-FIRST.md) for creating effective issues that work well with both human reviewers and AI-powered Cloud Agents. For additional contribution guidelines, see [CONTRIBUTING.md](CONTRIBUTING.md).
+
 ## Advanced Topics
 
 For details about logging, testing, how to use a passthrough option, and how to override HTTP client behavior,

{smartsheet_python_sdk-3.5.5 → smartsheet_python_sdk-3.6.0}/README.md

@@ -47,6 +47,10 @@ Use the following resources to learn more about the SDK capabilities:
 2. [Python SDK documentation](https://smartsheet.github.io/smartsheet-python-sdk/)
 3. [Smartsheet API Documentation](https://developers.smartsheet.com/api/smartsheet/)
 
+## Contributing
+
+We welcome contributions! Before submitting code changes, please review our [Issue First approach](ISSUE-FIRST.md) for creating effective issues that work well with both human reviewers and AI-powered Cloud Agents. For additional contribution guidelines, see [CONTRIBUTING.md](CONTRIBUTING.md).
+
 ## Advanced Topics
 
 For details about logging, testing, how to use a passthrough option, and how to override HTTP client behavior,