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.