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 forscheme
, or local (return True) otherwise. Also returns False ifsrc
isNone
.Parameters: src (str) – the value of image tag’s src
attributeReturns: 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 animg
tag, load it from disk. If the path is relative, it will be loaded relative toself._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’simghdr.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 ofbytes
)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 asrc
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 thesrc
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 inReturns: 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
andimages
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), orplace
(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. Setting this to True forces
editable
to be True. - header_alert (
str
ortuple
) – If not None, insert a Jive RTE “Alert” macro at the beginning of the html (after the Table of Contents, if present). Setting this to forceseditable
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
ortuple
) – If not None, insert a Jive RTE “Alert” macro at the end of the html. Setting this forceseditable
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: Raises:
-
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), orplace
(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. Setting this to True forces
editable
to be True. - header_alert (
str
ortuple
) – If not None, insert a Jive RTE “Alert” macro at the beginning of the html (after the Table of Contents, if present). Setting this to forceseditable
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
ortuple
) – If not None, insert a Jive RTE “Alert” macro at the end of the html. Setting this forceseditable
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 ofcreate_html_document()
orupdate_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:
-
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
ortuple
) – 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
orlxml.etree._ElementTree
- root (
-
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 toReturns: root node of etree containing modified HTML Return type: lxml.etree._Element
orlxml.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
orlxml.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 inReturns: root node of etree with CSS inlined Return type: lxml.etree._Element
orlxml.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 thestyle
attribute from anydiv
elements with a class ofsourceCode
. - In all
<pre>
elements, convert\n
to<br />\n
vianewline_to_br()
. - For any HTML tags that are keys of
TAGSTYLES
, set their style attribute according toTAGSTYLES
. - Change the
name
attribute on alla
elements to replace dashes with underscores, and do the same on thehref
attributes of anya
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 anydiv
elements with a class ofsourceCode
.
Returns: root node of etree containing jive-ized HTML
Return type: lxml.etree._Element
orlxml.etree._ElementTree
- If
-
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: Returns: jive-ized HTML
Return type:
-
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
andimages
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 orcreate_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), orplace
(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. Setting this to True forces
editable
to be True. - header_alert (
str
ortuple
) – If not None, insert a Jive RTE “Alert” macro at the beginning of the html (after the Table of Contents, if present). Setting this to forceseditable
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
ortuple
) – If not None, insert a Jive RTE “Alert” macro at the end of the html. Setting this forceseditable
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 orcreate_html_document()
.
Returns: dict describing the created content object in Jive. See JiveContent Return Dict Format for details.
Return type: Raises: - content_id (str) – the Jive contentID to update. This is the
-
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 modifyReturns: modified element Return type: lxml.etree._Element