timApp.document package#

Subpackages#

Submodules#

timApp.document.areainfo module#

class timApp.document.areainfo.AreaBoundary(name: str)[source]#

Bases: object

name: str#

class timApp.document.areainfo.AreaEnd(name: str)[source]#: Bases: timApp.document.areainfo.AreaBoundary

class timApp.document.areainfo.AreaStart(name: str, is_collapsed: bool | None)[source]#

Bases: timApp.document.areainfo.AreaBoundary

property area_class_str: str#

property collapse_state: str#

is_collapsed: bool | None#

timApp.document.attributeparser module#

class timApp.document.attributeparser.AttributeParser(string='')[source]#

Bases: object

static attr_list_end_char()[source]#

static attr_list_start_char()[source]#

current_char()[source]#

eat_whitespace()[source]#

get_attributes()[source]#

get_char()[source]#

has_chars()[source]#

parse_code_type()[source]#

set_str(string)[source]#

try_get_attributes(pos)[source]#

try_parse_attr_list_end_char()[source]#

try_parse_class()[source]#

try_parse_hash()[source]#

try_parse_helper(char)[source]#

try_parse_keyvaluepair()[source]#

exception timApp.document.attributeparser.AttributeParserException[source]#: Bases: Exception

timApp.document.caching module#

class timApp.document.caching.CacheResult(key: str, doc: timApp.document.docrenderresult.DocRenderResult | None)[source]#

Bases: object

doc: timApp.document.docrenderresult.DocRenderResult | None#

key: str#

timApp.document.caching.check_doc_cache(doc_info: timApp.document.docinfo.DocInfo, current_user: User, view_ctx: timApp.document.viewcontext.ViewContext, m: timApp.document.docviewparams.DocViewParams, nocache: bool) → timApp.document.caching.CacheResult[source]#

timApp.document.caching.clear_doc_cache(doc: Union[timApp.document.docinfo.DocInfo, timApp.document.document.Document, int], user: User) → None[source]#
timApp.document.caching.clear_doc_cache(doc: Union[timApp.document.docinfo.DocInfo, timApp.document.document.Document, int], user: None) → None
timApp.document.caching.clear_doc_cache(doc: None, user: User) → None

timApp.document.caching.get_doc_cache_key(doc: timApp.document.docinfo.DocInfo, user: User, view_ctx: timApp.document.viewcontext.ViewContext, m: timApp.document.docviewparams.DocViewParams) → str[source]#

timApp.document.caching.get_style_timestamp_hash(style_name: str) → str | None[source]#

timApp.document.caching.refresh_doc_expire(key: str, ex: int = 604800) → None[source]#

timApp.document.caching.set_doc_cache(key: str, value: timApp.document.docrenderresult.DocRenderResult, ex: int = 604800) → None[source]#

timApp.document.caching.set_style_timestamp_hash(style_name: str, hash_val: str) → None[source]#

timApp.document.changelog module#

class timApp.document.changelog.AuthorInfo(user_map: dict[int, typing.Union[ForwardRef('timApp.timdb.models.user.User'), ForwardRef('timApp.timdb.models.usergroup.UserGroup')]], entries: dict[int, list[timApp.document.changelogentry.ChangelogEntry]])[source]#

Bases: object

property display_name#

property time#

class timApp.document.changelog.Changelog[source]#

Bases: object

append(entry: timApp.document.changelogentry.ChangelogEntry)[source]#

get_authorinfo(pars: list[timApp.document.docparagraph.DocParagraph]) → dict[str, timApp.document.changelog.AuthorInfo][source]#

to_json()[source]#

timApp.document.changelog.get_author_str(u: Union[timApp.timdb.models.user.User, timApp.timdb.models.usergroup.UserGroup], es: list[timApp.document.changelogentry.ChangelogEntry])[source]#

timApp.document.changelogentry module#

class timApp.document.changelogentry.AddOperation(op: timApp.document.changelogentry.OperationType)[source]#: Bases: timApp.document.changelogentry.Operation

class timApp.document.changelogentry.ChangelogEntry(par_id: str, ver: tuple[int, int], op: str, time: str, group_id: int, op_params: dict)[source]#

Bases: object

to_json()[source]#

class timApp.document.changelogentry.DeleteOperation(op: timApp.document.changelogentry.OperationType)[source]#: Bases: timApp.document.changelogentry.Operation

class timApp.document.changelogentry.InsertOperation(op: timApp.document.changelogentry.OperationType, before_id: str)[source]#

Bases: timApp.document.changelogentry.Operation

to_json()[source]#

class timApp.document.changelogentry.ModifyOperation(op: timApp.document.changelogentry.OperationType, old_hash: str, new_hash: str)[source]#

Bases: timApp.document.changelogentry.Operation

to_json()[source]#

class timApp.document.changelogentry.Operation(op: timApp.document.changelogentry.OperationType)[source]#

Bases: object

static from_type_dict(op: timApp.document.changelogentry.OperationType, d: dict) → timApp.document.changelogentry.Operation[source]#

to_json()[source]#

class timApp.document.changelogentry.OperationType(value)[source]#

Bases: enum.Enum

An enumeration.

Add = 'Added'#

Delete = 'Deleted'#

Insert = 'Inserted'#

Modify = 'Modified'#

timApp.document.create_item module#

timApp.document.create_item.apply_template(item: timApp.document.docinfo.DocInfo, template_name: Optional[str] = None)[source]#

timApp.document.create_item.copy_document_and_enum_translations(source: timApp.document.docinfo.DocInfo, target: timApp.document.docinfo.DocInfo, copy_uploads: bool) → Generator[tuple[timApp.document.docinfo.DocInfo, timApp.document.docinfo.DocInfo], None, None][source]#

timApp.document.create_item.create_citation_doc(doc_id: int, doc_path: str, doc_title: str)[source]#

timApp.document.create_item.create_document(item_path: str, item_title: str, validation_rule: Optional[timApp.item.validation.ItemValidationRule] = None, parent_owner: Optional[timApp.user.usergroup.UserGroup] = None, doc_owner: Optional[timApp.user.usergroup.UserGroup] = None) → timApp.document.docinfo.DocInfo[source]#

timApp.document.create_item.create_or_copy_item(item_path: str, item_type: timApp.item.block.BlockType, item_title: str, copy_id: Optional[int] = None, template_name: Optional[str] = None, use_template: bool = True, copy_uploads: bool = True)[source]#

timApp.document.create_item.do_create_item(item_path: str, item_type: timApp.item.block.BlockType, item_title: str, validation_rule: Optional[timApp.item.validation.ItemValidationRule] = None, parent_owner: Optional[timApp.user.usergroup.UserGroup] = None, doc_owner: Optional[timApp.user.usergroup.UserGroup] = None) → timApp.document.docinfo.DocInfo | timApp.folder.folder.Folder[source]#

timApp.document.create_item.get_templates_for_folder(folder: timApp.folder.folder.Folder) → list[timApp.document.docentry.DocEntry][source]#

timApp.document.docentry module#

class timApp.document.docentry.DocEntry(**kwargs)[source]#

Bases: sqlalchemy.ext.declarative.api.Model, timApp.document.docinfo.DocInfo

Represents a TIM document in the directory hierarchy.

A document can have several aliases, which is why the primary key is “name” column and not “id”.

Most of the time you should use DocInfo class instead of this.

static create(path: str, owner_group: Optional[timApp.user.usergroup.UserGroup] = None, title: Optional[str] = None, from_file: Optional[str] = None, initial_par: Optional[str] = None, settings: Optional[dict] = None, folder_opts: timApp.folder.createopts.FolderCreationOptions = FolderCreationOptions(apply_default_rights=False, get_templates_rights_from_parent=True)) → timApp.document.docentry.DocEntry[source]#

Creates a new document with the specified properties.

Parameters

from_file – If provided, loads the document content from a file.
initial_par – The initial paragraph for the document.
settings – The settings for the document.
title – The document title.
path – The path of the document to be created (can be None). If None, no DocEntry is actually added to the database; only Block and Document objects are created.
owner_group – The owner group.
folder_opts – Options for creating intermediate folders.

Returns

The newly created document object.

static find_all_by_id(doc_id: int) → list[timApp.document.docentry.DocEntry][source]#

static find_by_id(doc_id: int, docentry_load_opts: Optional[Any] = None) → timApp.document.docinfo.DocInfo | None[source]#

Finds a DocInfo by id.

TODO: This method doesn’t really belong in DocEntry class.

static find_by_path(path: str, fallback_to_id: bool = False, try_translation: bool = True, docentry_load_opts: Optional[Any] = None) → timApp.document.docinfo.DocInfo | None[source]#

Finds a DocInfo by path, falling back to id if specified.

