better docs

Dockerfile

@@ -1,11 +1,10 @@
 # syntax=docker/dockerfile:1
 FROM python:3.10
-WORKDIR /app/
 RUN apt-get update
-RUN apt-get install -y python3-sphinx node.js
-RUN apt-get install -y npm
+RUN apt-get install -y python3-sphinx node.js npm
 RUN npm install -g http-server
 RUN pip install pydata-sphinx-theme
+WORKDIR /app/
 RUN pip install git+https://gitea.parrrate.ru/PTV/rainbowadn.git@e9fba7b064902ceedee0dd5578cb47030665a6aa
 
 RUN mkdir /app/docs/

docs/make.bat

@@ -1,35 +0,0 @@
-@ECHO OFF
-
-pushd %~dp0
-
-REM Command file for Sphinx documentation
-
-if "%SPHINXBUILD%" == "" (
-	set SPHINXBUILD=sphinx-build
-)
-set SOURCEDIR=source
-set BUILDDIR=build
-
-%SPHINXBUILD% >NUL 2>NUL
-if errorlevel 9009 (
-	echo.
-	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
-	echo.installed, then set the SPHINXBUILD environment variable to point
-	echo.to the full path of the 'sphinx-build' executable. Alternatively you
-	echo.may add the Sphinx directory to PATH.
-	echo.
-	echo.If you don't have Sphinx installed, grab it from
-	echo.https://www.sphinx-doc.org/
-	exit /b 1
-)
-
-if "%1" == "" goto help
-
-%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
-goto end
-
-:help
-%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
-
-:end
-popd

docs/source/conf.py

@@ -6,6 +6,9 @@
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
+import os.path
+import sys
+
 project = 'ptvp35'
 copyright = '2022, PARRRATE TNV'
 author = 'PARRRATE TNV'
@@ -26,15 +29,14 @@ templates_path = ['_templates']
 exclude_patterns = []
 
 
-
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
 html_theme = 'pydata_sphinx_theme'
+html_theme_options = {
+    "navbar_center": [],
+}
 html_static_path = ['_static']
 
 
-import sys
-import os.path
-
 sys.path.insert(0, os.path.abspath('../..'))

docs/source/development.rst

@@ -0,0 +1,20 @@
+Current core development values
+===============================
+
+* Target :code:`async` only.
+* Store the database file as a single human-editable file.
+* Keep the core module a single minimalistic file.
+* Provide for dynamic instrumentation.
+
+Guidelines for developers of Persistence 5
+==========================================
+
+These apply both to the internal PARRRATE TNV team behind Persistence 5 and to external contributors.
+
+* Before contributing a feature to Persistence 5, the following should be considered:
+    * Addition of a simple extensible/flexible support for the further integration of external features is preferred over adding features themselves.
+    * Addition of features as extensions is preferred over adding features to core codebase.
+    * Maintaining extensions as separate projects is preferred over adding them to the core repository.
+    * Forking of the repository is encouraged.
+    * Usage of the repository as a reference for custom data storage solutions is encouraged.
+* Instrumentation code base is more open to direct code contributions.

docs/source/history.rst

@@ -0,0 +1,58 @@
+Historical notes
+================
+
+Persistence 1.
+--------------
+
+* Used by CMB.
+
+Persistence 2. CmbPrst.
+--------------
+
+* Internal storage of CMB.
+
+Persistence 3. ptvp3.
+---------------------
+
+* Cluster of backed-up-on-disk dictionaries.
+* Used by CBMB.
+
+Persistence 4. ptvp3.4. ShelveSQLite.
+-------------------------------------
+
+* SQLite-based analogue of :code:`shelve` module.
+* Used by v6x12 implementation of CBMB.
+
+Persistence 5. ptvp3.5.
+-----------------------
+
+* First :code:`async` database in the line.
+* File stream storage.
+
+Persistence 5 early release candidates.
+--------------------------------------
+
+* Prevents database corruption.
+
+Persistence 5 1.0 (5.1.0).
+-------------------------
+
+* ACID compliant.
+* Reduced or none blocking code.
+
+Persistence 5 1.1 (5.1.1).
+-------------------------
+
+* Non-nightly support for transactions.
+* Instrumentation support.
+
+Proposed future versions
+========================
+
+Persistence 5 1.2.
+------------------
+* More abstract concepts (expansion of :code:`VirtualConnection` and :code:`LineRequest`).
+
+Persistence 5 2.0.
+------------------
+* Any future breaking changes are going to be listed here.

docs/source/index.rst

@@ -1,26 +1,26 @@
-Welcome to ptvp35's documentation!
-==================================
+Welcome to Persistence 5
+========================
+
+Memory-Resident DataBase for simple single-process asynchronous Python applications.
 
 .. toctree::
    :maxdepth: 2
    :caption: Contents:
+
    motivation
    usage
-   modules
    guarantees
    ordering
    projects
+   history
+   development
+   modules
 
 
 
 Indices and tables
 ==================
 
-* :doc:`motivation`
-* :doc:`usage`
-* :doc:`guarantees`
-* :doc:`ordering`
-* :doc:`projects`
 * :ref:`genindex`
 * :ref:`modindex`
 * :ref:`search`

docs/source/motivation.rst

@@ -1,5 +1,5 @@
-Motivation
-==========
+What is Persistence 5 for?
+==========================
 
 This page describes reasons for certain design decisions.
 

ptvp35/__init__.py

@@ -19,6 +19,7 @@ __all__ = (
     'Db',
     'Transaction',
     'TransactionView',
+    'FutureContext',
 )
 
 
@@ -56,7 +57,7 @@ class LineRequest(Request):
         self.line = line
 
 
-class KVFactory:
+class KVFactory(abc.ABC):
     """this class is for working with already normalised data values, not for data transformation (e.g. reducing keys to a common form).
 that functionality may be added in the future, though, probably, only for custom DbConnection implementations.
 note: unstable signature."""