jiveapi.content module¶

class jiveapi.content.JiveContent(api, image_dir=None)[source]¶

Bases: object

High-level Jive API interface that wraps JiveApi with convenience methods for common tasks relating to manipulating Content and Image objects.

Methods in this class that involve uploading images require storing state out-of-band. For information on that state, see JiveContent Images Dict Format.

Parameters:	api (jiveapi.api.JiveApi) – authenticated API instance image_dir (str) – The directory/path on disk to load images relative to. This should be an absolute path. If not specified, the result of `os.getcwd()` will be used.

static _is_local_image(src)[source]¶

Given the string path to an image, return True if it appears to be a local image and False if it appears to be a remote image. We consider an image remote (return False) if urllib.parse.urlparse() returns an empty string for scheme, or local (return True) otherwise. Also returns False if src is None.

Parameters:	src (str) – the value of image tag’s `src` attribute
Returns:	True if the image appears to be local (relative or absolute path) or False if it appears to be remote
Return type:	bool

_load_image_from_disk(img_path)[source]¶

Given the path to an image taken from the src attribute of an img tag, load it from disk. If the path is relative, it will be loaded relative to self._image_dir. Return a 3-tuple of a string describing the Content-Type of the image, the raw bytes of the image data, and the sha256 sum of the image data. The content type is determined using the Python standard library’s imghdr.what().

Parameters:	img_path (str) – path to the image on disk
Returns:	(`str` Content-Type, `bytes` binary image content read from disk, `str` hex sha256 sum of `bytes`)
Return type:	tuple

_upload_images(root, images={})[source]¶

Given the root Element of a (HTML) document, find all img tags. For any of them that have a src attribute pointing to a local image (as determined by _is_local_image()), read the corresponding image file from disk, upload it to the Jive server, and then replace the src attribute with the upload temporary URL and add an entry to the image dictionary (second element of the return value).

The format of the second element of the return value is the images dict format described in this class under JiveContent Images Dict Format.

Important: The images dict (second element of return value) must be externally persisted.

Parameters:	root (`lxml.etree._Element`) – root node of etree to inline CSS in
Returns:	2-tuple of (`root` with attributes modified as appropriate, and a dict mapping the original image paths to the API response data for them)
Return type:	tuple

create_html_document(subject, html, tags=[], place_id=None, visibility=None, set_datetime=None, inline_css=True, jiveize=True, handle_images=True, editable=False, toc=False, header_alert=None, footer_alert=None)[source]¶

Create a HTML Document in Jive. This is a convenience wrapper around create_content() to assist with forming the content JSON, as well as to assist with HTML handling.

Important: In order to update the Document in the future, the entire return value of this method must be externally persisted and passed in to future method calls via the content_id and images parameters.

Parameters:	subject (str) – The subject / title of the Document. html (str) – The HTML for the Document’s content. See the notes in the jiveapi package documentation about HTML handling. tags (list) – List of string tags to add to the Document place_id (str) – If specified, post this document in the Place with the specified placeID. According to the API documentation for the Document type (linked above), this requires visibility to be set to “place”. visibility (str) – The visibility policy for the Document. Valid values per the API documentation are: `all` (anyone with appropriate permissions can see the content), `hidden` (only the author can see the content), or `place` (place permissions specify which users can see the content). set_datetime (datetime.datetime) – datetime.datetime to set as the publish time. This allows backdating Documents to match their source publish time. inline_css (bool) – if True, pass input HTML through `inline_css_etree()` to convert any embedded CSS to inline CSS so that Jive will preserve/respect it. jiveize (bool) – if True, pass input HTML through `jiveize_etree()` to make it look more like how Jive styles HTML internally. handle_images (bool) – if True, pass input HTML through `_upload_images()` to upload all local images to Jive. editable (bool) – set to True if the content HTML includes Jive RTE Macros. Otherwise, they will not be processed by Jive. toc (bool) – If True, insert the Jive RTE “Table of Contents” macro at the beginning of the html, after header_alert (if specified). Setting this to True forces `editable` to be True. header_alert (`str` or `tuple`) – If not None, insert a Jive RTE “Alert” macro at the beginning of the html (before the Table of Contents, if present). Setting this to forces `editable` to be True. The value of this parameter can either be a string which will be used as the content of a “info” alert box, or a 2-tuple of the string alert box type (one of “info”, “success”, “warning” or “danger”) and the string content. footer_alert (`str` or `tuple`) – If not None, insert a Jive RTE “Alert” macro at the end of the html. Setting this forces `editable` to be True. The value of this parameter can either be a string which will be used as the content of a “info” alert box, or a 2-tuple of the string alert box type (one of “info”, “success”, “warning” or “danger”) and the string content.
Returns:	dict describing the created content object in Jive. See JiveContent Return Dict Format for details.
Return type:	dict
Raises:	`RequestFailedException`, `ContentConflictException`