TODO: This method doesn’t really belong in DocEntry class.

static get_all() → list[timApp.document.docentry.DocEntry][source]#

static get_dummy(title: str) → timApp.document.docentry.DocEntry[source]#

id#: Document identifier.

property lang_id: str | None#

name#

Full path of the document.

TODO: Improve the name.

property path: str#: Returns the Document path, including the language part in case of a translation.

property path_without_lang: str#: Returns the Document path without the language part in case of a translation.

public#: Whether the document is visible in directory listing.

property tr: timApp.document.translation.translation.Translation | None#

property translations: list[timApp.document.translation.translation.Translation]#: Returns the translations of the document. NOTE: The list includes the document itself.

trs: list[timApp.document.translation.translation.Translation]#

timApp.document.docentry.create_document_and_block(owner_group: timApp.user.usergroup.UserGroup | None, desc: Optional[str] = None) → timApp.document.document.Document[source]#

timApp.document.docentry.get_documents(include_nonpublic: bool = False, filter_folder: str | None = None, search_recursively: bool = True, filter_user: User | None = None, custom_filter: Any = None, query_options: Any = None) → list[DocEntry][source]#

Gets all the documents in the database matching the given criteria.

Parameters

filter_user – If specified, returns only the documents that the user has view access to.
search_recursively – Whether to search recursively.
filter_folder – Optionally restricts the search to a specific folder.
include_nonpublic – Whether to include non-public document names or not.
custom_filter – Any custom filter to use.
query_options – Any additional options for the query.

Returns

A list of DocEntry objects.

timApp.document.docentry.get_documents_in_folder(folder_pathname: str, include_nonpublic: bool = False) → list[timApp.document.docentry.DocEntry][source]#

Gets all the documents in a folder.

Parameters

folder_pathname – path to be searched for documents without ending ‘/’
include_nonpublic – Whether to include non-public document names or not.

Returns

A list of DocEntry objects.

timApp.document.docinfo module#

class timApp.document.docinfo.DocInfo[source]#

Bases: timApp.item.item.Item

A base class for DocEntry and Translation.

add_alias(new_name, is_public)[source]#

property aliases#

property document: timApp.document.document.Document#: Returns the corresponding Document object.

property document_as_current_user: timApp.document.document.Document#

get_changelog_with_names(length=None)[source]#

get_notifications(condition) → list[timApp.notification.notification.Notification][source]#

get_preamble_docs() → list[timApp.document.docinfo.DocInfo][source]#: Gets the list of preamble documents for this document. The first document in the list is the nearest root.

get_preamble_pars() → Generator[timApp.document.docparagraph.DocParagraph, None, None][source]#

get_preamble_pars_with_class(class_names: list[str])[source]#

Get all preamble pars with any of the given classes.

Parameters: class_names – Class names.
Returns: Filtered pars from the preamble document.

has_translation(lang_id)[source]#

property id: int#: Returns the item id.

property is_original_translation: bool#: Returns whether this object is the document from which other translated documents were created.

property lang_id: str | None#

property last_modified#

property path: str#: Returns the Document path, including the language part in case of a translation.

property path_without_lang: str#: Returns the Document path without the language part in case of a translation.

property src_doc: timApp.document.docinfo.DocInfo#: Returns the source document in case of a translation or the document itself otherwise.

property src_docid: int#: Returns the source document id in case of a translation or the document id itself otherwise.

to_json(**kwargs)[source]#

property translations: list[Translation]#: Returns the translations of the document. NOTE: The list includes the document itself.

update_last_modified() → None[source]#

timApp.document.docinfo.find_free_name(destination, item: timApp.item.item.Item)[source]#

timApp.document.docinfo.get_non_settings_pars_from_docs(docs: Iterable[timApp.document.docinfo.DocInfo]) → Generator[timApp.document.docparagraph.DocParagraph, None, None][source]#

timApp.document.docinfo.get_pars_with_class_from_docs(docs: Iterable[timApp.document.docinfo.DocInfo], class_names: list[str]) → Generator[timApp.document.docparagraph.DocParagraph, None, None][source]#

Loads all non-settings pars that have the given class.

Parameters

docs – Document.
class_names – Class name list.

Returns

Pars that have any of the filtering class names.

timApp.document.docinfo.move_document(d: timApp.document.docinfo.DocInfo, destination)[source]#

timApp.document.docparagraph module#

class timApp.document.docparagraph.DocParagraph(doc: Document)[source]#

Bases: object

Represents a paragraph that is associated with a Document. See DocParagraph for more info.

add_class(*classes: str)[source]#: Adds the specified class to this paragraph.

answer_nr: int | None#

ask_new: bool | None#

attrs: dict[str, str] | None#

property classes: list[str] | None#

clear_cache() → None[source]#: Clears the HTML cache of this paragraph.

clone() → timApp.document.docparagraph.DocParagraph[source]#

Clones the paragraph.

Returns: The cloned paragraph.

Creates a DocParagraph from the given parameters.

Parameters

doc – The Document object to which this paragraph is connected.
par_id – The paragraph id or None if it should be autogenerated.
md – The markdown content.
par_hash – The hash for the paragraph or None if it should be computed.
html – The HTML for the paragraph or None if it should be generated based on markdown.
attrs – The attributes for the paragraph.

Returns

The created DocParagraph.

static create_area_reference(doc: Document, area_name: str, r: str | None = None, rd: int | None = None) → DocParagraph[source]#

Creates an area reference paragraph.

Parameters

area_name – The name of the area.
doc – The Document object in which the reference paragraph will reside.
r – The kind of the reference.
rd – ID of the referenced document.

Returns

The created DocParagraph.

create_reference(doc, translator: Optional[str] = None, r: Optional[str] = None, add_rd: bool = True) → timApp.document.docparagraph.DocParagraph[source]#

Creates a reference paragraph to this paragraph.

Parameters

doc – The Document object in which the reference paragraph will reside.
r – The kind of the reference.
add_rd – If True, sets the rd attribute for the reference paragraph.
translator – The name of the machine translator set to mt on machine translation.

Returns

The created DocParagraph.

dict(include_html_cache: bool = False) → dict[source]#: Returns the persistent data as a dict.

doc: Document#

classmethod from_dict(doc, d: dict) → timApp.document.docparagraph.DocParagraph[source]#

Creates a paragraph from a dictionary.

Parameters

doc – The Document object in which the paragraph will reside.
d – The dictionary.

Returns

The created DocParagraph.

from_preamble() → DocInfo | None[source]#: Returns the preamble document for this paragraph if the paragraph has been copied from a preamble.

classmethod get(doc, par_id: str, t: str) → timApp.document.docparagraph.DocParagraph[source]#

Retrieves a specific paragraph version from the data store.

Parameters

doc – The Document object for which to retrieve the paragraph.
par_id – The paragraph id.
t – The paragraph hash.

Returns

The retrieved DocParagraph.

get_attr(attr_name: str, default_value: Optional[str] = None) → str | None[source]#

Returns the value of the specified attribute.

Parameters

attr_name – The name of the attribute to get.
default_value – The default value to return if the attribute does not exist.

Returns

The attribute value.

get_attrs() → dict[source]#

get_auto_id() → str[source]#

get_auto_macro_values(macros, env: timApp.markdown.autocounters.TimSandboxedEnvironment, auto_macro_cache, heading_cache, auto_number_start)[source]#

Returns 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.
auto_number_start – Object of heading start numbers.
env – Environment 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[source]#: Returns the filesystem path for the versions of this paragraph.

get_basic_data()[source]#

get_doc_id() → int[source]#: Returns the Document id to which this paragraph is attached.

get_dumbo_options(base_opts: timApp.markdown.dumboclient.DumboOptions = DumboOptions(math_type=<MathType.MathJax: 'mathjax'>, math_preamble='', input_format=<InputFormat.Markdown: 'markdown'>, smart_punct=False)) → timApp.markdown.dumboclient.DumboOptions[source]#

get_expanded_markdown(macroinfo: timApp.document.macroinfo.MacroInfo, ignore_errors: bool = False) → str[source]#

Returns the macro-processed markdown for this paragraph.

Parameters: macroinfo – The MacroInfo to use. If None, the MacroInfo is taken from the document that has the

paragraph. :param ignore_errors: Whether or not to ignore errors when expanding the macros :return: The expanded markdown.

get_exported_markdown(skip_tr=False, export_ids=False) → str[source]#: Returns the markdown in exported form for this paragraph.

get_hash() → str[source]#: Returns the hash of this paragraph.

get_html(view_ctx: timApp.document.viewcontext.ViewContext, no_persist: bool = True) → str[source]#: Returns the html for the paragraph.

get_id() → str[source]#: Returns the id of this paragraph.

