dmr API

Input

Input parsing routines for dmr.

dmr.input.parse(filehandle)

Parse a document read from the given filehandle into a dmr.data.Document object.

The document must contain:

• A top-level title, the resume owner’s name;
• A docutils.nodes.line_block containing contact information for the resume, to be parsed with dmr.data.Contact.parse(); and
• Any number of subsections that conform to the restrictions of the various dmr.data.Section subclasses.

Parameters:filehandle (file) – The file-like object to parse the document from. Returns:dmr.data.Document

Output

class dmr.output.base.BaseOutput(document)

Bases: object

Base dmr output class. All dmr output format classes should inherit from this class.

Parameters:document (dmr.data.Document) – The DMR document to output

document = None

The dmr.data.Document object to output

classmethod get_options()

Get a list of options to parse from the config files and command line when this output class is selected.

Returns:list - A list of dmr.config.DMROption objects

output()

Get the document output as rendered by this output format. Child classes must implement this method.

Returns:str - The document output

HTML

This module provides a dmr output format to write HTML output using the docutils HTML translator.

This is the default output format. Because a dmr document is already structured to look like a resume, this just uses the default docutils HTML translator – it’s basically equivalent to running rst2html on your reST resume.

class dmr.output.html.Html(document)

Bases: dmr.output.base.BaseOutput

dmr output format class to write HTML output using the docutils HTML translator.

Parameters:document (dmr.data.Document) – The DMR document to output

classmethod get_options()

Get a list of options to parse from the config files and command line when this output class is selected.

Returns:list - A list of dmr.config.DMROption objects

JSON

This module provides a JSON output format for dmr. This is useful if you want to get the data from a resume for use in other scripts or programs.

Note

N.B.! This output format is lossy! Text formatting (e.g., emphasis, etc.) is discarded, and only the actual text data is output.

class dmr.output.json.Json(document)

Bases: dmr.output.base.BaseOutput

dmr output format class to write JSON output. Note that this output format is lossy; text formatting (e.g., emphasis, etc.) is discarded.

dump_contact(tpl)

Dump a rendered namedtuple data class (dmr.data.Contact and dmr.data.Dates) to a dict in preparation for JSON serialization.

dump_dates(tpl)

Dump a rendered namedtuple data class (dmr.data.Contact and dmr.data.Dates) to a dict in preparation for JSON serialization.

dump_experience(section)

Dump a rendered dmr.data.Exception object to a list in preparation for JSON serialization.

dump_job(job)

Dump a rendered dmr.data.Job to a dict in preparation for JSON serialization.

dump_list(section)

Dump a rendered dmr.data.Section subclass object to a list in preparation for JSON serialization.

dump_namedtuple(tpl)

Dump a rendered namedtuple data class (dmr.data.Contact and dmr.data.Dates) to a dict in preparation for JSON serialization.

dump_references(section)

Dump a rendered dmr.data.Section subclass object to a list in preparation for JSON serialization.

dump_section(section)

Dump a rendered dmr.data.Section subclass object to a list in preparation for JSON serialization.

dump_text(section)

Dump a rendered dmr.data.Section subclass object to a list in preparation for JSON serialization.

Genshi

Genshi helper output format for dmr. This helper output module should not be called by itself, but can be used by other output modules to easily add Genshi templating abilities.

class dmr.output.genshi.GenshiOutput(document)

Bases: dmr.output.base.BaseOutput

dmr output class that renders the data in the document with a Genshi template. This class is not a usable output format itself; child classes can inherit from it to implement their own Genshi templating.

The child class will use a docutils Writer to translate all of the doctrees in the dmr.data.Document that will be rendered.

renderer

Get a renderer for a doctree snippet. By default, this uses dmr.data.WriterRenderer, which passes the snippets through to a docutils Writer class.

writer = None

A docutils.writers.Writer subclass that will be used to translate the snippets in the dmr document.

LaTeX

This module provides a dmr output format to write LaTeX files based on Genshi templates using dmr.output.genshi.

