docs: clarify username formats, ProjectLeader-as-group, and filter special-char behavior - #1854
Open
jacalata wants to merge 1 commit into
Open
docs: clarify username formats, ProjectLeader-as-group, and filter special-char behavior#1854jacalata wants to merge 1 commit into
jacalata wants to merge 1 commit into
Conversation
…ecial-char behavior Bundles three long-standing docs gaps flagged in stale issues: #993 - users.add example used a fake short username with no explanation that `name` is the server auth identifier (email on Cloud, SAM@Domain on AD-backed Server), not the person's display name. Rewrote the users.add docstring intro to describe the required formats per auth scheme, split the example into a Cloud invocation and an AD invocation, and added matching guidance to UserItem.name. #1067 - projects.update_permissions had no examples, so callers had no guide for the common "assign group as Project Leader" case. Added an example that shows constructing a PermissionsRule with grantee=<group> and capability=ProjectLeader, plus a note that update_permissions is a full replacement (call populate_permissions first if preserving existing rules). #1200 - the REST filter grammar treats ',', '&', ':', '[' and ']' as delimiters and the server does not support escaping, so `filter(name="T(L-F,SZ&V-MY)")` fails with 400065 for any name containing those characters. Documented the constraint on the Filter class docstring and on QuerySet.filter, along with the working wildcard workaround (Equals with '*' substituted). No behavior change. Docs only. Closes #993, #1067, #1200.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Bundles three long-standing docs gaps flagged in stale issues. Docs only, no behavior change.
#993 —
users.addusername formatsThe primary
users.addexample (TSC.UserItem('new_user', ...)) gave no hint thatnameis the server-side authentication identifier, not the person's display name. Rewrote theusers.adddocstring to describe the required format per auth scheme (Cloud = email, local Server = username, AD-backed =SAMAccountName@FullyQualifiedDomainor UPN), split the example into a Cloud invocation and an AD invocation, and added matching guidance toUserItem.name.#1067 — ProjectLeader-as-group example
projects.update_permissionshad no examples, so callers had no guide for the common "assign a group as Project Leader on a project" case. Added an example that constructs aPermissionsRulewithgrantee=<group>and capability=ProjectLeader, plus a note thatupdate_permissionsis a full replacement (callpopulate_permissionsfirst if preserving existing rules).#1200 — filter special-character behavior
The REST filter grammar treats
,,&,:,[and]as delimiters and the server does not support escaping, sofilter(name="T(L-F,SZ&V-MY)")fails with400065for any name containing those characters. Documented the constraint on theFilterclass docstring and onQuerySet.filter, along with the working wildcard workaround (Equals with*substituted for the special char).Test plan
test/test_user.py,test_user_model.py,test_project.py,test_project_model.py,test_filter.py: 89 passedCloses #993, #1067, #1200.
🤖 Generated with Claude Code