Utilities

Counter Formatters

The flm.counter module provides functions for formatting numbers in various styles (alphabetic, roman, Arabic, Unicode superscript, etc.). These are used by features such as footnotes, equations, and enumerations.

flm.counter.alphacounter(n, lower=True)

Returns a string representing the number n using a latin letter, starting at n=1. The sequence is ‘a’, ‘b’, ‘c’, …, ‘y’, ‘z’, ‘aa’, ‘bb’, …, ‘zz’, ‘aaa’, …

If lower=True (the default), then lowercase letters are used. Uppercase letters are used if lower=False.

flm.counter.Alphacounter(n)

Shorthand for alphacounter(n, lower=False).

flm.counter.romancounter(n, lower=True, zero='')

Returns a string representing the number n as a roman numeral (I, II, III, IV, etc.).

If lower=True (the default), then lowercase letters are used; uppercase letters are used if lower=False.

The argument zero is a string to return in case n is equal to zero (by default, an empty string).

flm.counter.Romancounter(n)

Shorthand for romancounter(n, lower=False).

flm.counter.fnsymbolcounter(n, symbols=['*', '†', '‡', '§', '¶', '‖'])

Return a symbol that is suitable for representing a footnote whose internal numbering is given by n. Numbering starts at n=1.

The argument symbols provides a sequence of symbols to go through. By default, the sequence is '*', '†', '‡', '§', '¶', '‖'.

For n larger than the symbols sequence length, we begin returning the symbol repeated multiple times. I.e., with the default symbols sequence, we’ll get '*', '†', '‡', '§', '¶', '‖', '**', '††', ..., '‖‖', '***', ...

flm.counter.customdigitscounter(n, digits: str | list[str] = '0123456789')

Return a string representation of n using the digits digits (the base is determined by the length of the digits list).

For example, to get a binary representation of n using ‘F’ and ‘T’ instead of ‘0’ and ‘1’, you can use customdigitscounter(n, 'FT')

flm.counter.unicodesuperscriptcounter(n)

Return a unicode string representation of the number n, in base 10, using unicode superscript characters.

For instance, unicodesuperscriptcounter(17) == "¹⁷".

flm.counter.unicodesubscriptcounter(n)

Return a unicode string representation of the number n, in base 10, using unicode subscript characters.

For instance, unicodesubscriptcounter(17) == "₁₇".

flm.counter.standard_counter_formatters = {'Alph': <function <lambda>>, 'Roman': <function <lambda>>, 'alph': <function <lambda>>, 'arabic': <class 'str'>, 'fnsymbol': <function fnsymbolcounter>, 'roman': <function <lambda>>, 'unicodesubscript': <function unicodesubscriptcounter>, 'unicodesuperscript': <function unicodesuperscriptcounter>}

Dictionary providing standard counter formatters by name. Some names mirror their LaTeX counter formatter counterparts (e.g., ‘arabic’, ‘Roman’).

The value of the dictionary is a callable (function or lambda) that takes a positional argument (the number) and returns a string representation of that number.

flm.counter.parse_counter_format_num(counter_formatter: ~typing.Literal['alph', 'Alph', 'roman', 'Roman', 'arabic', 'fnsymbol', 'unicodesuperscript', 'unicodesubscript'] | ~flm._typing_helpers.TypeFormatNumTemplate | ~typing.Callable[[int], str], named_counter_formatters: dict[str, ~typing.Callable[[int], str]] = {'Alph': <function <lambda>>, 'Roman': <function <lambda>>, 'alph': <function <lambda>>, 'arabic': <class 'str'>, 'fnsymbol': <function fnsymbolcounter>, 'roman': <function <lambda>>, 'unicodesubscript': <function unicodesubscriptcounter>, 'unicodesuperscript': <function unicodesuperscriptcounter>}, str_use_tag_template: bool = False, tag_template_initials_counters: dict[str, ~typing.Callable[[int], str]] = {'1': <class 'str'>, 'A': <function Alphacounter>, 'I': <function Romancounter>, 'a': <function alphacounter>, 'i': <function romancounter>})

Doc………..

flm.counter.parse_counter_format_subnum(format_subnum: Callable[[int], TypeSubnumResult] | TypeSubnumFormatDict)

flm.counter.build_counter_formatter(counter_formatter: None | TypeCounterFormatter | Literal['alph', 'Alph', 'roman', 'Roman', 'arabic', 'fnsymbol', 'unicodesuperscript', 'unicodesubscript'] | TypeFormatNumTemplate | TypeCounterFormatterSpecDict, default_counter_formatter_spec: TypeCounterFormatterSpecDict, *, counter_formatter_id: str) → CounterFormatter

Build a CounterFormatter instance from the given configuration counter_formatter. It can be a string (e.g. ‘arabic’) or a dictionary (doc………………….)

class flm.counter.ValueWithSubNums(value, subnums=())

get_num()

get_subnums()

astuple()

targetidstr(numprefix=None)

does_immediately_succeed(val2)

equals(val2)

incremented(subnum_level=None)

extended_by_one(subnum_value=0)

class flm.counter.CounterFormatter(format_num: Literal['alph', 'Alph', 'roman', 'Roman', 'arabic', 'fnsymbol', 'unicodesuperscript', 'unicodesubscript'] | TypeFormatNumTemplate | Callable[[int], str], prefix_display: None | str | TypePrefixDisplaySpec = None, delimiters: tuple[str, str] | None = None, join_spec: None | Literal['default', 'compact'] | TypeJoinSpecDict = None, name_in_link: bool = True, repeat_numprefix_in_range: bool = False, counter_formatter_id: None | str = None, subnums_format_nums: Sequence[Callable[[int], TypeSubnumResult] | TypeSubnumFormatDict] = ())

Engine to format one or more counter values, including prefixes/suffixes (with plural forms), hyperlinks, labels, ranges, and conjuctions.

E.g. Equation (2), Equations (3)–(5).

FIXME: Document me! Doc…………………..

format_number(n, numprefix=None, subnums=None)

get_subnums_format_nums(n, *, numprefix=None, subnums=None)

asdict()

format_flm(value, numprefix=None, subnums=None, prefix_variant=None, with_delimiters=True, with_prefix=True, wrap_format_num=None, wrap_link_fn=None)

Doc…….

Value is an integer, any numprefix should be specified separately via the numprefix arg. …………..

format_many_flm(values, prefix_variant=None, with_delimiters=True, with_prefix=True, wrap_link_fn=None, wrap_format_num=None, get_raw_s_items=False, s_items_join=None)

DOC……….

Here, values may include a “numprefix” and “subnums”…..

values = [list of values…] values = [(numprefix, [list of values…]), (numprefix2, […]), …]

also each [list of values…] can be a list that contains ints but also ValueWithSubNums() instances with sub-numbers.