timApp.documentmodel package

Submodules

timApp.documentmodel.attributeparser module

class timApp.documentmodel.attributeparser.AttributeParser(string='')

Bases: object

static attr_list_end_char()

static attr_list_start_char()

current_char()

eat_whitespace()

find_attr_list_start_char()

get_attributes()

get_char()

has_chars()

set_str(string)

try_parse_attr_list_end_char()

try_parse_class()

try_parse_hash()

try_parse_helper(char)

try_parse_keyvaluepair()

exception timApp.documentmodel.attributeparser.AttributeParserException

Bases: Exception

timApp.documentmodel.clipboard module

class timApp.documentmodel.clipboard.Clipboard(files_root: str)

Bases: object

class UserClipboard(parent: timApp.documentmodel.clipboard.Clipboard, user_id: int)

Bases: object

clear()

clear_refs()

copy_pars(doc: documentmodel.document.Document, par_start: str, par_end: str, area_name: typing.Union[str, NoneType] = None, ref_doc: typing.Union[documentmodel.document.Document, NoneType] = None, disable_ref: bool = False) → typing.List[documentmodel.docparagraph.DocParagraph]

cut_pars(doc: documentmodel.document.Document, par_start: str, par_end: str, area_name: typing.Union[str, NoneType] = None) → typing.List[documentmodel.docparagraph.DocParagraph]

delete_from_source()

get_clipfilename() → str

get_metafilename() → str

get_parreffilename() → str

get_reffilename() → str

paste_after(doc: documentmodel.document.Document, par_id: str, as_ref: bool = False) → typing.List[documentmodel.docparagraph.DocParagraph]

paste_before(doc: documentmodel.document.Document, par_id: str, as_ref: bool = False) → typing.List[documentmodel.docparagraph.DocParagraph]

read(as_ref: typing.Union[bool, NoneType] = False, force_parrefs: typing.Union[bool, NoneType] = False) → typing.Union[typing.List[typing.Dict[str, str]], NoneType]

read_metadata() → typing.Dict[str, str]

write(pars: typing.List[typing.Dict[str, typing.Generic]])

write_metadata(**kwargs)

write_refs(pars: typing.List[documentmodel.docparagraph.DocParagraph], area_name: typing.Union[str, NoneType])

Clipboard.clear_all()

Clipboard.get(user_id: int)

Clipboard.get_path()

timApp.documentmodel.docparagraph module

class timApp.documentmodel.docparagraph.DocParagraph(doc, files_root: typing.Union[str, NoneType] = None)

Bases: object

add_class(class_name)

add_link(doc_id: int)

classmethod create(doc, par_id: typing.Union[str, NoneType] = None, md: str = '', t: typing.Union[str, NoneType] = None, html: typing.Union[str, NoneType] = None, attrs: typing.Union[typing.Dict[KT, VT], NoneType] = None, props: typing.Union[typing.Dict[KT, VT], NoneType] = None, files_root: typing.Union[str, NoneType] = None) → timApp.documentmodel.docparagraph.DocParagraph

classmethod create_area_reference(doc, area_name: str, r: typing.Union[str, NoneType] = None, add_rd: typing.Union[bool, NoneType] = True, files_root: typing.Union[str, NoneType] = None)

create_reference(doc, r: typing.Union[str, NoneType] = None, add_rd: bool = True) → timApp.documentmodel.docparagraph.DocParagraph

default_files_root = 'tim_files'

dict() → typing.Dict[KT, VT]

classmethod from_dict(doc, d: typing.Dict[KT, VT], files_root: typing.Union[str, NoneType] = None) → timApp.documentmodel.docparagraph.DocParagraph

classmethod get(doc, par_id: str, t: str, files_root: typing.Union[str, NoneType] = None) → timApp.documentmodel.docparagraph.DocParagraph

get_attr(attr_name: str, default_value: typing.Generic = None, dereference: bool = False) → typing.Generic

