openaccess_epub.commands package

Module contents

openaccess_epub.commands defines modules useful as scripts, available through oaepub interface.

The commands in the openaccess.commands module can be run as standalones or through the oaepub interface installed with OpenAccess_EPUB. Each command’s interface is defined by its own documentation (using docopt). Some additional documentation on the use of conversion commands is covered in Overview of Conversion Commands with Examples.

Submodules

openaccess_epub.commands.batch module

oaepub batch

Convert all XML files in a directory to individual EPUB files

Usage:
  batch [options] DIR ...

Options:
  -h --help             show this help message and exit
  -v --version          show program version and exit
  -s --silent           Print nothing to the console during execution
  -V --verbosity=LEVEL  Set how much information is printed to the console
                        during execution (one of: "CRITICAL", "ERROR",
                        "WARNING", "INFO", "DEBUG") [default: WARNING]

Batch Specific Options:
  -2 --epub2            Convert to EPUB2 (not implemented)
  -3 --epub3            Convert to EPUB3 (not implemented)
  --no-epubcheck        Disable the use of epubcheck to validate EPUBs
  --no-validate         Disable DTD validation of XML files during conversion.
                        This is only advised if you have pre-validated the files
                        (see 'oaepub validate -h')
  -r --recursive        Recursively traverse subdirectories for conversion
  -o --output=DIR       Directory in which to put the output. Default is set in
                        config file (see 'oaepub configure where')
  -i --images=DIR       Directory in which to find the images for the article
                        to be converted to EPUB. Be sure to use wildcard
                        filename matching with a "*", which will expand to the
                        filename without extension. For more information and
                        default configuration see the config file
                        ('oaepub configure where')

Logging Options:
  --no-log-file         Disable logging to file
  -l --log-to=FILE      Specify a single filepath to contain all log data
  --log-level=LEVEL     Set the level for the logging (one of: "CRITICAL",
                        "ERROR", "WARNING", "INFO", "DEBUG") [default: DEBUG]

In contrast to the 'convert' command, the 'batch' command is intended for larger
scale conversions of article XML to EPUB and is somewhat more specialized and
less flexible. Local XML files are the only allowed input, all directory
conflicts will result in the article being skipped (preventing overwrites), and
the command will attempt to convert all XML files in the specified directories.

If using the --images option, the argument should employ the "*" expansion. As
a precaution against wasting time, this command will quit if the "*" is missing.

openaccess_epub.commands.clearcache module

oaepub clearcache

Clear out portions or all of OpenAccess_EPUB's cache

Usage:
  clearcache [options] COMMAND

Options:
  -h --help        show this help message and exit
  -v --version     show program version and exit

Clearcache Specific Options:
  -d --dry-run     Will print out what it would delete, instead of actually
                   deleting anything. Good idea to try this once before you
                   trust the command (because you are cautious and wise)

Recognized commands for oaepub clearcache are:
  all     Delete all cached data: images, logs
  images  Delete only the cached image files
  logs    Delete only the cached log files
  manual  Print out the cache location then exit

Remember that you can disable any or all caching. Caching is very helpful for
development, but may not be necessary for all users. If you want to manually
alter your cache, you can use 'oaepub clearcache manual' to tell you where the
cache is located.

openaccess_epub.commands.collection module

oaepub collection

Convert and compile a collection of article XML files into a single EPUB

Usage:
  collection [--silent | --verbosity=LEVEL] [--epub2 | --epub3] [options]
             COLLECTION_FILE

General Options:
  -h --help             Show this help message and exit
  -v --version          Show program version and exit
  -s --silent           Print nothing to the console during execution
  -V --verbosity=LEVEL  Set how much information is printed to the console
                        during execution (one of: "CRITICAL", "ERROR",
                        "WARNING", "INFO", "DEBUG") [default: INFO]

Collection Specific Options:
  -2 --epub2            Convert to EPUB2
  -3 --epub3            Convert to EPUB3
  --no-cleanup          The EPUB contents prior to .epub-packaging will not be
                        removed
  --no-epubcheck        Disable the use of epubcheck to validate EPUBs
  --no-validate         Disable DTD validation of XML files during conversion.
                        This is only advised if you have pre-validated the files
                        (see 'oaepub validate -h')
  -o --output=DIR       Directory in which to put the output. Default is set in
                        config file (see 'oaepub configure where')
  -i --images=DIR       Directory in which to find the images for the article
                        to be converted to EPUB. Be sure to use wildcard
                        filename matching with a "*", which will expand to the
                        filename without extension. For more information and
                        default configuration see the config file
                        ('oaepub configure where')

