sphobjinv.cmdline (non-API)

CLI module for sphobjinv.

sphobjinv is a toolkit for manipulation and inspection of Sphinx objects.inv files.

Note

This module is NOT part of the public API for sphobjinv. Its entire contents should be considered implementation detail.

Author
Brian Skinn (bskinn@alum.mit.edu)
File Created
17 May 2016
Copyright
(c) Brian Skinn 2016-2018
Source Repository
http://www.github.com/bskinn/sphobjinv
Documentation
http://sphobjinv.readthedocs.io
License
The MIT License; see LICENSE.txt for full license terms

Members

do_convert(inv, in_path, params)

Carry out the conversion operation, including writing output.

If OVERWRITE is passed and the output file (the default location, or as passed to OUTFILE) exists, it will be overwritten without a prompt. Otherwise, the user will be queried if it is desired to overwrite the existing file.

If QUIET is passed, nothing will be printed to stdout (potentially useful for scripting), and any existing output file will be overwritten without prompting.

Parameters:
  • inv – Inventory – Inventory object to be output in the format indicated by MODE.
  • in_path – str – For a local input file, its absolute path. For a URL, the (possibly truncated) URL text.
  • params – dict – Parameters/values mapping from the active subparser
do_suggest(inv, params)

Perform the suggest call and output the results.

Results are printed one per line.

If neither INDEX nor SCORE is specified, the results are output without a header. If either or both are specified, the results are output in a lightweight tabular format.

If the number of results exceeds SUGGEST_CONFIRM_LENGTH, the user will be queried whether to display all of the returned results unless ALL is specified.

No --quiet option is available here, since a silent mode for suggestion output is nonsensical.

Parameters:
  • inv – Inventory – Inventory object to be output in the format indicated by MODE.
  • params – dict – Parameters/values mapping from the active subparser
err_format(exc)

Pretty-format an exception.

Parameters:exc – Exception – Exception instance to pretty-format
Returns:pretty_exc – str – Exception type and message formatted as ’{type}: {message}’
getparser()

Generate argument parser.

Returns:prs – ArgumentParser – Parser for commandline usage of sphobjinv
import_infile(in_path)

Attempt import of indicated file.

Convenience function wrapping attempts to load an Inventory from a local path.

Parameters:in_path – str – Path to input file
Returns:inv – Inventory or None – If instantiation with the file at in_path succeeds, the resulting Inventory instance; otherwise, None
inv_local(params)

Create Inventory from local source.

Uses resolve_inpath() to sanity-check and/or convert INFILE.

Calls sys.exit() internally in error-exit situations.

Parameters:params – dict – Parameters/values mapping from the active subparser
Returns:
inv_url(params)

Create Inventory from file downloaded from URL.

Initially, treats INFILE as a download URL to be passed to the url initialization argument of Inventory.

If an inventory is not found at that exact URL, progressively searches the directory tree of the URL for objects.inv.

Calls sys.exit() internally in error-exit situations.

Parameters:params – dict – Parameters/values mapping from the active subparser
Returns:
  • inv – Inventory – Object representation of the inventory at INFILE
  • ret_path – str – URL from INFILE used to construct inv. If URL is longer than 45 characters, the central portion is elided.
main()

Handle command line invocation.

Parses command line arguments, handling the no-arguments and VERSION cases.

Creates the Inventory from the indicated source and method.

Invokes do_convert() or do_suggest() per the subparser name stored in SUBPARSER_NAME.

resolve_inpath(in_path)

Resolve the input file, handling invalid values.

Currently, only checks for existence and not-directory.

Parameters:in_path – str – Path to desired input file
Returns:abs_path – str – Absolute path to indicated file
Raises:FileNotFoundError – If a file is not found at the given path
resolve_outpath(out_path, in_path, params)

Resolve the output location, handling mode-specific defaults.

If the output path or basename are not specified, they are taken as the same as the input file. If the extension is unspecified, it is taken as the appropriate mode-specific value from DEF_OUT_EXT.

If URL is passed, the input directory is taken to be os.getcwd() and the input basename is taken as DEF_BASENAME.

Parameters:
  • out_path – str or None – Output location provided by the user, or None if omitted
  • in_path – str – For a local input file, its absolute path. For a URL, the (possibly truncated) URL text.
  • params – dict – Parameters/values mapping from the active subparser
Returns:

out_path – str – Absolute path to the target output file
selective_print(thing, params)

Print thing if not in quiet mode.

Quiet mode is indicated by the value at the QUIET key within params.

Quiet mode is not implemented for the “suggest” CLI mode.

Parameters:
  • thing – any – Object to be printed
  • params – dict – Parameters/values mapping from the active subparser
write_json(inv, path, *, expand=False, contract=False)

Write an Inventory to JSON.

Writes output via fileops.writejson().

Calling with both expand and contract as True is invalid.

Parameters:
  • inv – Inventory – Objects inventory to be written zlib-compressed
  • path – str – Path to output file
  • expand – bool (optional) – Generate output with any uri or dispname abbreviations expanded
  • contract – bool (optional) – Generate output with abbreviated uri and dispname values
Raises:

ValueError – If both expand and contract are True
write_plaintext(inv, path, *, expand=False, contract=False)

Write an Inventory to plaintext.

