feat: add family account management API by OfekAvergil · Pull Request #1701 · descope/python-sdk

OfekAvergil · 2026-09-24T09:47:29Z

https://github.com/descope/etc/issues/18737

Description

Adds the family account management API to the Python SDK. Equivalent of descope/node-sdk#793, adapted to Python SDK conventions (sync + async variants, shared _family_base.py, snake_case args, raw dict responses).

New `mgmt.family` module (`Family` / `FamilyAsync`)

create, update (patch semantics, omitted fields unchanged), delete, search (no args = all families)
create_dependent, delete_dependent
impersonate_dependent, stop_impersonation (return the JWT string, like mgmt.jwt.impersonate)
load_settings, update_settings (partial update)
load_custom_attributes, create_custom_attributes, delete_custom_attributes (definitions on the family entity)

`mgmt.user` additions

add_families (merges into existing memberships), remove_families
load_family_scoped_custom_attributes, create_family_scoped_custom_attributes, delete_family_scoped_custom_attributes
family_associations on create, create_test_user, invite, update, patch, and UserObj (batch invite / patch batch)
family_ids and dependent filters on search_all

New public types

AssociatedFamily, CustomAttribute, CustomAttributeOption (exported from descope).

Docs and sample

README "Manage Families" section
samples/management/family_sample_app.py: end-to-end walkthrough (settings, attribute definitions, family CRUD/search, guardian created into the family, add_families merge, dependent, user search by family, impersonation, cleanup in reverse order and settings restore). Credentials from DESCOPE_PROJECT_ID / DESCOPE_MANAGEMENT_KEY (optional DESCOPE_BASE_URL, FAMILY_ROLE, SKIP_CLEANUP=1); any failed step, including cleanup, exits non-zero.

Note on the separate README commit

docs: format README code blocks with ruff is formatter output only. ruff-pre-commit v0.16.5 formats Python blocks in Markdown, so the ruff-format hook rejects any commit touching README.md until the existing blocks are formatted. Kept as its own commit so it can be reviewed (or dropped) independently.

Testing

uv run ruff check ., uv run ruff format --check ., uv run mypy descope tests samples, pylic check: pass
uv run coverage run -m pytest tests --ignore=tests/e2e: 1142 passed, total coverage 98% (new modules 100%)
The sample was not run against a live project

🤖 Generated with Claude Code

ruff-pre-commit v0.16.5 formats Python code blocks in Markdown, so any commit touching README.md fails the ruff-format hook until the existing blocks are formatted. No content changes. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

Add a `family` management module (sync and async) covering family CRUD and search, dependents, dependent impersonation, family settings and family entity custom attribute definitions. Extend the user module with add_families / remove_families, family-scoped user custom attribute definitions, family_associations on create, invite, update, patch and batch operations, and family_ids / dependent search filters. Equivalent of descope/node-sdk#793. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

github-actions · 2026-09-24T09:57:23Z

Coverage report

The coverage rate went from 98.3% to 98.38% ⬆️

100% of new lines are covered.

Diff Coverage details (click to unfold)

descope/management/_family_base.py

100% of new lines are covered (100% of the complete file).

descope/management/family.py

100% of new lines are covered (100% of the complete file).

descope/management/common.py

100% of new lines are covered (99.81% of the complete file).

descope/management/user.py

100% of new lines are covered (98.7% of the complete file).

descope/management/user_async.py

100% of new lines are covered (98.71% of the complete file).

descope/mgmt_async.py

100% of new lines are covered (100% of the complete file).

descope/management/family_async.py

100% of new lines are covered (100% of the complete file).

descope/mgmt.py

100% of new lines are covered (100% of the complete file).

descope/management/_user_base.py

100% of new lines are covered (93.2% of the complete file).

Log the decoded sub, act and dcf claims of the impersonation and stop-impersonation JWTs, without logging the tokens themselves. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

An assert with a side effect is skipped under python -O, so the call under test would silently not run. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

shuni-bot · 2026-09-24T12:06:41Z

🐕 Shuni Review

No new issues found.

⚠️ Review follow-up issue: Prior review threads were not verified after the latest updates.

