Python Markdown: options precedence

Contents

The winner: environment variables

Given the discussion below, I’ve declared configuration options to be at the bottom of the prioirity list. The priority order, from most important to least, is:

  • MDX_EXT_NAME_OPTION environment variable, so I can over-ride meta-data without modifying a file
  • Meta-data keyword
  • For the full_html extension, title comes from the first header in the input
  • Configuration option

Meta-data vs config options: meta-data takes precedence

I note that Python Markdown’s officially supported extensions and my extensions differ on the precdence of meta-data and configuration options:

  • In Python Markdown, meta-data overrides config options. This puts config options at lowest priority: specifying a config option doesn’t change an extension’s behaviour if there’s a meta-data entry in the input.
  • My extensions currently have meta-data low, followed by environment variables, followed by config options. I’ve put config options high–the exact opposite of how Python Markdown does it.

The case for environment variables

Python markdown has been in development for twelve years; the first commmit was back in March 2006. In all that time, not one extension has ever used an environment variable to alter the way it works. It’s all done through the use of configuration options or a configuration file named on the command line. That means for my own extensions I’m likely to be the only person to define an environment variable and expect it to work. Ergo, should it not work regardless of the configuration options?

In addition, assuming I’ve gone to the trouble of writing an elaborate config file, I may want to use that from the command line most of the time when I’m running Python markdown, and use environment variables as needed to override the file. By the time my extensions get to determining their confiugration, all they know is they have config values; they don’t know if the values were passed to the directly to the Extension object or if they were first read from a file and then passed. So they can’t decide to use an option if it came from the command line, ignore it if it came from a configuration file, and use it in favour of anything else if it was passed directly to the object when it was instantiated.

The case for config options

Configuration options can be specified at execution time in the Python shell or a Python program. Here we use the proc_summary extension and override the standard summary layout with a custom one:

import sys
sys.path.append('/home/brian/projects/python')
from markdown import markdown, markdownFromFile
from markdown_extensions.proc_summary import ProcSummaryExtension
print(markdown('Testing', extensions = [ ProcSummaryExtension(layout='%Q') ]))

If the environment variable MDX_PROC_SUMMARY_LAYOUT took precedence, in the above example it wouldn’t matter what was passed to ProcSummaryExtension; the output would always be formatted according to the environment variable.

However, as noted in Meta-data vs config options: meta-data takes precedence above, in the two officially supported extensions that use meta-data–wikilinks and headerid )which is being deprecated)–meta-data overrides configuration.