get_attrs(base_attrs: typing.Union[typing.Dict[KT, VT], NoneType] = None) → typing.Dict[KT, VT]

get_attrs_str() → str

get_auto_macro_values(macros, macro_delim, auto_macro_cache, heading_cache)

Gets the auto macros values for the current paragraph. Auto macros include things like current heading/table/figure numbers.

Parameters:

• heading_cache – A cache object to store headings into. The key is paragraph id and value is a list of headings in that paragraph.
• macros – Macros to apply for the paragraph.
• auto_macro_cache – The cache object from which to retrieve and store the auto macro data.
• macro_delim – Delimiter for macros.

Returns:

Auto macro values as a dict.

Returns:

A dict(str, dict(int,int)) containing the auto macro information.

get_base_path() → str

get_class_str() → str

classmethod get_default_files_root()

get_doc_id() → int

get_exported_markdown() → str

get_hash() → str

get_html(from_preview: bool = True) → str

Gets the html for the paragraph. :param from_preview: Whether this is called from a preview window or not.

If True, previous paragraphs are preloaded too and the result is not cached. Safer, but slower. Set explicitly False if you know what you’re doing.

Returns:html string

get_id() → str

classmethod get_latest(doc, par_id: str, files_root: typing.Union[str, NoneType] = None) → timApp.documentmodel.docparagraph.DocParagraph

get_links() → typing.List[str]

get_markdown() → str

get_original() → timApp.documentmodel.docparagraph.DocParagraph

get_path() → str

get_properties(base_props: typing.Union[typing.Dict[KT, VT], NoneType] = None) → typing.Dict[KT, VT]

get_rd() → typing.Union[int, NoneType]

get_referenced_pars(edit_window: bool = False, set_html: bool = True, source_doc: bool = None, tr_get_one: bool = True, cycle: typing.Union[typing.List[typing.Tuple[int, str]], NoneType] = None)

get_title() → typing.Union[str, NoneType]

classmethod get_unloaded_pars(pars, settings, auto_macro_cache, heading_cache, clear_cache=False)

Finds out which of the given paragraphs need to be preloaded again.

Parameters:

• pars – The list of paragraphs to be processed.
• settings – The settings for the document.
• auto_macro_cache – The cache object from which to retrieve and store the auto macro data.
• heading_cache – A cache object to store headings into. The key is paragraph id and value is a list of headings in that paragraph.
• clear_cache – Whether all caches should be refreshed.

Returns:

A 5-tuple of the form: (paragraph, hash of the auto macro values, auto macros, so far used headings, old HTML).

has_class(class_name)

has_headers() → bool

html_dict() → typing.Dict[KT, VT]

is_area_reference() → bool

is_different_from(par: timApp.documentmodel.docparagraph.DocParagraph) → bool

is_dynamic() → bool

is_multi_block() → bool

is_par_reference() → bool

is_plugin() → bool

is_question() → bool

is_reference() → bool

is_setting() → bool

is_translation() → bool

classmethod preload_htmls(pars: typing.List[typing.DocParagraph], settings, clear_cache: bool = False, context_par: typing.Union[typing.DocParagraph, NoneType] = None, persist: bool = True)

Loads the HTML for each paragraph in the given list. :param context_par: The context paragraph. Required only for previewing for now. :param persist: Whether the result of preloading should be saved to disk. :param clear_cache: Whether all caches should be refreshed. :param settings: The document settings. :param pars: Paragraphs to preload. :return: A list of paragraphs whose HTML changed as the result of preloading.

remove_link(doc_id: int)

sanitize_html()

set_attr(attr_name: str, attr_val: typing.Generic, dereference: bool = False)

set_id(par_id: str)

set_latest()

set_original(orig: timApp.documentmodel.docparagraph.DocParagraph)

update_links()

timApp.documentmodel.docparagraphencoder module

class timApp.documentmodel.docparagraphencoder.DocParagraphEncoder(skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)