classmethod get_latest(doc, par_id: str) → timApp.document.docparagraph.DocParagraph[source]#

Retrieves the latest paragraph version from the data store.

Parameters

doc – The Document object for which to retrieve the paragraph.
par_id – The paragraph id.

Returns

The retrieved DocParagraph.

get_markdown() → str[source]#: Returns the markdown of this paragraph.

get_nomacros()[source]#

get_path() → str[source]#: Returns the filesystem path for this paragraph.

get_rands()[source]#

get_referenced_pars(view_ctx: Optional[timApp.document.viewcontext.ViewContext] = None) → list[timApp.document.docparagraph.DocParagraph][source]#

get_referenced_pars_impl(visited_pars: Optional[list[tuple[int, str]]] = None) → list[timApp.document.docparagraph.DocParagraph][source]#

Returns the paragraphs that are referenced by this paragraph.

The references are resolved recursively, i.e. if the referenced paragraphs are references themselves, they will also be resolved, and so on, until we get a list of non-reference paragraphs.

Parameters: visited_pars – A list of already visited paragraphs to prevent infinite recursion.
Returns: The list of resolved paragraphs.

get_title() → str | None[source]#

Attempts heuristically to return a title for this paragraph.

Returns: The title for this paragraph or None if there is no sensible title.

classmethod get_unloaded_pars(pars, settings, auto_macro_cache, heading_cache, clear_cache=False)[source]#

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)[source]#: Returns whether this paragraph has the specified class.

has_dumbo_options()[source]#

has_plugins() → bool[source]#: Returns whether this paragraph has inline plugins.

hash#

static help_par()[source]#: Returns a dummy paragraph with id ‘HELP_PAR’ that is used as a placeholder for an empty document.

html#

html_cache#

html_sanitized#

id#

insert_rnds(rnd_seed: Optional[Union[str, int, timApp.util.rndutils.SeedClass]]) → bool[source]#: Inserts Jinja rnd variable as a list of random numbers based to attribute rnd and rnd_seed return True if attribute rnd found and OK, else False

is_area()[source]#

is_area_reference() → bool[source]#: Returns whether this paragraph is a reference to an area.

is_citation()[source]#

is_different_from(par: timApp.document.docparagraph.DocParagraph) → bool[source]#: Determines whether the given paragraph is different from this paragraph content-wise.

is_dynamic() → bool[source]#

Returns whether this paragraph is a dynamic paragraph.

A dynamic paragraph is a paragraph which is either

a plugin,
a reference which is not a translation, or
a setting.

is_identical_to(par: timApp.document.docparagraph.DocParagraph)[source]#

is_new_task()[source]#

static is_no_macros(settings, doc_macros)[source]#

is_par_reference() → bool[source]#: Returns whether this paragraph is a reference to a single paragraph.

is_plugin() → bool[source]#: Returns whether this paragraph is a plugin.

is_question() → bool[source]#: Returns whether this paragraph is a question paragraph.

is_reference() → bool[source]#: Returns whether this paragraph is a reference to some other paragraph.

is_same_as(par: timApp.document.docparagraph.DocParagraph) → bool[source]#: Determines whether the given paragraph is same as this paragraph content-wise.

is_same_as_html(par: timApp.document.docparagraph.DocParagraph, view_ctx: timApp.document.viewcontext.ViewContext)[source]#

is_setting() → bool[source]#: Returns whether this paragraph is a settings paragraph.

is_task()[source]#: Returns whether the paragraph is a task.

is_theme_style() → bool[source]#

is_translation() → bool[source]#: Returns whether this paragraph is a translated paragraph.

is_translation_out_of_date()[source]#

is_translation_unchecked()[source]#

Checks whether or not the paragraph’s translation has been checked by a human.

Returns: False if the paragraph is not a translation or it has been checked, true if it is not checked

is_yaml() → bool[source]#: Returns whether this paragraph is YAML markup.

md#

no_macros()[source]#

property nocache#

nomacros#

original: DocParagraph | None#

preamble_doc#

classmethod preload_htmls(pars: list[timApp.document.docparagraph.DocParagraph], settings, view_ctx: timApp.document.viewcontext.ViewContext, clear_cache: bool = False, context_par: Optional[timApp.document.docparagraph.DocParagraph] = None, persist: bool | None = True)[source]#

Loads the HTML for each paragraph in the given list.

Parameters

view_ctx –
context_par – The context paragraph. Required only for previewing for now.
persist – Whether the result of preloading should be saved to disk.
clear_cache – Whether all caches should be refreshed.
settings – The document settings.
pars – Paragraphs to preload.

Returns

A list of paragraphs whose HTML changed as the result of preloading.

prepare(view_ctx: timApp.document.viewcontext.ViewContext, use_md: bool = False, cache: bool = True) → timApp.document.prepared_par.PreparedPar[source]#: Returns the corresponding PreparedPar.

prepared_par: PreparedPar | None#

prev_deref: DocParagraph | None#

ref_chain#

ref_doc#

ref_pars#

sanitize_html()[source]#

Sanitizes the HTML for this paragraph.

If the HTML has already been sanitized or the HTML has not been loaded, this method does nothing.

save(add: bool = False) → None[source]#

Performs a save operation for this paragraph.

This updates the document version and paragraph list appropriately.

Parameters: add – Whether to add (True) or modify an existing (False).

set_attr(attr_name: str, attr_val: str | None)[source]#

Sets the value of the specified attribute.

Parameters

attr_name – The name of the attribute to set.
attr_val – The value for the attribute.

set_id(par_id: str)[source]#

Sets the id for this paragraph.

Parameters: par_id – The new id for the paragraph.

set_latest()[source]#: Updates the ‘current’ symlink to point to this paragraph version.

set_markdown(new_md: str)[source]#

Sets markdown for this paragraph.

Parameters: new_md – The new markdown.

store()[source]#: Stores the paragraph to disk.

was_invalid#

timApp.document.docparagraph.add_heading_numbers(s: str, ctx: timApp.document.docparagraph.DocParagraph, heading_format: dict, heading_ref_format: Optional[dict] = None, jump_name: Optional[str] = None, counters: Optional[timApp.markdown.autocounters.AutoCounters] = None, initial_heading_counts: Optional[dict[int, int]] = None)[source]#

timApp.document.docparagraph.add_headings_to_counters(s: str, jump_name: Optional[str] = None, counters: Optional[timApp.markdown.autocounters.AutoCounters] = None)[source]#

timApp.document.docparagraph.create_final_par(reached_par: timApp.document.docparagraph.DocParagraph, view_ctx: timApp.document.viewcontext.ViewContext | None) → timApp.document.docparagraph.DocParagraph[source]#: Creates the finalized dereferenced paragraph based on a chain of references.

timApp.document.docparagraph.create_reference(doc: DocumentType, doc_id: int, par_id: str, translator: str | None = None, r: str | None = None, add_rd: bool = True) → DocParagraph[source]#

Creates a reference paragraph to a paragraph.

Parameters

par_id – Id of the original paragraph.
doc_id – Id of the original document.
doc – The Document object in which the reference paragraph will reside.
r – The kind of the reference.
add_rd – If True, sets the rd attribute for the reference paragraph.
translator – The name of the machine translator set to mt on machine translation.

Returns

The created DocParagraph.

timApp.document.docparagraph.get_heading_counts(ctx: timApp.document.docparagraph.DocParagraph)[source]#

timApp.document.docparagraph.is_real_id(par_id: str | None)[source]#

Returns whether the given paragraph id corresponds to some real paragraph instead of being None or a placeholder value (‘HELP_PAR’).

Parameters: par_id – The paragraph id.
Returns: True if the given paragraph id corresponds to some real paragraph, False otherwise.

timApp.document.docrenderresult module#

class timApp.document.docrenderresult.DocRenderResult(head_html: str, content_html: str, allowed_to_cache: bool, override_theme: str | None, hide_readmarks: bool = False)[source]#

Bases: object

allowed_to_cache: bool#

content_html: str#

head_html: str#

hide_readmarks: bool = False#

override_theme: str | None#

timApp.document.docsettings module#

class timApp.document.docsettings.DocSettingTypes(themes: list[str], override_user_themes: bool, hide_sidemenu: str | None, answer_submit_time_tolerance: int, scoreboard_docs: list[str], show_scoreboard: bool, hideBrowser: bool, autocounters: dict[str, Any], macros: dict[str, Any], texmacros: dict[str, Any], urlmacros: dict[str, Union[int, float, str]], rndmacros: dict[str, str], cache: bool, peer_review: bool, peer_review_count: int, access_denied_message: str, disable_answer: str, smart_punct: bool, slide_themes: list[str], slide_size: tuple[int, int], allow_url_permission_edits: bool, additional_angular_modules: list[str], exam_mode: str, exam_mode_themes: list[str], hide_readmarks: bool, sync_answerbrowsers: bool, peer_review_start: datetime.datetime, peer_review_stop: datetime.datetime, anonymize_reviewers: str)[source]#

