sphinx.util

package documentation

Utility functions for Sphinx.

Unknown Field: copyright
Copyright 2007-2022 by the Sphinx team, see AUTHORS.
Unknown Field: license
BSD, see LICENSE for details.

Module	`docutils`	sphinx.util.docutils ~~~~~~~~~~~~~~~~~~~~
Module	`logging`	sphinx.util.logging ~~~~~~~~~~~~~~~~~~~
Module	`build_phase`	sphinx.util.build_phase ~~~~~~~~~~~~~~~~~~~~~~~
Module	`cfamily`	sphinx.util.cfamily ~~~~~~~~~~~~~~~~~~~
Module	`compat`	sphinx.util.compat ~~~~~~~~~~~~~~~~~~
Module	`console`	sphinx.util.console ~~~~~~~~~~~~~~~~~~~
Module	`docfields`	sphinx.util.docfields ~~~~~~~~~~~~~~~~~~~~~
Module	`docstrings`	sphinx.util.docstrings ~~~~~~~~~~~~~~~~~~~~~~
Module	`fileutil`	sphinx.util.fileutil ~~~~~~~~~~~~~~~~~~~~
Module	`i18n`	sphinx.util.i18n ~~~~~~~~~~~~~~~~
Module	`images`	sphinx.util.images ~~~~~~~~~~~~~~~~~~
Module	`inspect`	sphinx.util.inspect ~~~~~~~~~~~~~~~~~~~
Module	`inventory`	sphinx.util.inventory ~~~~~~~~~~~~~~~~~~~~~
Module	`jsdump`	sphinx.util.jsdump ~~~~~~~~~~~~~~~~~~
Module	`matching`	sphinx.util.matching ~~~~~~~~~~~~~~~~~~~~
Module	`math`	sphinx.util.math ~~~~~~~~~~~~~~~~
Module	`nodes`	sphinx.util.nodes ~~~~~~~~~~~~~~~~~
Module	`osutil`	sphinx.util.osutil ~~~~~~~~~~~~~~~~~~
Module	`parallel`	sphinx.util.parallel ~~~~~~~~~~~~~~~~~~~~
Module	`png`	sphinx.util.png ~~~~~~~~~~~~~~~
Module	`pycompat`	sphinx.util.pycompat ~~~~~~~~~~~~~~~~~~~~
Module	`requests`	sphinx.util.requests ~~~~~~~~~~~~~~~~~~~~
Module	`rst`	sphinx.util.rst ~~~~~~~~~~~~~~~
Module	`smartypants`	sphinx.util.smartypants ~~~~~~~~~~~~~~~~~~~~~~~
Package	`stemmer`	sphinx.util.stemmer ~~~~~~~~~~~~~~~~~~~
Module	`tags`	sphinx.util.tags ~~~~~~~~~~~~~~~~
Module	`template`	sphinx.util.template ~~~~~~~~~~~~~~~~~~~~
Module	`texescape`	sphinx.util.texescape ~~~~~~~~~~~~~~~~~~~~~
Module	`typing`	sphinx.util.typing ~~~~~~~~~~~~~~~~~~

From __init__.py:

Variable	`logger`	Undocumented
Variable	`url_re`	Undocumented
Variable	`ws_re`	Undocumented
Class	`DownloadFiles`	A special dictionary for download files.
Class	`FilenameUniqDict`	A dictionary that automatically generates unique names for its keys, interpreted as filenames, and keeps track of a set of docnames they appear in. Used for images and downloadable files in the environment.
Class	`progress_message`	Undocumented
Class	`SkipProgressMessage`	Undocumented
Class	`Tee`	File-like object writing to two streams.
Class	`UnicodeDecodeErrorHandler`	Custom error handler for open() that warns and replaces.
Function	`display_chunk`	Undocumented
Function	`docname_join`	Undocumented
Function	`encode_uri`	Undocumented
Function	`epoch_to_rfc1123`	Convert datetime format epoch to RFC1123.
Function	`force_decode`	Forcibly get a unicode string out of a bytestring.
Function	`format_exception_cut_frames`	Format an exception with traceback, but only the last x frames.
Function	`get_filetype`	Undocumented
Function	`get_full_modname`	Undocumented
Function	`get_matching_files`	Get all file names in a directory, recursively.
Function	`import_object`	Import python object by qualname.
Function	`isurl`	Check url is URL or not.
Function	`md5`	Wrapper around hashlib.md5
Function	`old_status_iterator`	Undocumented
Function	`parselinenos`	Parse a line number spec (such as "1,2,4-6") and return a list of wanted line numbers.
Function	`path_stabilize`	Normalize path separator and unicode string
Function	`rfc1123_to_epoch`	Undocumented
Function	`rpartition`	Similar to str.rpartition from 2.5, but doesn't return the separator.
Function	`save_traceback`	Save the current exception's traceback in a temporary file.
Function	`sha1`	Wrapper around hashlib.sha1
Function	`split_full_qualified_name`	Split full qualified name to a pair of modname and qualname.
Function	`split_index_msg`	Undocumented
Function	`split_into`	Split an index entry into a given number of parts at semicolons.
Function	`status_iterator`	Undocumented
Function	`xmlname_checker`	Undocumented
Constant	`_DEBUG_HEADER`	Undocumented
Variable	`_coding_re`	Undocumented

logger =

Undocumented

ws_re: Pattern =

Undocumented

url_re: Pattern =

Undocumented

def docname_join(basedocname, docname):

