l.a.b.s.FormattersAPI : class documentation

Part of lp.app.browser.stringformatter View In Hierarchy

Adapter from strings to HTML formatted text.
Method __init__ Undocumented
Method nl_to_br Quote HTML characters, then replace newlines with <br /> tags.
Method escape Undocumented
Method break_long_words Add manual word breaks to long words.
Method text_to_html Quote text according to DisplayingParagraphsOfText.
Method text_to_html_with_target See `text_to_html`().
Method nice_pre <pre>, except the browser knows it is allowed to break long lines
Method email_to_html text_to_html and hide signatures and full-quoted emails.
Method obfuscate_email Obfuscate an email address if there's no authenticated user.
Method strip_email Strip out things that may be email.
Method linkify_email Linkify any email address recognised in Launchpad.
Method lower Return the string in lowercase
Method shorten Use like tal:content="context/foo/fmt:shorten/60".
Method ellipsize Use like tal:content="context/foo/fmt:ellipsize/60".
Method format_diff Format the string as a diff in a table with line numbers.
Method format_ssdiff Format the string as a side-by-side diff.
Method css_id Return a CSS compliant id.
Method zope_css_id Return a CSS compliant id compatible with zope's form fields.
Method oops_id Format an OOPS ID for display.
Method markdown Undocumented
Method traverse Undocumented
Static Method _substitute_matchgroup_for_spaces Return a string made up of '&nbsp;' for each character in the
Static Method _linkify_bug_number Undocumented
Static Method _handle_parens_in_trailers Move closing parens from the trailer back into the url if needed.
Static Method _split_url_and_trailers Given a URL return a tuple of the URL and punctuation trailers.
Static Method _linkify_url_should_be_ignored Don't linkify URIs consisting of just the protocol.
Static Method _linkify_substitution Undocumented
Static Method _linkify_substitution_with_target See `_linkify_substitution`().
Method _ssdiff_emit_line Undocumented
Method _ssdiff_emit_queued_lines Undocumented
Method _css_id Return a CSS compliant id.
def __init__(self, stringtoformat):
Undocumented
def nl_to_br(self):
Quote HTML characters, then replace newlines with <br /> tags.
def escape(self):
Undocumented
def break_long_words(self):
Add manual word breaks to long words.
@staticmethod
def _substitute_matchgroup_for_spaces(match):
Return a string made up of '&nbsp;' for each character in the first match group.

Used when replacing leading spaces with nbsps.

There must be only one match group.

@staticmethod
def _linkify_bug_number(text, bugnum, trailers=''):
Undocumented
@staticmethod
def _handle_parens_in_trailers(url, trailers):
Move closing parens from the trailer back into the url if needed.

If there are opening parens in the url that are matched by closing parens at the start of the trailer, those closing parens should be part of the url.

@staticmethod
def _split_url_and_trailers(url):
Given a URL return a tuple of the URL and punctuation trailers.
Returnsan unescaped url, an unescaped trailer.
@staticmethod
def _linkify_url_should_be_ignored(url):
Don't linkify URIs consisting of just the protocol.
@staticmethod
def _linkify_substitution(match):
Undocumented
@staticmethod
def _linkify_substitution_with_target(match): 
See `_linkify_substitution`().

The target attribute of the links will be updated to point to
"_new", so that links will open in a new window.
def text_to_html(self, linkify_text=True, linkify_substitution=None, last_paragraph_class=None):
Quote text according to DisplayingParagraphsOfText.
def text_to_html_with_target(self): 
See `text_to_html`().

URLs will be linkified with a target="_new" attribute.
def nice_pre(self):
<pre>, except the browser knows it is allowed to break long lines

Note that CSS will eventually have a property to specify this behaviour, but we want this now. To do this we need to use the mozilla specific -moz-pre-wrap value of the white-space property. We try to fall back for IE by using the IE specific word-wrap property.

TODO: Test IE compatibility. StuartBishop 20041118

def email_to_html(self):
text_to_html and hide signatures and full-quoted emails.

This method wraps inclusions like signatures and PGP blocks in <span class="foldable"></span> tags. Quoted passages are wrapped <span class="foldable-quoted"></span> tags. The tags identify the extra content in the message to the presentation layer. CSS and JavaScript may use this markup to control the content's display behaviour.

def obfuscate_email(self):
Obfuscate an email address if there's no authenticated user.

The email address is obfuscated as <email address hidden>.

This formatter is intended to hide possible email addresses from unauthenticated users who view this text on the Web. Run this before the text is converted to html because text-to-html and email-to-html will insert markup into the address. eg. foo/fmt:obfuscate-email/fmt:email-to-html

The pattern used to identify an email address is not 2822. It strives to match any possible email address embedded in the text. For example, mailto:person@domain.dom and http://person:password@domain.dom both match, though the http match is in fact not an email address.

def strip_email(self):
Strip out things that may be email.

This is a variation on obfuscate_email for when we are generating a snipped for page metadata: we don't want to waste space spelling out "<email address hidden>", and we do want to strip addresses even for logged-in users in case they use the summary in a sharing tool.

def linkify_email(self, preloaded_person_data=None):
Linkify any email address recognised in Launchpad.

If an email address is recognised as one registered in Launchpad, it is linkified to point to the profile page for that person.

Note that someone could theoretically register any old email address in Launchpad and then have it linkified. This may or not may be a concern but is noted here for posterity anyway.

def lower(self):
Return the string in lowercase
def shorten(self, maxlength):
Use like tal:content="context/foo/fmt:shorten/60".
def ellipsize(self, maxlength):
Use like tal:content="context/foo/fmt:ellipsize/60".
def format_diff(self):
Format the string as a diff in a table with line numbers.
def _ssdiff_emit_line(self, result, row, cells):
Undocumented
def _ssdiff_emit_queued_lines(self, result, queue_removed, queue_added):
Undocumented
def format_ssdiff(self):
Format the string as a side-by-side diff.
def css_id(self, prefix=None):
Return a CSS compliant id.
def zope_css_id(self, prefix=None):
Return a CSS compliant id compatible with zope's form fields.

The strip pattern allows ids which contain periods which is required for compatibility with zope form fields.

def _css_id(self, strip_pattern, prefix=None):
Return a CSS compliant id.

The id may contain letters, numbers, hyphens and underscores. The first character must be a letter. Unsupported characters are converted to hyphens. Multiple characters are replaced by a single hyphen. The letter 'j' will start the id if the string's first character is not a letter.

Parametersprefixan optional string to prefix to the id. It can be used to ensure that the start of the id is predictable.
def oops_id(self):
Format an OOPS ID for display.
def markdown(self):
Undocumented
def traverse(self, name, furtherPath):
Undocumented
API Documentation for Launchpad, generated by pydoctor at 2022-06-16 00:00:12.