Newlines are inserted in an OS-aware manner, based on the value of os.linesep.

Calling with both expand and contract as True is invalid.

Parameters:
  • inv – Inventory – Objects inventory to be written as plaintext
  • path – str – Path to output file
  • expand – bool (optional) – Generate output with any uri or dispname abbreviations expanded
  • contract – bool (optional) – Generate output with abbreviated uri and dispname values
Raises:

ValueError – If both expand and contract are True
write_zlib(inv, path, *, expand=False, contract=False)

Write an Inventory to zlib-compressed format.

Calling with both expand and contract as True is invalid.
Parameters:
  • inv – Inventory – Objects inventory to be written zlib-compressed
  • path – str – Path to output file
  • expand – bool (optional) – Generate output with any uri or dispname abbreviations expanded
  • contract – bool (optional) – Generate output with abbreviated uri and dispname values
Raises:

ValueError – If both expand and contract are True
yesno_prompt(prompt)

Query user at stdin for yes/no confirmation.

Uses input(), so will hang if used programmatically unless stdin is suitably mocked.

The value returned from input() must satisfy either resp.lower() == ‘n’ or resp.lower() == ‘y’, or else the query will be repeated ad infinitum. This function does NOT augment prompt to indicate the constraints on the accepted values.

Parameters:prompt – str – Prompt to display to user that requests a ‘Y’ or ‘N’ response
Returns:resp – str – User response
ALL = 'all'

Optional argument name for use with the SUGGEST subparser, indicating to print all returned objects, regardless of the number returned, without asking for confirmation

CONTRACT = 'contract'

Optional argument name for use with the CONVERT subparser, indicating to contract URIs and display names to abbreviated forms in the generated output file

CONVERT = 'convert'

Subparser name for inventory file conversions; stored in SUBPARSER_NAME when selected

DEF_BASENAME = 'objects'

Default base name for an unspecified OUTFILE

DEF_OUT_EXT = {'json': '.json', 'plain': '.txt', 'zlib': '.inv'}

Default extensions for an unspecified OUTFILE

DEF_THRESH = 75

Default match threshold for sphobjinv suggest --thresh

EXPAND = 'expand'

Optional argument name for use with the CONVERT subparser, indicating to expand URI and display name abbreviations in the generated output file

HELP_CONV_EXTS = "'.inv/.txt/.json'"

Help text for default extensions for the various conversion types

HELP_CO_PARSER = 'Convert intersphinx inventory to zlib-compressed, plaintext, or JSON formats.'

Help text for the CONVERT subparser

HELP_SU_PARSER = 'Fuzzy-search intersphinx inventory for desired object(s).'

Help text for the SUGGEST subparser

INDEX = 'index'

Optional argument name for use with the SUGGEST subparser, indicating to print the location index of each returned object within INFILE along with the object domain/role/name (may be specified with SCORE)

INFILE = 'infile'

Required positional argument name for use with both CONVERT and SUGGEST subparsers, holding the path (or URL, if URL is specified) to the input file

JSON = 'json'

Argument value for CONVERT MODE, to output an inventory as JSON

MODE = 'mode'

Positional argument name for use with CONVERT subparser, indicating output file format (ZLIB, PLAIN or JSON)

OUTFILE = 'outfile'

Optional positional argument name for use with the CONVERT subparser, holding the path to the output file (DEF_BASENAME and the appropriate item from DEF_OUT_EXT are used if this argument is not provided)

OVERWRITE = 'overwrite'

Optional argument name for use with the CONVERT subparser, indicating to overwrite any existing output file without prompting

PLAIN = 'plain'

Argument value for CONVERT MODE, to output a plaintext inventory

QUIET = 'quiet'

Optional argument name for use with the CONVERT subparser, indicating to suppress console output

SCORE = 'score'

Optional argument name for use with the SUGGEST subparser, indicating to print the fuzzywuzzy score of each returned object within INFILE along with the object domain/role/name (may be specified with INDEX)

SEARCH = 'search'

Positional argument name for use with the SUGGEST subparser, holding the search term for fuzzywuzzy text matching

SUBPARSER_NAME = 'sprs_name'

Param for storing subparser name (CONVERT or SUGGEST)

SUGGEST = 'suggest'

Subparser name for inventory object suggestions; stored in SUBPARSER_NAME when selected

SUGGEST_CONFIRM_LENGTH = 30

Number of returned objects from a SUGGEST subparser invocation above which user will be prompted for confirmation to print the results (unless ALL is specified)

THRESH = 'thresh'

Optional argument name for use with the SUGGEST subparser, taking the minimum desired fuzzywuzzy match quality as one required argument

URL = 'url'

Optional argument name for use with both CONVERT and SUGGEST subparsers, indicating that INFILE is to be treated as a URL rather than a local file path

VERSION = 'version'

Optional argument name for use with the base argument parser, to show version &c. info, and exit

VER_TXT = '\nsphobjinv v2.0\n\nCopyright (c) Brian Skinn 2016-2018\nLicense: The MIT License\n\nBug reports & feature requests: https://github.com/bskinn/sphobjinv\nDocumentation: http://sphobjinv.readthedocs.io\n'

Version &c. output blurb

ZLIB = 'zlib'

Argument value for CONVERT MODE, to output a zlib-compressed inventory