dict_for_html_document(subject, html, tags=[], place_id=None, visibility=None, inline_css=True, jiveize=True, handle_images=True, editable=False, toc=False, header_alert=None, footer_alert=None, images={})[source]¶

Generate the API (dict/JSON) representation of a HTML Document in Jive, used by create_html_document().

The format of the second element of the return value is the images dict format described in this class under JiveContent Images Dict Format.

Important: The images dict (second element of return value) must be externally persisted or else all images will be re-uploaded every time this is run.

Parameters:	subject (str) – The subject / title of the Document. html (str) – The HTML for the Document’s content. See the notes in the jiveapi package documentation about HTML handling. tags (list) – List of string tags to add to the Document place_id (str) – If specified, post this document in the Place with the specified placeID. According to the API documentation for the Document type (linked above), this requires visibility to be set to “place”. visibility (str) – The visibility policy for the Document. Valid values per the API documentation are: `all` (anyone with appropriate permissions can see the content), `hidden` (only the author can see the content), or `place` (place permissions specify which users can see the content). set_datetime (datetime.datetime) – datetime.datetime to set as the publish time. This allows backdating Documents to match their source publish time. inline_css (bool) – if True, pass input HTML through `inline_css_etree()` to convert any embedded CSS to inline CSS so that Jive will preserve/respect it. jiveize (bool) – if True, pass input HTML through `jiveize_etree()` to make it look more like how Jive styles HTML internally. handle_images (bool) – if True, pass input HTML through `_upload_images()` to upload all local images to Jive. editable (bool) – set to True if the content HTML includes Jive RTE Macros. Otherwise, they will not be processed by Jive. toc (bool) – If True, insert the Jive RTE “Table of Contents” macro at the beginning of the html, after header_alert (if specified). Setting this to True forces `editable` to be True. header_alert (`str` or `tuple`) – If not None, insert a Jive RTE “Alert” macro at the beginning of the html (before the Table of Contents, if present). Setting this to forces `editable` to be True. The value of this parameter can either be a string which will be used as the content of a “info” alert box, or a 2-tuple of the string alert box type (one of “info”, “success”, “warning” or “danger”) and the string content. footer_alert (`str` or `tuple`) – If not None, insert a Jive RTE “Alert” macro at the end of the html. Setting this forces `editable` to be True. The value of this parameter can either be a string which will be used as the content of a “info” alert box, or a 2-tuple of the string alert box type (one of “info”, “success”, “warning” or “danger”) and the string content. images (dict) – a dict of information about images that have been already uploaded for this Document. This parameter should be the value of the `images` key from the return value of this method (or of `create_html_document()` or `update_html_document()`).
Returns:	2-tuple of (`dict` representation of the desired Document ready to pass to the Jive API, `dict` images data to persist for updates)
Return type:	tuple

static etree_add_alert(root, alert_spec, header=True)[source]¶

Add an alert macro to the specified tree, either at the beginning or end of the body.

Parameters:	root (`lxml.etree._Element`) – root node of etree to add Alert macro to alert_spec (`str` or `tuple`) – The value of this parameter can either be a string which will be used as the content of a “info” alert box, or a 2-tuple of the string alert box type (one of “info”, “success”, “warning” or “danger”) and the string content. header (bool) – add to beginning of body element (header) if True, otherwise add to end of body element (footer)
Returns:	root node of etree containing modified HTML
Return type:	`lxml.etree._Element` or `lxml.etree._ElementTree`

static etree_add_toc(root)[source]¶

Return the provided Element with a Jive RTE “Table of Contents” macro prepended to the body.