Bases: object

access_denied_message: str#

additional_angular_modules: list[str]#

allow_url_permission_edits: bool#

anonymize_reviewers: str#

answer_submit_time_tolerance: int#

autocounters: dict[str, Any]#

cache: bool#

disable_answer: str#

exam_mode: str#

exam_mode_themes: list[str]#

hideBrowser: bool#

hide_readmarks: bool#

hide_sidemenu: str | None#

macros: dict[str, Any]#

override_user_themes: bool#

peer_review: bool#

peer_review_count: int#

peer_review_start: datetime.datetime#

peer_review_stop: datetime.datetime#

rndmacros: dict[str, str]#

scoreboard_docs: list[str]#

show_scoreboard: bool#

slide_size: tuple[int, int]#

slide_themes: list[str]#

smart_punct: bool#

sync_answerbrowsers: bool#

texmacros: dict[str, Any]#

themes: list[str]#

urlmacros: dict[str, Union[int, float, str]]#

class timApp.document.docsettings.DocSettings(doc: Document, settings_dict: timApp.document.yamlblock.YamlBlock | None = None)[source]#

Bases: object

access_denied_message() → str | None[source]#

add_par_button_text(default='Add paragraph') → str[source]#

add_par_button_text_key = 'add_par_button_text'#

additional_angular_modules() → list[str][source]#

allow_self_confirm_from()[source]#

allow_self_confirm_from_key = 'allow_self_confirm_from'#

allow_url_permission_edits() → bool[source]#

anonymize_reviewers() → str | None[source]#

answer_grace_period() → datetime.timedelta[source]#

answer_grace_period_key = 'answer_grace_period'#

answer_submit_time_tolerance() → datetime.timedelta[source]#

auto_confirm()[source]#

auto_confirm_key = 'auto_confirm'#

auto_number_headings() → int[source]#

auto_number_headings_key = 'auto_number_headings'#

auto_number_questions() → bool[source]#

auto_number_start() → dict[int, int][source]#

auto_number_start_key = 'auto_number_start'#

autocounters() → dict[source]#

autocounters_key = 'autocounters'#

bookmark_key = 'bookmarks'#

charmacros_key = 'charmacros'#

comments() → str[source]#

comments_key = 'comments'#

course_allow_manual_enroll() → bool[source]#

course_allow_manual_enroll_key = 'course_allow_manual_enroll'#

course_group()[source]#

course_group_key = 'course_group'#

css()[source]#

css_key = 'css'#

disable_answer() → str | None[source]#

doctexmacros_key = 'doctexmacros'#

exam_mode() → str | None[source]#

exam_mode_themes() → list[str][source]#

expire_next_doc_message()[source]#

expire_next_doc_message_key = 'expire_next_doc_message'#

classmethod from_paragraph(par: timApp.document.docparagraph.DocParagraph)[source]#

Constructs DocSettings from the given DocParagraph.

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

get(key: str, default: Optional[Any] = None) → Any[source]#

get_bookmarks() → BookmarkCollection[source]#

get_charmacros(default=None)[source]#

get_dict() → timApp.document.yamlblock.YamlBlock[source]#

get_doctexmacros() → str[source]#

get_dumbo_options() → timApp.markdown.dumboclient.DumboOptions[source]#

get_globalmacros() → dict[str, str][source]#

get_hash()[source]#

get_macro_delimiter() → str[source]#

get_macroinfo(view_ctx: timApp.document.viewcontext.ViewContext, user_ctx: Optional[timApp.document.usercontext.UserContext] = None) → timApp.document.macroinfo.MacroInfo[source]#

get_print_settings(default=None)[source]#

get_safe_dict() → dict[source]#

get_setting_or_default(name: str, default: timApp.document.docsettings.T) → timApp.document.docsettings.T[source]#

get_slide_background_color(default=None) → str | None[source]#

get_slide_background_url(default=None) → str | None[source]#

get_source_document() → int | None[source]#

get_texmacroinfo(view_ctx: timApp.document.viewcontext.ViewContext, user_ctx: Optional[timApp.document.usercontext.UserContext] = None) → timApp.document.macroinfo.MacroInfo[source]#

global_plugin_attrs() → dict[source]#

global_plugin_attrs_key = 'global_plugin_attrs'#

globalmacros_key = 'globalmacros'#

group() → str | None[source]#

group_key = 'group'#

heading_format() → dict[source]#

heading_format_key = 'heading_format'#

heading_format_ret(defaults, format_key)[source]#

heading_ref_format() → dict[source]#

heading_ref_format_key = 'heading_ref_format'#

hide_browser() → bool[source]#

hide_links(default=None)[source]#

hide_links_key = 'hide_links'#

hide_readmarks() → bool[source]#

hide_sidemenu() → str | None[source]#

hide_top_buttons(default=None)[source]#

hide_top_buttons_key = 'hide_top_buttons'#

input_format()[source]#

input_format_key = 'input_format'#

is_cached()[source]#

is_style_document() → bool[source]#

is_texplain()[source]#

is_textplain()[source]#

lazy(default=False)[source]#

lazy_key = 'lazy'#

live_updates(default=None)[source]#

live_updates_key = 'live_updates'#

macro_delimiter_key = 'macro_delimiter'#

math_preamble()[source]#

math_preamble_key = 'math_preamble'#

mathtype(default='mathjax') → timApp.markdown.dumboclient.MathType[source]#

mathtype_key = 'math_type'#

max_points(default=None)[source]#

max_points_key = 'max_points'#

memo_minutes() → bool[source]#

memo_minutes_key = 'memo_minutes'#

memo_minutes_settings() → dict | None[source]#

no_question_auto_numbering_key = 'no_question_auto_numbering'#

nomacros(default=False)[source]#

nomacros_key = 'nomacros'#

override_user_themes() → bool[source]#

pars_only(default=None)[source]#

pars_only_key = 'pars_only'#

static parse_values(par) → timApp.document.yamlblock.YamlBlock[source]#

peer_review() → bool[source]#

peer_review_count() → int[source]#

peer_review_start() → datetime.datetime | None[source]#

peer_review_stop() → datetime.datetime | None[source]#

plugin_md(default=True) → bool[source]#

plugin_md_key = 'plugin_md'#

point_sum_rule(default=None) → timApp.answer.pointsumrule.PointSumRule | None[source]#

point_sum_rule_key = 'point_sum_rule'#

postcharmacros_key = 'postcharmacros'#

preamble(default='preamble')[source]#

preamble_key = 'preamble'#

print_settings_key = 'print_settings'#

read_expiry(default=datetime.timedelta(days=69993)) → datetime.timedelta[source]#

read_expiry_key = 'read_expiry'#

rndmacros() → dict[str, str][source]#

rndmacros_key = 'rndmacros'#

scoreboard_docs() → list[str][source]#

set_bookmarks(bookmarks: list[dict])[source]#

set_charmacros(charmacros: dict)[source]#

set_source_document(source_docid: int | None)[source]#

show_authors(default=False)[source]#

show_authors_key = 'show_authors'#

show_scoreboard() → bool[source]#

show_task_summary(default=False) → bool[source]#

show_task_summary_key = 'show_task_summary'#

show_velps() → bool[source]#

show_velps_key = 'show_velps'#

sisu_require_manual_enroll()[source]#

sisu_require_manual_enroll_key = 'sisu_require_manual_enroll'#

slide_background_color_key = 'slide_background_color'#

slide_background_url_key = 'slide_background_url'#

slide_size() → tuple[int, int][source]#

slide_themes() → list[str][source]#

smart_punct() → bool[source]#

source_document_key = 'source_document'#

sync_answerbrowsers() → bool[source]#

texplain_key = 'texplain'#

textplain_key = 'textplain'#

themes() → list[str][source]#

to_paragraph() → timApp.document.docparagraph.DocParagraph[source]#

urlmacros() → dict[str, Union[int, float, str]][source]#

class timApp.document.docsettings.MinimalVisibilitySettings(exam_mode: bool = False, hide_sidemenu: bool = False)[source]#

Bases: object

exam_mode: bool = False#

hide_sidemenu: bool = False#

timApp.document.docsettings.get_minimal_visibility_settings(item: Optional[Document])[source]#

timApp.document.docsettings.resolve_settings_for_pars(pars: Iterable[timApp.document.docparagraph.DocParagraph]) → timApp.document.yamlblock.YamlBlock[source]#

timApp.document.document module#

