Support include=planName on List User Plans

[adecounter]

Pull Request

Description

Adds support for the optional include query parameter on GET /2.0/users/{userId}/plans (List User Plans), and exposes the resulting planName on the UserPlan model as plan_name.

Related Issue

Related Issue: #162

Type of Change

• New feature

Environment Information

• Smartsheet API Version: 2.0
• Smartsheet Python SDK Version: 4.3.0 (unreleased main)
• Python Version: 3.14 (suite also targets the SDK's supported matrix)

What Changes Were Made

• Users.list_user_plans accepts a new include keyword argument. The only value the API currently accepts is planName, which matches the response field it controls. It is passed as a list and serialized comma-separated by prepare_request, exactly like every other include parameter in the SDK, so it is forward-compatible if more values are added later.
• UserPlan gains a plan_name property, which carries the name of the plan's owning organization when the enrichment is requested.
• Docstring updated to describe the accepted value and its effect.

Files changed:

• smartsheet/users.py - include kwarg plumbed into query_params
• smartsheet/models/user_plan.py - new plan_name String field with getter/setter
• tests/mock_api/users/test_list_user_plans.py - assertions for the query parameter and both populated/absent plan_name
• CHANGELOG.md - two entries under Unreleased

Why These Changes Were Made

Callers listing a user's plans typically want to display which organization each plan belongs to, which previously required a separate lookup per plan. include=planName lets the API return that name inline.

plan_name is deliberately optional and deserializes to None in two distinct cases: when the enrichment was not requested, and when the owning organization has no name. Callers should treat None as "unknown" rather than "no organization".

Testing

Full mock suite run against the shared WireMock mappings: 331 passed, 9 skipped (the 9 skips are pre-existing in test_mock_serialization.py and unrelated to this change).

New/updated coverage in tests/mock_api/users/test_list_user_plans.py:

• include is present in the outgoing query string with the expected comma-separated value
• plan_name == 'Acme Corporation' on the first plan of the all-properties response
• plan_name is None on the second plan, which omits the field
• plan_name is None in the required-properties response, where the enrichment was not requested

The mapping this relies on (planName on the List User Plans all-properties mapping) has been merged to smartsheet-sdk-tests mainline, which is the ref CI clones, so these tests pass in CI without any additional coordination.

Checklist

• My code follows the style guidelines of this project
• 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/ - no change needed; the API and model docs are generated by autodoc from the docstrings, which are updated here
• 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

Additional Notes

Backwards compatibility: include defaults to None. When it is omitted the request is byte-identical to today's behavior - the parameter is not emitted at all, and plan_name is simply absent from the deserialized model. No existing caller is affected.

Staleness caveat: organization names are cached for roughly four hours downstream of this endpoint, so a recently renamed organization may briefly return its previous name. This is worth keeping in mind if you are using plan_name in a UI right after a rename.

Summary by CodeRabbit

• New Features

  • Added support for requesting plan names when listing user plans.
  • User plan results can now include a plan_name field.

• Documentation

  • Documented the plan-name option and response field.

• Tests

  • Added coverage for plan-name requests and returned values.

[coderabbitai]

📝 Walkthrough

Walkthrough

The PR adds UserPlan.plan_name and extends Users.list_user_plans with an include parameter. Tests verify include=planNames and optional plan-name responses.

Changes

User plan names

Layer / File(s)	Summary
Plan name model and listing API smartsheet/models/user_plan.py, smartsheet/users.py	UserPlan stores and exposes plan_name. list_user_plans accepts include, documents planNames, and sends it as a query parameter.
Request and response validation tests/mock_api/users/test_list_user_plans.py, CHANGELOG.md	Tests verify the query parameter and returned or omitted plan_name values. The changelog records the new support.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related issues

• smartsheet/smartsheet-python-sdk issue 162 — Covers the same include=planNames and UserPlan.plan_name changes.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly and concisely identifies the main change: adding include=planName support to List User Plans.
Description check	✅ Passed	The description follows the template and covers the change, issue, environment, rationale, testing, checklist, and compatibility notes.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@tests/mock_api/users/test_list_user_plans.py`:
- Around line 67-76: Update both response tests, including the assertions around
the first and second user plans and the later assertion near line 99, to use
whole-object comparisons via response.to_dict() or each UserPlan.to_dict().
Build complete expected objects for every plan, including plan_name, while
preserving the existing expected values for all other fields.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: a662245a-ae39-4ad6-a313-3b945afc04af

📥 Commits

Reviewing files that changed from the base of the PR and between c830825 and 3de03e5.

📒 Files selected for processing (4)

• CHANGELOG.md
• smartsheet/models/user_plan.py
• smartsheet/users.py
• tests/mock_api/users/test_list_user_plans.py