def put(self, key, value, data):
restUrl = self.url + API_REST_BIND_PATH + '/' + key + '/' + value
try:
rsp = self.session.put(restUrl, json=data)
except requests.exceptions.Timeout:
raise ConfluenceTimeoutError(self.url)
except requests.exceptions.SSLError as ex:
raise ConfluenceSslError(self.url, ex)
except requests.exceptions.ConnectionError as ex:
raise ConfluenceBadServerUrlError(self.url, ex)
if rsp.status_code == 401:
raise ConfluenceAuthenticationFailedUrlError
if rsp.status_code == 403:
raise ConfluencePermissionError("REST PUT")
if rsp.status_code == 407:
raise ConfluenceProxyPermissionError
if not rsp.ok:
errdata = self._format_error(rsp, key)
if self.verbosity > 0:
errdata += "\n"
errdata += json.dumps(data, indent=2)
raise ConfluenceBadApiError(errdata)
if not rsp.text:
raise ConfluenceSeraphAuthenticationFailedUrlError
try:
rsp.encoding = self.CONFLUENCE_DEFAULT_ENCODING
json_data = json.loads(rsp.text)
except ValueError:
raise ConfluenceBadServerUrlError(
self.url, "REST reply did not provide valid JSON data.")
return json_data
def remove_page(self, page_id):
if self.dryrun:
self._dryrun('removing page', page_id)
return
elif self.onlynew:
self._onlynew('page removal restricted', page_id)
return
try:
try:
self.rest_client.delete('content', page_id)
except ConfluenceBadApiError as ex:
if str(ex).find('Transaction rolled back') == -1:
raise
logger.warn('delete failed; retrying...')
time.sleep(3)
self.rest_client.delete('content', page_id)
except ConfluenceBadApiError as ex:
# Check if Confluence reports that this content does not exist. If
# so, we want to suppress the API error. This is most likely a
# result of a Confluence instance reporting a page descendant
# identifier which no longer exists (possibly a caching issue).
if str(ex).find('No content found with id') == -1:
raise
logger.verbose('ignore missing delete for page '
'identifier: {}'.format(page_id))
except ConfluencePermissionError:
raise ConfluencePermissionError(
"""Publish user does not have permission to delete """
"""from the configured space.""")
def get(self, key, params):
restUrl = self.url + API_REST_BIND_PATH + '/' + key
try:
rsp = self.session.get(restUrl, params=params)
except requests.exceptions.Timeout:
raise ConfluenceTimeoutError(self.url)
except requests.exceptions.SSLError as ex:
raise ConfluenceSslError(self.url, ex)
except requests.exceptions.ConnectionError as ex:
raise ConfluenceBadServerUrlError(self.url, ex)
if rsp.status_code == 401:
raise ConfluenceAuthenticationFailedUrlError
if rsp.status_code == 403:
raise ConfluencePermissionError("REST GET")
if rsp.status_code == 407:
raise ConfluenceProxyPermissionError
if not rsp.ok:
raise ConfluenceBadApiError(self._format_error(rsp, key))
if not rsp.text:
raise ConfluenceSeraphAuthenticationFailedUrlError
try:
rsp.encoding = self.CONFLUENCE_DEFAULT_ENCODING
json_data = json.loads(rsp.text)
except ValueError:
raise ConfluenceBadServerUrlError(
self.url, "REST reply did not provide valid JSON data.")
return json_data
def store_page_by_id(self, page_name, page_id, data):
"""
request to store page information on the page with a matching id
Performs a request which will attempt to store the provided page
information and publish it to a page with the provided ``page_id``.
Args:
page_name: the page title to use on the updated page
page_id: the id of the page to update
data: the page data to apply
"""
assert page_id
if self.onlynew:
self._onlynew('skipping explicit page update for', page_id)
return page_id
if self.dryrun:
_, page = self.get_page_by_id(page_id)
if not page:
self._dryrun('unable to find page with id', page_id)
return None
else:
self._dryrun('updating existing page', page_id)
return page_id
expand = 'version'
if self.append_labels:
expand += ',metadata.labels'
try:
_, page = self.get_page_by_id(page_id, expand=expand)
except ConfluenceBadApiError as ex:
if str(ex).find('No content found with id') == -1:
raise
raise ConfluenceMissingPageIdError(self.space_key, page_id)
try:
self._update_page(page, page_name, data)
except ConfluencePermissionError:
raise ConfluencePermissionError(
"""Publish user does not have permission to add page """
"""content to the configured space.""")
if not self.watch:
self.rest_client.delete('user/watch/content', page_id)
return page_id
def removePage(self, page_id):
if self.dryrun:
self._dryrun('removing page', page_id)
return
elif self.onlynew:
self._onlynew('page removal restricted', page_id)
return
try:
self.rest_client.delete('content', page_id)
except ConfluencePermissionError:
raise ConfluencePermissionError(
"""Publish user does not have permission to delete """
"""from the configured space.""")
def post(self, key, data, files=None):
restUrl = self.url + API_REST_BIND_PATH + '/' + key
try:
headers = dict(self.session.headers)
# Atlassian's documenation indicates to the security token check
# when publishing attachments [1][2]. If adding files, set a
# 'nocheck' value to the token.
#
# [1]: https://developer.atlassian.com/cloud/confluence/rest/#api-content-id-child-attachment-post
# [2]: https://developer.atlassian.com/server/jira/platform/form-token-handling/
if files:
headers['X-Atlassian-Token'] = 'nocheck'
rsp = self.session.post(restUrl,
json=data,
files=files,
headers=headers)
except requests.exceptions.Timeout:
raise ConfluenceTimeoutError(self.url)
except requests.exceptions.SSLError as ex:
raise ConfluenceSslError(self.url, ex)
except requests.exceptions.ConnectionError as ex:
raise ConfluenceBadServerUrlError(self.url, ex)
if rsp.status_code == 401:
raise ConfluenceAuthenticationFailedUrlError
if rsp.status_code == 403:
raise ConfluencePermissionError("REST POST")
if rsp.status_code == 407:
raise ConfluenceProxyPermissionError
if not rsp.ok:
errdata = self._format_error(rsp, key)
if self.verbosity > 0:
errdata += "\n"
errdata += json.dumps(data, indent=2)
raise ConfluenceBadApiError(errdata)
if not rsp.text:
raise ConfluenceSeraphAuthenticationFailedUrlError
try:
rsp.encoding = self.CONFLUENCE_DEFAULT_ENCODING
json_data = json.loads(rsp.text)
except ValueError:
raise ConfluenceBadServerUrlError(
self.url, "REST reply did not provide valid JSON data.")
return json_data
def delete(self, key, value):
restUrl = self.url + API_REST_BIND_PATH + '/' + key + '/' + value
try:
rsp = self.session.delete(restUrl)
except requests.exceptions.Timeout:
raise ConfluenceTimeoutError(self.url)
except requests.exceptions.SSLError as ex:
raise ConfluenceSslError(self.url, ex)
except requests.exceptions.ConnectionError as ex:
raise ConfluenceBadServerUrlError(self.url, ex)
if rsp.status_code == 401:
raise ConfluenceAuthenticationFailedUrlError
if rsp.status_code == 403:
raise ConfluencePermissionError("REST DELETE")
if rsp.status_code == 407:
raise ConfluenceProxyPermissionError
if not rsp.ok:
raise ConfluenceBadApiError(self._format_error(rsp, key))
def _handle_common_request(self, rsp):
# if confluence or a proxy reports a retry-after delay (to pace us),
# track it to delay the next request made
# (https://datatracker.ietf.org/doc/html/rfc2616.html#section-14.37)
raw_delay = rsp.headers.get(RSP_HEADER_RETRY_AFTER)
if raw_delay:
delay = None
try:
# attempt to parse a seconds value from the header
delay = int(raw_delay)
except ValueError:
# if seconds are not provided, attempt to parse
parsed_dtz = parsedate_tz(raw_delay)
if parsed_dtz:
target_datetime = mktime_tz(parsed_dtz)
delay = target_datetime - time.time()
if delay > 0:
self.next_delay = delay
# if this delay is over a minute, provide a notice to a client
# that requests are being delayed -- but we'll only notify a
# user once
if delay >= 60 and not self._reported_large_delay:
logger.warn('(warning) site has reported a long '
'rate-limit delay ({} seconds)'.format(
math.ceil(delay)))
self._reported_large_delay = True
if rsp.status_code == 401:
raise ConfluenceAuthenticationFailedUrlError
if rsp.status_code == 403:
raise ConfluencePermissionError('rest-call')
if rsp.status_code == 407:
raise ConfluenceProxyPermissionError
if rsp.status_code == 429:
raise ConfluenceRateLimited
def updateSpaceHome(self, page_id):
if not page_id:
return
if self.dryrun:
self._dryrun('updating space home to', page_id)
return
elif self.onlynew:
self._onlynew('space home updates restricted')
return
page = self.rest_client.get('content/' + page_id, None)
try:
self.rest_client.put('space', self.space_name, {
'key': self.space_name,
'name': self.space_display_name,
'homepage': page
})
except ConfluencePermissionError:
raise ConfluencePermissionError(
"""Publish user does not have permission to update """
"""space's homepage."""
)
def remove_attachment(self, id_):
"""
request to remove an attachment
Makes a request to a Confluence instance to remove an existing
attachment.
Args:
id_: the attachment
"""
if self.dryrun:
self._dryrun('removing attachment', id_)
return
elif self.onlynew:
self._onlynew('attachment removal restricted', id_)
return
try:
self.rest_client.delete('content', id_)
except ConfluencePermissionError:
raise ConfluencePermissionError(
"""Publish user does not have permission to delete """
"""from the configured space.""")
def storePage(self, page_name, data, parent_id=None):
uploaded_page_id = None
if self.config.confluence_adv_trace_data:
ConfluenceLogger.trace('data', data['content'])
if self.dryrun:
_, page = self.getPage(page_name, 'version,ancestors')
if not page:
self._dryrun('adding new page ' + page_name)
return None
else:
misc = ''
if parent_id and 'ancestors' in page:
if not any(a['id'] == parent_id for a in page['ancestors']):
if parent_id in self._name_cache:
misc += '[new parent page {} ({})]'.format(
self._name_cache[parent_id], parent_id)
else:
misc += '[new parent page]'
self._dryrun('updating existing page', page['id'], misc)
return page['id']
can_labels = 'labels' not in self.config.confluence_adv_restricted
expand = 'version'
if can_labels and self.append_labels:
expand += ',metadata.labels'
_, page = self.getPage(page_name, expand=expand)
if self.onlynew and page:
self._onlynew('skipping existing page', page['id'])
return page['id']
try:
# new page
if not page:
newPage = {
'type': 'page',
'title': page_name,
'body': {
'storage': {
'representation': 'storage',
'value': data['content'],
}
},
'space': {
'key': self.space_name
},
}
if can_labels:
self._populate_labels(newPage, data['labels'])
if parent_id:
newPage['ancestors'] = [{'id': parent_id}]
try:
rsp = self.rest_client.post('content', newPage)
if 'id' not in rsp:
api_err = ('Confluence reports a successful page ' +
'creation; however, provided no ' +
'identifier.\n\n')
try:
api_err += 'DATA: {}'.format(json.dumps(
rsp, indent=2))
except TypeError:
api_err += 'DATA: <not-or-invalid-json>'
raise ConfluenceBadApiError(api_err)
uploaded_page_id = rsp['id']
except ConfluenceBadApiError as ex:
# Check if Confluence reports that the new page request
# fails, indicating it already exists. This is usually
# (outside of possible permission use cases) that the page
# name's casing does not match. In this case, attempt to
# re-check for the page in a case-insensitive fashion. If
# found, attempt to perform an update request instead.
if str(ex).find('title already exists') == -1:
raise
ConfluenceLogger.verbose('title already exists warning '
'for page {}'.format(page_name))
_, page = self.getPageCaseInsensitive(page_name)
if not page:
raise
if self.onlynew:
self._onlynew('skipping existing page', page['id'])
return page['id']
# update existing page
if page:
last_version = int(page['version']['number'])
updatePage = {
'id': page['id'],
'type': 'page',
'title': page_name,
'body': {
'storage': {
'representation': 'storage',
'value': data['content'],
}
},
'space': {
'key': self.space_name
},
'version': {
'number': last_version + 1
},
}
if can_labels:
labels = list(data['labels'])
if self.append_labels:
labels.extend([lbl.get('name')
for lbl in page.get('metadata', {}).get(
'labels', {}).get('results', {})
])
self._populate_labels(updatePage, labels)
if not self.notify:
updatePage['version']['minorEdit'] = True
if parent_id:
updatePage['ancestors'] = [{'id': parent_id}]
try:
self.rest_client.put('content', page['id'], updatePage)
except ConfluenceBadApiError as ex:
if str(ex).find('unreconciled') != -1:
raise ConfluenceUnreconciledPageError(
page_name, page['id'], self.server_url, ex)
# Confluence Cloud may (rarely) fail to complete a
# content request with an OptimisticLockException/
# StaleObjectStateException exception. It is suspected
# that this is just an instance timing/processing issue.
# If this is observed, wait a moment and retry the
# content request. If it happens again, the put request
# will fail as it normally would.
if str(ex).find('OptimisticLockException') == -1:
raise
ConfluenceLogger.warn(
'remote page updated failed; retrying...')
time.sleep(1)
self.rest_client.put('content', page['id'], updatePage)
uploaded_page_id = page['id']
except ConfluencePermissionError:
raise ConfluencePermissionError(
"""Publish user does not have permission to add page """
"""content to the configured space."""
)
if not self.watch:
self.rest_client.delete('user/watch/content', uploaded_page_id)
return uploaded_page_id
def storeAttachment(self, page_id, name, data, mimetype, hash, force=False):
"""
request to store an attachment on a provided page
Makes a request to a Confluence instance to either publish a new
attachment or update an existing attachment. If the attachment's hash
matches the tracked hash (via the comment field) of an existing
attachment, this call will assume the attachment is already published
and will return (unless forced).
Args:
page_id: the identifier of the page to attach to
name: the attachment name
data: the attachment data
mimetype: the mime type of this attachment
hash: the hash of the attachment
force (optional): force publishing if exists (defaults to False)
Returns:
the attachment identifier
"""
HASH_KEY = 'SCB_KEY'
uploaded_attachment_id = None
_, attachment = self.getAttachment(page_id, name)
# check if attachment (of same hash) is already published to this page
comment = None
if attachment and 'metadata' in attachment:
metadata = attachment['metadata']
if 'comment' in metadata:
comment = metadata['comment']
if not force and comment:
parts = comment.split(HASH_KEY + ':')
if len(parts) > 1:
tracked_hash = parts[1]
if hash == tracked_hash:
ConfluenceLogger.verbose('attachment ({}) is already '
'published to document with same hash'.format(name))
return attachment['id']
if self.dryrun:
if not attachment:
self._dryrun('adding new attachment ' + name)
return None
else:
self._dryrun('updating existing attachment', attachment['id'])
return attachment['id']
elif self.onlynew and attachment:
self._onlynew('skipping existing attachment', attachment['id'])
return attachment['id']
# publish attachment
try:
data = {
'comment': '{}:{}'.format(HASH_KEY, hash),
'file': (name, data, mimetype),
}
if not self.notify:
# using str over bool to support requests pre-v2.19.0
data['minorEdit'] = 'true'
if not attachment:
url = 'content/{}/child/attachment'.format(page_id)
rsp = self.rest_client.post(url, None, files=data)
uploaded_attachment_id = rsp['results'][0]['id']
else:
url = 'content/{}/child/attachment/{}/data'.format(
page_id, attachment['id'])
rsp = self.rest_client.post(url, None, files=data)
uploaded_attachment_id = rsp['id']
if not self.watch:
self.rest_client.delete('user/watch/content',
uploaded_attachment_id)
except ConfluencePermissionError:
raise ConfluencePermissionError(
"""Publish user does not have permission to add an """
"""attachment to the configured space."""
)
return uploaded_attachment_id
def store_page(self, page_name, data, parent_id=None):
"""
request to store page information to a confluence instance
Performs a request which will attempt to store the provided page
information and publish it to either a new page with the provided page
name or update an existing page with a matching page name. Pages will be
published at the root of a Confluence space unless a provided parent
page identifier is provided.
Args:
page_name: the page title to use on the updated page
data: the page data to apply
parent_id (optional): the id of the ancestor to use
"""
uploaded_page_id = None
if self.config.confluence_adv_trace_data:
logger.trace('data', data['content'])
if self.dryrun:
_, page = self.get_page(page_name, 'version,ancestors')
if not page:
self._dryrun('adding new page ' + page_name)
return None
else:
misc = ''
if parent_id and 'ancestors' in page:
if not any(a['id'] == parent_id
for a in page['ancestors']):
if parent_id in self._name_cache:
misc += '[new parent page {} ({})]'.format(
self._name_cache[parent_id], parent_id)
else:
misc += '[new parent page]'
self._dryrun('updating existing page', page['id'], misc)
return page['id']
expand = 'version'
if self.append_labels:
expand += ',metadata.labels'
_, page = self.get_page(page_name, expand=expand)
if self.onlynew and page:
self._onlynew('skipping existing page', page['id'])
return page['id']
try:
# new page
if not page:
new_page = self._build_page(page_name, data)
self._populate_labels(new_page, data['labels'])
if parent_id:
new_page['ancestors'] = [{'id': parent_id}]
try:
rsp = self.rest_client.post('content', new_page)
if 'id' not in rsp:
api_err = ('Confluence reports a successful page ' +
'creation; however, provided no ' +
'identifier.\n\n')
try:
api_err += 'DATA: {}'.format(
json.dumps(rsp, indent=2))
except TypeError:
api_err += 'DATA: <not-or-invalid-json>'
raise ConfluenceBadApiError(-1, api_err)
uploaded_page_id = rsp['id']
# if we have labels and this is a non-cloud instance,
# initial labels need to be applied in their own request
labels = new_page['metadata']['labels']
if not self.cloud and labels:
url = 'content/{}/label'.format(uploaded_page_id)
self.rest_client.post(url, labels)
except ConfluenceBadApiError as ex:
# Check if Confluence reports that the new page request
# fails, indicating it already exists. This is usually
# (outside of possible permission use cases) that the page
# name's casing does not match. In this case, attempt to
# re-check for the page in a case-insensitive fashion. If
# found, attempt to perform an update request instead.
if str(ex).find('title already exists') == -1:
raise
logger.verbose('title already exists warning '
'for page {}'.format(page_name))
_, page = self.get_page_case_insensitive(page_name)
if not page:
raise
if self.onlynew:
self._onlynew('skipping existing page', page['id'])
return page['id']
# update existing page
if page:
self._update_page(page, page_name, data, parent_id=parent_id)
uploaded_page_id = page['id']
except ConfluencePermissionError:
raise ConfluencePermissionError(
"""Publish user does not have permission to add page """
"""content to the configured space.""")
if not self.watch:
self.rest_client.delete('user/watch/content', uploaded_page_id)
return uploaded_page_id