Parameters:	root (`lxml.etree._Element`) – root node of etree to add Table of Contents macro to
Returns:	root node of etree containing modified HTML
Return type:	`lxml.etree._Element` or `lxml.etree._ElementTree`

static html_to_etree(html)[source]¶

Given a string of HTML, parse via etree.fromstring() and return either the roottree if a doctype is present or the root otherwise.

Important Note: If the document passed in has a doctype, it will be stripped out. That’s fine, since Jive wouldn’t recognize it anyway.

Parameters:	html (str) – HTML string
Returns:	root of the HTML tree for parsing and manipulation purposes
Return type:	`lxml.etree._Element` or `lxml.etree._ElementTree`

static inline_css_etree(root)[source]¶

Given an etree root node, uses premailer’s transform method to convert all CSS from embedded/internal/external to inline, as Jive only allows inline CSS.

Parameters:	root (`lxml.etree._Element`) – root node of etree to inline CSS in
Returns:	root node of etree with CSS inlined
Return type:	`lxml.etree._Element` or `lxml.etree._ElementTree`

static inline_css_html(html)[source]¶

Wrapper around inline_css_etree() that takes a string of HTML and returns a string of HTML.

Parameters:	html (str) – input HTML to inline CSS in
Returns:	HTML with embedded/internal CSS inlined
Return type:	str

static jiveize_etree(root, no_sourcecode_style=True)[source]¶

Given a lxml etree root, perform some formatting and style fixes to get each element in it to render correctly in the Jive UI:

If no_sourcecode_style is True, remove the style attribute from any div elements with a class of sourceCode.
In all <pre> elements, convert \n to <br />\n via newline_to_br().
For any HTML tags that are keys of TAGSTYLES, set their style attribute according to TAGSTYLES.
Change the name attribute on all a elements to replace dashes with underscores, and do the same on the href attributes of any a elements that begin with #. Apparently Jive breaks anchor links that contain dashes.
For any element with an id attribute, append a named anchor to it with a name the same as its’ id. If it is an anchor, copy the id to the name. We do this because Jive removes or overwrites many id attributes.

Elements which have a “jivemacro” attribute present will not be modified.

Parameters:	root (`lxml.etree._Element`) – root node of etree to jive-ize no_sourcecode_style (bool) – If True, remove the `style` attribute from any `div` elements with a class of `sourceCode`.
Returns:	root node of etree containing jive-ized HTML
Return type:	`lxml.etree._Element` or `lxml.etree._ElementTree`

static jiveize_html(html, no_sourcecode_style=True)[source]¶

Wrapper around jiveize_etree() that takes a string of HTML and returns a string of HTML.

Parameters:	html (str) – input HTML to Jive-ize no_sourcecode_style (bool) – If True, remove the `style` attribute from any `div` elements with a class of `sourceCode`.
Returns:	jive-ized HTML
Return type:	str

update_html_document(content_id, subject, html, tags=[], place_id=None, visibility=None, set_datetime=None, inline_css=True, jiveize=True, handle_images=True, editable=False, toc=False, header_alert=None, footer_alert=None, images={})[source]¶

Update a HTML Document in Jive. This is a convenience wrapper around update_content() to assist with forming the content JSON, as well as to assist with HTML handling.

Important: In order to update the Document in the future, the entire return value of this method must be externally persisted and passed in to future method calls via the content_id and images parameters.