Bases: json.encoder.JSONEncoder

default(o)

timApp.documentmodel.docsettings module

class timApp.documentmodel.docsettings.DocSettings

Bases: object

auto_number_headings() → bool

Return type:bool

auto_number_headings_key = 'auto_number_headings'

css()

css_key = 'css'

classmethod from_paragraph(par)

Constructs DocSettings from the given DocParagraph.

Parameters:par (DocParagraph) – The DocParagraph to extract settings from. Returns:The DocSettings object.

get_dict() → dict

Return type:dict

get_macro_delimiter() → str

Return type:str

get_macros() → dict

Return type:dict

get_source_document()

Return type:int|None

global_plugin_attrs() → dict

Return type:dict

global_plugin_attrs_key = 'global_plugin_attrs'

heading_format() → dict

Return type:dict

heading_format_key = 'heading_format'

classmethod is_valid_paragraph(par)

macro_delimiter_key = 'macro_delimiter'

macros_key = 'macros'

static parse_values(par)

sanitize_macros()

set_source_document()

Parameters:source_docid (int|None) –

show_task_summary(default=False) → bool

show_task_summary_key = 'show_task_summary'

source_document_key = 'source_document'

to_paragraph()

Return type:DocParagraph

timApp.documentmodel.document module

class timApp.documentmodel.document.CacheIterator(i)

Bases: object

class timApp.documentmodel.document.DocParagraphIter(doc: timApp.documentmodel.document.Document)

Bases: object

close()

class timApp.documentmodel.document.Document(doc_id: typing.Union[int, NoneType] = None, files_root=None, modifier_group_id: typing.Union[int, NoneType] = 0)

Bases: object

add_area_ref_paragraph(src_doc: timApp.documentmodel.document.Document, src_area_name: str, text: typing.Union[str, NoneType] = None, attrs: typing.Union[dict, NoneType] = None, properties: typing.Union[dict, NoneType] = None) → documentmodel.docparagraph.DocParagraph

static add_index_entry(index_table, current_headers, header)

add_paragraph(text: str, par_id: typing.Union[str, NoneType] = None, attrs: typing.Union[dict, NoneType] = None, properties: typing.Union[dict, NoneType] = None) → documentmodel.docparagraph.DocParagraph

Appends a new paragraph into the document. :param par_id: The id of the paragraph or None if it should be autogenerated. :param attrs: The attributes for the paragraph. :param text: New paragraph text. :return: The new paragraph object.

add_paragraph_obj(p: documentmodel.docparagraph.DocParagraph) → documentmodel.docparagraph.DocParagraph

Appends a new paragraph into the document. :param p: Paragraph to be added. :return: The same paragraph object, or None if could not add.

add_ref_paragraph(src_par: documentmodel.docparagraph.DocParagraph, text: typing.Union[str, NoneType] = None, attrs: typing.Union[dict, NoneType] = None, properties: typing.Union[dict, NoneType] = None) → documentmodel.docparagraph.DocParagraph

add_setting(key: str, value) → None

calculate_referenced_document_ids(ver: typing.Union[typing.Tuple[int, int], NoneType] = None) → typing.Set[int]

Gets all the document ids that are referenced from this document recursively. :return: The set of the document ids.

clear_mem_cache()

create(ignore_exists: bool = False)

default_files_root = 'tim_files'

delete_paragraph(par_id: str)

Removes a paragraph from the document. :param par_id: Paragraph id to remove.

delete_section(area_start, area_end)

classmethod doc_exists(doc_id: int, files_root: typing.Union[str, NoneType] = None) → bool

Checks if a document id exists. :param doc_id: Document id. :return: Boolean.

exists() → bool

export_markdown(export_hashes: bool = False) → str

export_section(par_id_start: str, par_id_end: str, export_hashes=False) → str

find_insert_index(i2, old_ids)

get_changelog(max_entries: int = 100) → typing.List[dict]