See Genshi output options for details on how the template is selected.

class dmr.output.latex.Latex(document)

Bases: dmr.output.genshi.GenshiOutput

dmr output format to write LaTeX files using dmr.output.genshi.GenshiOutput.

renderer

Get a renderer for a doctree snippet. By default, this uses dmr.data.WriterRenderer, which passes the snippets through to a docutils Writer class.

Data model

The dmr data model.

class dmr.data.Contact

Bases: dmr.data.ContactBase, dmr.data.RenderableNamedTuple, dmr.data.Parseable

An address block is a line block giving the contact information for a resume, an employer, a reference, or similar. It consists of six different types of lines:

• The name is freeform and must come on the first line, if it is needed at all. See below for when a name is required and when it’s not.
• Any number of phone numbers may be provided; they must come after the name, but there is no other ordering requirement. A phone number is any line that consists of dashes, parentheses, plus signs, whitespace, and digits, preceeded by an optional identifier. E.g., (555) 555-5555, cell: (02) 1234 5678, and +44 01 56 60 56 60 are all valid phone numbers. Additionally, any line containing a docutils reference that uses the tel: protocol will be considered a phone number.
• Any number of email addresses, which also must come after the name. Any line containing something that is automatically recognized by docutils as a reference and whose URI starts with mailto: is considered an email address. (Note that it’s usually unnecessary to specify mailto: explicitly; docutils is pretty smart about finding email addresses. If you’re still using that old bangpath address, though, you might need to.)
• Any number of URLs, which also must come after the name. Any line containing something thing that is automatically recognized by docutils as a reference and which uses neither the mailto: nor the tel: protocol will be considered a URL.
• The first contiguous set of lines that are not any of the above types will be considered the physical address.
• All lines that are not any of the above types wil be considered other data. Other data must come after the physical address, and the physical address must be separated from the other data by a phone number, URL, or email address. See the examples below.

If the address block describes a reference, then the first line must be that person’s name. Otherwise, the name will be taken from the title of the section the address block is in, and must not be included in the address block itself. (See below for examples to clarify this.)

Outside of the few ordering requirements listed, order is neither required nor respected; the order of address elements in the output document is specified by the output format class. The canonical output order is: name, address, phone, email, url, other. No output format is required to honor that.

Examples

So the start of a resume might look like:

============================
 Dennis MacAlistair Ritchie
============================

| 1234 No. Such Ln.
| Berkeley Heights, NJ 07922
| (908) 555-5555
| dmr@lucent.com

Whereas a personal reference might look like:

References
==========

| Dennis MacAlistair Ritchie
| 1234 No. Such Ln.
| Berkeley Heights, NJ 07922
| (908) 555-5555
| dmr@lucent.com

Note the different ways the name is specified.

Physical address matching is greedy, so if you have several unrecognizable lines in a row, they will all become the physical address. Consider this example:

============================
 Dennis MacAlistair Ritchie
============================

| 1234 No. Such Ln.
| Berkeley Heights, NJ 07922
| "I invented C."
| (908) 555-5555
| dmr@lucent.com

In this case, the physical address would have three lines – “1234 No. Such Ln.”, ‘Berkeley Heights, NJ 07922”, and “‘I invented C.’” In order to treat the final line as “other data” instead of as the physical address, it must be separated from the physical address by another data type. E.g.:

============================
 Dennis MacAlistair Ritchie
============================

| 1234 No. Such Ln.
| Berkeley Heights, NJ 07922
| (908) 555-5555
| dmr@lucent.com
| "I invented C."

URL

Alias for field number 4

address

Alias for field number 1

count(value) → integer -- return number of occurrences of value

email

Alias for field number 3

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

name

Alias for field number 0

other

Alias for field number 5

classmethod parse(node)

Parse a node into a dmr.data.Contact object. The node must either a) be a docutils.nodes.line_block; or b) contain a docutils.nodes.Titular and a docutils.nodes.line_block.