Logging Options:
  --no-log-file         Disable logging to file
  -l --log-to=FILE      Specify a single filepath to contain all log data
  --log-level=LEVEL     Set the level for the logging (one of: "CRITICAL",
                        "ERROR", "WARNING", "INFO", "DEBUG") [default: DEBUG]

To prepare a collection, begin by ensuring that all required XMl files are
stored locally. Create a text file which contains a path to an XML file on
each line, in the order in which they should appear in the EPUB. The root name
of this text file will also serve as the name of the EPUB and the log (unless
the --log-to option is used).

If using the --images option, the argument should employ the "*" expansion. As
a precaution against wasting time, this command will quit if the "*" is missing.

Note: Metadata in a Collection EPUB is limited by necessity, not by mistake.

openaccess_epub.commands.configure module

oaepub configure

Configure basic defaults for OpenAccess_EPUB conversion.

Usage:
  configure [--help | --version | --default | --dev | where]

Options:
  -h --help     Show this help message and exit
  -v --version  Show program version and exit
  -d --default  Set configuration to default and exit
  --dev         Set developer configuration and exit

openaccess_epub.commands.convert module

oaepub convert

Convert explicitly listed articles to EPUB, takes input of XML file, DOI, or URL

Usage:
  convert [--silent | --verbosity=LEVEL] [--epub2 | --epub3] [options] INPUT ...

General Options:
  -h --help             Show this help message and exit
  -v --version          Show program version and exit
  -s --silent           Print nothing to the console during execution
  -V --verbosity=LEVEL  Set how much information is printed to the console
                        during execution (one of: "CRITICAL", "ERROR",
                        "WARNING", "INFO", "DEBUG") [default: INFO]

Convert Specific Options:
  -2 --epub2            Convert to EPUB2
  -3 --epub3            Convert to EPUB3
  --no-cleanup          The EPUB contents prior to .epub-packaging will not be
                        removed
  --no-epubcheck        Disable the use of epubcheck to validate EPUBs
  --no-validate         Disable DTD validation of XML files during conversion.
                        This is only advised if you have pre-validated the files
                        (see 'oaepub validate -h')
  -o --output=DIR       Directory in which to put the output. Default is set in
                        config file (see 'oaepub configure where')
  -i --images=DIR       Directory in which to find the images for the article
                        to be converted to EPUB. If using this option with
                        multiple XML inputs, be sure to use wildcard filename
                        matching with a "*", which will expand to the filename
                        without extension. For more information and default
                        configuration see the config file
                        ('oaepub configure where')

Logging Options:
  --no-log-file         Disable logging to file
  -l --log-to=FILE      Specify a single filepath to contain all log data
  --log-level=LEVEL     Set the level for the logging (one of: "CRITICAL",
                        "ERROR", "WARNING", "INFO", "DEBUG") [default: DEBUG]

Convert supports input of the following types:
  XML - Input points to the location of a local XML file (ends with: '.xml')
  DOI - A DOI to be resolved for XML download, if publisher is supported
        (starts with 'doi:')
  URL - A URL link to the article for XML download, if publisher is supported
        (starts with 'http:' or 'https:')

Each individual input will receive its own log (replace '.xml' with '.log')
unless '--log-to' is used to direct all logging information to a specific file
Many default actions for your installation of OpenAccess_EPUB are configurable.
Execute 'oaepub configure' to interactively configure, or modify the config
file manually in a text editor; executing 'oaepub configure where' will tell you
where the config file is located.

openaccess_epub.commands.validate module

oaepub validate

Validates XML files according to their DTD specification

Usage:
  validate [options] DIR ...

Options:
  -h --help             show this help message and exit
  -v --version          show program version and exit
  -s --silent           print nothing to the console during execution

Validate Specific Options:
  -l --log-to=LOG       Specify a location to store the log of DTD validation
  -p --print-only       Report output only to the console
  -P --record-pass      Keep records of XML files which pass DTD validation,
                        otherwise only the failures will be recorded
  -r --recursive        Recursively traverse subdirectories for validation

This command is especially useful for validating large numbers of XML files, so
that one can safely disable validation during repeated EPUB conversions of the
same XML files.

This command creates a single specialized log file within each directory given
as a DIR argument. This is true even with --recursive, a log will only be made
in the top level directory. This log will record which XML files failed (and
optionally, passed) validation along with the reason and details.