publication – tools for preparing astronomy papers in LaTeX

The publication module contains classes and funtions to assist in preparing papers or other publications with an emphasis on common astronomy journals. The tools here are for use with LaTeX as the actual authoring tools.

Classes and Inheritance Structure

Module API

class astropysics.publication.Command(parent, content)

Bases: astropysics.publication.TeXNode

A LaTeX command (anything with leading backslash and possible arguments that isn’t an environment)

Parameters:

• parent – The parent node
• content – Either a string with the command text, or a (name,args) tuple where args is a sequence of strings or a string ‘{arg1}[oarg1]{arg2}...’

getSelfText()

optargs

A list of strings with the text of the optional arguments (arguments enclosed in square brackets)

reqargs

A list of strings with the text of the required arguments (arguments enclosed in curly braces).

class astropysics.publication.Comment(parent, ctext, endswithnewline=False)

Bases: astropysics.publication.TeXNode

A single-line comment of a TeX File. Note that unlike most

Parameters:

• parent – The parent node
• ctext – The comment text (with or without an initial %)

children = ()

getSelfText()

text = ''

The text of this comment (not including the initial %)

class astropysics.publication.Document(parent, content, envname=None)

Bases: astropysics.publication.Environment

abstract = None

The abstract environment for this document or None if one does not exist

name = 'document'

sections = {}

A dictionary mapping section names to the associated index into

class astropysics.publication.EnclosedDeclaration(parent, content)

Bases: astropysics.publication.TeXNode

A TeX construct of the form {name{op}[op] content}. Note that declarations terminated by the end command will not be treated as this kind of object.

Parameters:

• parent – The parent node
• content – A (padstr,commandnode,innercontent) tuple where padstr is the string before the command, commandnode is a Command object with the command portion of the declaration, and innercontent is the content after the command either as a string or a list of nodes (possibly mixed with strings). Alternatively, it can be the full text string including the outermost braces.

cmd = None

A Command object with the command in the declaration

getSelfText()

padstr = ''

Whitespace string between the opening brace and the command

class astropysics.publication.Environment(parent, content, envname=None)

Bases: astropysics.publication.TeXNode

A LaTex environment.

Subclassing Subclasses can implement the postParse() method - see the method for syntax. They should also be registered with the registerEnvironment() static method to have them be parsed with the default TeXFile parser. Generally, they should also have a class attribute named name that gives the name of the environment (this name will be automatically used to determine which environments the subclass represents)

Parameters:

• parent – The parent node
• content – The string between ‘egin{...}’ and ‘end{...}’
• envname – If a string, it will be taken as the environment name. If None, it will be taken from the class-level name

static getEnvironments()

Returns a tuple of the registered environments.

getSelfText()

name = ''

The name of this environment.

postParse(nodes)

static registerEnvironment(envclass)

Registers the provided envclass in the environment registry. Also returns the class to allow use as a decorator.

Parameters:

envclass – The Environment object to be registered.

Raises:

• TypeError – If the provided class is not a Environment subclass.
• ValueError – If the name attribute of envclass matches one already in the registry.

static unregisterEnvironment(envclass)

Removes the envclass Environment object from the registered environment list

Parameters:envclass – The Environment object to be removed, or its associated name.

class astropysics.publication.Figure(parent, content, envname=None)

Bases: astropysics.publication.Environment

filenames

The names of the files (usually .eps) in this figure.

name = ['figure', 'figure*']

class astropysics.publication.MathMode(parent, content)

Bases: astropysics.publication.TeXNode

A math environment surrounded by $ symbols or $$ (for display mode)

Parameters:

• parent – The parent node
• content – The full string (including $) or a tuple(displaymode,content) where displaymode is a bool and content is a string

displaymode = False

determines if the MathMode is in display mode ($$) or not ($)

getSelfText()

name = ''

class astropysics.publication.Newline(parent)

Bases: astropysics.publication.TeXt

A node that stores just a new line. This is always a leaf.

text = '\n'

class astropysics.publication.OptionalArgument(parent, text)

Bases: astropysics.publication.TeXNode

An argument to a macro that is required (i.e. enclosed in square brackets)

children = ()

getSelfText()

class astropysics.publication.Preamble(parent, content)

Bases: astropysics.publication.TeXNode

The preamble of a TeX File (i.e. everything before egin{document} )

Parameters:

• parent – The parent node
• content (string) – The text of the preamble

docclass

The document class of the tex file as a string

docclassopts

The document class options for the tex file as a comma-seperated string.

getSelfText()

class astropysics.publication.RequiredArgument(parent, text)

Bases: astropysics.publication.TeXNode

An argument to a macro that is required (i.e. enclosed in curly braces)

children = ()

getSelfText()

text = ''

The text of this argument object

class astropysics.publication.TeXFile(fn=None, flatteninputs=False)

Bases: astropysics.publication.TeXNode

A TeX Document loaded from a file.

document = None

The first Document environment in this file or None if there isn’t one

getSelfText()

preamble = None

The Preamble object for this file

save(fn)

Save the content of this object to a new file.

Parameters:fn (str) – The name of the file to save.

class astropysics.publication.TeXNode(parent)

Bases: object

An element in the TeX parsing tree. The main shared characteristic is that calling the node will return a string with the combined text.

Subclassing

Subclasses must implement getSelfText() (see docstring for details)

children = ()

A list of child nodes of this node.

getSelfText()