Parameters:block (docutils.nodes.Node) – The line block to parse. Returns:dmr.data.Contact

phone

Alias for field number 2

class dmr.data.ContactBase

Bases: tuple

ContactBase(name, address, phone, email, URL, other)

URL

Alias for field number 4

address

Alias for field number 1

count(value) → integer -- return number of occurrences of value

email

Alias for field number 3

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

name

Alias for field number 0

other

Alias for field number 5

phone

Alias for field number 2

class dmr.data.DateBase

Bases: tuple

DateBase(start, end)

count(value) → integer -- return number of occurrences of value

end

Alias for field number 1

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

start

Alias for field number 0

class dmr.data.Dates

Bases: dmr.data.DateBase, dmr.data.RenderableNamedTuple, dmr.data.Parseable

A date range is a one-line paragraph giving a range of dates. The dates themselves are not parsed; only the start and end of the range are determined. The start and end may be separated:

• By the word ‘to’ surrounded by whitespace;
• By a hyphen surrounded by whitespace;
• By a hyphen with optional whitespace around it, if neither date contains a hyphen.

In other words, the following are all valid:

1 February 2013 to 27 February 2013
2-1-2013 to 2-27-2013
2013-1-2 - 2013-27-2
1 Feb 2013-27 Feb 2013
1999-2004
Marceau, Nonidi 9 Ventôse an 221 - Présent

The following are invalid:

2013-1-2-2013-27-2
1 février 2013 à 27 février 2013

The latter invalid example is a localization problem, which someone should probably solve some day. However, it should be noted that the actual display of the separator between the dates is left to the output format; the separator used in the source file is not preserved. (I.e., non-English-language resumes can use the hyphen as a separator, and the appropriate word or separator in the output formatter.)

count(value) → integer -- return number of occurrences of value

end

Alias for field number 1

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

start

Alias for field number 0

class dmr.data.Document(source=None, contact=None, sections=None)

Bases: list, dmr.data.Parseable

Every dmr resume must start with a top-level title that contains the full name of the person whose resume it is. For example:

============================
 Dennis MacAlistair Ritchie
============================

Immediately after the title there should be an Address Block for the person whose resume it is, followed by any number of other Sections.

That’s it – a top title, an address block, and then other sections. All of the data is held in other sections.

Parameters:

• source (docutils.nodes.document) – The docutils.nodes.document representing the original doctree.
• contact (dmr.data.Contact) – The contact for the resume (i.e., the person whose resume it is).
• sections (list of dmr.data.Section subclass objects) – A list of sections in the document.

append()

L.append(object) – append object to end

contact = None

The contact for the resume (i.e., the person whose resume it is), as a dmr.data.Contact.

count(value) → integer -- return number of occurrences of value

extend()

L.extend(iterable) – extend list by appending elements from the iterable

insert()

L.insert(index, object) – insert object before index

pop([index]) → item -- remove and return item at index (default last).

Raises IndexError if list is empty or index is out of range.

remove()

L.remove(value) – remove first occurrence of value. Raises ValueError if the value is not present.

reverse()

L.reverse() – reverse IN PLACE

sections

A list of names of the sections contained in this document

sort()

L.sort(cmp=None, key=None, reverse=False) – stable sort IN PLACE; cmp(x, y) -> -1, 0, 1

source = None

The docutils.nodes.document representing the original doctree.

class dmr.data.Experience(name)

Bases: dmr.data.Section

The Experience section is by far the most complex section. It is useful for job experience, education history, and anything that consists of multiple discrete items with dates and descriptions. It may take one of two formats:

With Positions

For most job experience sections, you’ll want to use the format that allows you to specify both employers and positions. In this case, the Experience section must consist only of any number of subsections, each of which describes an employer. Each employer section must itself contain:

• An Address Block (optional), giving the employer’s contact information; and
• Any number of subsections, each of which describes a position held at that employer.

Note

This makes it simple and efficient to specify multiple jobs you held at a single employer.

Each position subsection is a Job Section.

See the examples below.

