Can you add a dash (-) to the list of escapable characters?

[virtadpt]

Bug summary

Hi. I'm using this Python module to run searches on Jira tickets (right now, just the ticket summary field) and I'm running into a problem with the use of dashes.

I know that dashes are reserved characters and have to be doubly escaped (\\-) in regular JQL queries; that works just fine when prototyping the query I'm trying to use with the jira module. But when I do the same thing in Python, I get this (partially redacted):

>>> jira.search_issues("project=MANHATTAN and summary ~ 'findings \\-'")
... Traceback elided...
response text = {"errorMessages":["Error in the JQL Query: '\\-' is an illegal JQL escape sequence. The valid escape sequences are \\', \\\", \\t, \\n, \\r, \\\\, '\\ ' and \\uXXXX. (line 1, character 34)"],"errors":{}}

I've tried the same thing with a single backslash-escape and get pretty much the same thing:

>>> jira.search_issues("project=MANHATTAN and summary ~ 'findings \-'")
... Traceback elided...
response text = {"errorMessages":["Error in the JQL Query: '\\-' is an illegal JQL escape sequence. The valid escape sequences are \\', \\\", \\t, \\n, \\r, \\\\, '\\ ' and \\uXXXX. (line 1, character 34)"],"errors":{}}

Trying without a backslash escape at all fails just as one would expect:

>>> jira.search_issues("project=MANHATTAN and summary ~ 'findings -'")
... Traceback elided...
response text = {"errorMessages":["Unable to parse the text 'findings -' for field 'summary'."],"warningMessages":[]}

Is this a bug in the module? An option that I can provide to .search_issues()? Or is there a workaround of some kind?

Is there an existing issue for this?

• [x] I have searched the existing issues

Jira Instance type

Jira Cloud (Hosted by Atlassian)

Jira instance version

1001.0.0-SNAPSHOT (I don't have admin access so all I can do is view the source code of our Jira frontpage)

jira-python version

3.8.0

Python Interpreter version

3.12.6

Which operating systems have you used?

• [ ] Linux
• [x] macOS
• [ ] Windows

Reproduction steps

# 1. Given a Jira client instance
# Our Jira instance's URL, my username, and API key are redacted.

jira = JIRA(server=tickets, basic_auth=(username, api_key))
myself = jira.myself()

# This is just to make sure that authentication worked.  It does.
if not myself:
    print("Authentication to %s failed.  ABENDing." % tickets)
    sys.exit(1)

# 2. I run a search on our Jira tickets.  A very simple one for now.  Slightly redacted.
jira.search_issues("project=MANHATTAN and summary ~ 'findings \\-'")

Stack trace

Partially redacted per policy:

Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/Users/me/atlassian_api/lib/python3.12/site-packages/jira/client.py", line 3557, in search_issues
    issues = self._fetch_pages(
             ^^^^^^^^^^^^^^^^^^
  File "/Users/me/atlassian_api/lib/python3.12/site-packages/jira/client.py", line 817, in _fetch_pages
    resource = self._get_json(
               ^^^^^^^^^^^^^^^
  File "/Users/me/atlassian_api/lib/python3.12/site-packages/jira/client.py", line 4358, in _get_json
    else self._session.get(url, params=params)
         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/me/atlassian_api/lib/python3.12/site-packages/requests/sessions.py", line 602, in get
    return self.request("GET", url, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/me/atlassian_api/lib/python3.12/site-packages/jira/resilientsession.py", line 247, in request
    elif raise_on_error(response, **processed_kwargs):
         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/me/atlassian_api/lib/python3.12/site-packages/jira/resilientsession.py", line 72, in raise_on_error
    raise JIRAError(
jira.exceptions.JIRAError: JiraError HTTP 400 url: https://company.atlassian.net/rest/api/2/search?jql=project%3DMANHATTAN+and+summary+~+%27findings+%5C-%27&startAt=0&validateQuery=True&fields=%2Aall&maxResults=50
        text: Error in the JQL Query: '\-' is an illegal JQL escape sequence. The valid escape sequences are \', \", \t, \n, \r, \\, '\ ' and \uXXXX. (line 1, character 34)

        response headers = {'Date': 'Thu, 23 Jan 2025 23:55:35 GMT', 'Content-Type': 'application/json;charset=UTF-8', 'Server': 'AtlassianEdge', 'Timing-Allow-Origin': '*', 'X-Arequestid': 'ba43c4a480ca231a5a54ca1f360f1845', 'X-Aaccountid': '31337db9c3566031337cac2c', 'Cache-Control': 'no-cache, no-store, no-transform', 'X-Content-Type-Options': 'nosniff', 'X-Xss-Protection': '1; mode=block', 'Atl-Traceid': '371f3afa574748b4ba3f7857dd87b03a', 'Atl-Request-Id': '371f3afa-5747-48b4-ba3f-7857dd87b03a', 'Strict-Transport-Security': 'max-age=63072000; includeSubDomains; preload', 'Report-To': '{"endpoints": [{"url": "https://dz8aopenkvv6s.cloudfront.net"}], "group": "endpoint-1", "include_subdomains": true, "max_age": 600}', 'Nel': '{"failure_fraction": 0.001, "include_subdomains": true, "max_age": 600, "report_to": "endpoint-1"}', 'Server-Timing': 'atl-edge;dur=212,atl-edge-internal;dur=26,atl-edge-upstream;dur=185,atl-edge-pop;desc="aws-us-west-2"', 'Transfer-Encoding': 'chunked'}
        response text = {"errorMessages":["Error in the JQL Query: '\\-' is an illegal JQL escape sequence. The valid escape sequences are \\', \\\", \\t, \\n, \\r, \\\\, '\\ ' and \\uXXXX. (line 1, character 34)"],"errors":{}}

Expected behaviour

At least a partial list of Jira tickets whose summaries contain the string "findings -":

[<JIRA Issue: key='MANHATTAN-3480', id='50104'>, <JIRA Issue: key='MANHATTAN-3477', id='49990'>, <JIRA Issue: key='MANHATTAN-3476', id='49989'>, <JIRA Issue: key='MANHATTAN-3475', id='49988'>, <JIRA Issue: key='MANHATTAN-3474', id='49950'>, ...

Or an empty list if there weren't any.

Additional Context

No response

[virtadpt]

Weirdly, quadruple escaping the dash works:

jira.search_issues("project=MANHATTAN and summary ~ 'findings \\\\-'")

[<JIRA Issue: key='MANHATTAN-3480', id='50104'>, <JIRA Issue: key='MANHATTAN-3477', id='49990'>, ...