timApp.markdown package

Submodules

timApp.markdown.autocounters module

class timApp.markdown.autocounters.AutoCounters(macros: dict | None, doc: Document | None = None)

Bases: object

add_counter(ctype: str, name: str, show_val: str, long_val: str = '') → dict | None

Used to add chapter and paragraph counters.

Parameters

• ctype – usually “chap”

• name – counters name

• show_val – value like 2.4

• long_val – long for with tilte like 2.4 Counters

Returns

None

auto_labels: bool

auto_name_base: str | None

auto_name_counter: int

auto_name_ctype: str

auto_name_plugin: bool

auto_number_headings: int

autocnts: TMacroCounters

autocounters: dict[str, Any]

autonames: TAutoNames

begin1_counter(name: Union[str, int], what: str = 'align*', ctype: str = 'eq') → str

For filter c_begin1 Creates one label, LaTeX environment begin and counter for first equation

Parameters

• name – name + base name for autoname

• what – what LaTeX environment to start

• ctype – what is default type for counters

Returns

label, LaTeX begin commands and one counter

begin_counter(name: Union[str, int], what: str = 'align*', ctype: str = 'eq') → str

For filter c_begin Cretes placfeholder for labels and LaTeX environment begin

Parameters

• name – base name for autoname

• what – what LaTeX environment to start

• ctype – what is default type for counters

Returns

label’s placeholder and LaTeX begin commands

block_counters: TMacroCounters

counter_stack: list[str]

counters: TCounters

create_new_counter(name: Union[str, int], ctype: str) → tuple[str, str, dict[str, Union[str, int]]]

Create new counter as text that has name and ctype

Parameters

• name – counters name, can include pre text t1 and post text t2

• ctype – counters type

Returns

counter as text and name

current_labels: list[str]

do_char_macros(text: str) → str

Do counters charmacros

Parameters

text – what to convert

Returns

converted text

doc: Document | None

doing_latex_environment = False

end_counter(_dummy: str = '') → str

For filter c_end End last started LaTeX egin command Move last used labels to cache

Parameters

_dummy – this filter has no parameters

Returns

LaTeX environment end command

eq_counter(name: Union[str, int]) → str

For filter c_eq, same as “name” | c_n(eq”)

Parameters

name – counter’s name

Returns

tag counter

error(s: str) → str

Return string as md red

Parameters

s – string to show as red

Returns

s surrounded be []{.red}

ex_counter(name: Union[str, int]) → str

fig_counter(name: Union[str, int]) → str

get_auto_name(name: str, ctype: str) → tuple[str, str, str | None]

Get automatic name and ctype if not given

Parameters

• name – if empty, give autoname

• ctype – if empty give ctype from auto name

Returns

name, ctype, error

get_base_name(name: str) → str

Returns basename for name

Parameters

name – name to use

Returns

basename

get_counter_macros(_dummy: Union[str, int] = 0) → str

Return counter values as string to be appended to settings

Parameters

_dummy – if used as filter

Returns

counter values as settigs macro

get_counter_type(ctype: str) → timApp.markdown.autocounters.TOneCounterType

Get type counter, so with value of how many has been totally during the whole document. If this is first call for ctype, create new type counter.

Parameters

ctype – counter’s type

Returns

type counter with value.

get_counter_value(ctype: str) → int

For filter c_get Gets the value of counter while renumbering

Parameters

ctype – for what type of counters

Returns

0 in view, but value of counter in renumbering

get_label_placeholder() → str

returns next labels placeholder if there is labels that can not be anchored to begining of the LaTeX environment :return: placeholder for label that is replaced by

real labes after whole block is ready

get_show_params(name: Union[str, int], showtype: str = 'r') → tuple[str, str, dict[str, Union[str, int]], str]

Get show parameters for counter name.

Parameters

• name – name to separate t1, name nand t2

• showtype – how to show counter with name

Returns

sname, text for counter, macros for counter, document the reference is located in

static get_texts_and_name(name: Union[str, int]) → tuple[str, str, str]

Separate from “t1|name|t2” t1, name and t2. If like “name” jsu return “”, name, t2

Parameters

name – counter name where pre and post texts are separated

Returns

t1, name, t2

get_type_text(ctype: str, name: str, value: int | str, showtype: str, pure: str) → str

Get how to show counter with type name ctype

Parameters

• ctype – counter’s type name

• name – name of counter

• value – value of counter to show

• showtype – for what purpose value is formated

• pure – pure value of counter

Returns

formated show value

heading_vals: dict | None

heading_vals_def: dict[int, int]

is_plugin = False

label_cache: list[list[str]]

static label_place_holder(n: int) → str

Placeholder for labels that should come before egin

Parameters

n – What is the number of this olaceholder in this block

Returns

string like <!– LABEL002 –>