Without Positions

In this format, you only specify employers, not positions. This is useful for education sections, where you often wish to list the school, but a “position” as such is nonsensical. (Of course, more complex education sections will likely wish to use the format with positions in order to present more data.)

The positionless format is simply the format with positions with one level of subsection removed. The Experience section must consist only of any number of subsections, each of which is a Job Section.

See the examples below.

Examples

This is an example of an Experience section with positions:

Experience
==========

Bell Labs
---------
| 600 Mountain Ave.
| New Providence, NJ 07974

Scientist
~~~~~~~~~
1967 - 1975

* Invented C.
* Invented C while inventing UNIX.
* Wrote *The C Programming Language*.

Research Fellow
~~~~~~~~~~~~~~~
1975 - 1996

* Developed ANSI C (C89).
* Won the Turing Award and the Hamming Medal.

Lucent Technologies
-------------------

Chair, System Software Research Department
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1996 - 2007

* Got about a zillion more awards for being the guy who
  invented C.

This is an example of an Experience section without positions:

Education
=========

Harvard University
------------------
1959 - 1963

* B.S., Physics
* B.A., Applied Mathematics

Harvard University
------------------
1963 - 1967

* PhD, Applied Mathematics
* Dissertation: "Program Structure and Computational
  Complexity"

Parameters:name (docutils.nodes.Text) – The name (title) of the section

append()

L.append(object) – append object to end

count(value) → integer -- return number of occurrences of value

extend()

L.extend(iterable) – extend list by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

insert()

L.insert(index, object) – insert object before index

classmethod is_valid(node)

Return True if the node contains a valid section of this type, False otherwise. Subclasses must not return false positives in any case, since dmr.input.parse() does not necessarily check sections in any particular order.

Parameters:node (docutils.nodes.Node) – The node to check Returns:bool

pop([index]) → item -- remove and return item at index (default last).

Raises IndexError if list is empty or index is out of range.

remove()

L.remove(value) – remove first occurrence of value. Raises ValueError if the value is not present.

reverse()

L.reverse() – reverse IN PLACE

sort()

L.sort(cmp=None, key=None, reverse=False) – stable sort IN PLACE; cmp(x, y) -> -1, 0, 1

class dmr.data.Job(employer=None, position=None, dates=None, start=None, end='Present', description=None)

Bases: _abcoll.MutableSequence, dmr.data.Renderable, dmr.data.Parseable

Representation of an element in a Experience section. We call it a “Job,” but it could be schooling or anything else with dates and a bullet list description. It contains:

• An Address Block (optional), giving the employer’s contact information; and
• A Date Range (optional), giving the dates in the position; and
• A bulleted list of your duties at that employer.

Parameters:

• employer (dmr.data.Contact) – The employer (or school, etc.)
• position (str) – The position at said employer. This is completely optional, for instance for education history.
• dates (dmr.data.Dates) – The date range for the given job. Either provide dates or start and end, but not both.
• start (str) – The start of the date range for the given job. Either provide dates or start and end, but not both.
• end (str) – The end of the date range for the given job. Either provide dates or start and end, but not both.
• description (list of strings) – The itemized description of the position.

dates = None

The dates at this job, as a dmr.data.Dates

description = None

A list of things you did at the job.

employer = None

The employer (or school, etc.) as a dmr.data.Contact

end

The end date of the position

classmethod parse(node, employer=None)

Parameters:

• node (docutils.nodes.Node) – The node to parse a job from
• employer (dmr.data.Contact) – Optionally, the employer for this job, if it was provided elsewhere and the job node only describes a position at the employer.

Returns:

dmr.data.Job

position = None

The position at the employer, or None if not applicable.

start

The start date of the position

class dmr.data.List(name)

Bases: dmr.data.Section

A List section contains only a bulleted list – for example, a list of publications, or related experience.

Examples

Other Qualifications
====================

* Invented C.
* No seriously.
* Invented a lot of UNIX, too.

Parameters:name (docutils.nodes.Text) – The name (title) of the section

