diff --git a/Dockerfile b/Dockerfile index 549f059..cb6a44b 100644 --- a/Dockerfile +++ b/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/ diff --git a/docs/make.bat b/docs/make.bat deleted file mode 100644 index 747ffb7..0000000 --- a/docs/make.bat +++ /dev/null @@ -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 diff --git a/docs/source/conf.py b/docs/source/conf.py index ca81efa..c49fc06 100644 --- a/docs/source/conf.py +++ b/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('../..')) diff --git a/docs/source/development.rst b/docs/source/development.rst new file mode 100644 index 0000000..d253082 --- /dev/null +++ b/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. diff --git a/docs/source/history.rst b/docs/source/history.rst new file mode 100644 index 0000000..c8a83f7 --- /dev/null +++ b/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. diff --git a/docs/source/index.rst b/docs/source/index.rst index a87cfe3..c262916 100644 --- a/docs/source/index.rst +++ b/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` diff --git a/docs/source/motivation.rst b/docs/source/motivation.rst index f3f5ab0..942db8d 100644 --- a/docs/source/motivation.rst +++ b/docs/source/motivation.rst @@ -1,5 +1,5 @@ -Motivation -========== +What is Persistence 5 for? +========================== This page describes reasons for certain design decisions. diff --git a/ptvp35/__init__.py b/ptvp35/__init__.py index 15342c6..10b00c4 100644 --- a/ptvp35/__init__.py +++ b/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."""