labels(names: list) → str

For filter labels Creates a a-tag or LaTeX label list from counter names.

Parameters

names – list of counter names that are converted to labels

Returns

string to output either a-tag’s or LaTeX labels

make_latex_envoronment_begin(name: Union[str, int], what: str = 'align*', ctype: str = 'eq') → str

Crete LaTeX environment begin with label before

Parameters

• name – base name for equations

• what – what LaTeX environment to start

• ctype – type for counters

Returns

need_label_update = False

need_update_labels = False

new_autonames: TAutoNames

new_counter(name: Union[str, int], ctype: str = '') → str

Creates a counter for filter c_n

Parameters

• name – counter’s name

• ctype – counter’s type

Returns

counter as text

new_label_counter(name: Union[str, int], ctype: str = '') → str

Creates a counter for filter c_

Parameters

• name – counter’s name can be also “text|name”

• ctype – counter’s type

Returns

counter as text with label where to jump

par: DocParagraph | None

pure_reset_formats: list[str]

renumbering: bool

reset_counters(n: int) → None

Reset all counters that should be reset when heading level n changes

Parameters

n – what heading level to check

Returns

None

reset_label_cache() → None

Reset label cache so that new label list’s can start :return: None

set_auto_name(base_name: str) → str

Set start of autonames

Parameters

base_name – base name for counters in this block

Returns

emtpy string because used from filter

set_auto_names(base_name: Optional[Union[str, int]], ctype: str = 'eq') → str

Set start of autonames

Parameters

• base_name – base name for counters in this block

• ctype – default type for counters in this block

Returns

emtpy string because used from filter

set_auto_number_headings(n: int) → None

Set from what level the headings are numbered. Make also the dafault counter number template for that level like “{h2}.{v}” if counting start from level 2.

Parameters

n – from what level to start heading counting

Returns

none

set_counter(value: int, ctype: str) → str

For filter c_set Sets the type counter value

Parameters

• value – new value

• ctype – for what type of counters

Returns

””

set_env_filters(env: jinja2.sandbox.SandboxedEnvironment) → None

Add new filters to environment

Parameters

env – to what environment to add values

Returns

None

set_heading_vals(vals: dict) → None

This should be called every time when handling heading line. Check whta counters should be reseted when heading numebrs changes

Parameters

vals – new values for current heading numbers

Returns

None

set_renumbering(value: bool) → None

This should be called from print command that generates new values

Parameters

value – is renumbering true or false

Returns

None

show_lref_value(name: Union[str, int], showtype: str = 'l') → str

Return long reference to counter using hyperlink

Parameters

• name – counter’s name

• showtype – how to show counter

Returns

string for reference

show_pref_value(name: Union[str, int], showtype: str = '') → str

Return pure reference for counter name (without jump link)

Parameters

• name – counter’s name

• showtype – how to show counter

Returns

string for reference

show_ref_value(name: Union[str, int], showtype: str = '') → str

Return reference to counter using hyperlink

Parameters

• name – counter’s name

• showtype – how to show counter

Returns

string for reference

start_of_block() → None

Do things needed to know when convertiong of new block starts Can autoname and cache labels in one block. Remember to do reset_label_cache when used first time Also reset auto names before first use :return: None

tag_counter(name: Union[str, int], ctype: str = 'eq', lf: str = '\\\\') → str

For filter c_tag Counter inside LaTeX ag{}

Parameters

• name – counter’s name

• ctype – type for the counter, default for eq

• lf – what is coming to the end of counterline

Returns

tag counter

task_counter(name: Union[str, int]) → str

task_id: str | None

tbl_counter(name: Union[str, int]) → str

tex: bool

update_labels(text: str) → str

Replace label placeholders by actual labels. This should be called when block is totally converted.

Parameters

text – block text where to replace labels

Returns

text with labels inserted

class timApp.markdown.autocounters.TOneCounterType(count: 'int' = 0, counters: 'dict[str, TCounter]' = <factory>)

Bases: object

count: int = 0

counters: dict[str, dict[str, Union[str, int]]]

class timApp.markdown.autocounters.TimSandboxedEnvironment(macro_delimiter: str = '%%', autoescape: bool = False)

Bases: jinja2.sandbox.SandboxedEnvironment

Environment to replace Jinja2 environment. Add auto counters to environment

get_counters() → timApp.markdown.autocounters.AutoCounters | None

set_counters(counters: timApp.markdown.autocounters.AutoCounters) → None

timApp.markdown.autocounters.add_h_values(counts: dict, values: dict) → None

Add all non-zero h-value from counts to values

Parameters

• counts – where to finds h-values

• values – where to add h-values

Returns

None

timApp.markdown.autocounters.check_autonumber_error(m: str) → str | None