🤖 Model: gpt-6-sol (fallback from claude-opus-5.5) · Effort: high

Review scope: Partial incremental re-review

Reviewed new changes (3)

descope/management/user.py
descope/management/user_async.py
tests/management/test_user.py

Previously reviewed and unchanged: 12 files.

🐕 Review complete — View session on Shuni Portal 🐾

🤖 Model: gpt-6-sol (fallback from claude-opus-5.5) · Effort: high

shuni-bot

🐕 Shuni review: 2 inline findings. Every changed file in this pull request was reviewed.

The full review summary is in Shuni's sticky review comment on this pull request.

LioriE

Wire shape checked against the backend proto and the node/go family branches: all 19 calls match. Comments inline.

Commit 5da8df5 (README reformat) is unrelated to families. Separate PR please.

- Rename search to search_all with ids, names, text - create takes an optional id, matching tenant.create - Rename load_settings/update_settings to get_settings/configure_settings, matching password - create_dependent takes the dependent's family-scoped attributes for its family only - Validate empty input on impersonate_dependent and stop_impersonation - Add default_value to CustomAttribute - Add family_ids and dependent filters to search_all_test_users - Document that update replaces family memberships and family custom attributes - Sample and README cleanups Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

shuni-bot

🐕 Shuni review: 1 inline finding. Every changed file in this pull request was reviewed.

The full review summary is in Shuni's sticky review comment on this pull request.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

shuni-bot

🐕 Shuni review: no new findings. Every changed file in this pull request was reviewed.

The full review summary is in Shuni's sticky review comment on this pull request.

LioriE

Checked the two follow-up commits against the backend proto and the node/go branches. All review comments addressed, wire shape unchanged, sync/async identical, ruff and tests green locally.

OfekAvergil and others added 2 commits September 24, 2026 12:45

github-code-quality Bot found potential problems Sep 24, 2026

View reviewed changes

Comment thread tests/management/test_family.py Fixed

fix(samples): log impersonation claims after impersonating

6dfb442

Log the decoded sub, act and dcf claims of the impersonation and stop-impersonation JWTs, without logging the tokens themselves. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

OfekAvergil marked this pull request as ready for review September 24, 2026 12:01

test: move awaited calls out of asserts in family tests

4e5b614

An assert with a side effect is skipped under python -O, so the call under test would silently not run. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

shuni-bot Bot reviewed Sep 24, 2026

View reviewed changes

Comment thread descope/management/user.py

Comment thread descope/management/_family_base.py Outdated

LioriE reviewed Sep 26, 2026

View reviewed changes

shuni-bot Bot reviewed Sep 27, 2026

View reviewed changes

Comment thread descope/management/user.py

fix(user): send an explicit empty familyAssociations list on update

b18db23

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

shuni-bot Bot reviewed Sep 27, 2026

View reviewed changes

OfekAvergil requested a review from LioriE September 27, 2026 12:59

LioriE approved these changes Sep 28, 2026

View reviewed changes

Conversation

OfekAvergil commented Sep 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

New mgmt.family module (Family / FamilyAsync)

mgmt.user additions

New public types

Docs and sample

Note on the separate README commit

Testing

Uh oh!

Uh oh!

github-actions Bot commented Sep 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Coverage report

descope/management/_family_base.py

descope/management/family.py

descope/management/common.py

descope/management/user.py

descope/management/user_async.py

descope/mgmt_async.py

descope/management/family_async.py

descope/mgmt.py

descope/management/_user_base.py

Uh oh!

shuni-bot Bot commented Sep 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🐕 Shuni Review

Uh oh!

shuni-bot Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

LioriE left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

shuni-bot Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

shuni-bot Bot left a comment

Choose a reason for hiding this comment

Uh oh!

LioriE left a comment

Choose a reason for hiding this comment

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

OfekAvergil commented Sep 24, 2026 •

edited

Loading

New `mgmt.family` module (`Family` / `FamilyAsync`)

`mgmt.user` additions

github-actions Bot commented Sep 24, 2026 •

edited

Loading

shuni-bot Bot commented Sep 24, 2026 •

edited

Loading