get_closest_paragraph_title(par_id: typing.Union[str, NoneType])

classmethod get_default_files_root()

get_document_path() → str

get_id_version() → typing.Tuple[int, int, int]

get_index() → typing.List[typing.Tuple]

get_last_modified()

get_last_par()

get_latest_version()

get_named_section(section_name: str)

classmethod get_next_free_id(files_root: typing.Union[str, NoneType] = None) → int

Gets the next free document id. :return:

get_original_document()

get_paragraph(par_id: str) → documentmodel.docparagraph.DocParagraph

get_paragraph_by_task(task_id_name)

get_paragraphs() → typing.List[documentmodel.docparagraph.DocParagraph]

get_pars_till(par)

get_previous_par(par, get_last_if_no_prev=False)

get_referenced_document_ids(ver: typing.Union[typing.Tuple[int, int], NoneType] = None) → typing.Set[int]

get_reflist_filename(ver: typing.Union[typing.Tuple[int, int], NoneType] = None) → str

get_refs_dir(ver: typing.Union[typing.Tuple[int, int], NoneType] = None) → str

get_section(par_id_start: str, par_id_end: str) → typing.List[documentmodel.docparagraph.DocParagraph]

get_settings() → documentmodel.docsettings.DocSettings

get_version() → typing.Tuple[int, int]

Gets the latest version of the document as a major-minor tuple. :return: Latest version, or (-1, 0) if there isn’t yet one.

get_version_path(ver: typing.Union[typing.Tuple[int, int], NoneType] = None) → str

getlogfilename() → str

has_paragraph(par_id: str) → bool

Checks if the document has the given paragraph. :param par_id: The paragraph id. :return: Boolean.

insert_paragraph(text: str, insert_before_id: typing.Union[str, NoneType], attrs: typing.Union[dict, NoneType] = None, properties: typing.Union[dict, NoneType] = None, par_id: typing.Union[str, NoneType] = None) → documentmodel.docparagraph.DocParagraph

Inserts a paragraph before a given paragraph id. :param par_id: The id of the new paragraph or None if it should be autogenerated. :param attrs: The attributes for the paragraph. :param text: New paragraph text. :param insert_before_id: Id of the paragraph to insert before, or None if last. :return: The inserted paragraph object.

insert_paragraph_obj(p: documentmodel.docparagraph.DocParagraph, insert_before_id: typing.Union[str, NoneType]) → documentmodel.docparagraph.DocParagraph

insert_temporary_pars(pars, context_par)

load_pars()

Loads the paragraphs from disk to memory so that subsequent iterations for the Document are faster.

modify_paragraph(par_id: str, new_text: str, new_attrs: typing.Union[dict, NoneType] = None, new_properties: typing.Union[dict, NoneType] = None) → documentmodel.docparagraph.DocParagraph

Modifies the text of the given paragraph. :param par_id: Paragraph id. :param new_text: New text. :return: The new paragraph object.

modify_paragraph_obj(par_id: str, p: documentmodel.docparagraph.DocParagraph) → documentmodel.docparagraph.DocParagraph

classmethod remove(doc_id: int, files_root: typing.Union[str, NoneType] = None, ignore_exists=False)

Removes the whole document. :param doc_id: Document id to remove. :return:

set_settings(settings: dict)

update(text: str, original: str, strict_validation=True)

Replaces the document’s contents with the specified text.

Parameters:

• text – The new text for the document.
• original – The original text for the document.
• strict_validation – Whether to use stricter validation rules for areas etc.

update_section()

Updates a section of the document.

Parameters:

• text – The text of the section.
• par_id_first – The id of the paragraph that denotes the start of the section.
• par_id_last – The id of the paragraph that denotes the end of the section.

classmethod version_exists()

Checks if a document version exists. :param doc_id: Document id. :param doc_ver: Document version. :return: Boolean.