timApp.markdown.autocounters.escape_yaml_key(key: str) → str

timApp.markdown.dumboclient module

Defines a client interface for using Dumbo, the markdown converter.

exception timApp.markdown.dumboclient.DumboHTMLException

Bases: Exception

code = 400

description = ''

class timApp.markdown.dumboclient.DumboOptions(math_type, math_preamble, input_format, smart_punct)

Bases: NamedTuple

static default()

dict()

input_format: timApp.markdown.dumboclient.InputFormat

Alias for field number 2

math_preamble: str

Alias for field number 1

math_type: timApp.markdown.dumboclient.MathType

Alias for field number 0

smart_punct: bool

Alias for field number 3

class timApp.markdown.dumboclient.InputFormat(value)

Bases: enum.Enum

An enumeration.

CommonMark = 'commonmark'

GitHubMarkdown = 'gfm'

LaTeX = 'latex'

Markdown = 'markdown'

MarkdownStrict = 'markdown_strict'

MediaWiki = 'mediawiki'

RST = 'rst'

static from_string(s: str)

class timApp.markdown.dumboclient.MathType(value)

Bases: enum.Enum

An enumeration.

MathJax = 'mathjax'

PNG = 'png'

SVG = 'svg'

static from_string(s: str)

timApp.markdown.dumboclient.call_dumbo(data: list[str], path='', options: timApp.markdown.dumboclient.DumboOptions = DumboOptions.default(), data_opts: list[timApp.markdown.dumboclient.DumboOptions] | None = None) → list[str]

timApp.markdown.dumboclient.call_dumbo(data: dict, path='', options: timApp.markdown.dumboclient.DumboOptions = DumboOptions.default(), data_opts: list[timApp.markdown.dumboclient.DumboOptions] | None = None) → dict

timApp.markdown.dumboclient.call_dumbo(data: list[dict], path='', options: timApp.markdown.dumboclient.DumboOptions = DumboOptions.default(), data_opts: list[timApp.markdown.dumboclient.DumboOptions] | None = None) → list[dict]

Calls Dumbo for converting the given markdown to HTML.

Parameters

• options – Options for Dumbo.

• data – The data to be converted.

• path – The path of the request. Valid paths are: ‘’, ‘/’, ‘/mdkeys’ and ‘/markdown’ (same as ‘/’ and ‘’). If path is ‘/mdkeys’, data is expected to be a Dict or List[Dict]. Any dict value that begins with ‘md:’ is interpreted as Pandoc markdown and is converted to HTML. Otherwise the value is unchanged. The return value format will be the same as input. Otherwise, data is expected to be a List[str]. Each string is interpreted as Pandoc markdown and is converted to HTML. The return value format will be the same as input.

timApp.markdown.markdownconverter module

Provides functions for converting markdown-formatted text to HTML.

class timApp.markdown.markdownconverter.Belongs(user_ctx: 'UserContext')

Bases: object

belongs_to_group(groupname: str)

user_ctx: timApp.document.usercontext.UserContext

timApp.markdown.markdownconverter.Pz(i)

Returns number as a string so that from 0 comes “”, postive number comes like ” + 1” and negative comes like ” - 1”

Parameters

i – number to convert

Returns

number as a string suitable for expressions

timApp.markdown.markdownconverter.belongs_placeholder(_s)

timApp.markdown.markdownconverter.change_class(text_containing_html_tag: str, text_content: str, new_class: str) → list

Find the last html tag in the list and change that element’s class to new_class or add the new class to element’s classes or surround the new content with span element with the new class.

timApp.markdown.markdownconverter.change_classes_to_fragment(html_list: list) → str

If found, html_list[1] will have the content that we need to make a fragment of and html_list[0] might have the element tag that will have “fragment” added to it’s class.

There might be multiple fragments in the html list.

timApp.markdown.markdownconverter.check_and_edit_html_if_surrounded_with(html_content: str, string_delimeter: str, editing_function) → str

timApp.markdown.markdownconverter.create_environment(macro_delimiter: str, user_ctx: UserContext | None, view_ctx: ViewContext, macros: dict | None, doc: Document | None = None) → TimSandboxedEnvironment

timApp.markdown.markdownconverter.edit_html_with_own_syntax(raw: list) → list

timApp.markdown.markdownconverter.expand_macros(text: str, macros, settings: DocSettings | None, env: TimSandboxedEnvironment, ignore_errors: bool = False)

timApp.markdown.markdownconverter.fmt(x, f: str)

timApp.markdown.markdownconverter.fmt_date(d, frmt='')

Format date using extended %d1 and %m1 for one number values see: timApp/tests/unit/test_datefilters.py

Parameters

• d – date to format

• frmt – Python format

Returns

string from d an format