Subclass implementations must return a 2-tuple of strings such that the child text goes in between the tuple elements. Alternatively, it can return a 3-tuple (before,between,after), and the resulting text will be “<beforetext><childtext1><between><childtext2>...<after>”. It can also be None, in which case just the strings from the children will be returned. Otherwise, it can return a string, which will be returned as the full text.

isLeaf()

Returns True if this node is a leaf (has no children)

isRoot()

Returns True if this node is a root (has no parent)

parent = None

The parent of this node in the node tree, or None if this is a root.

prune(prunechildren=True)

Removes this node from the tree.

Parameters:prunechildren – If True, all the children of this node will be pruned (recursively). This is not strictly necessary, but will speed up garbage collection and probably prevent memory leaks.

visit(func)

Visits all the nodes in the tree (depth-first) and calls the supplied function on those nodes.

Parameters:func – The function to call on the nodes - should only accept the node as an argument. Returns:A sequence of the return values of the function. If the func returns None, it is not included in the returned list.

class astropysics.publication.TeXt(parent, text)

Bases: astropysics.publication.TeXNode

A node that stores generic text. This is always a leaf.

children

countWords(sep=None)

Returns the number of words in this object.

Parameters:sep – The seperator between words. If None, use any whitespace. Returns:The number of words in this TeXt object.

getSelfText()

text = ''

The text in this object

class astropysics.publication.TrailingCharCommand(parent, content)

Bases: astropysics.publication.Command

A special command that allows a single trailing character of any type - used for ‘left{‘ ‘right]’ and similar.

Parameters:

• parent – The parent node
• conent – A (name,char) tuple, or a command string

children = ()

getSelfText()

astropysics.publication.environment_factory(parent, texstr)

This function takes a string from a TeX document starting with ‘egin’ and ending in ‘end{...}’ and uses it to construct the appropriate Environment object.

astropysics.publication.prep_for_apj_pub(texfn, newdir='pubApJ', overwritedir=False, figexts=('eps', 'pdf'), verbose=True, flatteninputs=True, emulateapj=False)

Takes a LaTeX file and prepares it for submission to The Astrophysical Journal. This involves the following actions:

1. Removes all text after end{document} from the .tex file
2. Removes all comments from .tex file.
3. Checks that the abstract is within the ApJ word limit and issues a warning if it is not.
4. Sets the document class to aastex.
5. Converts deluxetable* environments to deluxetable.
6. Removes epsscale{?} from all figures
7. Makes the directory for the files.
8. Renames the figures to the ‘f1.eps’,’f2a.eps’, etc. convention for ApJ, and copies the appropriate files over.
9. Copies .bib (or .bbl if no .bib) file if bibliography is present.
10. Saves the .tex file as “ms.tex”
11. Creates ms.tar.gz file containing the files and places it in the newdir directory.

Parameters:

• texfn (str) – The filename of the .tex file to be submitted.
• newdir – The directory to save the publication files to.
• overwritedir – If True the directory specified by newdir will be overwritten if it is present. Otherwise, if newdir is present, the directory name will be newdir_# where # is the first number (starting from 2) that is not already present as a directory.
• figexts – A sequence of strings with the file name extensions that should be copied over for each figure, if present.
• verbose – If True, information will be printed when the each action is taken. Otherwise, only warnings will be issued when there is a problem.
• flatteninputs (bool) – If True, \input sections will be replaced with their actual content in the final output.
• emulateapj (bool) – If True, uses the emulateapj style file instead of aastex.

Returns:

(file,dir) where file is the altered TexFile object and dir is the directory used for the publication materials.

astropysics.publication.prep_for_arxiv_pub(texfn, newdir='pubArXiv', overwritedir=False, figexts=('eps', 'pdf'), verbose=True, flatteninputs=True)

Takes a LaTeX file and prepares it for posting to arXiv. This includes the following actions:

1. Removes all text after end{document} from the .tex file
2. Removes all comments from .tex file.
3. Checks that the abstract is within the ArXiv line limit and issues a warning if it is not (will require abridging during submission).
4. Makes the directory for the files.
5. Copies over all necessary .eps and/or .pdf files.
6. Copies .bbl (or .bib if no .bbl) file if bibliography is present.
7. Creates the modified .tex file.
8. Creates a .tar.gz file containing the files and places it in the newdir directory.

Parameters:

• texfn (str) – The filename of the .tex file to be submitted.
• newdir – The directory to save the publication files to.
• overwritedir – If True the directory specified by newdir will be overwritten if it is present. Otherwise, if newdir is present, the directory name will be newdir_# where # is the first number (starting from 2) that is not already present as a directory.
• figexts – A sequence of strings with the file name extensions that should be copied over for each figure, if present.
• verbose – If True, information will be printed when the each action is taken. Otherwise, only warnings will be issued when there is a problem.
• flatteninputs (bool) – If True, \input sections will be replaced with their actual content in the final output.

Returns:

(file,dir) where file is the altered TexFile object and dir is the directory used for the publication materials.

astropysics.publication.print_warnings = True

Can be False to hide, True to print, or ‘builtin’ to use the python warnings mechanism

astropysics.publication.text_to_nodes(parent, txt, flatteninputs=False)

Converts a string into a list of corresponding TeXNode objects.

Parameters:

• parent – The parent node
• txt – The text to parse
• flatteninputs (bool) – If True, “include” directives will be replaced by the content if their referenced file.

Returns:

A list of TeXNode objects