' + _('Hide Search Matches') + '
') - .appendTo($('#searchbox')); - } - }, - - /** - * init the domain index toggle buttons - */ - initIndexTable : function() { - var togglers = $('img.toggler').click(function() { - var src = $(this).attr('src'); - var idnum = $(this).attr('id').substr(7); - $('tr.cg-' + idnum).toggle(); - if (src.substr(-9) === 'minus.png') - $(this).attr('src', src.substr(0, src.length-9) + 'plus.png'); - else - $(this).attr('src', src.substr(0, src.length-8) + 'minus.png'); - }).css('display', ''); - if (DOCUMENTATION_OPTIONS.COLLAPSE_INDEX) { - togglers.click(); - } - }, + }; - /** - * helper function to hide the search marks again - */ - hideSearchWords : function() { - $('#searchbox .highlight-link').fadeOut(300); - $('span.highlighted').removeClass('highlighted'); - var url = new URL(window.location); - url.searchParams.delete('highlight'); - window.history.replaceState({}, '', url); + const togglerElements = document.querySelectorAll("img.toggler"); + togglerElements.forEach((el) => + el.addEventListener("click", (event) => toggler(event.currentTarget)) + ); + togglerElements.forEach((el) => (el.style.display = "")); + if (DOCUMENTATION_OPTIONS.COLLAPSE_INDEX) togglerElements.forEach(toggler); }, - /** - * make the url absolute - */ - makeURL : function(relativeURL) { - return DOCUMENTATION_OPTIONS.URL_ROOT + '/' + relativeURL; - }, - - /** - * get the current relative url - */ - getCurrentURL : function() { - var path = document.location.pathname; - var parts = path.split(/\//); - $.each(DOCUMENTATION_OPTIONS.URL_ROOT.split(/\//), function() { - if (this === '..') - parts.pop(); - }); - var url = parts.join('/'); - return path.substring(url.lastIndexOf('/') + 1, path.length - 1); - }, - - initOnKeyListeners: function() { - $(document).keydown(function(event) { - var activeElementType = document.activeElement.tagName; - // don't navigate when in search box, textarea, dropdown or button - if (activeElementType !== 'TEXTAREA' && activeElementType !== 'INPUT' && activeElementType !== 'SELECT' - && activeElementType !== 'BUTTON' && !event.altKey && !event.ctrlKey && !event.metaKey - && !event.shiftKey) { - switch (event.keyCode) { - case 37: // left - var prevHref = $('link[rel="prev"]').prop('href'); - if (prevHref) { - window.location.href = prevHref; - return false; + initOnKeyListeners: () => { + // only install a listener if it is really needed + if ( + !DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS && + !DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS + ) + return; + + document.addEventListener("keydown", (event) => { + // bail for input elements + if (BLACKLISTED_KEY_CONTROL_ELEMENTS.has(document.activeElement.tagName)) return; + // bail with special keys + if (event.altKey || event.ctrlKey || event.metaKey) return; + + if (!event.shiftKey) { + switch (event.key) { + case "ArrowLeft": + if (!DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS) break; + + const prevLink = document.querySelector('link[rel="prev"]'); + if (prevLink && prevLink.href) { + window.location.href = prevLink.href; + event.preventDefault(); } break; - case 39: // right - var nextHref = $('link[rel="next"]').prop('href'); - if (nextHref) { - window.location.href = nextHref; - return false; + case "ArrowRight": + if (!DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS) break; + + const nextLink = document.querySelector('link[rel="next"]'); + if (nextLink && nextLink.href) { + window.location.href = nextLink.href; + event.preventDefault(); } break; } } + + // some keyboard layouts may need Shift to get / + switch (event.key) { + case "/": + if (!DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS) break; + Documentation.focusSearchBar(); + event.preventDefault(); + } }); - } + }, }; // quick alias for translations -_ = Documentation.gettext; +const _ = Documentation.gettext; -$(document).ready(function() { - Documentation.init(); -}); +_ready(Documentation.init); diff --git a/docs/documentation/_static/documentation_options.js b/docs/documentation/_static/documentation_options.js index 164f076e..f9bbedc6 100644 --- a/docs/documentation/_static/documentation_options.js +++ b/docs/documentation/_static/documentation_options.js @@ -1,12 +1,13 @@ -var DOCUMENTATION_OPTIONS = { - URL_ROOT: document.getElementById("documentation_options").getAttribute('data-url_root'), - VERSION: '5.1.0', - LANGUAGE: 'None', +const DOCUMENTATION_OPTIONS = { + VERSION: '5.2.0', + LANGUAGE: 'en', COLLAPSE_INDEX: false, BUILDER: 'html', FILE_SUFFIX: '.html', LINK_SUFFIX: '.html', HAS_SOURCE: true, SOURCELINK_SUFFIX: '.txt', - NAVIGATION_WITH_KEYS: false + NAVIGATION_WITH_KEYS: false, + SHOW_SEARCH_SUMMARY: true, + ENABLE_SEARCH_SHORTCUTS: true, }; \ No newline at end of file diff --git a/docs/documentation/_static/language_data.js b/docs/documentation/_static/language_data.js index ebe2f03b..250f5665 100644 --- a/docs/documentation/_static/language_data.js +++ b/docs/documentation/_static/language_data.js @@ -5,12 +5,12 @@ * This script contains the language-specific data used by searchtools.js, * namely the list of stopwords, stemmer, scorer and splitter. * - * :copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS. + * :copyright: Copyright 2007-2023 by the Sphinx team, see AUTHORS. * :license: BSD, see LICENSE for details. * */ -var stopwords = ["a","and","are","as","at","be","but","by","for","if","in","into","is","it","near","no","not","of","on","or","such","that","the","their","then","there","these","they","this","to","was","will","with"]; +var stopwords = ["a", "and", "are", "as", "at", "be", "but", "by", "for", "if", "in", "into", "is", "it", "near", "no", "not", "of", "on", "or", "such", "that", "the", "their", "then", "there", "these", "they", "this", "to", "was", "will", "with"]; /* Non-minified version is copied as a separate JS file, is available */ @@ -197,101 +197,3 @@ var Stemmer = function() { } } - - - -var splitChars = (function() { - var result = {}; - var singles = [96, 180, 187, 191, 215, 247, 749, 885, 903, 907, 909, 930, 1014, 1648, - 1748, 1809, 2416, 2473, 2481, 2526, 2601, 2609, 2612, 2615, 2653, 2702, - 2706, 2729, 2737, 2740, 2857, 2865, 2868, 2910, 2928, 2948, 2961, 2971, - 2973, 3085, 3089, 3113, 3124, 3213, 3217, 3241, 3252, 3295, 3341, 3345, - 3369, 3506, 3516, 3633, 3715, 3721, 3736, 3744, 3748, 3750, 3756, 3761, - 3781, 3912, 4239, 4347, 4681, 4695, 4697, 4745, 4785, 4799, 4801, 4823, - 4881, 5760, 5901, 5997, 6313, 7405, 8024, 8026, 8028, 8030, 8117, 8125, - 8133, 8181, 8468, 8485, 8487, 8489, 8494, 8527, 11311, 11359, 11687, 11695, - 11703, 11711, 11719, 11727, 11735, 12448, 12539, 43010, 43014, 43019, 43587, - 43696, 43713, 64286, 64297, 64311, 64317, 64319, 64322, 64325, 65141]; - var i, j, start, end; - for (i = 0; i < singles.length; i++) { - result[singles[i]] = true; - } - var ranges = [[0, 47], [58, 64], [91, 94], [123, 169], [171, 177], [182, 184], [706, 709], - [722, 735], [741, 747], [751, 879], [888, 889], [894, 901], [1154, 1161], - [1318, 1328], [1367, 1368], [1370, 1376], [1416, 1487], [1515, 1519], [1523, 1568], - [1611, 1631], [1642, 1645], [1750, 1764], [1767, 1773], [1789, 1790], [1792, 1807], - [1840, 1868], [1958, 1968], [1970, 1983], [2027, 2035], [2038, 2041], [2043, 2047], - [2070, 2073], [2075, 2083], [2085, 2087], [2089, 2307], [2362, 2364], [2366, 2383], - [2385, 2391], [2402, 2405], [2419, 2424], [2432, 2436], [2445, 2446], [2449, 2450], - [2483, 2485], [2490, 2492], [2494, 2509], [2511, 2523], [2530, 2533], [2546, 2547], - [2554, 2564], [2571, 2574], [2577, 2578], [2618, 2648], [2655, 2661], [2672, 2673], - [2677, 2692], [2746, 2748], [2750, 2767], [2769, 2783], [2786, 2789], [2800, 2820], - [2829, 2830], [2833, 2834], [2874, 2876], [2878, 2907], [2914, 2917], [2930, 2946], - [2955, 2957], [2966, 2968], [2976, 2978], [2981, 2983], [2987, 2989], [3002, 3023], - [3025, 3045], [3059, 3076], [3130, 3132], [3134, 3159], [3162, 3167], [3170, 3173], - [3184, 3191], [3199, 3204], [3258, 3260], [3262, 3293], [3298, 3301], [3312, 3332], - [3386, 3388], [3390, 3423], [3426, 3429], [3446, 3449], [3456, 3460], [3479, 3481], - [3518, 3519], [3527, 3584], [3636, 3647], [3655, 3663], [3674, 3712], [3717, 3718], - [3723, 3724], [3726, 3731], [3752, 3753], [3764, 3772], [3774, 3775], [3783, 3791], - [3802, 3803], [3806, 3839], [3841, 3871], [3892, 3903], [3949, 3975], [3980, 4095], - [4139, 4158], [4170, 4175], [4182, 4185], [4190, 4192], [4194, 4196], [4199, 4205], - [4209, 4212], [4226, 4237], [4250, 4255], [4294, 4303], [4349, 4351], [4686, 4687], - [4702, 4703], [4750, 4751], [4790, 4791], [4806, 4807], [4886, 4887], [4955, 4968], - [4989, 4991], [5008, 5023], [5109, 5120], [5741, 5742], [5787, 5791], [5867, 5869], - [5873, 5887], [5906, 5919], [5938, 5951], [5970, 5983], [6001, 6015], [6068, 6102], - [6104, 6107], [6109, 6111], [6122, 6127], [6138, 6159], [6170, 6175], [6264, 6271], - [6315, 6319], [6390, 6399], [6429, 6469], [6510, 6511], [6517, 6527], [6572, 6592], - [6600, 6607], [6619, 6655], [6679, 6687], [6741, 6783], [6794, 6799], [6810, 6822], - [6824, 6916], [6964, 6980], [6988, 6991], [7002, 7042], [7073, 7085], [7098, 7167], - [7204, 7231], [7242, 7244], [7294, 7400], [7410, 7423], [7616, 7679], [7958, 7959], - [7966, 7967], [8006, 8007], [8014, 8015], [8062, 8063], [8127, 8129], [8141, 8143], - [8148, 8149], [8156, 8159], [8173, 8177], [8189, 8303], [8306, 8307], [8314, 8318], - [8330, 8335], [8341, 8449], [8451, 8454], [8456, 8457], [8470, 8472], [8478, 8483], - [8506, 8507], [8512, 8516], [8522, 8525], [8586, 9311], [9372, 9449], [9472, 10101], - [10132, 11263], [11493, 11498], [11503, 11516], [11518, 11519], [11558, 11567], - [11622, 11630], [11632, 11647], [11671, 11679], [11743, 11822], [11824, 12292], - [12296, 12320], [12330, 12336], [12342, 12343], [12349, 12352], [12439, 12444], - [12544, 12548], [12590, 12592], [12687, 12689], [12694, 12703], [12728, 12783], - [12800, 12831], [12842, 12880], [12896, 12927], [12938, 12976], [12992, 13311], - [19894, 19967], [40908, 40959], [42125, 42191], [42238, 42239], [42509, 42511], - [42540, 42559], [42592, 42593], [42607, 42622], [42648, 42655], [42736, 42774], - [42784, 42785], [42889, 42890], [42893, 43002], [43043, 43055], [43062, 43071], - [43124, 43137], [43188, 43215], [43226, 43249], [43256, 43258], [43260, 43263], - [43302, 43311], [43335, 43359], [43389, 43395], [43443, 43470], [43482, 43519], - [43561, 43583], [43596, 43599], [43610, 43615], [43639, 43641], [43643, 43647], - [43698, 43700], [43703, 43704], [43710, 43711], [43715, 43738], [43742, 43967], - [44003, 44015], [44026, 44031], [55204, 55215], [55239, 55242], [55292, 55295], - [57344, 63743], [64046, 64047], [64110, 64111], [64218, 64255], [64263, 64274], - [64280, 64284], [64434, 64466], [64830, 64847], [64912, 64913], [64968, 65007], - [65020, 65135], [65277, 65295], [65306, 65312], [65339, 65344], [65371, 65381], - [65471, 65473], [65480, 65481], [65488, 65489], [65496, 65497]]; - for (i = 0; i < ranges.length; i++) { - start = ranges[i][0]; - end = ranges[i][1]; - for (j = start; j <= end; j++) { - result[j] = true; - } - } - return result; -})(); - -function splitQuery(query) { - var result = []; - var start = -1; - for (var i = 0; i < query.length; i++) { - if (splitChars[query.charCodeAt(i)]) { - if (start !== -1) { - result.push(query.slice(start, i)); - start = -1; - } - } else if (start === -1) { - start = i; - } - } - if (start !== -1) { - result.push(query.slice(start)); - } - return result; -} - - diff --git a/docs/documentation/_static/pygments.css b/docs/documentation/_static/pygments.css index 691aeb82..0d49244e 100644 --- a/docs/documentation/_static/pygments.css +++ b/docs/documentation/_static/pygments.css @@ -17,6 +17,7 @@ span.linenos.special { color: #000000; background-color: #ffffc0; padding-left: .highlight .cs { color: #408090; background-color: #fff0f0 } /* Comment.Special */ .highlight .gd { color: #A00000 } /* Generic.Deleted */ .highlight .ge { font-style: italic } /* Generic.Emph */ +.highlight .ges { font-weight: bold; font-style: italic } /* Generic.EmphStrong */ .highlight .gr { color: #FF0000 } /* Generic.Error */ .highlight .gh { color: #000080; font-weight: bold } /* Generic.Heading */ .highlight .gi { color: #00A000 } /* Generic.Inserted */ diff --git a/docs/documentation/_static/searchtools.js b/docs/documentation/_static/searchtools.js index 2d778593..7918c3fa 100644 --- a/docs/documentation/_static/searchtools.js +++ b/docs/documentation/_static/searchtools.js @@ -4,22 +4,24 @@ * * Sphinx JavaScript utilities for the full-text search. * - * :copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS. + * :copyright: Copyright 2007-2023 by the Sphinx team, see AUTHORS. * :license: BSD, see LICENSE for details. * */ +"use strict"; -if (!Scorer) { - /** - * Simple result scoring code. - */ +/** + * Simple result scoring code. + */ +if (typeof Scorer === "undefined") { var Scorer = { // Implement the following function to further tweak the score for each result - // The function takes a result array [filename, title, anchor, descr, score] + // The function takes a result array [docname, title, anchor, descr, score, filename] // and returns the new score. /* - score: function(result) { - return result[4]; + score: result => { + const [docname, title, anchor, descr, score, filename] = result + return score }, */ @@ -28,9 +30,11 @@ if (!Scorer) { // or matches in the last dotted part of the object name objPartialMatch: 6, // Additive scores depending on the priority of the object - objPrio: {0: 15, // used to be importantResults - 1: 5, // used to be objectResults - 2: -5}, // used to be unimportantResults + objPrio: { + 0: 15, // used to be importantResults + 1: 5, // used to be objectResults + 2: -5, // used to be unimportantResults + }, // Used when the priority is not in the mapping. objPrioDefault: 0, @@ -39,456 +43,503 @@ if (!Scorer) { partialTitle: 7, // query found in terms term: 5, - partialTerm: 2 + partialTerm: 2, }; } -if (!splitQuery) { - function splitQuery(query) { - return query.split(/\s+/); +const _removeChildren = (element) => { + while (element && element.lastChild) element.removeChild(element.lastChild); +}; + +/** + * See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions#escaping + */ +const _escapeRegExp = (string) => + string.replace(/[.*+\-?^${}()|[\]\\]/g, "\\$&"); // $& means the whole matched string + +const _displayItem = (item, searchTerms, highlightTerms) => { + const docBuilder = DOCUMENTATION_OPTIONS.BUILDER; + const docFileSuffix = DOCUMENTATION_OPTIONS.FILE_SUFFIX; + const docLinkSuffix = DOCUMENTATION_OPTIONS.LINK_SUFFIX; + const showSearchSummary = DOCUMENTATION_OPTIONS.SHOW_SEARCH_SUMMARY; + const contentRoot = document.documentElement.dataset.content_root; + + const [docName, title, anchor, descr, score, _filename] = item; + + let listItem = document.createElement("li"); + let requestUrl; + let linkUrl; + if (docBuilder === "dirhtml") { + // dirhtml builder + let dirname = docName + "/"; + if (dirname.match(/\/index\/$/)) + dirname = dirname.substring(0, dirname.length - 6); + else if (dirname === "index/") dirname = ""; + requestUrl = contentRoot + dirname; + linkUrl = requestUrl; + } else { + // normal html builders + requestUrl = contentRoot + docName + docFileSuffix; + linkUrl = docName + docLinkSuffix; } + let linkEl = listItem.appendChild(document.createElement("a")); + linkEl.href = linkUrl + anchor; + linkEl.dataset.score = score; + linkEl.innerHTML = title; + if (descr) { + listItem.appendChild(document.createElement("span")).innerHTML = + " (" + descr + ")"; + // highlight search terms in the description + if (SPHINX_HIGHLIGHT_ENABLED) // set in sphinx_highlight.js + highlightTerms.forEach((term) => _highlightText(listItem, term, "highlighted")); + } + else if (showSearchSummary) + fetch(requestUrl) + .then((responseData) => responseData.text()) + .then((data) => { + if (data) + listItem.appendChild( + Search.makeSearchSummary(data, searchTerms) + ); + // highlight search terms in the summary + if (SPHINX_HIGHLIGHT_ENABLED) // set in sphinx_highlight.js + highlightTerms.forEach((term) => _highlightText(listItem, term, "highlighted")); + }); + Search.output.appendChild(listItem); +}; +const _finishSearch = (resultCount) => { + Search.stopPulse(); + Search.title.innerText = _("Search Results"); + if (!resultCount) + Search.status.innerText = Documentation.gettext( + "Your search did not match any documents. Please make sure that all words are spelled correctly and that you've selected enough categories." + ); + else + Search.status.innerText = _( + `Search finished, found ${resultCount} page(s) matching the search query.` + ); +}; +const _displayNextItem = ( + results, + resultCount, + searchTerms, + highlightTerms, +) => { + // results left, load the summary and display it + // this is intended to be dynamic (don't sub resultsCount) + if (results.length) { + _displayItem(results.pop(), searchTerms, highlightTerms); + setTimeout( + () => _displayNextItem(results, resultCount, searchTerms, highlightTerms), + 5 + ); + } + // search finished, update title and status message + else _finishSearch(resultCount); +}; + +/** + * Default splitQuery function. Can be overridden in ``sphinx.search`` with a + * custom function per language. + * + * The regular expression works by splitting the string on consecutive characters + * that are not Unicode letters, numbers, underscores, or emoji characters. + * This is the same as ``\W+`` in Python, preserving the surrogate pair area. + */ +if (typeof splitQuery === "undefined") { + var splitQuery = (query) => query + .split(/[^\p{Letter}\p{Number}_\p{Emoji_Presentation}]+/gu) + .filter(term => term) // remove remaining empty strings } /** * Search Module */ -var Search = { - - _index : null, - _queued_query : null, - _pulse_status : -1, - - htmlToText : function(htmlString) { - var virtualDocument = document.implementation.createHTMLDocument('virtual'); - var htmlElement = $(htmlString, virtualDocument); - htmlElement.find('.headerlink').remove(); - docContent = htmlElement.find('[role=main]')[0]; - if(docContent === undefined) { - console.warn("Content block not found. Sphinx search tries to obtain it " + - "via '[role=main]'. Could you check your theme or template."); - return ""; - } - return docContent.textContent || docContent.innerText; +const Search = { + _index: null, + _queued_query: null, + _pulse_status: -1, + + htmlToText: (htmlString) => { + const htmlElement = new DOMParser().parseFromString(htmlString, 'text/html'); + htmlElement.querySelectorAll(".headerlink").forEach((el) => { el.remove() }); + const docContent = htmlElement.querySelector('[role="main"]'); + if (docContent !== undefined) return docContent.textContent; + console.warn( + "Content block not found. Sphinx search tries to obtain it via '[role=main]'. Could you check your theme or template." + ); + return ""; }, - init : function() { - var params = $.getQueryParameters(); - if (params.q) { - var query = params.q[0]; - $('input[name="q"]')[0].value = query; - this.performSearch(query); - } + init: () => { + const query = new URLSearchParams(window.location.search).get("q"); + document + .querySelectorAll('input[name="q"]') + .forEach((el) => (el.value = query)); + if (query) Search.performSearch(query); }, - loadIndex : function(url) { - $.ajax({type: "GET", url: url, data: null, - dataType: "script", cache: true, - complete: function(jqxhr, textstatus) { - if (textstatus != "success") { - document.getElementById("searchindexloader").src = url; - } - }}); - }, + loadIndex: (url) => + (document.body.appendChild(document.createElement("script")).src = url), - setIndex : function(index) { - var q; - this._index = index; - if ((q = this._queued_query) !== null) { - this._queued_query = null; - Search.query(q); + setIndex: (index) => { + Search._index = index; + if (Search._queued_query !== null) { + const query = Search._queued_query; + Search._queued_query = null; + Search.query(query); } }, - hasIndex : function() { - return this._index !== null; - }, + hasIndex: () => Search._index !== null, - deferQuery : function(query) { - this._queued_query = query; - }, + deferQuery: (query) => (Search._queued_query = query), - stopPulse : function() { - this._pulse_status = 0; - }, + stopPulse: () => (Search._pulse_status = -1), - startPulse : function() { - if (this._pulse_status >= 0) - return; - function pulse() { - var i; + startPulse: () => { + if (Search._pulse_status >= 0) return; + + const pulse = () => { Search._pulse_status = (Search._pulse_status + 1) % 4; - var dotString = ''; - for (i = 0; i < Search._pulse_status; i++) - dotString += '.'; - Search.dots.text(dotString); - if (Search._pulse_status > -1) - window.setTimeout(pulse, 500); - } + Search.dots.innerText = ".".repeat(Search._pulse_status); + if (Search._pulse_status >= 0) window.setTimeout(pulse, 500); + }; pulse(); }, /** * perform a search for something (or wait until index is loaded) */ - performSearch : function(query) { + performSearch: (query) => { // create the required interface elements - this.out = $('#search-results'); - this.title = $('').appendTo(this.out); - this.output = $('
' + + '' + + _("Hide Search Matches") + + "
" + ) + ); + }, + + /** + * helper function to hide the search marks again + */ + hideSearchWords: () => { + document + .querySelectorAll("#searchbox .highlight-link") + .forEach((el) => el.remove()); + document + .querySelectorAll("span.highlighted") + .forEach((el) => el.classList.remove("highlighted")); + localStorage.removeItem("sphinx_highlight_terms") + }, + + initEscapeListener: () => { + // only install a listener if it is really needed + if (!DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS) return; + + document.addEventListener("keydown", (event) => { + // bail for input elements + if (BLACKLISTED_KEY_CONTROL_ELEMENTS.has(document.activeElement.tagName)) return; + // bail with special keys + if (event.shiftKey || event.altKey || event.ctrlKey || event.metaKey) return; + if (DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS && (event.key === "Escape")) { + SphinxHighlight.hideSearchWords(); + event.preventDefault(); + } + }); + }, +}; + +_ready(() => { + /* Do not call highlightSearchWords() when we are on the search page. + * It will highlight words from the *previous* search query. + */ + if (typeof Search === "undefined") SphinxHighlight.highlightSearchWords(); + SphinxHighlight.initEscapeListener(); +}); diff --git a/docs/documentation/available-scan-commands.html b/docs/documentation/available-scan-commands.html index 396df1fe..dae3d56c 100644 --- a/docs/documentation/available-scan-commands.html +++ b/docs/documentation/available-scan-commands.html @@ -1,18 +1,16 @@ - - + - - -Every type of TLS check that SSLyze can run against a server (supported cipher suites, session renegotiation, etc.) is
represented by a ScanCommand, which, when run against a server, will return a specific result.
This page lists all the ScanCommand and their corresponding results available in the current release of SSLyze.
For an example on how to run a scan via the Python API, see Running a Scan in Python.
-Release 5.1.0
+Release 5.2.0
@@ -42,7 +40,7 @@ The Python API gives full access to SSLyze’s scanning engine in order to make it easy to implement SSL/TLS scanning as part of a continuous security testing platform, and detect any misconfiguration across a range of public and/or internal endpoints.
@@ -79,7 +77,7 @@The result of SSLyze scans can be serialized to JSON for further processing. SSLyze also provides a helper class to parse JSON scan results; it can be used to process the results of SSLyze scans in a separate Python program.
SSLyze’s Python API can be used to run scans and process results in an automated fashion.
Every SSLyze class has typing annotations, which allows IDEs such as VS Code and PyCharms to auto-import modules and auto-complete field names. Make sure to leverage this typing information as it will make it significantly easier @@ -78,7 +76,7 @@
A full example of running a scan on a couple servers follow:
def main() -> None:
print("=> Starting the scans")
@@ -170,16 +168,16 @@ Full Example
-Classes for Starting a Scan¶
+Classes for Starting a Scan¶
-
-class sslyze.ServerScanRequest(server_location, network_configuration=None, scan_commands=<factory>, scan_commands_extra_arguments=<factory>, uuid=<factory>)¶
+class sslyze.ServerScanRequest(server_location, network_configuration=None, scan_commands=<factory>, scan_commands_extra_arguments=<factory>, uuid=<factory>)¶
A request to scan a specific server.
-- Parameters
+- Parameters:
server_location (ServerNetworkLocation) – The server to scan.
network_configuration (Optional[ServerNetworkConfiguration]) – An optional network configuration. If not supplied, a default configuration will be used.
network_configuration (ServerNetworkConfiguration) – An optional network configuration. If not supplied, a default configuration will be used.
scan_commands (Set[ScanCommand]) – An optional list of scan commands to run against the server. If not supplied, all available
scan commands will be run.
scan_commands_extra_arguments (ScanCommandsExtraArguments) – An optional list of extra arguments specific to some scan commands. If not
@@ -192,64 +190,44 @@
Classes for Starting a Scan
-
-class sslyze.ServerNetworkLocation(hostname, port=443, ip_address=None, http_proxy_settings=None)¶
+class sslyze.ServerNetworkLocation(hostname, port=443, ip_address=None, http_proxy_settings=None)¶
All the information needed to connect to a server.
-
-connection_type¶
+connection_type¶
How sslyze should connect to the server: either directly, or via an HTTP proxy.
-
-ip_address¶
+ip_address¶
The server’s IP address; only set if sslyze is connecting directly to the server. If no IP address
is supplied and connection_type is set to DIRECT, sslyze will automatically lookup one IP address for the
supplied hostname.
-
-- Type
-Optional[str]
-
-
-http_proxy_settings¶
+http_proxy_settings¶
The HTTP proxy configuration to use in order to tunnel the scans through a proxy; only set
if sslyze is connecting to the server via an HTTP proxy. The proxy will be responsible for looking up the
server’s IP address and connecting to it.
-
-- Type
-Optional[sslyze.server_setting.HttpProxySettings]
-
-- Parameters
+- Parameters:
hostname (str) –
port (int) –
Classes for Starting a Scan
-
-class sslyze.Scanner(per_server_concurrent_connections_limit=None, concurrent_server_scans_limit=None, observers=None)¶
+class sslyze.Scanner(per_server_concurrent_connections_limit=None, concurrent_server_scans_limit=None, observers=None)¶
-- Parameters
+- Parameters:
per_server_concurrent_connections_limit (Optional[int]) –
concurrent_server_scans_limit (Optional[int]) –
Classes for Starting a Scan
-Additional settings: StartTLS, SNI, etc.¶
+Additional settings: StartTLS, SNI, etc.¶
-
-class sslyze.ServerNetworkConfiguration(tls_server_name_indication, tls_opportunistic_encryption=None, tls_client_auth_credentials=None, xmpp_to_hostname=None, network_timeout=5, network_max_retries=3)¶
+class sslyze.ServerNetworkConfiguration(tls_server_name_indication, tls_opportunistic_encryption=None, tls_client_auth_credentials=None, xmpp_to_hostname=None, network_timeout=5, network_max_retries=3)¶
Additional network settings to provide fine-grained control on how to connect to a specific server.
-
-tls_server_name_indication¶
+tls_server_name_indication¶
The hostname to set within the Server Name Indication TLS extension.
-
-- Type
-str
-
-
-tls_wrapped_protocol¶
+tls_wrapped_protocol¶
The protocol wrapped in TLS that the server expects. It allows SSLyze to figure out
how to establish a (Start)TLS connection to the server and what kind of “hello” message
(SMTP, XMPP, etc.) to send to the server after the handshake was completed. If not supplied, standard
@@ -302,56 +275,36 @@
Additional settings: StartTLS, SNI, etc.
-
-tls_client_auth_credentials¶
+tls_client_auth_credentials¶
The client certificate and private key needed to perform mutual authentication
with the server. If not supplied, SSLyze will attempt to connect to the server without performing
client authentication.
-
-- Type
-Optional[sslyze.server_setting.ClientAuthenticationCredentials]
-
-
-xmpp_to_hostname¶
+xmpp_to_hostname¶
The hostname to set within the to attribute of the XMPP stream. If not supplied, the
server’s hostname will be used. Should only be set if the supplied tls_wrapped_protocol is an
XMPP protocol.
-
-- Type
-Optional[str]
-
-
-network_timeout¶
+network_timeout¶
The timeout (in seconds) to be used when attempting to establish a connection to the
server.
-
-- Type
-int
-
-
-network_max_retries¶
+network_max_retries¶
The number of retries SSLyze will perform when attempting to establish a connection
to the server.
-
-- Type
-int
-
-- Parameters
+- Parameters:
tls_server_name_indication (str) –
tls_opportunistic_encryption (Optional[ProtocolWithOpportunisticTlsEnum]) –
Additional settings: StartTLS, SNI, etc.
-
-class sslyze.ProtocolWithOpportunisticTlsEnum(value)¶
+class sslyze.ProtocolWithOpportunisticTlsEnum(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)¶
The list of plaintext protocols supported by SSLyze for opportunistic TLS upgrade (such as STARTTLS).
This allows SSLyze to figure out how to complete an SSL/TLS handshake with the server.
-
-classmethod from_default_port(port)¶
+classmethod from_default_port(port)¶
Given a port number, return the protocol that uses this port number by default.
-- Parameters
+- Parameters:
port (int) –
- Return type
+- Return type:
Optional[ProtocolWithOpportunisticTlsEnum]
@@ -432,57 +385,37 @@ Additional settings: StartTLS, SNI, etc.
-Enabling SSL/TLS client authentication¶
+Enabling SSL/TLS client authentication¶
-
-class sslyze.ClientAuthenticationCredentials(certificate_chain_path, key_path, key_password='', key_type=OpenSslFileTypeEnum.PEM)¶
+class sslyze.ClientAuthenticationCredentials(certificate_chain_path, key_path, key_password='', key_type=OpenSslFileTypeEnum.PEM)¶
Everything needed by a client to perform SSL/TLS client authentication with the server.
-
-certificate_chain_path¶
+certificate_chain_path¶
Path to the file containing the client’s certificate.
-
-- Type
-pathlib.Path
-
-
-key_path¶
+key_path¶
Path to the file containing the client’s private key.
-
-- Type
-pathlib.Path
-
-- Parameters
+- Parameters:
certificate_chain_path (Path) –
key_path (Path) –
Enabling SSL/TLS client authentication
-
-class sslyze.OpenSslFileTypeEnum(value)¶
+class sslyze.OpenSslFileTypeEnum(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)¶
Certificate and private key format constants which map to the SSL_FILETYPE_XXX OpenSSL constants.
@@ -512,98 +445,58 @@ Enabling SSL/TLS client authentication
-Classes for Processing Scan Results¶
+Classes for Processing Scan Results¶
-
-class sslyze.ServerScanResult(uuid, server_location, network_configuration, connectivity_status, connectivity_error_trace, connectivity_result, scan_status, scan_result)¶
+class sslyze.ServerScanResult(uuid, server_location, network_configuration, connectivity_status, connectivity_error_trace, connectivity_result, scan_status, scan_result)¶
The result of scanning a server.
-
-uuid¶
-
-- Type
-uuid.UUID
-
-
+uuid¶
+
-
-server_location¶
-
-- Type
--
-
-
-
+server_location¶
+
-
-network_configuration¶
--
-
+network_configuration¶
+
-
-connectivity_status¶
+connectivity_status¶
Whether SSLyze was able to connect to the server, or not.
-
-
-connectivity_error_trace¶
+connectivity_error_trace¶
The connectivity error; only set if SSLyze was NOT able to connect to the server.
-
-- Type
-Optional[traceback.TracebackException]
-
-
-connectivity_result¶
+connectivity_result¶
The result of connectivity testing; only set if SSLyze was able to connect to the server.
-
-- Type
--
-
-
-
-scan_result¶
+scan_result¶
The result of the scan; only set if SSLyze was able to complete the scan.
-
-- Type
--
-
-
-- Parameters
+- Parameters:
uuid (UUID) –
server_location (ServerNetworkLocation) –
Classes for Processing Scan Results
-
-class sslyze.ServerConnectivityStatusEnum(value)¶
-An enumeration.
-
+class sslyze.ServerConnectivityStatusEnum(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)¶
+
-
-class sslyze.ServerScanStatusEnum(value)¶
-An enumeration.
-
+class sslyze.ServerScanStatusEnum(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)¶
+
-
-class sslyze.ServerTlsProbingResult(highest_tls_version_supported, cipher_suite_supported, client_auth_requirement, supports_ecdh_key_exchange)¶
+class sslyze.ServerTlsProbingResult(highest_tls_version_supported, cipher_suite_supported, client_auth_requirement, supports_ecdh_key_exchange)¶
Additional details about the server, detected via connectivity testing.
-- Parameters
+- Parameters:
highest_tls_version_supported (TlsVersionEnum) –
cipher_suite_supported (str) –
Classes for Processing Scan Results
-
-class sslyze.AllScanCommandsAttempts(certificate_info, ssl_2_0_cipher_suites, ssl_3_0_cipher_suites, tls_1_0_cipher_suites, tls_1_1_cipher_suites, tls_1_2_cipher_suites, tls_1_3_cipher_suites, tls_compression, tls_1_3_early_data, openssl_ccs_injection, tls_fallback_scsv, heartbleed, robot, session_renegotiation, session_resumption, elliptic_curves, http_headers)¶
+class sslyze.AllScanCommandsAttempts(certificate_info, ssl_2_0_cipher_suites, ssl_3_0_cipher_suites, tls_1_0_cipher_suites, tls_1_1_cipher_suites, tls_1_2_cipher_suites, tls_1_3_cipher_suites, tls_compression, tls_1_3_early_data, openssl_ccs_injection, tls_fallback_scsv, heartbleed, robot, session_renegotiation, session_resumption, elliptic_curves, http_headers)¶
The result of every scan command supported by SSLyze.
-- Parameters
+- Parameters:
certificate_info (CertificateInfoScanAttempt) –
ssl_2_0_cipher_suites (CipherSuitesScanAttempt) –
Classes for Processing Scan Results
-
-class sslyze.ScanCommandAttempt(status, error_reason, error_trace, result)¶
+class sslyze.ScanCommandAttempt(status, error_reason, error_trace, result)¶
The result of a single scan command.
-
-status¶
+status¶
Whether this specific scan command was ran successfully.
-
-- Type
-sslyze.scanner.scan_command_attempt.ScanCommandAttemptStatusEnum
-
-
-error_reason¶
+error_reason¶
The reason why the scan command failed; None if the scan command succeeded.
-
-- Type
-Optional[sslyze.scanner.scan_command_attempt.ScanCommandErrorReasonEnum]
-
-
-error_trace¶
+error_trace¶
The exception trace of when the scan command failed; None if the scan command succeeded.
-
-- Type
-Optional[traceback.TracebackException]
-
-
-result¶
+result¶
The actual result of the scan command; None if the scan command failed. The type of this attribute is
the “ScanResult” object corresponding to the scan command.
-
-- Type
-Optional[sslyze.scanner.scan_command_attempt._ScanCommandResultTypeVar]
-
-- Parameters
+- Parameters:
status (ScanCommandAttemptStatusEnum) –
error_reason (Optional[ScanCommandErrorReasonEnum]) –
Classes for Processing Scan Results
-
-class sslyze.ScanCommandErrorReasonEnum(value)¶
-An enumeration.
-
+class sslyze.ScanCommandErrorReasonEnum(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)¶
+-
@@ -816,7 +686,7 @@ Quick search