app#

Applications that execute the steps of the RSM file processing pipeline.

Classes in this module use the steps implemented elsewhere (rsm.reader, rsm.tsparser, etc) and actually execute those steps, feeding the output of one step into the next. The base class for all of these is RSMApp, which stores the sequence of steps and executes them all via a run() method.

The three main applications provided currently are make(), render(), and lint(). These simply instantiate an object of class FullBuildApp, LinterApp, ProcessorApp, respectively, and call their run() method.

The functions make(), render(), and lint() can be called directly via rsm.make(), rsm.render(), and rsm.lint(). They each receive RSM source (either a string or a path to a file), run the application, and return the result. For more control over the execution, or post-execution inspection, instantiate the appropriate class manually. For example, this:

>>> src = "Hello, RSM!"
>>> html = rsm.build(source=src)

Is essentially equivalent to the following:

>>> app = FullBuildApp(plain=src)
>>> html = app.run()

Except that now, app can be inspected:

>>> print(app.parser.ast.sexp())
(Manuscript
  (Paragraph
    (Text)))

The module rsm.cli exposes these apps as command line utilities.

The RSM library code (i.e. all of the previous modules) does not itself set up any logging facilities. This is at recommendation of the Python standard library. Instead, this module uses the functions in rsm.rsmlogger before executing an application. In other words, manually handling RSM source with classes such as rsm.tsparser.TSParser or rsm.transformer.Transformer will not issue any logging messages, while calling the run() method on an RSMApp instance will.

Classes

FullBuildApp

LinterApp

ParserApp

Pipeline

A sequence of Task instances executed one after the other.

ProcessorApp

RSMApp

Task

A step in a Pipeline.

Functions

rsm.app.build(source='', path='', handrails=True, lint=True, loglevel=30, log_format='rsm', log_time=True, log_lineno=True, asset_resolver=None, structured=False, standalone=False, write_output=False, output_dir='.', output_filename='index.html', custom_css=None, theme_toggle=True, menu_position='left', strict=False)[source]#

Process RSM source and optionally write output files.

Parameters:

  • source (str) – RSM source as a string

  • path (str) – Path to RSM source file

  • handrails (bool) – Include interactive handrails in output

  • lint (bool) – Run linter before building

  • loglevel (int) – Logging level

  • log_format (str) – Format for log messages

  • log_time (bool) – Include timestamps in logs

  • log_lineno (bool) – Include line numbers in logs

  • asset_resolver (AssetResolver, optional) – Custom asset resolver

  • structured (bool) – Return structured dict instead of HTML string

  • standalone (bool) – Generate standalone HTML with CDN URLs

  • write_output (bool) – Write output files to disk (index.html + static/). When False (default), returns HTML without writing files. When True, writes files and still returns HTML.

  • output_dir (str) – Directory where output files should be written (default: “.”)

  • output_filename (str) – Name of the main HTML file (default: “index.html”)

  • theme_toggle (bool) – Include dark mode toggle button and localStorage script (default: True)

  • menu_position (str) – Position of handrail context menus: “left” or “right” (default: “left”)

  • strict (bool) – Raise exception if CST errors are detected after transformation (default: False)

Returns:

str or dict – HTML string (or structured dict if structured=True)

Return type:

str | dict

rsm.app.lint(source='', path='', handrails=False, loglevel=30, log_format='rsm', log_time=True, log_lineno=True, strict=False)[source]#
rsm.app.render(source='', path='', handrails=False, add_source=False, loglevel=30, log_format='rsm', log_time=True, log_lineno=True, asset_resolver=None, strict=False)[source]#

Exceptions

RSMApplicationError