timApp.documentmodel.document.dereference_pars(pars, edit_window: bool = False, source_doc: typing.Union[timApp.documentmodel.document.Document, NoneType] = None)

Resolves references in the given paragraphs.

Parameters:

• pars (list[DocParagraph]) – The DocParagraphs to be processed.
• edit_window – Calling from edit window or not.
• source_doc – Default document for referencing.

timApp.documentmodel.document.get_index_from_html_list(html_table) → typing.List[typing.Tuple]

Return type:List

timApp.documentmodel.documentparser module

class timApp.documentmodel.documentparser.DocReader(lines, i=0)

Bases: object

Parameters:

• lines (list[str]) –
• i (int) –

get_line_and_advance()

has_more_lines()

peek_line()

Return type:str Returns:

class timApp.documentmodel.documentparser.DocumentParser(doc_text='')

Bases: object

Splits documents into paragraphs.

add_missing_attributes(hash_func=<function hashfunc>, id_func=<function random_id>)

eat_whitespace(doc)

Return type:NoneType

extract_attrs(result, tokens)

get_blocks(options: typing.Union[documentmodel.documentparseroptions.DocumentParserOptions, NoneType] = None)

is_beginning_of_code_block(doc)

is_beginning_of_header_block(doc)

is_empty_line(doc)

parse_normal_block(doc)

try_parse_code_block(doc)

Return type:dict

try_parse_header_block(doc)

Return type:dict Parameters:doc (DocReader) – Returns:

validate_structure(id_validator_func=<function is_valid_id>, is_whole_document=True)

exception timApp.documentmodel.documentparser.SplitterException

Bases: Exception

exception timApp.documentmodel.documentparser.ValidationException

Bases: Exception

exception timApp.documentmodel.documentparser.ValidationWarning

Bases: timApp.documentmodel.documentparser.ValidationException

timApp.documentmodel.documentparseroptions module

class timApp.documentmodel.documentparseroptions.DocumentParserOptions(break_on_empty_line=False, break_on_code_block=True, break_on_header=True, break_on_normal=True)

Bases: object

static break_on_empty_lines() → timApp.documentmodel.documentparseroptions.DocumentParserOptions

static single_paragraph() → timApp.documentmodel.documentparseroptions.DocumentParserOptions

static whole_document() → timApp.documentmodel.documentparseroptions.DocumentParserOptions

timApp.documentmodel.documentversion module

class timApp.documentmodel.documentversion.DocumentVersion

Bases: documentmodel.document.Document

add_paragraph()

Parameters:

• text (str) –
• properties (dict|None) –
• attrs (dict|None) –
• par_id (str|None) –

Return type:

DocParagraph

add_paragraph_obj()

Parameters:p (DocParagraph) – Return type:DocParagraph

add_ref_paragraph()

cache_index()

create(ignore_exists: bool = False)

Parameters:ignore_exists (bool) –

delete_paragraph(par_id: str)

Parameters:par_id (str) –

delete_section(area_start: str, area_end: str)

Parameters:

• area_start (str) –
• area_end (str) –

exists() → bool

Return type:bool

static get_diff(d1, d2)

get_paragraph()

Parameters:par_id (str) – Return type:DocParagraph

get_settings()

Return type:DocSettings

get_version()

Return type:tuple(int,int)

has_paragraph(par_id: str) → bool

Checks if the document has the given paragraph.

Parameters:par_id (str) – The paragraph id. Returns:Boolean. Return type:bool

insert_paragraph()

Parameters:

• text (str) –
• properties (dict|None) –
• insert_before_id (str|None) –
• attrs (dict|None) –
• par_id (str|None) –

Return type:

DocParagraph

insert_paragraph_obj()

Parameters:

• p (DocParagraph) –
• insert_before_id (str|None) –

Return type:

DocParagraph

modify_paragraph()

Parameters:

• new_attrs (dict|None) –
• new_properties (dict|None) –
• par_id (str) –
• new_text (str) –

Return type:

