Return behavior of functions should be normalized

[kamakazikamikaze]

The Confluence class has several functions documented to return a specific type. However, when a target page does not exist the function will log an error and return None. This behavior is not always documented for the user to expect/check.

Confluence.get_page_by_title will intercept an error and return None, which is documented for the user.

atlassian-python-api/atlassian/confluence.py

Lines 275 to 288 in 63c2faf

	def get_page_by_title(self, space, title, start=0, limit=1, expand=None, type="page"):
	"""
	Returns the first page on a piece of Content.
	:param space: Space key
	:param title: Title of the page
	:param start: OPTIONAL: The start point of the collection to return. Default: None (0).
	:param limit: OPTIONAL: The limit of the number of labels to return, this may be restricted by
	fixed system limits. Default: 1.
	:param expand: OPTIONAL: expand e.g. history
	:param type: OPTIONAL: Type of content: Page or Blogpost. Defaults to page
	:return: The JSON data returned from searched results the content endpoint, or the results of the
	callback. Will raise requests.HTTPError on bad input, potentially.
	If it has IndexError then return the None.
	"""

atlassian-python-api/atlassian/confluence.py

Lines 314 to 319 in 63c2faf

	try:
	return response.get("results")[0]
	except (IndexError, TypeError) as e:
	log.error("Can't find '%s' page on the %s!", title, self.url)
	log.debug(e)
	return None

Confluence.get_tables_from_page will return a dictionary with a completely different key structure which isn't documented. Either the same structure should be followed with "number_of_tables_in_page" set to 0 or an exception should be raised.

atlassian-python-api/atlassian/confluence.py

Lines 374 to 385 in 63c2faf

	if len(tables_raw) > 0:
	return json.dumps(
	{
	"page_id": page_id,
	"number_of_tables_in_page": len(tables_raw),
	"tables_content": tables_raw,
	}
	)
	else:
	return {
	"No tables found for page: ": page_id,
	}

Confluence.attach_content will return the API response upon success or None when a target page does not exist. This is not documented.

atlassian-python-api/atlassian/confluence.py

Lines 1265 to 1268 in 63c2faf

	return response
	else:
	log.warning("No 'page_id' found, not uploading attachments")
	return None

Confluence.download_attachments_from_page returns a str if no attachments are found, otherwise it returns a dict.

Confluence.update_page will return None if page does not exist. This is not documented for the user.

atlassian-python-api/atlassian/confluence.py

Lines 1725 to 1728 in 63c2faf

	except (IndexError, TypeError) as e:
	log.error("Can't find '%s' %s!", title, type)
	log.debug(e)
	return None

These are just a small sample of functions where behavior diverges from the documentation or unnecessarily changes the return type. I would suggest either:

• Raising an exception when a target page does not exist (similar to an ApiNotFoundError, but as a new unique exception). However this would break backwards-compatibility for existing users.
• Correcting function documentation to warn of the varying return types and/or normalizing structure of certain returns (e.g. dict for Confluence.get_tables_from_page using same keys).