timApp.markdown.markdownconverter.format_heading(text, level, counts, heading_format, heading_ref_format: Optional[dict] = None, jump_name: Optional[str] = None, counters: Optional[timApp.markdown.autocounters.AutoCounters] = None, initial_counts: Optional[dict[int, int]] = None)

timApp.markdown.markdownconverter.genfields(flds, attrs='', stemfield='stem')

Generates fields from namelist like [‘se1’, ‘d1’, ‘d2=demo2’] See usescases from: /tim/timApp/tests/server/test_genfields.py

Parameters

• flds – list of fields, maybe with aliases to show in stem

• attrs – possible list of attributes

• stemfield – field to use to show filed ste, like sten, header or inputstem

Returns

TIM-format of fields

timApp.markdown.markdownconverter.get_document_id(doc_path: Any) → int

timApp.markdown.markdownconverter.get_document_path(doc_id: Any) → str

timApp.markdown.markdownconverter.gfrange(s, i1, i2, attrs='', stemfield='stem')

timApp.markdown.markdownconverter.has_macros(text: str, env: timApp.markdown.autocounters.TimSandboxedEnvironment)

timApp.markdown.markdownconverter.insert_heading_numbers(html_str: str, heading_info, auto_number_headings: int | bool = True, heading_format: Optional[dict] = None, initial_heading_counts: Optional[dict[int, int]] = None)

Applies the given heading_format to the HTML if it is a heading, based on the given heading_info. Additionally corrects the id attribute of the heading in case it has been used earlier.

Parameters

• heading_info – A dict containing the heading information (‘h’: dict(int,int) of heading counts and ‘headings’: dict(str,int) of so-far used headings and their counts).

• html_str – The HTML string to be processed.

• auto_number_headings – Whether the headings should be formatted at all.

• heading_format – A dict(int,str) of the heading formats to be used.

• initial_heading_counts – Initial heading counter value for each level

Returns

The HTML with the formatted headings.

timApp.markdown.markdownconverter.make_slide_fragments(html_text: str) → str

timApp.markdown.markdownconverter.md_to_html(text: str, sanitize: bool = True, macros: Optional[dict[str, object]] = None) → str

Converts the specified markdown text to HTML.

Parameters

• macros – The macros to use.

• sanitize – Whether the HTML should be sanitized. Default is True.

• text – The text to be converted.

Returns

A HTML string.

timApp.markdown.markdownconverter.month_to_week(month, daynr=1, year=None)

get week number for month see: timApp/tests/unit/test_datefilters.py

Parameters

• month – month numer starting from 1

• daynr – day number of month

• year – from what year

Returns

week number

timApp.markdown.markdownconverter.now(frmt=0)

Used in Jinja macros like tomorrow: %%1 | now%% Or this week %% “%w” | now %%

Parameters

frmt – format for current date or delta for current date

Returns

current date + (fmt as int) if fmt is int, otherwise current timestamp formated

timApp.markdown.markdownconverter.par_list_to_html_list(pars: list[DocParagraph], settings: DocSettings, view_ctx: ViewContext, auto_macros: Iterable[dict] | None = None)

Converts the specified list of DocParagraphs to an HTML list.

Parameters

• view_ctx –

• settings – The document settings.

• auto_macros – Currently a list(dict) containing the heading information (‘h’: dict(int,int) of heading counts and ‘headings’: dict(str,int) of so-far used headings and their counts).

• pars – The list of DocParagraphs to be converted.

Returns

A list of HTML strings.

timApp.markdown.markdownconverter.postinc(v, delta=1)

timApp.markdown.markdownconverter.preinc(v, delta=1)

timApp.markdown.markdownconverter.srange(s, i1, i2, step=1, *argv)

Jinja2 filter for generating indexed names

Parameters

• s – format string for item

• i1 – start index

• i2 – exclusive end index

• step – how much increment

:param argv pair of value to add and mul index :return: like “d1 d2 d3 ” by call sfrom(‘d{0} ‘, 1, 3)

timApp.markdown.markdownconverter.url_quote(s: Any) → str

timApp.markdown.markdownconverter.week_to_date(week_nr, daynr=1, year=None, frmt=None)

date object for week see: timApp/tests/unit/test_datefilters.py

Parameters

• week_nr – week number to get the date object

• daynr – day of week to get date

• year – year to get date

• frmt – extended format string

Returns

date object or formated string

timApp.markdown.markdownconverter.week_to_text(week_nr, year=None, frmt=' %d1.%m1|', days='ma|ti|ke|to|pe|', first_day=1)

Convert week to clendar header format see: timApp/tests/unit/test_datefilters.py

Parameters

• week_nr – what week to convert

• year – what year

• frmt – extended Python date format

• days – pipe separated list of day names

• first_day – from what weekday to start

Returns

string suitable for calandar header

Module contents