class timApp.document.document.CacheIterator(i)[source]#: Bases: object

class timApp.document.document.DocParagraphIter(doc: timApp.document.document.Document)[source]#

Bases: object

close()[source]#

class timApp.document.document.Document(doc_id: int, modifier_group_id: int | None = 0, preload_option: timApp.document.preloadoption.PreloadOption = PreloadOption.none)[source]#

Bases: object

add_paragraph(text: str, par_id: Optional[str] = None, attrs: Optional[dict] = None) → timApp.document.docparagraph.DocParagraph[source]#

Appends a new paragraph into the document.

Parameters

par_id – The id of the paragraph or None if it should be autogenerated.
attrs – The attributes for the paragraph.
text – New paragraph text.

Returns

The new paragraph object.

add_paragraph_obj(p: timApp.document.docparagraph.DocParagraph, update_meta=True) → timApp.document.docparagraph.DocParagraph[source]#

Appends a new paragraph into the document.

Parameters

update_meta – Whether to update metadata.
p – Paragraph to be added.

Returns

The same paragraph object, or None if could not add.

add_setting(key: str, value) → None[source]#

add_text(text: str) → list[timApp.document.docparagraph.DocParagraph][source]#: Converts the given text to (possibly) multiple paragraphs and adds them to the document.

calculate_referenced_document_ids(ver: Optional[tuple[int, int]] = None) → set[int][source]#

Gets all the document ids that are referenced from this document recursively.

Returns: The set of the document ids.

clear_mem_cache()[source]#

create(ignore_exists: bool = False)[source]#

delete_paragraph(par_id: str)[source]#

Removes a paragraph from the document.

Parameters: par_id – Paragraph id to remove.

delete_section(area_start, area_end) → timApp.document.editing.documenteditresult.DocumentEditResult[source]#

ensure_par_ids_loaded() → None[source]#

ensure_pars_loaded()[source]#

exists() → bool[source]#

export_markdown(export_hashes: bool = False, export_ids: bool = True, export_settings: bool = True, with_tl: bool = False) → str[source]#

export_raw_data()[source]#: Exports the raw JSON data of paragraphs. Useful for debugging.

export_section(par_id_start: str | None, par_id_end: str | None, export_hashes=False) → str[source]#

find_insert_index(i2, old_ids)[source]#

get_changelog(max_entries: int = 100) → timApp.document.changelog.Changelog[source]#

get_closest_paragraph_title(par_id: str | None)[source]#

get_dereferenced_paragraphs(view_ctx: timApp.document.viewcontext.ViewContext) → list[timApp.document.docparagraph.DocParagraph][source]#

get_doc_dir()[source]#

get_doc_version(version=None) → timApp.document.document.Document[source]#

get_docinfo() → DocInfo[source]#

classmethod get_documents_dir() → pathlib.Path[source]#

get_id_version() → tuple[int, int, int][source]#

get_index(view_ctx: timApp.document.viewcontext.ViewContext) → list[tuple][source]#

get_last_par()[source]#

get_latest_version()[source]#

get_lock() → filelock._unix.UnixFileLock[source]#

get_named_section(section_name: str) → list[timApp.document.docparagraph.DocParagraph][source]#

get_own_settings() → timApp.document.yamlblock.YamlBlock[source]#: Returns the settings for this document excluding any preamble documents.

get_par_ids(no_preamble=False)[source]#

get_par_not_found_msg(par_id: str)[source]#

get_paragraph(par_id: str) → timApp.document.docparagraph.DocParagraph[source]#

get_paragraphs(include_preamble=False) → list[timApp.document.docparagraph.DocParagraph][source]#

get_pars_till(par)[source]#

get_previous_par(par: timApp.document.docparagraph.DocParagraph, get_last_if_no_prev=False) → timApp.document.docparagraph.DocParagraph | None[source]#

get_previous_par_by_id(par_id: str, get_last_if_no_prev=False) → timApp.document.docparagraph.DocParagraph | None[source]#

get_ref_doc(ref_docid: int)[source]#

get_referenced_document_ids(ver: Optional[tuple[int, int]] = None) → set[int][source]#

get_reflist_filename(ver: Optional[tuple[int, int]] = None) → pathlib.Path[source]#

get_refs_dir(ver: Optional[tuple[int, int]] = None) → pathlib.Path[source]#

get_section(par_id_start: str | None, par_id_end: str | None) → list[timApp.document.docparagraph.DocParagraph][source]#

get_settings() → timApp.document.docsettings.DocSettings[source]#

get_settings_pars() → Generator[timApp.document.docparagraph.DocParagraph, None, None][source]#

get_source_document() → timApp.document.document.Document | None[source]#

get_tasks() → Generator[timApp.document.docparagraph.DocParagraph, None, None][source]#

get_version() → tuple[int, int][source]#

Gets the latest version of the document as a major-minor tuple.

Returns: Latest version, or (-1, 0) if there isn’t yet one.

get_version_path(ver: Optional[tuple[int, int]] = None) → pathlib.Path[source]#

get_word_list() → list[str][source]#

getlogfilename() → pathlib.Path[source]#

has_paragraph(par_id: str) → bool[source]#

Checks if the document has the given paragraph.

Parameters: par_id – The paragraph id.
Returns: Boolean.

property id#

insert_paragraph(text: str, insert_before_id: Optional[str] = None, insert_after_id: Optional[str] = None, attrs: Optional[dict] = None, par_id: Optional[str] = None) → timApp.document.docparagraph.DocParagraph[source]#

Inserts a paragraph before a given paragraph id.

Parameters

par_id – The id of the new paragraph or None if it should be autogenerated.
attrs – The attributes for the paragraph.
text – New paragraph text.
insert_before_id – Id of the paragraph to insert before, or None if last.
insert_after_id – Id of the paragraph to insert after, or None if first.

Returns

The inserted paragraph object.

insert_paragraph_obj(p: timApp.document.docparagraph.DocParagraph, insert_before_id: Optional[str] = None, insert_after_id: Optional[str] = None) → timApp.document.docparagraph.DocParagraph[source]#

insert_preamble_pars(class_names: Optional[list[str]] = None)[source]#: Add preamble pars. :param class_names: Optionally include only pars any of the listed classes. :return: Preamble pars.

insert_temporary_pars(pars, context_par)[source]#

load_pars()[source]#: 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: Optional[dict] = None) → timApp.document.docparagraph.DocParagraph[source]#

Modifies the text of the given paragraph.

Parameters

par_id – Paragraph id.
new_text – New text.
new_attrs – New attributes.

Returns

The new paragraph object.

modify_paragraph_obj(par_id: str, p: timApp.document.docparagraph.DocParagraph) → timApp.document.docparagraph.DocParagraph[source]#

named_section_exists(section_name: str) → bool[source]#

parwise_diff(other_doc: timApp.document.document.Document, view_ctx: Optional[timApp.document.viewcontext.ViewContext] = None)[source]#

raise_if_not_exist(par_id: str)[source]#

classmethod remove(doc_id: int, ignore_exists=False)[source]#

Removes the whole document.

Parameters: doc_id – Document id to remove.
Returns

set_settings(settings: dict | timApp.document.yamlblock.YamlBlock, force_new_par: bool = False)[source]#

text_to_paragraphs(text: str, break_on_elements: bool) → tuple[list[timApp.document.docparagraph.DocParagraph], timApp.document.validationresult.ValidationResult][source]#

update(text: str, original: str, strict_validation=True, regenerate_ids=False) → tuple[str, str, timApp.document.editing.documenteditresult.DocumentEditResult][source]#

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.
regenerate_ids – If True, paragraph IDs are regenerated for all blocks.

update_section(text: str, par_id_first: str, par_id_last: str) → tuple[str, str, timApp.document.editing.documenteditresult.DocumentEditResult][source]#

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.

validate() → timApp.document.validationresult.ValidationResult[source]#

classmethod version_exists(doc_id: int, doc_ver: tuple[int, int]) → bool[source]#

Checks if a document version exists.

Parameters

doc_id – Document id.
doc_ver – Document version.

Returns

Boolean.

timApp.document.document.add_index_entry(index_table, current_headers, header)[source]#

timApp.document.document.dereference_pars(pars: Iterable[timApp.document.docparagraph.DocParagraph], context_doc: timApp.document.document.Document, view_ctx: timApp.document.viewcontext.ViewContext | None) → list[timApp.document.docparagraph.DocParagraph][source]#

Resolves references in the given paragraphs.

Parameters

view_ctx –
pars – The DocParagraphs to be processed.
context_doc – The document being processing.

timApp.document.document.get_duplicate_id_msg(conflicting_ids)[source]#

timApp.document.document.get_index_from_html_list(html_table) → list[tuple][source]#

