Parser for command-line and library use. The settings_spec specification here and in other Docutils components are merged to build the set of command-line options and runtime settings for this process.
Common settings (defined below) and component-specific settings must not conflict. Short options are reserved for common settings, and components are restrict to using long options.
There are no implemented interfaces.
booleans
(type:
dict
)
{'': 0, 'on': 1, 'off': 0, 'no': 0, '1': 1, '0': 0, 'false': 0, 'yes': 1, 'true': 1}
config_section
(type:
str
)
'general'
config_section_dependencies
(type: NoneType
)
None
default_error_encoding_error_handler
(type:
str
)
'backslashreplace'
relative_path_settings
(type:
tuple
)
('warning_stream',)
settings_default_overrides
(type: NoneType
)
None
settings_defaults
(type:
dict
)
{'_disable_config': None, '_destination': None, '_source': None}
settings_spec
(type:
tuple
)
('General Docutils Options', None, (('Specify the document title as metadata (not part of the document body). Overrides a document-provided title. There is no default.', ['--title'], {}), ('Include a "Generated by Docutils" credit and link at the end of the document.', ['--generator', '-g'], {'action': 'store_true', 'validator': <function validate_boolean at 0x413ce9cc>}), ('Do not include a generator credit.', ['--no-generator'], {'action': 'store_false', 'dest': 'generator'}), ('Include the date at the end of the document (UTC).', ['--date', '-d'], {'action': 'store_const', 'dest': 'datestamp', 'const': '%Y-%m-%d'}), ('Include the time & date at the end of the document (UTC).', ['--time', '-t'], {'action': 'store_const', 'dest': 'datestamp', 'const': '%Y-%m-%d %H:%M UTC'}), ('Do not include a datestamp of any kind.', ['--no-datestamp'], {'action': 'store_const', 'dest': 'datestamp', 'const': None}), ('Include a "View document source" link (relative to destination).', ['--source-link', '-s'], {'action': 'store_true', 'validator': <function validate_boolean at 0x413ce9cc>}), ('Use the supplied <URL> verbatim for a "View document source" link; implies --source-link.', ['--source-url'], {'metavar': '<URL>'}), ('Do not include a "View document source" link.', ['--no-source-link'], {'action': 'callback', 'callback': <function store_multiple at 0x413ce8b4>, 'callback_args': ('source_link', 'source_url')}), ('Enable backlinks from section headers to table of contents entries. This is the default.', ['--toc-entry-backlinks'], {'dest': 'toc_backlinks', 'action': 'store_const', 'default': 'entry', 'const': 'entry'}), ('Enable backlinks from section headers to the top of the table of contents.', ['--toc-top-backlinks'], {'dest': 'toc_backlinks', 'action': 'store_const', 'const': 'top'}), ('Disable backlinks to the table of contents.', ['--no-toc-backlinks'], {'dest': 'toc_backlinks', 'action': 'store_false'}), ('Enable backlinks from footnotes and citations to their references. This is the default.', ['--footnote-backlinks'], {'action': 'store_true', 'default': 1, 'validator': <function validate_boolean at 0x413ce9cc>}), ('Disable backlinks from footnotes and citations.', ['--no-footnote-backlinks'], {'dest': 'footnote_backlinks', 'action': 'store_false'}), ('Enable Docutils section numbering (default: enabled).', ['--section-numbering'], {'action': 'store_true', 'dest': 'sectnum_xform', 'default': 1, 'validator': <function validate_boolean at 0x413ce9cc>}), ('Disable Docutils section numbering (default: enabled).', ['--no-section-numbering'], {'action': 'store_false', 'dest': 'sectnum_xform', 'validator': <function validate_boolean at 0x413ce9cc>}), ('Remove comment elements from the document tree (default: leave them).', ['--strip-comments'], {'action': 'store_true', 'validator': <function validate_boolean at 0x413ce9cc>}), ('Leave comment elements in the document tree (this is the default).', ['--leave-comments'], {'action': 'store_false', 'dest': 'strip_comments', 'validator': <function validate_boolean at 0x413ce9cc>}), ('Set verbosity threshold; report system messages at or higher than <level> (by name or number: "info" or "1", warning/2, error/3, severe/4; also, "none" or "5"). Default is 2 (warning).', ['--report', '-r'], {'default': 2, 'dest': 'report_level', 'validator': <function validate_threshold at 0x413cea3c>, 'metavar': '<level>', 'choices': ['info', '1', 'warning', '2', 'error', '3', 'severe', '4', 'none', '5']}), ('Report all system messages, info-level and higher. (Same as "--report=info".)', ['--verbose', '-v'], {'action': 'store_const', 'dest': 'report_level', 'const': 1}), ('Do not report any system messages. (Same as "--report=none".)', ['--quiet', '-q'], {'action': 'store_const', 'dest': 'report_level', 'const': 5}), ('Set the threshold (<level>) at or above which system messages are converted to exceptions, halting execution immediately by exiting (or propagating the exception if --traceback set). Levels as in --report. Default is 4 (severe).', ['--halt'], {'dest': 'halt_level', 'default': 4, 'validator': <function validate_threshold at 0x413cea3c>, 'metavar': '<level>', 'choices': ['info', '1', 'warning', '2', 'error', '3', 'severe', '4', 'none', '5']}), ('Same as "--halt=info": halt processing at the slightest problem.', ['--strict'], {'action': 'store_const', 'dest': 'halt_level', 'const': 'info'}), ('Enable a non-zero exit status for normal exit if non-halting system messages (at or above <level>) were generated. Levels as in --report. Default is 5 (disabled). Exit status is the maximum system message level plus 10 (11 for INFO, etc.).', ['--exit-status'], {'dest': 'exit_status_level', 'default': 5, 'validator': <function validate_threshold at 0x413cea3c>, 'metavar': '<level>', 'choices': ['info', '1', 'warning', '2', 'error', '3', 'severe', '4', 'none', '5']}), ('Report debug-level system messages and generate diagnostic output.', ['--debug'], {'action': 'store_true', 'validator': <function validate_boolean at 0x413ce9cc>}), ('Do not report debug-level system messages or generate diagnostic output.', ['--no-debug'], {'action': 'store_false', 'dest': 'debug'}), ('Send the output of system messages (warnings) to <file>.', ['--warnings'], {'dest': 'warning_stream', 'metavar': '<file>'}), ('Enable Python tracebacks when halt-level system messages and other exceptions occur. Useful for debugging, and essential for issue reports.', ['--traceback'], {'action': 'store_true', 'default': None, 'validator': <function validate_boolean at 0x413ce9cc>}), ('Disable Python tracebacks when errors occur; report just the error instead. This is the default.', ['--no-traceback'], {'dest': 'traceback', 'action': 'store_false'}), ('Specify the encoding of input text. Default is locale-dependent. Optionally also specify the error handler for undecodable characters, after a colon (":"); default is "strict". (See "--intput-encoding-error-handler".)', ['--input-encoding', '-i'], {'validator': <function validate_encoding_and_error_handler at 0x413ce994>, 'metavar': '<name[:handler]>'}), ('Specify the error handler for undecodable characters in the input. Acceptable values include "strict", "ignore", and "replace". Default is "strict". Usually specified as part of --input-encoding.', ['--input-encoding-error-handler'], {'default': 'strict', 'validator': <function validate_encoding_error_handler at 0x413ce95c>}), ('Specify the text encoding for output. Default is UTF-8. Optionally also specify the error handler for unencodable characters, after a colon (":"); default is "strict". (See "--output-encoding-error-handler".)', ['--output-encoding', '-o'], {'default': 'utf-8', 'validator': <function validate_encoding_and_error_handler at 0x413ce994>, 'metavar': '<name[:handler]>'}), ('Specify the error handler for unencodable characters in the output. Acceptable values include "strict", "ignore", "replace", "xmlcharrefreplace", and "backslashreplace" (in Python 2.3+). Default is "strict". Usually specified as part of --output-encoding.', ['--output-encoding-error-handler'], {'default': 'strict', 'validator': <function validate_encoding_error_handler at 0x413ce95c>}), ('Specify the text encoding for error output. Default is ASCII. Optionally also specify the error handler for unencodable characters, after a colon (":"); default is "backslashreplace". (See "--output-encoding-error-handler".)', ['--error-encoding', '-e'], {'default': 'ascii', 'validator': <function validate_encoding_and_error_handler at 0x413ce994>, 'metavar': '<name[:handler]>'}), ('Specify the error handler for unencodable characters in error output. See --output-encoding-error-handler for acceptable values. Default is "backslashreplace". Usually specified as part of --error-encoding.', ['--error-encoding-error-handler'], {'default': 'backslashreplace', 'validator': <function validate_encoding_error_handler at 0x413ce95c>}), ('Specify the language of input text (ISO 639 2-letter identifier). Default is "en" (English).', ['--language', '-l'], {'dest': 'language_code', 'default': 'en', 'metavar': '<name>'}), ('Write dependencies (caused e.g. by file inclusions) to <file>. Useful in conjunction with programs like "make".', ['--record-dependencies'], {'default': None, 'validator': <function validate_dependency_file at 0x413ceae4>, 'metavar': '<file>'}), ('Read configuration settings from <file>, if it exists.', ['--config'], {'action': 'callback', 'callback': <function read_config_file at 0x413ce8ec>, 'type': 'string', 'metavar': '<file>'}), ("Show this program's version number and exit.", ['--version', '-V'], {'action': 'version'}), ('Show this help message and exit.', ['--help', '-h'], {'action': 'help'}), ('SUPPRESSHELP', ['--id-prefix'], {'default': ''}), ('SUPPRESSHELP', ['--auto-id-prefix'], {'default': 'id'}), ('SUPPRESSHELP', ['--dump-settings'], {'action': 'store_true'}), ('SUPPRESSHELP', ['--dump-internals'], {'action': 'store_true'}), ('SUPPRESSHELP', ['--dump-transforms'], {'action': 'store_true'}), ('SUPPRESSHELP', ['--dump-pseudo-xml'], {'action': 'store_true'}), ('SUPPRESSHELP', ['--expose-internal-attribute'], {'action': 'append', 'dest': 'expose_internals', 'validator': <function validate_colon_separated_string_list at 0x413cea74>}), ('SUPPRESSHELP', ['--strict-visitor'], {'action': 'store_true'})))
standard_config_files
(type:
list
)
['/etc/docutils.conf', './docutils.conf', '~/.docutils']
standard_option_list
(type:
list
)
[]
threshold_choices
(type:
list
)
['info', '1', 'warning', '2', 'error', '3', 'severe', '4', 'none', '5']
thresholds
(type:
dict
)
{'info': 1, 'severe': 4, 'warning': 2, 'none': 5, 'error': 3}
version_template
(type:
str
)
'%prog (Docutils 0.4 [release])'
add_option(*args, **kwargs)
add_option(Option) add_option(opt_str, ..., kwarg=val, ...)
add_option_group(*args, **kwargs)
add_options(option_list)
check_args(args)
check_values(values, args)
Store positional arguments as runtime settings.
disable_interspersed_args()
enable_interspersed_args()
error(msg)
error(msg : string)
Print a usage message incorporating msg
to stderr and exit.
If you override this in a subclass, it should not return -- it
should either exit or raise an exception.
exit(status=0, msg=None)
expand_prog_name(s)
format_description(formatter)
format_help(formatter=None)
format_option_help(formatter=None)
get_config_file_settings(config_file)
Returns a dictionary containing appropriate config file settings.
get_default_values()
Needed to get custom Values instances.
get_description()
get_option(opt_str)
get_option_by_dest(dest)
Get an option by its dest.
If you're supplying a dest which is shared by several options, it is undefined which option of those is returned.
A KeyError is raised if there is no option with the supplied dest.
get_option_group(opt_str)
get_prog_name()
get_standard_config_files()
Return list of config files, from environment or standard.
get_standard_config_settings()
get_usage()
get_version()
has_option(opt_str)
parse_args(args=None, values=None)
parse_args(args : [string] = sys.argv[1:], values : Values = None) -> (values : Values, args : [string])
Parse the command-line options found in args
(default:
sys.argv[1:]). Any errors result in a call to error()
, which
by default prints the usage message to stderr and calls
sys.exit() with an error message. On success returns a pair
(values, args) where values
is an Values instance (with all
your option values) and args
is the list of arguments left
over after parsing options.
populate_from_components(components)
For each component, first populate from the SettingsSpec.settings_spec structure, then from the SettingsSpec.settings_defaults dictionary. After all components have been processed, check for and populate from each component's SettingsSpec.settings_default_overrides dictionary.
print_help(file=None)
print_help(file : file = stdout)
Print an extended help message, listing all options and any
help text provided with them, to file
(default stdout).
print_usage(file=None)
print_usage(file : file = stdout)
Print the usage message for the current program (self.usage) to
file
(default stdout). Any occurence of the string "%prog" in
self.usage is replaced with the name of the current program
(basename of sys.argv[0]). Does nothing if self.usage is empty
or not defined.
print_version(file=None)
print_version(file : file = stdout)
Print the version message for this program (self.version) to
file
(default stdout). As with print_usage(), any occurence
of "%prog" in self.version is replaced by the current program's
name. Does nothing if self.version is empty or undefined.
remove_option(opt_str)
set_conflict_handler(handler)
set_default(dest, value)
set_defaults(**kwargs)
set_description(description)
set_process_default_values(process)
set_usage(usage)
There are no known subclasses.