diff --git a/__init__.py b/__init__.py index 49b3dcd..4d5d2df 100644 --- a/__init__.py +++ b/__init__.py @@ -37,7 +37,7 @@ except ImportError: logger = logging.getLogger(ROOT_LOGGER_NAME).getChild(__name__) __DESCRIPTION__ = """The Module {\\tt %s} is designed to store information in {\\tt json} or {\\tt pickle} files to support them much faster then generating them from the original source file. -For more Information read the documentation.""" % __name__.replace('_', '\_') +For more Information read the documentation.""" % __name__.replace('_', '\\_') """The Module Description""" __INTERPRETER__ = (3, ) """The Tested Interpreter-Versions""" diff --git a/_docs_/.buildinfo b/_docs_/.buildinfo index 94104c7..5de16f6 100644 --- a/_docs_/.buildinfo +++ b/_docs_/.buildinfo @@ -1,4 +1,4 @@ # Sphinx build info version 1 -# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done. -config: 7b165219304607239cf8050fe95b27cb +# This file records the configuration used when building these files. When it is not found, a full rebuild will be done. +config: a38a7ae3b32a9ccb90c479800659a502 tags: 645f666f9bcd5a90fca523b33c5a78b7 diff --git a/_docs_/_downloads/94762bb00bd81e32c327265770b9c2bc/unittest.pdf b/_docs_/_downloads/94762bb00bd81e32c327265770b9c2bc/unittest.pdf new file mode 100644 index 0000000..be88bb7 Binary files /dev/null and b/_docs_/_downloads/94762bb00bd81e32c327265770b9c2bc/unittest.pdf differ diff --git a/_docs_/_downloads/f5f51665bfc67c10ccc039770b738067/unittest.pdf b/_docs_/_downloads/f5f51665bfc67c10ccc039770b738067/unittest.pdf deleted file mode 100644 index d74ec6c..0000000 Binary files a/_docs_/_downloads/f5f51665bfc67c10ccc039770b738067/unittest.pdf and /dev/null differ diff --git a/_docs_/_sources/index.rst.txt b/_docs_/_sources/index.rst.txt index d367f78..f8ff591 100644 --- a/_docs_/_sources/index.rst.txt +++ b/_docs_/_sources/index.rst.txt @@ -1,4 +1,4 @@ -.. socket_protocol documentation master file, created by +.. documentation master file, created by sphinx-quickstart on Fri Jan 1 19:56:01 2021. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. @@ -21,3 +21,4 @@ Indices and tables * :ref:`genindex` * :ref:`modindex` * :ref:`search` + diff --git a/_docs_/_static/basic.css b/_docs_/_static/basic.css index f316efc..4738b2e 100644 --- a/_docs_/_static/basic.css +++ b/_docs_/_static/basic.css @@ -1,12 +1,5 @@ /* - * basic.css - * ~~~~~~~~~ - * * Sphinx stylesheet -- basic theme. - * - * :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS. - * :license: BSD, see LICENSE for details. - * */ /* -- main layout ----------------------------------------------------------- */ @@ -115,15 +108,11 @@ img { /* -- search page ----------------------------------------------------------- */ ul.search { - margin: 10px 0 0 20px; - padding: 0; + margin-top: 10px; } ul.search li { - padding: 5px 0 5px 20px; - background-image: url(file.png); - background-repeat: no-repeat; - background-position: 0 7px; + padding: 5px 0; } ul.search li a { @@ -752,14 +741,6 @@ abbr, acronym { cursor: help; } -.translated { - background-color: rgba(207, 255, 207, 0.2) -} - -.untranslated { - background-color: rgba(255, 207, 207, 0.2) -} - /* -- code displays --------------------------------------------------------- */ pre { diff --git a/_docs_/_static/classic.css b/_docs_/_static/classic.css index 0815acc..6553d2c 100644 --- a/_docs_/_static/classic.css +++ b/_docs_/_static/classic.css @@ -1,12 +1,5 @@ /* - * classic.css_t - * ~~~~~~~~~~~~~ - * * Sphinx stylesheet -- classic theme. - * - * :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS. - * :license: BSD, see LICENSE for details. - * */ @import url("basic.css"); diff --git a/_docs_/_static/copybutton.js b/_docs_/_static/copybutton.js index 7367c4a..de071f4 100644 --- a/_docs_/_static/copybutton.js +++ b/_docs_/_static/copybutton.js @@ -1,65 +1,59 @@ -// ``function*`` denotes a generator in JavaScript, see -// https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function* -function* getHideableCopyButtonElements(rootElement) { - // yield all elements with the "go" (Generic.Output), - // "gp" (Generic.Prompt), or "gt" (Generic.Traceback) CSS class - for (const el of rootElement.querySelectorAll('.go, .gp, .gt')) { - yield el - } - // tracebacks (.gt) contain bare text elements that need to be - // wrapped in a span to hide or show the element - for (let el of rootElement.querySelectorAll('.gt')) { - while ((el = el.nextSibling) && el.nodeType !== Node.DOCUMENT_NODE) { - // stop wrapping text nodes when we hit the next output or - // prompt element - if (el.nodeType === Node.ELEMENT_NODE && el.matches(".gp, .go")) { - break - } - // if the node is a text node with content, wrap it in a - // span element so that we can control visibility - if (el.nodeType === Node.TEXT_NODE && el.textContent.trim()) { - const wrapper = document.createElement("span") - el.after(wrapper) - wrapper.appendChild(el) - el = wrapper - } - yield el +// Extract copyable text from the code block ignoring the +// prompts and output. +function getCopyableText(rootElement) { + rootElement = rootElement.cloneNode(true) + // tracebacks (.gt) contain bare text elements that + // need to be removed + const tracebacks = rootElement.querySelectorAll(".gt") + for (const el of tracebacks) { + while ( + el.nextSibling && + (el.nextSibling.nodeType !== Node.ELEMENT_NODE || + !el.nextSibling.matches(".gp, .go")) + ) { + el.nextSibling.remove() } } + // Remove all elements with the "go" (Generic.Output), + // "gp" (Generic.Prompt), or "gt" (Generic.Traceback) CSS class + const elements = rootElement.querySelectorAll(".gp, .go, .gt") + for (const el of elements) { + el.remove() + } + return rootElement.innerText.trim() } - const loadCopyButton = () => { - /* Add a [>>>] button in the top-right corner of code samples to hide - * the >>> and ... prompts and the output and thus make the code - * copyable. */ - const hide_text = "Hide the prompts and output" - const show_text = "Show the prompts and output" - - const button = document.createElement("span") + const button = document.createElement("button") button.classList.add("copybutton") - button.innerText = ">>>" - button.title = hide_text - button.dataset.hidden = "false" - const buttonClick = event => { + button.type = "button" + button.innerText = _("Copy") + button.title = _("Copy to clipboard") + + const makeOnButtonClick = () => { + let timeout = null // define the behavior of the button when it's clicked - event.preventDefault() - const buttonEl = event.currentTarget - const codeEl = buttonEl.nextElementSibling - if (buttonEl.dataset.hidden === "false") { - // hide the code output - for (const el of getHideableCopyButtonElements(codeEl)) { - el.hidden = true + return async event => { + // check if the clipboard is available + if (!navigator.clipboard || !navigator.clipboard.writeText) { + return; } - buttonEl.title = show_text - buttonEl.dataset.hidden = "true" - } else { - // show the code output - for (const el of getHideableCopyButtonElements(codeEl)) { - el.hidden = false + + clearTimeout(timeout) + const buttonEl = event.currentTarget + const codeEl = buttonEl.nextElementSibling + + try { + await navigator.clipboard.writeText(getCopyableText(codeEl)) + } catch (e) { + console.error(e.message) + return } - buttonEl.title = hide_text - buttonEl.dataset.hidden = "false" + + buttonEl.innerText = _("Copied!") + timeout = setTimeout(() => { + buttonEl.innerText = _("Copy") + }, 1500) } } @@ -78,10 +72,8 @@ const loadCopyButton = () => { // if we find a console prompt (.gp), prepend the (deeply cloned) button const clonedButton = button.cloneNode(true) // the onclick attribute is not cloned, set it on the new element - clonedButton.onclick = buttonClick - if (el.querySelector(".gp") !== null) { - el.prepend(clonedButton) - } + clonedButton.onclick = makeOnButtonClick() + el.prepend(clonedButton) }) } diff --git a/_docs_/_static/doctools.js b/_docs_/_static/doctools.js index 4d67807..0398ebb 100644 --- a/_docs_/_static/doctools.js +++ b/_docs_/_static/doctools.js @@ -1,12 +1,5 @@ /* - * doctools.js - * ~~~~~~~~~~~ - * * Base JavaScript utilities for all Sphinx HTML documentation. - * - * :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS. - * :license: BSD, see LICENSE for details. - * */ "use strict"; diff --git a/_docs_/_static/language_data.js b/_docs_/_static/language_data.js index 367b8ed..c7fe6c6 100644 --- a/_docs_/_static/language_data.js +++ b/_docs_/_static/language_data.js @@ -1,13 +1,6 @@ /* - * language_data.js - * ~~~~~~~~~~~~~~~~ - * * This script contains the language-specific data used by searchtools.js, * namely the list of stopwords, stemmer, scorer and splitter. - * - * :copyright: Copyright 2007-2024 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"]; diff --git a/_docs_/_static/pydoctheme.css b/_docs_/_static/pydoctheme.css index 662d987..4873116 100644 --- a/_docs_/_static/pydoctheme.css +++ b/_docs_/_static/pydoctheme.css @@ -1,5 +1,3 @@ -@import url('classic.css'); - /* Common colours */ :root { --good-color: rgb(41 100 51); @@ -140,6 +138,8 @@ span.pre { } div.sphinxsidebar { + display: flex; + width: min(25vw, 350px); float: none; position: sticky; top: 0; @@ -156,13 +156,17 @@ div.sphinxsidebar h4 { margin-top: 1.5em; } +div.bodywrapper { + margin-left: min(25vw, 350px); +} + div.sphinxsidebarwrapper { - width: 217px; box-sizing: border-box; height: 100%; overflow-x: hidden; overflow-y: auto; - float: left; + float: none; + flex-grow: 1; } div.sphinxsidebarwrapper > h3:first-child { @@ -191,28 +195,15 @@ div.sphinxsidebar input[type='text'] { } #sidebarbutton { - /* Sphinx 4.x and earlier compat */ - height: 100%; - background-color: #CCCCCC; - margin-left: 0; - color: #444444; - font-size: 1.2em; - cursor: pointer; - padding-top: 1px; - float: right; - display: table; - /* after Sphinx 4.x and earlier is dropped, only the below is needed */ + display: flex; + justify-content: center; + align-items: center; width: 12px; + min-width: 12px; border-radius: 0 5px 5px 0; border-left: none; } -#sidebarbutton span { - /* Sphinx 4.x and earlier compat */ - display: table-cell; - vertical-align: middle; -} - #sidebarbutton:hover { background-color: #AAAAAA; } @@ -337,6 +328,10 @@ tt, code, pre { font-size: 96.5%; } +div.body pre { + line-height: 120%; +} + div.body tt, div.body code { border-radius: 3px; @@ -447,17 +442,32 @@ div.genindex-jumpbox a { top: 0; right: 0; font-family: Menlo, Consolas, Monaco, Liberation Mono, Lucida Console, monospace; - padding-left: 0.2em; - padding-right: 0.2em; + font-size: 80%; + padding-left: .5em; + padding-right: .5em; + height: 100%; + max-height: min(100%, 2.4em); border-radius: 0 3px 0 0; - color: #ac9; /* follows div.body pre */ - border-color: #ac9; /* follows div.body pre */ - border-style: solid; /* follows div.body pre */ - border-width: 1px; /* follows div.body pre */ + color: #000; + background-color: #fff; + border: 1px solid #ac9; /* follows div.body pre */ + display: none; } -.copybutton[data-hidden='true'] { - text-decoration: line-through; +.copybutton:hover { + background-color: #eee; +} + +.copybutton:active { + background-color: #ddd; +} + +.highlight:active .copybutton { + display: block; +} + +.highlight:hover .copybutton { + display: block; } @media (max-width: 1023px) { @@ -489,7 +499,7 @@ div.genindex-jumpbox a { margin-inline-end: 0; } /* Remove sidebar and top related bar */ - div.related, .sphinxsidebar { + div.related, div.sphinxsidebar { display: none; } /* Anchorlinks are not hidden by fixed-positioned navbar when scrolled to */ @@ -754,3 +764,10 @@ div.deprecated-removed .versionmodified, div.versionremoved .versionmodified { color: var(--deprecated); } + +/* Hide header when printing */ +@media print { + div.mobile-nav { + display: none; + } +} diff --git a/_docs_/_static/pydoctheme_dark.css b/_docs_/_static/pydoctheme_dark.css index 4509960..582e4dd 100644 --- a/_docs_/_static/pydoctheme_dark.css +++ b/_docs_/_static/pydoctheme_dark.css @@ -176,3 +176,16 @@ img.invert-in-dark-mode { --versionchanged: var(--middle-color); --deprecated: var(--bad-color); } + +.copybutton { + color: #ac9; /* follows div.body pre */ + background-color: #222222; /* follows body */ +} + +.copybutton:hover { + background-color: #434343; +} + +.copybutton:active { + background-color: #656565; +} diff --git a/_docs_/_static/pygments.css b/_docs_/_static/pygments.css index 84ab303..6f8b210 100644 --- a/_docs_/_static/pygments.css +++ b/_docs_/_static/pygments.css @@ -6,9 +6,9 @@ span.linenos.special { color: #000000; background-color: #ffffc0; padding-left: .highlight .hll { background-color: #ffffcc } .highlight { background: #f8f8f8; } .highlight .c { color: #3D7B7B; font-style: italic } /* Comment */ -.highlight .err { border: 1px solid #FF0000 } /* Error */ +.highlight .err { border: 1px solid #F00 } /* Error */ .highlight .k { color: #008000; font-weight: bold } /* Keyword */ -.highlight .o { color: #666666 } /* Operator */ +.highlight .o { color: #666 } /* Operator */ .highlight .ch { color: #3D7B7B; font-style: italic } /* Comment.Hashbang */ .highlight .cm { color: #3D7B7B; font-style: italic } /* Comment.Multiline */ .highlight .cp { color: #9C6500 } /* Comment.Preproc */ @@ -25,34 +25,34 @@ span.linenos.special { color: #000000; background-color: #ffffc0; padding-left: .highlight .gp { color: #000080; font-weight: bold } /* Generic.Prompt */ .highlight .gs { font-weight: bold } /* Generic.Strong */ .highlight .gu { color: #800080; font-weight: bold } /* Generic.Subheading */ -.highlight .gt { color: #0044DD } /* Generic.Traceback */ +.highlight .gt { color: #04D } /* Generic.Traceback */ .highlight .kc { color: #008000; font-weight: bold } /* Keyword.Constant */ .highlight .kd { color: #008000; font-weight: bold } /* Keyword.Declaration */ .highlight .kn { color: #008000; font-weight: bold } /* Keyword.Namespace */ .highlight .kp { color: #008000 } /* Keyword.Pseudo */ .highlight .kr { color: #008000; font-weight: bold } /* Keyword.Reserved */ .highlight .kt { color: #B00040 } /* Keyword.Type */ -.highlight .m { color: #666666 } /* Literal.Number */ +.highlight .m { color: #666 } /* Literal.Number */ .highlight .s { color: #BA2121 } /* Literal.String */ .highlight .na { color: #687822 } /* Name.Attribute */ .highlight .nb { color: #008000 } /* Name.Builtin */ -.highlight .nc { color: #0000FF; font-weight: bold } /* Name.Class */ -.highlight .no { color: #880000 } /* Name.Constant */ -.highlight .nd { color: #AA22FF } /* Name.Decorator */ +.highlight .nc { color: #00F; font-weight: bold } /* Name.Class */ +.highlight .no { color: #800 } /* Name.Constant */ +.highlight .nd { color: #A2F } /* Name.Decorator */ .highlight .ni { color: #717171; font-weight: bold } /* Name.Entity */ .highlight .ne { color: #CB3F38; font-weight: bold } /* Name.Exception */ -.highlight .nf { color: #0000FF } /* Name.Function */ +.highlight .nf { color: #00F } /* Name.Function */ .highlight .nl { color: #767600 } /* Name.Label */ -.highlight .nn { color: #0000FF; font-weight: bold } /* Name.Namespace */ +.highlight .nn { color: #00F; font-weight: bold } /* Name.Namespace */ .highlight .nt { color: #008000; font-weight: bold } /* Name.Tag */ .highlight .nv { color: #19177C } /* Name.Variable */ -.highlight .ow { color: #AA22FF; font-weight: bold } /* Operator.Word */ -.highlight .w { color: #bbbbbb } /* Text.Whitespace */ -.highlight .mb { color: #666666 } /* Literal.Number.Bin */ -.highlight .mf { color: #666666 } /* Literal.Number.Float */ -.highlight .mh { color: #666666 } /* Literal.Number.Hex */ -.highlight .mi { color: #666666 } /* Literal.Number.Integer */ -.highlight .mo { color: #666666 } /* Literal.Number.Oct */ +.highlight .ow { color: #A2F; font-weight: bold } /* Operator.Word */ +.highlight .w { color: #BBB } /* Text.Whitespace */ +.highlight .mb { color: #666 } /* Literal.Number.Bin */ +.highlight .mf { color: #666 } /* Literal.Number.Float */ +.highlight .mh { color: #666 } /* Literal.Number.Hex */ +.highlight .mi { color: #666 } /* Literal.Number.Integer */ +.highlight .mo { color: #666 } /* Literal.Number.Oct */ .highlight .sa { color: #BA2121 } /* Literal.String.Affix */ .highlight .sb { color: #BA2121 } /* Literal.String.Backtick */ .highlight .sc { color: #BA2121 } /* Literal.String.Char */ @@ -67,9 +67,9 @@ span.linenos.special { color: #000000; background-color: #ffffc0; padding-left: .highlight .s1 { color: #BA2121 } /* Literal.String.Single */ .highlight .ss { color: #19177C } /* Literal.String.Symbol */ .highlight .bp { color: #008000 } /* Name.Builtin.Pseudo */ -.highlight .fm { color: #0000FF } /* Name.Function.Magic */ +.highlight .fm { color: #00F } /* Name.Function.Magic */ .highlight .vc { color: #19177C } /* Name.Variable.Class */ .highlight .vg { color: #19177C } /* Name.Variable.Global */ .highlight .vi { color: #19177C } /* Name.Variable.Instance */ .highlight .vm { color: #19177C } /* Name.Variable.Magic */ -.highlight .il { color: #666666 } /* Literal.Number.Integer.Long */ \ No newline at end of file +.highlight .il { color: #666 } /* Literal.Number.Integer.Long */ \ No newline at end of file diff --git a/_docs_/_static/pygments_dark.css b/_docs_/_static/pygments_dark.css index 0e1cdf3..a5da35b 100644 --- a/_docs_/_static/pygments_dark.css +++ b/_docs_/_static/pygments_dark.css @@ -4,82 +4,82 @@ span.linenos { color: inherit; background-color: transparent; padding-left: 5px; td.linenos .special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; } span.linenos.special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; } .highlight .hll { background-color: #49483e } -.highlight { background: #272822; color: #f8f8f2 } +.highlight { background: #272822; color: #F8F8F2 } .highlight .c { color: #959077 } /* Comment */ -.highlight .err { color: #ed007e; background-color: #1e0010 } /* Error */ -.highlight .esc { color: #f8f8f2 } /* Escape */ -.highlight .g { color: #f8f8f2 } /* Generic */ -.highlight .k { color: #66d9ef } /* Keyword */ -.highlight .l { color: #ae81ff } /* Literal */ -.highlight .n { color: #f8f8f2 } /* Name */ -.highlight .o { color: #ff4689 } /* Operator */ -.highlight .x { color: #f8f8f2 } /* Other */ -.highlight .p { color: #f8f8f2 } /* Punctuation */ +.highlight .err { color: #ED007E; background-color: #1E0010 } /* Error */ +.highlight .esc { color: #F8F8F2 } /* Escape */ +.highlight .g { color: #F8F8F2 } /* Generic */ +.highlight .k { color: #66D9EF } /* Keyword */ +.highlight .l { color: #AE81FF } /* Literal */ +.highlight .n { color: #F8F8F2 } /* Name */ +.highlight .o { color: #FF4689 } /* Operator */ +.highlight .x { color: #F8F8F2 } /* Other */ +.highlight .p { color: #F8F8F2 } /* Punctuation */ .highlight .ch { color: #959077 } /* Comment.Hashbang */ .highlight .cm { color: #959077 } /* Comment.Multiline */ .highlight .cp { color: #959077 } /* Comment.Preproc */ .highlight .cpf { color: #959077 } /* Comment.PreprocFile */ .highlight .c1 { color: #959077 } /* Comment.Single */ .highlight .cs { color: #959077 } /* Comment.Special */ -.highlight .gd { color: #ff4689 } /* Generic.Deleted */ -.highlight .ge { color: #f8f8f2; font-style: italic } /* Generic.Emph */ -.highlight .ges { color: #f8f8f2; font-weight: bold; font-style: italic } /* Generic.EmphStrong */ -.highlight .gr { color: #f8f8f2 } /* Generic.Error */ -.highlight .gh { color: #f8f8f2 } /* Generic.Heading */ -.highlight .gi { color: #a6e22e } /* Generic.Inserted */ -.highlight .go { color: #66d9ef } /* Generic.Output */ -.highlight .gp { color: #ff4689; font-weight: bold } /* Generic.Prompt */ -.highlight .gs { color: #f8f8f2; font-weight: bold } /* Generic.Strong */ +.highlight .gd { color: #FF4689 } /* Generic.Deleted */ +.highlight .ge { color: #F8F8F2; font-style: italic } /* Generic.Emph */ +.highlight .ges { color: #F8F8F2; font-weight: bold; font-style: italic } /* Generic.EmphStrong */ +.highlight .gr { color: #F8F8F2 } /* Generic.Error */ +.highlight .gh { color: #F8F8F2 } /* Generic.Heading */ +.highlight .gi { color: #A6E22E } /* Generic.Inserted */ +.highlight .go { color: #66D9EF } /* Generic.Output */ +.highlight .gp { color: #FF4689; font-weight: bold } /* Generic.Prompt */ +.highlight .gs { color: #F8F8F2; font-weight: bold } /* Generic.Strong */ .highlight .gu { color: #959077 } /* Generic.Subheading */ -.highlight .gt { color: #f8f8f2 } /* Generic.Traceback */ -.highlight .kc { color: #66d9ef } /* Keyword.Constant */ -.highlight .kd { color: #66d9ef } /* Keyword.Declaration */ -.highlight .kn { color: #ff4689 } /* Keyword.Namespace */ -.highlight .kp { color: #66d9ef } /* Keyword.Pseudo */ -.highlight .kr { color: #66d9ef } /* Keyword.Reserved */ -.highlight .kt { color: #66d9ef } /* Keyword.Type */ -.highlight .ld { color: #e6db74 } /* Literal.Date */ -.highlight .m { color: #ae81ff } /* Literal.Number */ -.highlight .s { color: #e6db74 } /* Literal.String */ -.highlight .na { color: #a6e22e } /* Name.Attribute */ -.highlight .nb { color: #f8f8f2 } /* Name.Builtin */ -.highlight .nc { color: #a6e22e } /* Name.Class */ -.highlight .no { color: #66d9ef } /* Name.Constant */ -.highlight .nd { color: #a6e22e } /* Name.Decorator */ -.highlight .ni { color: #f8f8f2 } /* Name.Entity */ -.highlight .ne { color: #a6e22e } /* Name.Exception */ -.highlight .nf { color: #a6e22e } /* Name.Function */ -.highlight .nl { color: #f8f8f2 } /* Name.Label */ -.highlight .nn { color: #f8f8f2 } /* Name.Namespace */ -.highlight .nx { color: #a6e22e } /* Name.Other */ -.highlight .py { color: #f8f8f2 } /* Name.Property */ -.highlight .nt { color: #ff4689 } /* Name.Tag */ -.highlight .nv { color: #f8f8f2 } /* Name.Variable */ -.highlight .ow { color: #ff4689 } /* Operator.Word */ -.highlight .pm { color: #f8f8f2 } /* Punctuation.Marker */ -.highlight .w { color: #f8f8f2 } /* Text.Whitespace */ -.highlight .mb { color: #ae81ff } /* Literal.Number.Bin */ -.highlight .mf { color: #ae81ff } /* Literal.Number.Float */ -.highlight .mh { color: #ae81ff } /* Literal.Number.Hex */ -.highlight .mi { color: #ae81ff } /* Literal.Number.Integer */ -.highlight .mo { color: #ae81ff } /* Literal.Number.Oct */ -.highlight .sa { color: #e6db74 } /* Literal.String.Affix */ -.highlight .sb { color: #e6db74 } /* Literal.String.Backtick */ -.highlight .sc { color: #e6db74 } /* Literal.String.Char */ -.highlight .dl { color: #e6db74 } /* Literal.String.Delimiter */ -.highlight .sd { color: #e6db74 } /* Literal.String.Doc */ -.highlight .s2 { color: #e6db74 } /* Literal.String.Double */ -.highlight .se { color: #ae81ff } /* Literal.String.Escape */ -.highlight .sh { color: #e6db74 } /* Literal.String.Heredoc */ -.highlight .si { color: #e6db74 } /* Literal.String.Interpol */ -.highlight .sx { color: #e6db74 } /* Literal.String.Other */ -.highlight .sr { color: #e6db74 } /* Literal.String.Regex */ -.highlight .s1 { color: #e6db74 } /* Literal.String.Single */ -.highlight .ss { color: #e6db74 } /* Literal.String.Symbol */ -.highlight .bp { color: #f8f8f2 } /* Name.Builtin.Pseudo */ -.highlight .fm { color: #a6e22e } /* Name.Function.Magic */ -.highlight .vc { color: #f8f8f2 } /* Name.Variable.Class */ -.highlight .vg { color: #f8f8f2 } /* Name.Variable.Global */ -.highlight .vi { color: #f8f8f2 } /* Name.Variable.Instance */ -.highlight .vm { color: #f8f8f2 } /* Name.Variable.Magic */ -.highlight .il { color: #ae81ff } /* Literal.Number.Integer.Long */ \ No newline at end of file +.highlight .gt { color: #F8F8F2 } /* Generic.Traceback */ +.highlight .kc { color: #66D9EF } /* Keyword.Constant */ +.highlight .kd { color: #66D9EF } /* Keyword.Declaration */ +.highlight .kn { color: #FF4689 } /* Keyword.Namespace */ +.highlight .kp { color: #66D9EF } /* Keyword.Pseudo */ +.highlight .kr { color: #66D9EF } /* Keyword.Reserved */ +.highlight .kt { color: #66D9EF } /* Keyword.Type */ +.highlight .ld { color: #E6DB74 } /* Literal.Date */ +.highlight .m { color: #AE81FF } /* Literal.Number */ +.highlight .s { color: #E6DB74 } /* Literal.String */ +.highlight .na { color: #A6E22E } /* Name.Attribute */ +.highlight .nb { color: #F8F8F2 } /* Name.Builtin */ +.highlight .nc { color: #A6E22E } /* Name.Class */ +.highlight .no { color: #66D9EF } /* Name.Constant */ +.highlight .nd { color: #A6E22E } /* Name.Decorator */ +.highlight .ni { color: #F8F8F2 } /* Name.Entity */ +.highlight .ne { color: #A6E22E } /* Name.Exception */ +.highlight .nf { color: #A6E22E } /* Name.Function */ +.highlight .nl { color: #F8F8F2 } /* Name.Label */ +.highlight .nn { color: #F8F8F2 } /* Name.Namespace */ +.highlight .nx { color: #A6E22E } /* Name.Other */ +.highlight .py { color: #F8F8F2 } /* Name.Property */ +.highlight .nt { color: #FF4689 } /* Name.Tag */ +.highlight .nv { color: #F8F8F2 } /* Name.Variable */ +.highlight .ow { color: #FF4689 } /* Operator.Word */ +.highlight .pm { color: #F8F8F2 } /* Punctuation.Marker */ +.highlight .w { color: #F8F8F2 } /* Text.Whitespace */ +.highlight .mb { color: #AE81FF } /* Literal.Number.Bin */ +.highlight .mf { color: #AE81FF } /* Literal.Number.Float */ +.highlight .mh { color: #AE81FF } /* Literal.Number.Hex */ +.highlight .mi { color: #AE81FF } /* Literal.Number.Integer */ +.highlight .mo { color: #AE81FF } /* Literal.Number.Oct */ +.highlight .sa { color: #E6DB74 } /* Literal.String.Affix */ +.highlight .sb { color: #E6DB74 } /* Literal.String.Backtick */ +.highlight .sc { color: #E6DB74 } /* Literal.String.Char */ +.highlight .dl { color: #E6DB74 } /* Literal.String.Delimiter */ +.highlight .sd { color: #E6DB74 } /* Literal.String.Doc */ +.highlight .s2 { color: #E6DB74 } /* Literal.String.Double */ +.highlight .se { color: #AE81FF } /* Literal.String.Escape */ +.highlight .sh { color: #E6DB74 } /* Literal.String.Heredoc */ +.highlight .si { color: #E6DB74 } /* Literal.String.Interpol */ +.highlight .sx { color: #E6DB74 } /* Literal.String.Other */ +.highlight .sr { color: #E6DB74 } /* Literal.String.Regex */ +.highlight .s1 { color: #E6DB74 } /* Literal.String.Single */ +.highlight .ss { color: #E6DB74 } /* Literal.String.Symbol */ +.highlight .bp { color: #F8F8F2 } /* Name.Builtin.Pseudo */ +.highlight .fm { color: #A6E22E } /* Name.Function.Magic */ +.highlight .vc { color: #F8F8F2 } /* Name.Variable.Class */ +.highlight .vg { color: #F8F8F2 } /* Name.Variable.Global */ +.highlight .vi { color: #F8F8F2 } /* Name.Variable.Instance */ +.highlight .vm { color: #F8F8F2 } /* Name.Variable.Magic */ +.highlight .il { color: #AE81FF } /* Literal.Number.Integer.Long */ \ No newline at end of file diff --git a/_docs_/_static/searchtools.js b/_docs_/_static/searchtools.js index b08d58c..91f4be5 100644 --- a/_docs_/_static/searchtools.js +++ b/_docs_/_static/searchtools.js @@ -1,12 +1,5 @@ /* - * searchtools.js - * ~~~~~~~~~~~~~~~~ - * * Sphinx JavaScript utilities for the full-text search. - * - * :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS. - * :license: BSD, see LICENSE for details. - * */ "use strict"; @@ -20,7 +13,7 @@ if (typeof Scorer === "undefined") { // and returns the new score. /* score: result => { - const [docname, title, anchor, descr, score, filename] = result + const [docname, title, anchor, descr, score, filename, kind] = result return score }, */ @@ -47,6 +40,14 @@ if (typeof Scorer === "undefined") { }; } +// Global search result kind enum, used by themes to style search results. +class SearchResultKind { + static get index() { return "index"; } + static get object() { return "object"; } + static get text() { return "text"; } + static get title() { return "title"; } +} + const _removeChildren = (element) => { while (element && element.lastChild) element.removeChild(element.lastChild); }; @@ -64,9 +65,13 @@ const _displayItem = (item, searchTerms, highlightTerms) => { const showSearchSummary = DOCUMENTATION_OPTIONS.SHOW_SEARCH_SUMMARY; const contentRoot = document.documentElement.dataset.content_root; - const [docName, title, anchor, descr, score, _filename] = item; + const [docName, title, anchor, descr, score, _filename, kind] = item; let listItem = document.createElement("li"); + // Add a class representing the item's type: + // can be used by a theme's CSS selector for styling + // See SearchResultKind for the class names. + listItem.classList.add(`kind-${kind}`); let requestUrl; let linkUrl; if (docBuilder === "dirhtml") { @@ -115,8 +120,10 @@ const _finishSearch = (resultCount) => { "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." + Search.status.innerText = Documentation.ngettext( + "Search finished, found one page matching the search query.", + "Search finished, found ${resultCount} pages matching the search query.", + resultCount, ).replace('${resultCount}', resultCount); }; const _displayNextItem = ( @@ -138,7 +145,7 @@ const _displayNextItem = ( else _finishSearch(resultCount); }; // Helper function used by query() to order search results. -// Each input is an array of [docname, title, anchor, descr, score, filename]. +// Each input is an array of [docname, title, anchor, descr, score, filename, kind]. // Order the results by score (in opposite order of appearance, since the // `_displayNextItem` function uses pop() to retrieve items) and then alphabetically. const _orderResultsByScoreThenName = (a, b) => { @@ -248,6 +255,7 @@ const Search = { searchSummary.classList.add("search-summary"); searchSummary.innerText = ""; const searchList = document.createElement("ul"); + searchList.setAttribute("role", "list"); searchList.classList.add("search"); const out = document.getElementById("search-results"); @@ -318,7 +326,7 @@ const Search = { const indexEntries = Search._index.indexentries; // Collect multiple result groups to be sorted separately and then ordered. - // Each is an array of [docname, title, anchor, descr, score, filename]. + // Each is an array of [docname, title, anchor, descr, score, filename, kind]. const normalResults = []; const nonMainIndexResults = []; @@ -337,6 +345,7 @@ const Search = { null, score + boost, filenames[file], + SearchResultKind.title, ]); } } @@ -354,6 +363,7 @@ const Search = { null, score, filenames[file], + SearchResultKind.index, ]; if (isMain) { normalResults.push(result); @@ -475,6 +485,7 @@ const Search = { descr, score, filenames[match[0]], + SearchResultKind.object, ]); }; Object.keys(objects).forEach((prefix) => @@ -502,9 +513,11 @@ const Search = { // perform the search on the required terms searchTerms.forEach((word) => { const files = []; + // find documents, if any, containing the query word in their text/title term indices + // use Object.hasOwnProperty to avoid mismatching against prototype properties const arr = [ - { files: terms[word], score: Scorer.term }, - { files: titleTerms[word], score: Scorer.title }, + { files: terms.hasOwnProperty(word) ? terms[word] : undefined, score: Scorer.term }, + { files: titleTerms.hasOwnProperty(word) ? titleTerms[word] : undefined, score: Scorer.title }, ]; // add support for partial matches if (word.length > 2) { @@ -536,8 +549,9 @@ const Search = { // set score for the word in each file recordFiles.forEach((file) => { - if (!scoreMap.has(file)) scoreMap.set(file, {}); - scoreMap.get(file)[word] = record.score; + if (!scoreMap.has(file)) scoreMap.set(file, new Map()); + const fileScores = scoreMap.get(file); + fileScores.set(word, record.score); }); }); @@ -576,7 +590,7 @@ const Search = { break; // select one (max) score for the file. - const score = Math.max(...wordList.map((w) => scoreMap.get(file)[w])); + const score = Math.max(...wordList.map((w) => scoreMap.get(file).get(w))); // add result to the result list results.push([ docNames[file], @@ -585,6 +599,7 @@ const Search = { null, score, filenames[file], + SearchResultKind.text, ]); } return results; diff --git a/_docs_/_static/sidebar.js b/_docs_/_static/sidebar.js index 4fa25e4..ac7b39e 100644 --- a/_docs_/_static/sidebar.js +++ b/_docs_/_static/sidebar.js @@ -1,15 +1,8 @@ /* - * sidebar.js - * ~~~~~~~~~~ - * - * This file is functionally identical to "sidebar.js" in Sphinx 5.0. - * When support for Sphinx 4 and earlier is dropped from the theme, - * this file can be removed. - * * This script makes the Sphinx sidebar collapsible. * * .sphinxsidebar contains .sphinxsidebarwrapper. This script adds - * in .sphinxsidebar, after .sphinxsidebarwrapper, the #sidebarbutton + * in .sphixsidebar, after .sphinxsidebarwrapper, the #sidebarbutton * used to collapse and expand the sidebar. * * When the sidebar is collapsed the .sphinxsidebarwrapper is hidden @@ -20,34 +13,31 @@ * Once the browser is closed the cookie is deleted and the position * reset to the default (expanded). * - * :copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS. - * :license: BSD, see LICENSE for details. - * */ const initialiseSidebar = () => { + + + + // global elements used by the functions. const bodyWrapper = document.getElementsByClassName("bodywrapper")[0] const sidebar = document.getElementsByClassName("sphinxsidebar")[0] - const sidebarWrapper = document.getElementsByClassName("sphinxsidebarwrapper")[0] - - // exit early if the document has no sidebar for some reason - if (typeof sidebar === "undefined") { - return - } - - - + const sidebarWrapper = document.getElementsByClassName('sphinxsidebarwrapper')[0] const sidebarButton = document.getElementById("sidebarbutton") const sidebarArrow = sidebarButton.querySelector('span') + // for some reason, the document has no sidebar; do not run into errors + if (typeof sidebar === "undefined") return; + + const flipArrow = element => element.innerText = (element.innerText === "»") ? "«" : "»" const collapse_sidebar = () => { - bodyWrapper.style.marginLeft = ".8em" + bodyWrapper.style.marginLeft = ".8em"; sidebar.style.width = ".8em" sidebarWrapper.style.display = "none" - sidebarArrow.innerText = "»" - sidebarButton.title = _("Expand sidebar") + flipArrow(sidebarArrow) + sidebarButton.title = _('Expand sidebar') window.localStorage.setItem("sidebar", "collapsed") } @@ -55,8 +45,8 @@ const initialiseSidebar = () => { bodyWrapper.style.marginLeft = "" sidebar.style.removeProperty("width") sidebarWrapper.style.display = "" - sidebarArrow.innerText = "«" - sidebarButton.title = _("Collapse sidebar") + flipArrow(sidebarArrow) + sidebarButton.title = _('Collapse sidebar') window.localStorage.setItem("sidebar", "expanded") } @@ -64,18 +54,11 @@ const initialiseSidebar = () => { (sidebarWrapper.style.display === "none") ? expand_sidebar() : collapse_sidebar() }) - const sidebar_state = window.localStorage.getItem("sidebar") - if (sidebar_state === "collapsed") { - collapse_sidebar() - } - else if (sidebar_state === "expanded") { - expand_sidebar() - } + if (!window.localStorage.getItem("sidebar")) return + const value = window.localStorage.getItem("sidebar") + if (value === "collapsed") collapse_sidebar(); + else if (value === "expanded") expand_sidebar(); } -if (document.readyState !== "loading") { - initialiseSidebar() -} -else { - document.addEventListener("DOMContentLoaded", initialiseSidebar) -} \ No newline at end of file +if (document.readyState !== "loading") initialiseSidebar() +else document.addEventListener("DOMContentLoaded", initialiseSidebar) \ No newline at end of file diff --git a/_docs_/genindex.html b/_docs_/genindex.html index 5911a32..84861a9 100644 --- a/_docs_/genindex.html +++ b/_docs_/genindex.html @@ -6,17 +6,18 @@ Index — caching documentation - - - + + + + - + - + @@ -25,22 +26,22 @@
+ aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu"> @@ -79,7 +80,7 @@
  • modules |
  • -
  • Python logo
  • +
  • Python logo
  • Python »
  • @@ -96,8 +97,8 @@ | @@ -225,7 +226,7 @@
  • modules |
  • -
  • Python logo
  • +
  • Python logo
  • Python »
  • @@ -242,8 +243,8 @@ | @@ -263,24 +264,24 @@ diff --git a/_docs_/index.html b/_docs_/index.html index 2d3afb2..792d149 100644 --- a/_docs_/index.html +++ b/_docs_/index.html @@ -7,17 +7,18 @@ Welcome to cachings’s documentation! — caching documentation - - - + + + + - + - + @@ -26,22 +27,22 @@
    + aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu"> @@ -105,7 +106,7 @@
  • modules |
  • -
  • Python logo
  • +
  • Python logo
  • Python »
  • @@ -122,8 +123,8 @@ | @@ -165,12 +166,12 @@

    Unittest:

    -

    See also the unittest documentation.

    +

    See also the unittest documentation.

    -class caching.property_cache_json(source_instance, cache_filename, load_all_on_init=False, callback_on_data_storage=None, max_age=None, store_on_get=True)
    +class caching.property_cache_json(source_instance, cache_filename, load_all_on_init=False, callback_on_data_storage=None, max_age=None, store_on_get=True, return_source_on_none=False)

    See also parent property_cache_pickle for detailed information.

    Important

    @@ -184,13 +185,13 @@
    #!/usr/bin/env python
     # -*- coding: UTF-8 -*-
     
    -import caching
    -import logging
    -import sys
    -import time
    +import caching
    +import logging
    +import sys
    +import time
     
     
    -class test_slow_data(object):
    +class test_slow_data(object):
         DATA_VERSION = 0.1
         KEY_ONE = '1'
         KEY_TWO = '2'
    @@ -199,52 +200,52 @@
         KEY_FIVE = 'five'
         KEYS = [KEY_ONE, KEY_TWO, KEY_THREE, KEY_FOUR, KEY_FIVE]
     
    -    def data_version(self):
    +    def data_version(self):
             return self.DATA_VERSION
     
    -    def get(self, key, default=None):
    +    def get(self, key, default=None):
             try:
                 return getattr(self, f'__{key}__')()
             except AttributeError:
                 return default
     
    -    def keys(self):
    +    def keys(self):
             return self.KEYS
     
    -    def uid(self):
    +    def uid(self):
             return None
     
    -    def print_n_sleep(self, k):
    +    def print_n_sleep(self, k):
             sys.stdout.write('slow get executed for %s\n' % k)
             time.sleep(3)
     
    -    def __1__(self):
    +    def __1__(self):
             self.print_n_sleep("__1__")
             return 'one'
     
    -    def __2__(self):
    +    def __2__(self):
             self.print_n_sleep("__2__")
             return 'two'
     
    -    def __three__(self):
    +    def __three__(self):
             self.print_n_sleep("__three__")
             return 'three'
     
    -    def __four__(self):
    +    def __four__(self):
             self.print_n_sleep("__four__")
             return 'four'
     
    -    def __five__(self):
    +    def __five__(self):
             self.print_n_sleep("__five__")
             return 'five'
     
    -class test_slow_data_cached(test_slow_data):
    -    def __init__(self, *args, **kwargs) -> None:
    +class test_slow_data_cached(test_slow_data):
    +    def __init__(self, *args, **kwargs) -> None:
             super().__init__(*args, **kwargs)
             self._cache = caching.property_cache_json(test_slow_data(), 'cache.json')
             self._cache.add_source_get_keys(self.KEY_THREE)
     
    -    def get(self, key, default=None):
    +    def get(self, key, default=None):
             return self._cache.get(key, default)
     
     
    @@ -268,30 +269,31 @@
     

    Will result on the first execution to the following output (with a long execution time):

    Testing property_cache (json):
     --------------------------------
    -2024-09-22 11:01:08,845:    DEBUG - caching - Cache file does not exists (yet).
    -2024-09-22 11:01:08,846:    DEBUG - caching - cache-file stored (cache.json)
    -2024-09-22 11:01:08,846:    DEBUG - caching - Loading property for key='1' from source instance
    +2025-08-14 14:59:14,904:    DEBUG - caching - Cache file does not exists (yet).
    +2025-08-14 14:59:14,904:    DEBUG - caching - Loading property for key='1' from source instance
     slow get executed for __1__
    -2024-09-22 11:01:11,847:    DEBUG - caching - Adding key=1, value=one with timestamp=1726995671 to chache
    -2024-09-22 11:01:11,847:    DEBUG - caching - cache-file stored (cache.json)
    +2025-08-14 14:59:17,905:    DEBUG - caching - Adding key=1, value=one with timestamp=1755176357 to chache
    +2025-08-14 14:59:17,906:    DEBUG - caching - cache-file stored (cache.json)
     one
    -2024-09-22 11:01:11,848:    DEBUG - caching - Loading property for key='2' from source instance
    +2025-08-14 14:59:17,906:    DEBUG - caching - Loading property for key='2' from source instance
     slow get executed for __2__
    -2024-09-22 11:01:14,849:    DEBUG - caching - Adding key=2, value=two with timestamp=1726995674 to chache
    -2024-09-22 11:01:14,850:    DEBUG - caching - cache-file stored (cache.json)
    +2025-08-14 14:59:20,907:    DEBUG - caching - Adding key=2, value=two with timestamp=1755176360 to chache
    +2025-08-14 14:59:20,907:    DEBUG - caching - cache-file stored (cache.json)
     two
    -2024-09-22 11:01:14,850:    DEBUG - caching - Key 'three' is excluded by .add_source_get_keys(). Uncached data will be returned.
    +2025-08-14 14:59:20,908:    DEBUG - caching - Loading property for key='three' from source instance
     slow get executed for __three__
    +2025-08-14 14:59:23,908:    DEBUG - caching - Adding key=three, value=three with timestamp=1755176363 to chache
    +2025-08-14 14:59:23,909:    DEBUG - caching - cache-file stored (cache.json)
     three
    -2024-09-22 11:01:17,851:    DEBUG - caching - Loading property for key='four' from source instance
    +2025-08-14 14:59:23,909:    DEBUG - caching - Loading property for key='four' from source instance
     slow get executed for __four__
    -2024-09-22 11:01:20,851:    DEBUG - caching - Adding key=four, value=four with timestamp=1726995680 to chache
    -2024-09-22 11:01:20,853:    DEBUG - caching - cache-file stored (cache.json)
    +2025-08-14 14:59:26,910:    DEBUG - caching - Adding key=four, value=four with timestamp=1755176366 to chache
    +2025-08-14 14:59:26,911:    DEBUG - caching - cache-file stored (cache.json)
     four
    -2024-09-22 11:01:20,854:    DEBUG - caching - Loading property for key='five' from source instance
    +2025-08-14 14:59:26,911:    DEBUG - caching - Loading property for key='five' from source instance
     slow get executed for __five__
    -2024-09-22 11:01:23,854:    DEBUG - caching - Adding key=five, value=five with timestamp=1726995683 to chache
    -2024-09-22 11:01:23,855:    DEBUG - caching - cache-file stored (cache.json)
    +2025-08-14 14:59:29,911:    DEBUG - caching - Adding key=five, value=five with timestamp=1755176369 to chache
    +2025-08-14 14:59:29,912:    DEBUG - caching - cache-file stored (cache.json)
     five
     --------------------------------
     The execution time was 15.0s
    @@ -300,17 +302,19 @@
     

    With every following execution the time cosumption my by much smaller:

    Testing property_cache (json):
     --------------------------------
    -2024-09-22 11:01:23,983:    DEBUG - caching - Loading properties from cache (cache.json)
    -2024-09-22 11:01:23,984:    DEBUG - caching - Providing property for '1' from cache
    +2025-08-14 14:59:30,025:    DEBUG - caching - Loading properties from cache (cache.json)
    +2025-08-14 14:59:30,025:    DEBUG - caching - Providing property for '1' from cache
     one
    -2024-09-22 11:01:23,984:    DEBUG - caching - Providing property for '2' from cache
    +2025-08-14 14:59:30,025:    DEBUG - caching - Providing property for '2' from cache
     two
    -2024-09-22 11:01:23,984:    DEBUG - caching - Key 'three' is excluded by .add_source_get_keys(). Uncached data will be returned.
    +2025-08-14 14:59:30,025:    DEBUG - caching - Loading property for key='three' from source instance
     slow get executed for __three__
    +2025-08-14 14:59:33,027:    DEBUG - caching - Adding key=three, value=three with timestamp=1755176373 to chache
    +2025-08-14 14:59:33,027:    DEBUG - caching - cache-file stored (cache.json)
     three
    -2024-09-22 11:01:26,984:    DEBUG - caching - Providing property for 'four' from cache
    +2025-08-14 14:59:33,028:    DEBUG - caching - Providing property for 'four' from cache
     four
    -2024-09-22 11:01:26,985:    DEBUG - caching - Providing property for 'five' from cache
    +2025-08-14 14:59:33,028:    DEBUG - caching - Providing property for 'five' from cache
     five
     --------------------------------
     The execution time was 3.0s
    @@ -320,7 +324,7 @@
     
     
    -class caching.property_cache_pickle(source_instance, cache_filename, load_all_on_init=False, callback_on_data_storage=None, max_age=None, store_on_get=True)
    +class caching.property_cache_pickle(source_instance, cache_filename, load_all_on_init=False, callback_on_data_storage=None, max_age=None, store_on_get=True, return_source_on_none=False)

    This class caches the data from a given source_instance. It takes the data from the cache instead of generating the data from the source_instance, if the conditions for the cache usage are given.

    @@ -359,13 +363,13 @@ if the conditions for the cache usage are given.

    #!/usr/bin/env python
     # -*- coding: UTF-8 -*-
     
    -import caching
    -import logging
    -import sys
    -import time
    +import caching
    +import logging
    +import sys
    +import time
     
     
    -class test_slow_data(object):
    +class test_slow_data(object):
         DATA_VERSION = 0.1
         KEY_ONE = '1'
         KEY_TWO = '2'
    @@ -374,52 +378,52 @@ if the conditions for the cache usage are given.

    KEY_FIVE = 'five' KEYS = [KEY_ONE, KEY_TWO, KEY_THREE, KEY_FOUR, KEY_FIVE] - def data_version(self): + def data_version(self): return self.DATA_VERSION - def get(self, key, default=None): + def get(self, key, default=None): try: return getattr(self, f'__{key}__')() except AttributeError: return default - def keys(self): + def keys(self): return self.KEYS - def uid(self): + def uid(self): return None - def print_n_sleep(self, k): + def print_n_sleep(self, k): sys.stdout.write('slow get executed for %s\n' % k) time.sleep(3) - def __1__(self): + def __1__(self): self.print_n_sleep("__1__") return 'one' - def __2__(self): + def __2__(self): self.print_n_sleep("__2__") return 'two' - def __three__(self): + def __three__(self): self.print_n_sleep("__three__") return 'three' - def __four__(self): + def __four__(self): self.print_n_sleep("__four__") return 'four' - def __five__(self): + def __five__(self): self.print_n_sleep("__five__") return 'five' -class test_slow_data_cached(test_slow_data): - def __init__(self, *args, **kwargs) -> None: +class test_slow_data_cached(test_slow_data): + def __init__(self, *args, **kwargs) -> None: super().__init__(*args, **kwargs) self._cache = caching.property_cache_json(test_slow_data(), 'cache.pickle') self._cache.add_source_get_keys(self.KEY_THREE) - def get(self, key, default=None): + def get(self, key, default=None): return self._cache.get(key, default) @@ -442,30 +446,31 @@ if the conditions for the cache usage are given.

    Will result on the first execution to the following output (with a long execution time):

    Testing property_cache (pickle):
     --------------------------------
    -2024-09-22 11:01:27,126:    DEBUG - caching - Cache file does not exists (yet).
    -2024-09-22 11:01:27,127:    DEBUG - caching - cache-file stored (cache.pickle)
    -2024-09-22 11:01:27,127:    DEBUG - caching - Loading property for key='1' from source instance
    +2025-08-14 14:59:33,131:    DEBUG - caching - Cache file does not exists (yet).
    +2025-08-14 14:59:33,131:    DEBUG - caching - Loading property for key='1' from source instance
     slow get executed for __1__
    -2024-09-22 11:01:30,128:    DEBUG - caching - Adding key=1, value=one with timestamp=1726995690 to chache
    -2024-09-22 11:01:30,129:    DEBUG - caching - cache-file stored (cache.pickle)
    +2025-08-14 14:59:36,133:    DEBUG - caching - Adding key=1, value=one with timestamp=1755176376 to chache
    +2025-08-14 14:59:36,133:    DEBUG - caching - cache-file stored (cache.pickle)
     one
    -2024-09-22 11:01:30,129:    DEBUG - caching - Loading property for key='2' from source instance
    +2025-08-14 14:59:36,134:    DEBUG - caching - Loading property for key='2' from source instance
     slow get executed for __2__
    -2024-09-22 11:01:33,130:    DEBUG - caching - Adding key=2, value=two with timestamp=1726995693 to chache
    -2024-09-22 11:01:33,131:    DEBUG - caching - cache-file stored (cache.pickle)
    +2025-08-14 14:59:39,134:    DEBUG - caching - Adding key=2, value=two with timestamp=1755176379 to chache
    +2025-08-14 14:59:39,135:    DEBUG - caching - cache-file stored (cache.pickle)
     two
    -2024-09-22 11:01:33,132:    DEBUG - caching - Key 'three' is excluded by .add_source_get_keys(). Uncached data will be returned.
    +2025-08-14 14:59:39,135:    DEBUG - caching - Loading property for key='three' from source instance
     slow get executed for __three__
    +2025-08-14 14:59:42,136:    DEBUG - caching - Adding key=three, value=three with timestamp=1755176382 to chache
    +2025-08-14 14:59:42,136:    DEBUG - caching - cache-file stored (cache.pickle)
     three
    -2024-09-22 11:01:36,133:    DEBUG - caching - Loading property for key='four' from source instance
    +2025-08-14 14:59:42,136:    DEBUG - caching - Loading property for key='four' from source instance
     slow get executed for __four__
    -2024-09-22 11:01:39,134:    DEBUG - caching - Adding key=four, value=four with timestamp=1726995699 to chache
    -2024-09-22 11:01:39,135:    DEBUG - caching - cache-file stored (cache.pickle)
    +2025-08-14 14:59:45,137:    DEBUG - caching - Adding key=four, value=four with timestamp=1755176385 to chache
    +2025-08-14 14:59:45,138:    DEBUG - caching - cache-file stored (cache.pickle)
     four
    -2024-09-22 11:01:39,136:    DEBUG - caching - Loading property for key='five' from source instance
    +2025-08-14 14:59:45,138:    DEBUG - caching - Loading property for key='five' from source instance
     slow get executed for __five__
    -2024-09-22 11:01:42,136:    DEBUG - caching - Adding key=five, value=five with timestamp=1726995702 to chache
    -2024-09-22 11:01:42,137:    DEBUG - caching - cache-file stored (cache.pickle)
    +2025-08-14 14:59:48,138:    DEBUG - caching - Adding key=five, value=five with timestamp=1755176388 to chache
    +2025-08-14 14:59:48,139:    DEBUG - caching - cache-file stored (cache.pickle)
     five
     --------------------------------
     The execution time was 15.0s
    @@ -474,17 +479,19 @@ if the conditions for the cache usage are given.

    With every following execution the time cosumption my by much smaller:

    Testing property_cache (pickle):
     --------------------------------
    -2024-09-22 11:01:42,204:    DEBUG - caching - Loading properties from cache (cache.pickle)
    -2024-09-22 11:01:42,204:    DEBUG - caching - Providing property for '1' from cache
    +2025-08-14 14:59:48,211:    DEBUG - caching - Loading properties from cache (cache.pickle)
    +2025-08-14 14:59:48,212:    DEBUG - caching - Providing property for '1' from cache
     one
    -2024-09-22 11:01:42,205:    DEBUG - caching - Providing property for '2' from cache
    +2025-08-14 14:59:48,212:    DEBUG - caching - Providing property for '2' from cache
     two
    -2024-09-22 11:01:42,205:    DEBUG - caching - Key 'three' is excluded by .add_source_get_keys(). Uncached data will be returned.
    +2025-08-14 14:59:48,212:    DEBUG - caching - Loading property for key='three' from source instance
     slow get executed for __three__
    +2025-08-14 14:59:51,212:    DEBUG - caching - Adding key=three, value=three with timestamp=1755176391 to chache
    +2025-08-14 14:59:51,213:    DEBUG - caching - cache-file stored (cache.pickle)
     three
    -2024-09-22 11:01:45,205:    DEBUG - caching - Providing property for 'four' from cache
    +2025-08-14 14:59:51,213:    DEBUG - caching - Providing property for 'four' from cache
     four
    -2024-09-22 11:01:45,206:    DEBUG - caching - Providing property for 'five' from cache
    +2025-08-14 14:59:51,214:    DEBUG - caching - Providing property for 'five' from cache
     five
     --------------------------------
     The execution time was 3.0s
    @@ -603,7 +610,7 @@ and the resulting cache will be stored to the given file.

  • modules |
  • -
  • Python logo
  • +
  • Python logo
  • Python »
  • @@ -620,8 +627,8 @@ and the resulting cache will be stored to the given file.

    | @@ -641,24 +648,24 @@ and the resulting cache will be stored to the given file.

    diff --git a/_docs_/objects.inv b/_docs_/objects.inv index d94f04f..e342547 100644 Binary files a/_docs_/objects.inv and b/_docs_/objects.inv differ diff --git a/_docs_/py-modindex.html b/_docs_/py-modindex.html index 1c29cd2..301a28f 100644 --- a/_docs_/py-modindex.html +++ b/_docs_/py-modindex.html @@ -6,18 +6,19 @@ Python Module Index — caching documentation - - - + + + + - + - + @@ -32,22 +33,22 @@
    + aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu"> @@ -86,7 +87,7 @@
  • modules |
  • -
  • Python logo
  • +
  • Python logo
  • Python »
  • @@ -103,8 +104,8 @@ | @@ -175,7 +176,7 @@
  • modules |
  • -
  • Python logo
  • +
  • Python logo
  • Python »
  • @@ -192,8 +193,8 @@ | @@ -213,24 +214,24 @@ diff --git a/_docs_/search.html b/_docs_/search.html index 25bbf36..2bd56dc 100644 --- a/_docs_/search.html +++ b/_docs_/search.html @@ -6,13 +6,14 @@ Search — caching documentation - - - + + + + - + @@ -22,7 +23,7 @@ - + @@ -32,14 +33,14 @@
    + aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu">