Documentation for Jira user_find_by_user_string() should mention that query parameter only works for Jira Cloud

[grantsohn]

Documentation for Jira user_find_by_user_string() should mention that query parameter only works for Jira Cloud. For non-cloud servers, you need to specify the username parameter instead.

Exact docs are on page https://atlassian-python-api.readthedocs.io/jira.html, under the Manage users header.

Original docs:
# Fuzzy search using emailAddress or displayName
jira.user_find_by_user_string(query="a.user@example.com", start=0, limit=50, include_inactive_users=False)
jira.user_find_by_user_string(query="a.user", start=0, limit=50, include_inactive_users=False)
jira.user_find_by_user_string(query="a user")
jira.user_find_by_user_string(account_id="a-users-account-id")

Improvements: # Fuzzy search using emailAddress or displayName for Jira Cloud So adding an example like: jira.user_find_by_user_string(username="a.user") # for DC

Cut & paste of my terminal session showing the issue:

$ pip list
Package              Version
-------------------- -----------
atlassian-python-api 3.41.10
...
$ python3
Python 3.9.6 (default, Dec  7 2023, 05:42:47) 
[Clang 15.0.0 (clang-1500.1.0.2.5)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> from atlassian import Jira
...
>>> access_token = os.environ['JIRA_ACCESS_TOKEN']
>>> 
>>> jira = Jira(
...     url=internal_jira_server,
...     token=access_token)
>>> 
>>> jira.user_find_by_user_string(query='a.name')
'Username parameter is required for user search on Jira Server'
>>> jira.user_find_by_user_string(username='a.name')
[{'self': ....

[Spacetown]

Feel free to create a PR.

[grantsohn]

I get 'remote: Permission to atlassian-api/atlassian-python-api.git denied' error when I try to push my PR branch. But, here's the diff of the changes:

diff --git a/docs/jira.rst b/docs/jira.rst
index c5af95b..4369935 100644
--- a/docs/jira.rst
+++ b/docs/jira.rst
@@ -76,11 +76,15 @@ Manage users
     # Get web sudo cookies using normal http request
     jira.user_get_websudo()

-    # Fuzzy search using emailAddress or displayName
+    # Fuzzy search using emailAddress or displayName for Jira Cloud
     jira.user_find_by_user_string(query="a.user@example.com", start=0, limit=50, include_inactive_users=False)
     jira.user_find_by_user_string(query="a.user", start=0, limit=50, include_inactive_users=False)
     jira.user_find_by_user_string(query="a user")
     jira.user_find_by_user_string(account_id="a-users-account-id")
+    # for DC edition
+    jira.user_find_by_user_string(username="a.user")
+    jira.user_find_by_user_string(username="a user")
+    jira.user_find_by_user_string(username="a")

     # Get groups of a user. This API is only available for Jira Cloud platform.
     jira.get_user_groups(account_id)

[Spacetown]

You need to fork the repository, push your branch to your fork and the raise a PR for this repository.

[grantsohn]

Okay, got it working, thanks! https://github.com/atlassian-api/atlassian-python-api/pull/1368

[grantsohn]

Code merged with https://github.com/atlassian-api/atlassian-python-api/pull/1368.

[grantsohn]

Closing