timApp.document.document.par_list_to_text(sect: list[timApp.document.docparagraph.DocParagraph], export_hashes=False)[source]#

timApp.document.documentparser module#

class timApp.document.documentparser.DocReader(lines, i=0)[source]#

Bases: object

Parameters

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

get_line_and_advance()[source]#

has_more_lines()[source]#

peek_line()[source]#

Return type: str
Returns

class timApp.document.documentparser.DocumentParser(doc_text='', options: Optional[timApp.document.documentparseroptions.DocumentParserOptions] = None)[source]#

Bases: object

Splits documents into paragraphs.

add_missing_attributes(hash_func=<function hashfunc>, id_func=<function random_id>, force_new_ids=False)[source]#

eat_whitespace(doc)[source]#

Return type: NoneType

extract_attrs(result, tokens)[source]#

get_blocks()[source]#

is_beginning_of_code_block(doc)[source]#

is_beginning_of_header_block(doc)[source]#

is_empty_line(doc)[source]#

parse_normal_block(doc)[source]#

try_parse_code_block(doc)[source]#

Return type: dict

try_parse_header_block(doc)[source]#

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

validate_structure() → timApp.document.validationresult.ValidationResult[source]#

timApp.document.documentparseroptions module#

class timApp.document.documentparseroptions.DocumentParserOptions(break_on_empty_line=False, break_on_code_block=True, break_on_header=True, break_on_normal=True)[source]#

Bases: object

static break_on_empty_lines() → timApp.document.documentparseroptions.DocumentParserOptions[source]#

static single_paragraph() → timApp.document.documentparseroptions.DocumentParserOptions[source]#

static whole_document() → timApp.document.documentparseroptions.DocumentParserOptions[source]#

timApp.document.documents module#

Defines the Documents class.

timApp.document.documents.add_reference_pars(doc: timApp.document.document.Document, original_doc: timApp.document.document.Document, r: str, translator: Optional[str] = None)[source]#

timApp.document.documents.apply_citation(new_doc: timApp.document.docinfo.DocInfo, src_doc: timApp.document.document.Document)[source]#

Creates a citation document. Each paragraph of the citation document references the paragraph in the original document.

Parameters

new_doc – The document where the citation paragraphs will be added.
src_doc – The original document to be cited.

timApp.document.documents.delete_document(document_id: int)[source]#

Deletes the specified document.

Parameters: document_id – The id of the document to be deleted.

timApp.document.documents.import_document(content: str, path: str, owner_group: timApp.user.usergroup.UserGroup, title: Optional[str] = None) → timApp.document.docinfo.DocInfo[source]#

timApp.document.documents.import_document_from_file(document_file: str, path: str, owner_group: timApp.user.usergroup.UserGroup, title: Optional[str] = None) → timApp.document.docinfo.DocInfo[source]#

Imports the specified document in the database.

Parameters

title – Title for the document.
document_file – The file path of the document to import.
path – The path for the document.
owner_group – The owner group of the document.

Returns

The created document object.

timApp.document.documentversion module#

class timApp.document.documentversion.DocumentVersion(doc_id: int, doc_ver: tuple[int, int], modifier_group_id: int | None = 0, preload_option=PreloadOption.none)[source]#

Bases: timApp.document.document.Document

add_paragraph(text: str, par_id: Optional[str] = None, attrs: Optional[dict] = None) → timApp.document.docparagraph.DocParagraph[source]#

Appends a new paragraph into the document.

Parameters

par_id – The id of the paragraph or None if it should be autogenerated.
attrs – The attributes for the paragraph.
text – New paragraph text.

Returns

The new paragraph object.

add_paragraph_obj(p: timApp.document.docparagraph.DocParagraph) → timApp.document.docparagraph.DocParagraph[source]#

Appends a new paragraph into the document.

Parameters

update_meta – Whether to update metadata.
p – Paragraph to be added.

Returns

The same paragraph object, or None if could not add.

add_ref_paragraph(src_par: timApp.document.docparagraph.DocParagraph, text: Optional[str] = None) → timApp.document.docparagraph.DocParagraph[source]#

cache_index()[source]#

create(ignore_exists: bool = False)[source]#

delete_paragraph(par_id: str)[source]#

Removes a paragraph from the document.

Parameters: par_id – Paragraph id to remove.

delete_section(area_start: str, area_end: str)[source]#

exists() → bool[source]#

static get_diff(d1, d2)[source]#

get_paragraph(par_id: str) → timApp.document.docparagraph.DocParagraph[source]#

get_settings() → timApp.document.docsettings.DocSettings[source]#

get_version() → tuple[int, int][source]#

Gets the latest version of the document as a major-minor tuple.

Returns: Latest version, or (-1, 0) if there isn’t yet one.

has_paragraph(par_id: str) → bool[source]#

Checks if the document has the given paragraph.

Parameters: par_id – The paragraph id.
Returns: Boolean.

Inserts a paragraph before a given paragraph id.

Parameters

par_id – The id of the new paragraph or None if it should be autogenerated.
attrs – The attributes for the paragraph.
text – New paragraph text.
insert_before_id – Id of the paragraph to insert before, or None if last.
insert_after_id – Id of the paragraph to insert after, or None if first.

Returns

The inserted paragraph object.

insert_paragraph_obj(p: timApp.document.docparagraph.DocParagraph, insert_before_id: Optional[str] = None, insert_after_id: Optional[str] = None) → timApp.document.docparagraph.DocParagraph[source]#

modify_paragraph(par_id: str, new_text: str, new_attrs: Optional[dict] = None) → timApp.document.docparagraph.DocParagraph[source]#

Modifies the text of the given paragraph.

Parameters

par_id – Paragraph id.
new_text – New text.
new_attrs – New attributes.

Returns

The new paragraph object.

modify_paragraph_obj(par_id: str, p: timApp.document.docparagraph.DocParagraph) → timApp.document.docparagraph.DocParagraph[source]#

classmethod remove(doc_id: int, ignore_exists=False)[source]#

Removes the whole document.

Parameters: doc_id – Document id to remove.
Returns

update(text: str, original: str, strict_validation=True)[source]#

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.
regenerate_ids – If True, paragraph IDs are regenerated for all blocks.

update_section(text: str, par_id_first: str, par_id_last: str) → tuple[str, str][source]#

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.

timApp.document.documentwriter module#

Defines the DocumentWriter class.

class timApp.document.documentwriter.DocumentWriter(pars, export_hashes=False, export_ids=True)[source]#

Bases: object

Converts a sequence of document blocks to text.

attrs_to_str(attrs)[source]#

get_text(options: Optional[timApp.document.documentparseroptions.DocumentParserOptions] = None)[source]#

Gets the full text for the document.

Returns: The full text of the document.

timApp.document.docviewparams module#

class timApp.document.docviewparams.DocViewParams(b: Optional[Union[int, str]] = None, e: Optional[Union[int, str]] = None, edit: Optional[str] = None, group: Optional[str] = None, hide_names: Optional[bool] = None, lazy: Optional[bool] = None, noanswers: bool = False, pars_only: bool = False, preamble: bool = False, size: Optional[int] = None)[source]#

Bases: object

View route parameters that affect document rendering.

b: int | str | None = None#

e: int | str | None = None#

edit: str | None = None#

group: str | None = None#

hide_names: bool | None = None#

lazy: bool | None = None#

noanswers: bool = False#

pars_only: bool = False#

preamble: bool = False#

size: int | None = None#

timApp.document.exceptions module#

exception timApp.document.exceptions.AttributesAtEndOfCodeBlockException[source]#: Bases: timApp.document.exceptions.ValidationException

exception timApp.document.exceptions.DocExistsError(doc_id)[source]#: Bases: Exception

exception timApp.document.exceptions.ValidationException[source]#: Bases: Exception

exception timApp.document.exceptions.ValidationWarning[source]#: Bases: timApp.document.exceptions.ValidationException

timApp.document.hide_names module#

timApp.document.hide_names.force_hide_names(current_user: timApp.user.user.User, d: timApp.document.docinfo.DocInfo, context_user: Optional[timApp.user.user.User] = None) → bool[source]#

timApp.document.hide_names.hide_names_in_teacher(d: timApp.document.docinfo.DocInfo, context_user: Optional[timApp.user.user.User] = None) → bool[source]#

Determines whether user names should be hidden.

Parameters

d – The document we’re viewing.
context_user – The user whose data we are inspecting. If same as currently logged-in user, we don’t have to

force hiding.

timApp.document.hide_names.is_hide_names() → bool[source]#

timApp.document.macroinfo module#

class timApp.document.macroinfo.MacroInfo(view_ctx: ViewContext, doc: Document | None = None, macro_map: dict[str, object] = <factory>, macro_delimiter: str = '%%', user_ctx: UserContext | None = None, preserve_user_macros: bool = False)[source]#