DocParagraph

modify_paragraph_obj()

Parameters:

• p (DocParagraph) –
• par_id (str) –

Return type:

DocParagraph

classmethod remove()

Parameters:

• doc_id (int) –
• files_root (str|None) –

update(text: str, original: str, strict_validation=True)

Parameters:

• text (str) –
• original (str) –

update_section()

Parameters:

• text (str) –
• par_id_first (str) –
• par_id_last (str) –

Return type:

tuple(str,str)

timApp.documentmodel.documentwriter module

Defines the DocumentWriter class.

class timApp.documentmodel.documentwriter.DocumentWriter(pars, export_hashes=False, export_ids=True)

Bases: object

Converts a sequence of document blocks to text.

attrs_to_str(attrs)

get_text(options: typing.Union[documentmodel.documentparseroptions.DocumentParserOptions, NoneType] = None)

Gets the full text for the document.

Returns:The full text of the document.

timApp.documentmodel.exceptions module

exception timApp.documentmodel.exceptions.DocExistsError(doc_id)

Bases: Exception

timApp.documentmodel.randutils module

timApp.documentmodel.randutils.hashfunc(text, attrs=None)

timApp.documentmodel.randutils.idchecksum(randid)

timApp.documentmodel.randutils.is_valid_id(randid)

timApp.documentmodel.randutils.random_id()

timApp.documentmodel.randutils.random_jsonpar(par_id)

timApp.documentmodel.randutils.random_paragraph()

timApp.documentmodel.randutils.random_sentence()

timApp.documentmodel.randutils.random_sentences()

timApp.documentmodel.randutils.random_word(min_len=2, max_len=12)

timApp.documentmodel.test_attributeparser module

class timApp.documentmodel.test_attributeparser.AttributeParserTest(methodName='runTest')

Bases: unittest.case.TestCase

check_invalid(string)

check_valid(string, expected, expected_index=0)

test_broken()

test_keyvalues()

test_random()

test_whitespace()

timApp.documentmodel.test_clipboard module

Unit tests for Clipboard class.

Run from parent directory with command: python3 -m unittest dumboclient filemodehelper documentmodel/test_clipboard.py

class timApp.documentmodel.test_clipboard.ClipboardTest(methodName='runTest')

Bases: timdbtest.TimDbTest

setUp()

test_copy()

test_empty()

test_paste()

test_persistence()

test_readwrite()

timApp.documentmodel.test_clipboard.test_paste_ref(self)

timApp.documentmodel.test_document module

Unit tests for Document class.

Run from parent directory with command: python3 -m unittest dumboclient filemodehelper documentmodel/test_document.py

class timApp.documentmodel.test_document.DocumentTest(methodName='runTest')

Bases: timdbtest.TimDbTest

add_pars(d, num_docs)

init_testdoc(doc_id=None)

test_addparagraph()

test_delparagraph()

test_document_create()

test_document_remove()

test_get_html()

test_import()

test_insertparagraph()

test_iterator()

test_macros()

test_modify()

test_update()

test_update_section()

timApp.documentmodel.test_documentparser module

class timApp.documentmodel.test_documentparser.DocumentParserTest(methodName='runTest')

Bases: unittest.case.TestCase

test_parsing()

test_validation()

timApp.documentmodel.test_references module

Unit tests for testing paragraph referencing.

Run from parent directory with command: python3 -m unittest dumboclient filemodehelper documentmodel/test_references.py

class timApp.documentmodel.test_references.RefTest(methodName='runTest')

Bases: timdbtest.TimDbTest

assert_dict_issubset(a, b)

dict_issubset(a, b)

dict_merge(a, b)

doc_create(db, doc_name, doc_group)

init_testdb()

test_circular()

test_editparagraph_cite()

test_editparagraph_citearea()

test_editparagraph_translate()

test_editparagraph_translatearea()

test_simpleref()

test_transitive()

test_translation()

Module contents