append()

L.append(object) – append object to end

count(value) → integer -- return number of occurrences of value

extend()

L.extend(iterable) – extend list by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

insert()

L.insert(index, object) – insert object before index

classmethod is_valid(node)

Return True if the node contains a valid section of this type, False otherwise. Subclasses must not return false positives in any case, since dmr.input.parse() does not necessarily check sections in any particular order.

Parameters:node (docutils.nodes.Node) – The node to check Returns:bool

pop([index]) → item -- remove and return item at index (default last).

Raises IndexError if list is empty or index is out of range.

remove()

L.remove(value) – remove first occurrence of value. Raises ValueError if the value is not present.

reverse()

L.reverse() – reverse IN PLACE

sort()

L.sort(cmp=None, key=None, reverse=False) – stable sort IN PLACE; cmp(x, y) -> -1, 0, 1

class dmr.data.Parseable

Bases: object

An abstract base class that provides a parse class method, which parses the given doctree and returns a new object of the given type from the data in it.

classmethod parse(node)

Parse an object of this type out of the given node.

Parameters:node (docutils.nodes.Node) – The doctree to parse Returns:An object of this type

class dmr.data.References(name)

Bases: dmr.data.Section

A References section contains only a series of Address Blocks.

Examples

References
==========

| Dennis MacAlistair Ritchie
| 1234 No. Such Ln.
| Berkeley Heights, NJ 07922
| (908) 555-5555
| dmr@lucent.com

Parameters:name (docutils.nodes.Text) – The name (title) of the section

append()

L.append(object) – append object to end

count(value) → integer -- return number of occurrences of value

extend()

L.extend(iterable) – extend list by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

insert()

L.insert(index, object) – insert object before index

classmethod is_valid(node)

Return True if the node contains a valid section of this type, False otherwise. Subclasses must not return false positives in any case, since dmr.input.parse() does not necessarily check sections in any particular order.

Parameters:node (docutils.nodes.Node) – The node to check Returns:bool

pop([index]) → item -- remove and return item at index (default last).

Raises IndexError if list is empty or index is out of range.

remove()

L.remove(value) – remove first occurrence of value. Raises ValueError if the value is not present.

reverse()

L.reverse() – reverse IN PLACE

sort()

L.sort(cmp=None, key=None, reverse=False) – stable sort IN PLACE; cmp(x, y) -> -1, 0, 1

class dmr.data.Renderable

Bases: object

An abstract base class that provides a render method, which returns a new object of the given type with all internal data replaced by simple strings (as opposed to doctrees).

render(func)

Render the data in this object using the given function to convert all data to strings.

Parameters:func – The function to apply to all doctrees in this dmr data object. It should take a single argument, a doctress.node.Node subclass, and should return a string.

class dmr.data.RenderableNamedTuple

Bases: dmr.data.Renderable