Bases: object

Represents information required for expanding macros in a DocParagraph.

doc: Document | None = None#

get_macro_delimiter() → str[source]#

get_macros() → dict[str, object][source]#

get_macros_preserving_user() → dict[str, object][source]#: Gets the macros and defines user-specific variables in such a way that the macro replacement for user variables does effectively nothing.

get_macros_with_user_specific(user: Optional[timApp.document.usercontext.UserContext] = None) → dict[str, object][source]#

jinja_env#

macro_delimiter: str = '%%'#: The delimiter used for macros in the markdown.

macro_map: dict[str, object]#: The mapping of macro keys to their values.

preserve_user_macros: bool = False#: If True and user is not provided, get_macros() will preserve the user-specific-macros (instead of replacing them with empty values).

user_ctx: UserContext | None = None#

view_ctx: ViewContext#

timApp.document.macroinfo.get_rnd_macros(rndmacros_setting: dict[str, str], user: User | None) → dict[str, str][source]#

timApp.document.macroinfo.get_url_macros(docmacros: dict[str, Any], urlmacros: Mapping[str, int | float | str], urlargs: dict[str, str]) → dict[str, str][source]#

timApp.document.macroinfo.get_user_specific_macros(user_ctx: timApp.document.usercontext.UserContext) → dict[str, str | None][source]#

Gets the macros that are specific to the user.

The user macros are defined as follows:

userid: The user id of the user.
username: The username of the user.
realname: The real name of the user.
useremail: The email address of the user.
loggedUsername: The username of the user that is logged in.
userfolder: The personal folder of the user.

Parameters: user_ctx – User context to get the macros for.
Returns: Dictionary of user macros.

timApp.document.par_basic_data module#

class timApp.document.par_basic_data.ParBasicData(attrs: dict[str, str], doc_id: int, hash: str, id: str, md: str)[source]#

Bases: object

attrs: dict[str, str]#

property attrs_str: str#: Returns the attributes as a JSON string.

doc_id: int#

hash: str#

id: str#

md: str#

timApp.document.post_process module#

Common functions for use with routes.

class timApp.document.post_process.Area(name: str, attrs: dict, visible: bool | None = None)[source]#

Bases: object

attrs: dict#

name: str#

visible: bool | None = None#

class timApp.document.post_process.PostProcessResult(texts: list[timApp.document.prepared_par.PreparedPar], js_paths: list[str], css_paths: list[str], should_mark_all_read: bool, plugins: list[timApp.plugin.plugin.Plugin], has_plugin_errors: bool)[source]#

Bases: object

css_paths: list[str]#

has_plugin_errors: bool#

js_paths: list[str]#

plugins: list[timApp.plugin.plugin.Plugin]#

should_mark_all_read: bool#

texts: list[timApp.document.prepared_par.PreparedPar]#

timApp.document.post_process.post_process_pars(doc: timApp.document.document.Document, pars: list[timApp.document.docparagraph.DocParagraph], user_ctx: timApp.document.usercontext.UserContext, view_ctx: timApp.document.viewcontext.ViewContext, sanitize: bool = True, do_lazy: bool = False, load_plugin_states: bool = True, filter_return: Optional[timApp.document.editing.globalparid.GlobalParId] = None) → timApp.document.post_process.PostProcessResult[source]#

timApp.document.post_process.process_areas(settings: timApp.document.docsettings.DocSettings, pars: list[timApp.document.docparagraph.DocParagraph], macros, delimiter, env: timApp.markdown.autocounters.TimSandboxedEnvironment, view_ctx: timApp.document.viewcontext.ViewContext, use_md: bool = False, cache: bool = True) → list[timApp.document.prepared_par.PreparedPar][source]#

timApp.document.post_process.should_auto_read(doc: timApp.document.document.Document, usergroup_ids: list[int], user: timApp.user.user.User, for_cache: bool = False) → bool[source]#

timApp.document.preloadoption module#

class timApp.document.preloadoption.PreloadOption(value)[source]#

Bases: enum.Enum

Specifies how a Document should preload its paragraphs in memory when a single paragraph is accessed.

all = 2#

none = 1#

timApp.document.prepared_par module#

class timApp.document.prepared_par.PreparedPar(data: ParBasicData, target: ParBasicData | None, output: str, html_class: str, from_preamble: str | None, authorinfo: AuthorInfo | None = None, status: ReadMarkCollection | None = None, notes: list[UserNoteAndUser] | None = None, areainfo: AreaBoundary | None = None, plugin_htmls: dict[str, str] | None = None)[source]#

Bases: object

Represents a “prepared” paragraph that is ready to be rendered (e.g. to HTML).

areainfo: AreaBoundary | None = None#

property attrs: dict[str, Any]#

property attrs_str: str#

authorinfo: AuthorInfo | None = None#

property class_str: str#

data: ParBasicData#

property doc_id: int#

from_preamble: str | None#

property hash: str#

html_class: str#

property id: str#

property is_setting: bool#

property md: str#

property needs_angular: bool#

notes: list[UserNoteAndUser] | None = None#

output: str#

plugin_htmls: dict[str, str] | None = None#

status: ReadMarkCollection | None = None#

target: ParBasicData | None#

property target_data: timApp.document.par_basic_data.ParBasicData#

timApp.document.randutils module#

timApp.document.randutils.hashfunc(text: str, attrs: Optional[dict] = None) → str[source]#

timApp.document.randutils.idchecksum(randid)[source]#

timApp.document.randutils.is_valid_id(randid)[source]#

timApp.document.randutils.random_id()[source]#

timApp.document.randutils.random_jsonpar(par_id)[source]#

timApp.document.randutils.random_paragraph()[source]#

timApp.document.randutils.random_sentence()[source]#

timApp.document.randutils.random_sentences()[source]#

timApp.document.randutils.random_word(min_len=2, max_len=12)[source]#

timApp.document.routes module#

class timApp.document.routes.GetBlockModel(doc_id: int, par_id: str, area_start: str | None = None, area_end: str | None = None, par_hash: str | None = None, use_exported: bool = True)[source]#

Bases: object

area_end: str | None = None#

area_start: str | None = None#

doc_id: int#

par_hash: str | None = None#

par_id: str#

use_exported: bool = True#

timApp.document.routes.diff_document(doc_id: int, major1: int, minor1: int, major2: int, minor2: int)[source]#

timApp.document.routes.download_document(doc_id: int, format: str = 'md', with_tl: bool = False)[source]#

timApp.document.routes.download_document_version(doc_id: int, major: int, minor: int, format: str = 'md')[source]#

timApp.document.routes.get_block(doc_id: int, par_id: str, area_end: str | None = None, area_start: str | None = None)[source]#

timApp.document.routes.get_block_2(args: timApp.document.routes.GetBlockModel)[source]#

timApp.document.routes.get_block_schema(args: timApp.document.routes.GetBlockModel)[source]#

timApp.document.routes.return_doc_content(d: timApp.document.document.Document, format: str = 'md', with_tl: bool = False)[source]#

timApp.document.specialnames module#

timApp.document.timjsonencoder module#

class timApp.document.timjsonencoder.TimJsonEncoder(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)[source]#

Bases: json.encoder.JSONEncoder

default(o)[source]#

Implement this method in a subclass such that it returns a serializable object for o, or calls the base implementation (to raise a TypeError).

For example, to support arbitrary iterators, you could implement default like this:

def default(self, o):
    try:
        iterable = iter(o)
    except TypeError:
        pass
    else:
        return list(iterable)
    # Let the base class default method raise the TypeError
    return JSONEncoder.default(self, o)

timApp.document.usercontext module#

class timApp.document.usercontext.UserContext(user: 'User', logged_user: 'User')[source]#

Bases: object

static from_one_user(u: User) → UserContext[source]#

property is_different: bool#

logged_user: User#

user: User#

timApp.document.validationresult module#

class timApp.document.validationresult.AreaEndWithoutStart(par_id: Optional[str], area_name: str)[source]#

Bases: timApp.document.validationresult.AreaIssue

property issue_name#

class timApp.document.validationresult.AreaIssue(par_id: Optional[str], area_name: str)[source]#

Bases: timApp.document.validationresult.ValidationIssue

property issue_name#

class timApp.document.validationresult.AreaWithoutEnd(par_id: Optional[str], area_name: str)[source]#

Bases: timApp.document.validationresult.AreaIssue

property issue_name#

class timApp.document.validationresult.AttributesAtEndOfCodeBlock(par_id: Optional[str])[source]#

Bases: timApp.document.validationresult.ValidationIssue

property issue_name#