Undocumented

Parameters
basedocname:`str`	Undocumented
docname:`str`	Undocumented
Returns
`str`	Undocumented

def path_stabilize(filepath):

Normalize path separator and unicode string

Parameters
filepath:`str`	Undocumented
Returns
`str`	Undocumented

def get_matching_files(dirname, exclude_matchers=()):

Get all file names in a directory, recursively.

Exclude files and dirs matching some matcher in exclude_matchers.

Parameters
dirname:`str`	Undocumented
exclude_matchers:`Tuple[PathMatcher, ...]`	Undocumented
Returns
`Iterable[str]`	Undocumented

def get_filetype(source_suffix, filename):

Undocumented

Parameters
source_suffix:`Dict[str, str]`	Undocumented
filename:`str`	Undocumented
Returns
`str`	Undocumented

def md5(data=b'', **kwargs):

Wrapper around hashlib.md5

Attempt call with 'usedforsecurity=False' if we get a ValueError, which happens when OpenSSL FIPS mode is enabled: ValueError: error:060800A3:digital envelope routines:EVP_DigestInit_ex:disabled for fips

See: https://github.com/sphinx-doc/sphinx/issues/7611

def sha1(data=b'', **kwargs):

Wrapper around hashlib.sha1

Attempt call with 'usedforsecurity=False' if we get a ValueError

See: https://github.com/sphinx-doc/sphinx/issues/7611

_DEBUG_HEADER: str =

Undocumented

Value

'''# Sphinx version: %s
# Python version: %s (%s)
# Docutils version: %s %s
# Jinja2 version: %s
# Last messages:
%s
# Loaded extensions:
...

def save_traceback(app):

Save the current exception's traceback in a temporary file.

Parameters
app:`Sphinx`	Undocumented
Returns
`str`	Undocumented

def get_full_modname(modname, attribute):

Undocumented

Parameters
modname:`str`	Undocumented
attribute:`str`	Undocumented
Returns
`str`	Undocumented

_coding_re =

Undocumented

def parselinenos(spec, total):

Parse a line number spec (such as "1,2,4-6") and return a list of wanted line numbers.

Parameters
spec:`str`	Undocumented
total:`int`	Undocumented
Returns
`List[int]`	Undocumented

def force_decode(string, encoding):

Forcibly get a unicode string out of a bytestring.

Parameters
string:`str`	Undocumented
encoding:`str`	Undocumented
Returns
`str`	Undocumented

def rpartition(s, t):

Similar to str.rpartition from 2.5, but doesn't return the separator.

Parameters
s:`str`	Undocumented
t:`str`	Undocumented
Returns
`Tuple[str, str]`	Undocumented

def split_into(n, type, value):

Split an index entry into a given number of parts at semicolons.

Parameters
n:`int`	Undocumented
type:`str`	Undocumented
value:`str`	Undocumented
Returns
`List[str]`	Undocumented

def split_index_msg(type, value):

Undocumented

Parameters
type:`str`	Undocumented
value:`str`	Undocumented
Returns
`List[str]`	Undocumented

def format_exception_cut_frames(x=1):

Format an exception with traceback, but only the last x frames.

Parameters
x:`int`	Undocumented
Returns
`str`	Undocumented

def import_object(objname, source=None):

Import python object by qualname.

Parameters
objname:`str`	Undocumented
source:`str`	Undocumented
Returns
`Any`	Undocumented

def split_full_qualified_name(name):

Split full qualified name to a pair of modname and qualname.

A qualname is an abbreviation for "Qualified name" introduced at PEP-3155 (https://www.python.org/dev/peps/pep-3155/). It is a dotted path name from the module top-level.

A "full" qualified name means a string containing both module name and qualified name.

Note

This function actually imports the module to check its existence. Therefore you need to mock 3rd party modules if needed before calling this function.

Parameters
name:`str`	Undocumented
Returns
`Tuple[Optional[str], str]`	Undocumented

def encode_uri(uri):

Undocumented

Parameters
uri:`str`	Undocumented
Returns
`str`	Undocumented

def isurl(url):

Check url is URL or not.

Parameters
url:`str`	Undocumented
Returns
`bool`	Undocumented

def display_chunk(chunk):

Undocumented

Parameters
chunk:`Any`	Undocumented
Returns
`str`	Undocumented

def old_status_iterator(iterable, summary, color='darkgreen', stringify_func=display_chunk):

Undocumented

Parameters
iterable:`Iterable`	Undocumented
summary:`str`	Undocumented
color:`str`	Undocumented
stringify_func:`Callable[[Any], str]`	Undocumented
Returns
`Iterator`	Undocumented

def status_iterator(iterable, summary, color='darkgreen', length=0, verbosity=0, stringify_func=display_chunk):

Undocumented

Parameters
iterable:`Iterable`	Undocumented
summary:`str`	Undocumented
color:`str`	Undocumented
length:`int`	Undocumented
verbosity:`int`	Undocumented
stringify_func:`Callable[[Any], str]`	Undocumented
Returns
`Iterable`	Undocumented

def epoch_to_rfc1123(epoch):

Convert datetime format epoch to RFC1123.

Parameters
epoch:`float`	Undocumented
Returns
`str`	Undocumented

def rfc1123_to_epoch(rfc1123):

Undocumented

Parameters
rfc1123:`str`	Undocumented
Returns
`float`	Undocumented

def xmlname_checker():

Undocumented

Returns
`Pattern`	Undocumented