An abstract base class to provide a working render method (as per dmr.data.Renderable.render() for namedtuple subclasses.

class dmr.data.Section(name)

Bases: list, dmr.data.Renderable, dmr.data.Parseable

Abstract representation of a resume section

Parameters:name (docutils.nodes.Text) – The name (title) of the section

append()

L.append(object) – append object to end

count(value) → integer -- return number of occurrences of value

extend()

L.extend(iterable) – extend list by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

insert()

L.insert(index, object) – insert object before index

classmethod is_valid(node)

Return True if the node contains a valid section of this type, False otherwise. Subclasses must not return false positives in any case, since dmr.input.parse() does not necessarily check sections in any particular order.

Parameters:node (docutils.nodes.Node) – The node to check Returns:bool

classmethod parse(node)

Parse an object of this type out of the given node.

Parameters:node (docutils.nodes.Node) – The doctree to parse Returns:An object of this type

pop([index]) → item -- remove and return item at index (default last).

Raises IndexError if list is empty or index is out of range.

remove()

L.remove(value) – remove first occurrence of value. Raises ValueError if the value is not present.

reverse()

L.reverse() – reverse IN PLACE

sort()

L.sort(cmp=None, key=None, reverse=False) – stable sort IN PLACE; cmp(x, y) -> -1, 0, 1

dmr.data.SectionType

This very simple descriptor class exists only to get the name of the owner class. This way, every section can have a type attribute that is in the __class__.__name__ attribute (lowercased), which can be used by output formats to determine the type of a section without needing to use __class__ magic.

class dmr.data.Text(name)

Bases: dmr.data.Section

A Text section contains only freeform text – an objective, for instance. This is the simplest section.

A section header with no content (e.g., “References Available Upon Request”) will be treated as a Text section.

Examples

Objective
=========

To obtain a rewarding, high-level position inventing C.

References Available Upon Request
=================================

Parameters:name (docutils.nodes.Text) – The name (title) of the section

append()

L.append(object) – append object to end

count(value) → integer -- return number of occurrences of value

extend()

L.extend(iterable) – extend list by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

insert()

L.insert(index, object) – insert object before index

classmethod is_valid(node)

Return True if the node contains a valid section of this type, False otherwise. Subclasses must not return false positives in any case, since dmr.input.parse() does not necessarily check sections in any particular order.

Parameters:node (docutils.nodes.Node) – The node to check Returns:bool

pop([index]) → item -- remove and return item at index (default last).

Raises IndexError if list is empty or index is out of range.

remove()

L.remove(value) – remove first occurrence of value. Raises ValueError if the value is not present.

reverse()

L.reverse() – reverse IN PLACE

sort()

L.sort(cmp=None, key=None, reverse=False) – stable sort IN PLACE; cmp(x, y) -> -1, 0, 1

dmr.data.c

alias of References

dmr.data.child_by_class(parent, nodecls)

Get the first child of parent that is a member of nodecls. This differs from docutils.node.Node.first_child_matching_class(), which only returns the index of the first child. This returns the actual child.

Parameters:

• parent (docutils.node.Node) – The parent node to search for children in.
• nodecls (type or docutils.node.Node) – The docutils.node.Node subclass to find instances of (or children which are instances of a subclass). This can also be an instance of a Node subclass.

Returns:

docutils.node.Node instance or None

dmr.data.exclude(node)

Return True if the node should be skipped.

Parameters:node (docutils.nodes.Node) – The node to check Returns:bool

dmr.data.get_title(node)

Given a docutils.nodes.Structural node, get the content of the title of the section.

Parameters:node (docutils.nodes.Structural) – The structural node to get the title from. Returns:docutils.nodes.container

Rendering

Utilities for rendering doctrees.

class dmr.render.ReferenceTransformer(document)

Bases: docutils.nodes.GenericNodeVisitor

Node visitor that transforms docutils.nodes.reference nodes into plain-text representations of those references.

dispatch_departure(node)

Call self.”depart_ + node class name” with node as parameter. If the depart_... method does not exist, call self.unknown_departure.

dispatch_visit(node)

Call self.”visit_ + node class name” with node as parameter. If the visit_... method does not exist, call self.unknown_visit.

unknown_departure(node)

Called before exiting unknown Node types.

Raise exception unless overridden.

unknown_visit(node)

Called when entering unknown Node types.

Raise an exception unless overridden.

visit_reference(node)

Render a reference node

class dmr.render.Renderer(document, visitor_cls)

Bases: object

Get a renderer callable suitable for passing to dmr.data.Renderable.render().

Parameters:

• document (docutils.nodes.document) – The docutils document to use as a rendering base. This is not the document to render, but rendering a snippet requires a full document for things like settings and a reporter.
• visitor_cls (docutils.nodes.NodeVisitor) – A docutils.nodes.NodeVisitor subclass to use to walk the doctrees that are rendered. A new visitor is instantiated for each snippet that is rendered, because we are not rendering full documents and so a visitor does not necessarily get reset between renderings.

class dmr.render.WhitespaceRemovingRenderer(document, visitor_cls)

Bases: dmr.render.Renderer

dmr.render.Renderer that removes newlines and duplicate whitespace.

Parameters:

• document (docutils.nodes.document) – The docutils document to use as a rendering base. This is not the document to render, but rendering a snippet requires a full document for things like settings and a reporter.
• visitor_cls (docutils.nodes.NodeVisitor) – A docutils.nodes.NodeVisitor subclass to use to walk the doctrees that are rendered. A new visitor is instantiated for each snippet that is rendered, because we are not rendering full documents and so a visitor does not necessarily get reset between renderings.

class dmr.render.WriterRenderer(document, writer)

Bases: dmr.render.Renderer

Get a renderer callable for the given docutils Writer, suitable for passing to dmr.data.Renderable.render().

Configuration and argument parsing

dmr configuration parsing is done in several phases:

1. Command-line arguments are parsed to get the -c (config file) option. All core options are parsed in order to give a good help message, but that’s the only one we care about in this phase.
2. /etc/dmr.conf or the file specified with -c is parsed
3. $HOME/.dmr/config is parsed, and overwrites settings from /etc/dmr.conf
4. Core command-line arguments are re-parsed, and overwrite the settings in config files.
5. Once the output format is known, options specific to the output format are parsed from the config files.
6. Output format options are parsed from the command line.
7. Options are parsed from the document that is being rendered.

Each phase overwrites values that were read in the previous phase.

Some options can take multiple values --exclude. These are specified differently depending on where they are configured:

On the command line, give multiple option strings:

dmr --exclude foo --exclude "bar and baz"

In the config file, use a quoted, space-separated list:

.. code-block:: cfg

[global] exclude = foo “bar and baz”

In the document, give multiple option strings:

In-document options are specified as comments. For instance:

.. options
   footer
   exclude Experience

You can specify options for a specific output format thusly:

.. options=json
   footer
   exclude Experience

Output-specific options override generic in-document options.

See ConfigParser.RawConfigParser.getboolean() for acceptable values for boolean configuration options.

dmr.config.config = Namespace(name='dmr', uri='http://github.com/stpierre/dmr', version='0.1.0')

A module-level argparse.Namespace object that stores all configuration for dmr.

dmr.config.parse(argv=None)

Parse command-line arguments and config file(s).

Parameters:argv (list) – The argument list to parse, instead of sys.argv Returns:argparse.Namespace

dmr.config.options()

Get a list of core options. This is implemented as a function rather than as a module-level variable because it imports dmr.output, which itself imports dmr.config, so this list must be generated at run-time rather than at compile-time, or we get circular imports.

class dmr.config.DMROption(*args, **kwargs)

Bases: object

Representation of an option that can be specified on the command line or in a config file.

See argparse.ArgumentParser.add_argument() for a full list of accepted parameters.

In addition to supporting all arguments and keyword arguments from argparse.ArgumentParser.add_argument(), two additional keyword arguments are allowed.

Parameters:

• cf (tuple) – A tuple giving the section and option name that this argument can be referenced as in the config file.
• inline (string) – A string by which this argument can be referenced in the inline options block of a document.

add_to_parser(parser)

Add this option to the given parser.

Parameters:parser (argparse.ArgumentParser) – The parser to add the option to. Returns:argparse.Action

from_config(cfp)

Get the value of this option from the given ConfigParser.ConfigParser. If it is not found in the config file, the default is returned. (If there is no default, None is returned.)

Parameters:cfp (ConfigParser.ConfigParser) – The config parser to get the option value from Returns:varies

parse_value(value)

Manually set or append the given value.

Parameters:value – The value to set, append, or otherwise appropriately handle.

Logging

Logging for dmr.

dmr.logger.logger = <logging.Logger object at 0x2635290>

logging.Logger object that all dmr modules should use for output.

dmr.logger.fatal(msg, rv=1)

Log a fatal message and raise SystemExit.

Parameters:

• msg (str) – The message to log
• rv (int) – The return value to exit with.

Raises :

SystemExit