class timApp.document.validationresult.DuplicateAreaEnd(par_id: Optional[str], area_name: str)[source]#

Bases: timApp.document.validationresult.AreaIssue

property issue_name#

class timApp.document.validationresult.DuplicateParagraphId(par_id: Optional[str])[source]#

Bases: timApp.document.validationresult.ValidationIssue

property issue_name#

class timApp.document.validationresult.DuplicateTaskId(par_id: Optional[str], task_id: str)[source]#

Bases: timApp.document.validationresult.ValidationIssue

property issue_name#

class timApp.document.validationresult.InvalidParagraphId(par_id: Optional[str])[source]#

Bases: timApp.document.validationresult.ValidationIssue

property issue_name#

class timApp.document.validationresult.MultipleAreasWithSameName(par_id: Optional[str], area_name: str)[source]#

Bases: timApp.document.validationresult.AreaIssue

property issue_name#

class timApp.document.validationresult.OverlappingClassedArea(par_id: Optional[str], area_name: str, second_area: str)[source]#

Bases: timApp.document.validationresult.AreaIssue

property issue_name#

class timApp.document.validationresult.ValidationIssue(par_id: Optional[str])[source]#

Bases: object

property issue_name#

class timApp.document.validationresult.ValidationResult[source]#

Bases: object

add_issue(issue: timApp.document.validationresult.ValidationIssue)[source]#

has_any_issue(*issues: type)[source]#

property has_critical_issues#

has_issue(issue: type)[source]#

raise_if_has_any_issues()[source]#

raise_if_has_critical_issues()[source]#

class timApp.document.validationresult.ZeroLengthArea(par_id: Optional[str], area_name: str)[source]#

Bases: timApp.document.validationresult.AreaIssue

property issue_name#

timApp.document.version module#

Document version number.

Format is major, minor.

Major version is incremented whenever a paragraph is added, inserted or deleted from the document. The minor version is reset to zero. Minor version is incremented whenever a paragraph is modified.

timApp.document.version.ver_to_str(v: tuple[int, int])[source]#

timApp.document.viewcontext module#

class timApp.document.viewcontext.OriginInfo(doc_id: int, par_id: str)[source]#

Bases: object

doc_id: int#

par_id: str#

class timApp.document.viewcontext.ViewContext(route: timApp.document.viewcontext.ViewRoute, preview: bool, partial: bool = False, hide_names_requested: bool = False, urlmacros: tuple[tuple[str, str], ...] = (), extramacros: str = '', origin: timApp.document.viewcontext.OriginInfo | None = None, for_cache: bool = False)[source]#

Bases: object

property args: dict[str, str]#

property extra_macros: dict[str, object]#

extramacros: str = ''#

for_cache: bool = False#

get_url_param(key: str) → str | None[source]#

hide_names_requested: bool = False#

isview(ret_val: bool, mode: Optional[Any] = None) → bool[source]#

origin: timApp.document.viewcontext.OriginInfo | None = None#

partial: bool = False#

preview: bool#

route: timApp.document.viewcontext.ViewRoute#

property url_params: tuple[tuple[str, str], ...]#

urlmacros: tuple[tuple[str, str], ...] = ()#

property viewmode: bool#

class timApp.document.viewcontext.ViewRoute(value)[source]#

Bases: enum.Enum

An enumeration.

Answers = 'answers'#

Lecture = 'lecture'#

Review = 'review'#

ShowSlide = 'show_slide'#

Slide = 'slide'#

Teacher = 'teacher'#

Unknown = 'unknown'#

Velp = 'velp'#

View = 'view'#

property is_review: bool#

property teacher_or_see_answers: bool#

timApp.document.viewcontext.copy_of_default_view_ctx(extramacros: dict[str, object]) → timApp.document.viewcontext.ViewContext[source]#

timApp.document.viewcontext.viewroute_from_str(s: str) → timApp.document.viewcontext.ViewRoute | None[source]#

timApp.document.viewparams module#

class timApp.document.viewparams.ViewParams(direct_link_timer: int = 15, goto: Optional[str] = None, login: bool = False, nocache: bool = False, wait_max: int = 0)[source]#

Bases: object

View route parameters that don’t affect document rendering.

direct_link_timer: int = 15#

goto: str | None = None#

login: bool = False#

nocache: bool = False#

wait_max: int = 0#

timApp.document.yamlblock module#

exception timApp.document.yamlblock.BlockEndMissingError(end_str: str)[source]#: Bases: yaml.error.YAMLError

exception timApp.document.yamlblock.DuplicateKeyMergeHintError(key: str)[source]#: Bases: yaml.error.YAMLError

exception timApp.document.yamlblock.InvalidIndentError(line: str)[source]#: Bases: yaml.error.YAMLError

class timApp.document.yamlblock.MergeStyle(value)[source]#

Bases: enum.Enum

An enumeration.

Append = 'a'#

Replace = 'r'#

ReplaceIfNotExist = 'r?'#

class timApp.document.yamlblock.YamlBlock(values: Optional[dict] = None, merge_hints: Optional[dict[str, timApp.document.yamlblock.MergeStyle]] = None)[source]#

Bases: object

static from_markdown(md: str)[source]#

get(key: str, default=None)[source]#

merge_with(other: timApp.document.yamlblock.YamlBlock)[source]#

to_markdown()[source]#

timApp.document.yamlblock.compare_same(s1: str, s2: str, n: int) → bool[source]#

Parameters

s1 – string than can contain max n spaces at the begining
s2 – string to oompare, no spaces in the begining
n – how many spaces allowed to caintain still to be same

Returns

True is same False other

timApp.document.yamlblock.correct_obj(text: str) → str[source]#

Also gives an other way to write unindented object attributes, by starting the attribute like: object: @!! (!! could any combinations of chars except space and ending it by !! in first column.

Parameters: text – Text to convert to proper yaml.
Returns: Text that is proper yaml obj

timApp.document.yamlblock.correct_yaml(text: str) → tuple[str, dict[str, timApp.document.yamlblock.MergeStyle]][source]#

Inserts missing spaces after : Like width:20 => width: 20 Also gives an other way to write multiline attributes, by starting the multiline like: program: |!! (!! could any combinations of chars except space and ending it by !! in first column.

Parameters: text – Text to convert to proper yaml.
Returns: Text that is proper yaml.

timApp.document.yamlblock.get_code_block_str(md: str) → str[source]#

timApp.document.yamlblock.merge(a: dict, b: dict, merge_info: Optional[dict[str, timApp.document.yamlblock.MergeStyle]] = None)[source]#

Merges two dictionaries recursively. Stores the result in the first dictionary.

Parameters

merge_info – The merge hints to use while merging.
a – The first dictionary.
b – The second dictionary.

timApp.document.yamlblock.parse_yaml(text: str) → tuple[dict, dict[str, timApp.document.yamlblock.MergeStyle]][source]#

Parses the specified text as (customized) YAML.

Parameters: text – The text to parse.
Returns: The parsed YAML as a dict.

timApp.document.yamlblock.strip_code_block(md: str) → str[source]#

timApp.document.yamlblock.verify_anchor_depth(text: str, max_depth=3) → None[source]#

Verifies that the given YAML file does not include too deep anchor references.

Anchor references can be used for quadratic growth DoS attacks when YAML is being iterated through. The method verifies that the maximum reference depth is within the provided value. Default max depth is 3.

If YAML includes deep references, YAMLError is thrown.

Parameters

text – YAML to check
max_depth – Maximum anchor reference depth

TIM documentation

timApp.document package

Contents

timApp.document package#

Subpackages#

Submodules#

timApp.document.areainfo module#

timApp.document.attributeparser module#

timApp.document.caching module#

timApp.document.changelog module#

timApp.document.changelogentry module#

timApp.document.create_item module#

timApp.document.docentry module#

timApp.document.docinfo module#

timApp.document.docparagraph module#

timApp.document.docrenderresult module#

timApp.document.docsettings module#

timApp.document.document module#

timApp.document.documentparser module#

timApp.document.documentparseroptions module#

timApp.document.documents module#

timApp.document.documentversion module#

timApp.document.documentwriter module#

timApp.document.docviewparams module#

timApp.document.exceptions module#

timApp.document.hide_names module#

timApp.document.macroinfo module#

timApp.document.par_basic_data module#

timApp.document.post_process module#

timApp.document.preloadoption module#

timApp.document.prepared_par module#

timApp.document.randutils module#

timApp.document.routes module#

timApp.document.specialnames module#

timApp.document.timjsonencoder module#

timApp.document.usercontext module#

timApp.document.validationresult module#

timApp.document.version module#

timApp.document.viewcontext module#

timApp.document.viewparams module#

timApp.document.yamlblock module#

Module contents#