Parameters:	content_id (str) – the Jive contentID to update. This is the `contentID` element of the JiveContent Return Dict Format that is returned by this method or `create_html_document()`. subject (str) – The subject / title of the Document. html (str) – The HTML for the Document’s content. See the notes in the jiveapi package documentation about HTML handling. tags (list) – List of string tags to add to the Document place_id (str) – If specified, post this document in the Place with the specified placeID. According to the API documentation for the Document type (linked above), this requires visibility to be set to “place”. visibility (str) – The visibility policy for the Document. Valid values per the API documentation are: `all` (anyone with appropriate permissions can see the content), `hidden` (only the author can see the content), or `place` (place permissions specify which users can see the content). set_datetime (datetime.datetime) – datetime.datetime to set as the publish time. This allows backdating Documents to match their source publish time. inline_css (bool) – if True, pass input HTML through `inline_css_etree()` to convert any embedded CSS to inline CSS so that Jive will preserve/respect it. jiveize (bool) – if True, pass input HTML through `jiveize_etree()` to make it look more like how Jive styles HTML internally. handle_images (bool) – if True, pass input HTML through `_upload_images()` to upload all local images to Jive. editable (bool) – set to True if the content HTML includes Jive RTE Macros. Otherwise, they will not be processed by Jive. toc (bool) – If True, insert the Jive RTE “Table of Contents” macro at the beginning of the html, after header_alert (if specified). Setting this to True forces `editable` to be True. header_alert (`str` or `tuple`) – If not None, insert a Jive RTE “Alert” macro at the beginning of the html (before the Table of Contents, if present). Setting this to forces `editable` to be True. The value of this parameter can either be a string which will be used as the content of a “info” alert box, or a 2-tuple of the string alert box type (one of “info”, “success”, “warning” or “danger”) and the string content. footer_alert (`str` or `tuple`) – If not None, insert a Jive RTE “Alert” macro at the end of the html. Setting this forces `editable` to be True. The value of this parameter can either be a string which will be used as the content of a “info” alert box, or a 2-tuple of the string alert box type (one of “info”, “success”, “warning” or “danger”) and the string content. images (dict) – a dict of information about images that have been already uploaded for this Document. This parameter should be the value of the `images` key from the JiveContent Return Dict Format that is returned by this method or `create_html_document()`.
Returns:	dict describing the created content object in Jive. See JiveContent Return Dict Format for details.
Return type:	dict
Raises:	`RequestFailedException`, `ContentConflictException`

jiveapi.content.TAGSTYLES = {'blockquote': 'padding: 0 1em; color: #6a737d; border-left: 0.25em solid #dfe2e5; margin-top: 0; margin-bottom: 16px;', 'code': 'display: inline; max-width: auto; padding: 0; margin: 0; overflow: visible; line-height: inherit; word-wrap: normal; background-color: transparent; border: 0;', 'h1': 'color:#24292e; padding-bottom: 0.3em; font-size: 2em; border-bottom: 1px solid #eaecef', 'h2': 'color:#24292e; margin-top: 24px; margin-bottom: 16px; font-weight: 600; line-height: 1.25; padding-bottom: 0.3em; font-size: 1.5em; border-bottom: 1px solid #eaecef;', 'h3': 'color:#24292e; font-size: 1.25em; margin-top: 24px; margin-bottom: 16px; font-weight: 600; line-height: 1.25;', 'h4': 'color:#24292e; font-size: 1em; margin-top: 24px; margin-bottom: 16px; font-weight: 600; line-height: 1.25;', 'h5': 'color:#24292e; font-size: 0.8em; margin-top: 24px; margin-bottom: 16px; font-weight: 600; line-height: 1.25;', 'img': 'max-width:100%; box-sizing:content-box;', 'ol': 'color:#24292e; padding-left: 2em; margin-top: 0; margin-bottom: 16px;', 'p': 'color:#24292e; margin-top: 0; margin-bottom: 16px;', 'pre': 'word-wrap: normal; padding: 16px; overflow: auto; font-size: 85%; line-height: 1.45; background-color: #f6f8fa; border-radius: 3px; margin-top:2px', 'table': 'display: block; width: 100%; overflow: auto;', 'tbody': 'display: table-row-group; vertical-align: middle; border-color: inherit;', 'td': 'padding: 6px 13px; border: 1px solid #dfe2e5; ', 'th': 'padding: 6px 13px; border: 1px solid #dfe2e5; font-weight: 600; text-align: center;background-color: #f6f8fa; ', 'thead': 'display: table-header-group; vertical-align: middle; border-color: inherit;', 'tr': 'background-color: #fff; border-top: 1px solid #c6cbd1;', 'ul': 'color:#24292e; padding-left: 2em; margin-top: 0; margin-bottom: 16px;'}¶: This is a mapping of certain HTML tags to the Jive styles to apply to them.

jiveapi.content.newline_to_br(elem)[source]¶

Helper function for jiveize_html(). Given a html Element, convert it to a string, add explicit <br /> tags before all newlines, and return a new Element with that content.

Parameters:	elem (`lxml.etree._Element`) – element to modify
Returns:	modified element
Return type:	`lxml.etree._Element`