new docs build

Dockerfile

@@ -1,41 +1,47 @@
 # syntax=docker/dockerfile:1
-FROM python:3.10
+
+FROM python:3.10 as compile-sphinx5.3.0-base
+
 RUN apt-get update
-RUN apt-get install -y python3-sphinx node.js npm
+RUN apt-get install -y python3-sphinx
-RUN npm install -g http-server
+RUN pip install Sphinx==5.3.0 pydata-sphinx-theme==0.12.0
-RUN pip install pydata-sphinx-theme
 WORKDIR /app/
 RUN pip install git+https://gitea.parrrate.ru/PTV/rainbowadn.git@e9fba7b064902ceedee0dd5578cb47030665a6aa
 
 RUN mkdir /app/docs/
-RUN mkdir /app/docs/build/
+
-RUN mkdir /app/docs/build/html/
+
+FROM compile-sphinx5.3.0-base as compile-legacy
+
 WORKDIR /app/legacy/
 RUN git clone --branch 1.0 https://gitea.parrrate.ru/PTV/ptvp35.git
 WORKDIR /app/legacy/ptvp35/
+
+
+FROM compile-legacy as compile-1.0
+
 RUN python traced_example.py > traced_example.txt
 RUN python traced_example.py all > traced_example_all.txt
 RUN cp -r docs/source/ ./source/
 RUN cp docs/Makefile ./Makefile
 RUN make html
-RUN cp -r /app/legacy/ptvp35/build/html/ /app/docs/build/html/1.0/
+
-RUN git reset --hard
+
+FROM compile-legacy as compile-1.1rc0
 
 RUN git fetch && git checkout 1.1rc0
 WORKDIR /app/legacy/ptvp35/docs/
 RUN make html
-RUN cp -r /app/legacy/ptvp35/docs/build/html/ /app/docs/build/html/1.1rc0/
+
-RUN rm -r /app/legacy/ptvp35/docs/build/
+
-WORKDIR /app/legacy/ptvp35/
+FROM compile-legacy as compile-1.1rc2
 
 RUN git fetch && git checkout 1.1rc2
 WORKDIR /app/legacy/ptvp35/docs/
 RUN make html
-RUN cp -r /app/legacy/ptvp35/docs/build/html/ /app/docs/build/html/1.1rc2/
-RUN rm -r /app/legacy/ptvp35/docs/build/
-WORKDIR /app/legacy/ptvp35/
 
-WORKDIR /app/
+
+FROM compile-sphinx5.3.0-base as compile-latest
 
 COPY docs/Makefile docs/Makefile
 COPY setup.py setup.py
@@ -44,5 +50,14 @@ COPY ptvp35 ptvp35
 COPY docs/source docs/source
 WORKDIR /app/docs/
 RUN make html
+
+
+FROM node:19
+
+RUN npm install -g http-server
 WORKDIR /app/docs/build/html/
+COPY --from=compile-1.0 /app/legacy/ptvp35/build/html/ /app/docs/build/html/1.0/
+COPY --from=compile-1.1rc0 /app/legacy/ptvp35/docs/build/html/ /app/docs/build/html/1.1rc0/
+COPY --from=compile-1.1rc2 /app/legacy/ptvp35/docs/build/html/ /app/docs/build/html/1.1rc2/
+COPY --from=compile-latest /app/docs/build/html/ /app/docs/build/html/
 CMD [ "http-server", "-p", "80" ]

docs/scripts/traced_example.py

@@ -209,17 +209,18 @@ async def main():
             LogEE(__import__('ptvp35')._Backup, 'load_mmdb_sync').enter(es)
             LogEE(__import__('ptvp35')._Backup, 'uninitialize').enter(es)
 
-            LogEE(__import__('ptvp35')._Truncation, '__init__').enter(es)
+            LogEE(__import__('ptvp35')._Guard, '__init__').enter(es)
-            LogEE(__import__('ptvp35')._Truncation, 'backup').enter(es)
+            LogEE(__import__('ptvp35')._Guard, 'backup').enter(es)
-            LogEE(__import__('ptvp35')._Truncation, '_write_bytes_sync').enter(es)
+            LogEE(__import__('ptvp35')._Guard, '_write_bytes_sync').enter(es)
-            LogEE(__import__('ptvp35')._Truncation, '_write_value_sync').enter(es)
+            LogEE(__import__('ptvp35')._Guard, '_write_value_sync').enter(es)
-            LogEE(__import__('ptvp35')._Truncation, '_set_sync').enter(es)
+            LogEE(__import__('ptvp35')._Guard, '_set_sync').enter(es)
-            LogEE(__import__('ptvp35')._Truncation, '_unset_sync').enter(es)
+            LogEE(__import__('ptvp35')._Guard, '_unset_sync').enter(es)
-            LogEE(__import__('ptvp35')._Truncation, '_target_sync').enter(es)
+            LogEE(__import__('ptvp35')._Guard, '_read_bytes_sync').enter(es)
-            LogEE(__import__('ptvp35')._Truncation, '_truncate_sync').enter(es)
+            LogEE(__import__('ptvp35')._Guard, '_read_value_sync').enter(es)
-            LogEE(__import__('ptvp35')._Truncation, 'assure_sync').enter(es)
+            LogEE(__import__('ptvp35')._Guard, '_truncate_sync').enter(es)
-            LogEE(__import__('ptvp35')._Truncation, '_file_truncate_sync').enter(es)
+            LogEE(__import__('ptvp35')._Guard, 'assure_sync').enter(es)
-            LogEE(__import__('ptvp35')._Truncation, 'file_write_sync').enter(es)
+            LogEE(__import__('ptvp35')._Guard, '_file_truncate_sync').enter(es)
+            LogEE(__import__('ptvp35')._Guard, 'file_write_sync').enter(es)
 
             LogEE(__import__('ptvp35')._ReceivingQueue, '__init__').enter(es)
             LogEE(__import__('ptvp35')._ReceivingQueue, 'submit').enter(es)

docs/source/usage.rst

@@ -60,16 +60,16 @@ Different ways to get/set a value:
             transaction.set_nowait('increment-5', value5 + 1)
         await connection.commit()
 
-* :meth:`ptvp35.DbConnection.get`
+* :meth:`ptvp35.VirtualConnection.get`
     this method is instant.
-* :meth:`ptvp35.DbConnection.set`
+* :meth:`ptvp35.DbInterface.set`
     this method may take time to run.
     ordering may not be guaranteed (depends on event loop implementation).
-* :meth:`ptvp35.DbConnection.set_nowait`
+* :meth:`ptvp35.ExtendedVirtualConnection.set_nowait`
     this method is instant.
     ordering is guaranteed.
-* :meth:`ptvp35.DbConnection.commit`
+* :meth:`ptvp35.ExtendedVirtualConnection.commit`
     this method may take time to run.
     respects the ordering of previously called :code:`set_nowait` methods.
     will, depending on event loop implementation, also execute later changes.
-* :meth:`ptvp35.DbConnection.transaction`
+* :meth:`ptvp35.VirtualConnection.transaction`

ptvp35/__init__.py

@@ -1,11 +1,15 @@
-# Licensed under MIT License. Copyright: 2022-2023 PARRRATE TNV.
+# Licensed under MIT License. Copyright: 2022-2023 Alisa Feistel, PARRRATE TNV.
 
 from __future__ import annotations
 
 __all__ = (
     'VDELETE',
+    'KVProtocol',
     'KVFactory',
     'KVJson',
+    'VirtualConnection',
+    'ExtendedVirtualConnection',
+    'DbInterface',
     'DbConnection',
     'DbManager',
     'DbFactory',
@@ -470,7 +474,7 @@ class _Backup:
         del self.__initial_size
 
 
-class _Truncation:
+class _Guard:
     __slots__ = (
         '__backup',
         '__error',
@@ -498,6 +502,12 @@ class _Truncation:
     def _write_value_sync(self, value: int, /) -> None:
         self._write_bytes_sync(value.to_bytes(16, 'little'))
 
+    def _read_bytes_sync(self, /) -> bytes:
+        return self.__truncate.read_bytes()
+
+    def _read_value_sync(self, /) -> int:
+        return int.from_bytes(self._read_bytes_sync(), 'little')
+
     def _set_sync(self, /) -> None:
         self._write_value_sync(self.__file.tell())
         self.__flag.touch()
@@ -506,12 +516,9 @@ class _Truncation:
         self.__flag.unlink(missing_ok=True)
         self.__truncate.unlink(missing_ok=True)
 
-    def _target_sync(self, /) -> int:
-        return int.from_bytes(self.__truncate.read_bytes(), 'little')
-
     def _truncate_sync(self, /) -> None:
         with self.__path.open('r+') as file:
-            self._file_truncate_sync(file, self._target_sync())
+            self._file_truncate_sync(file, self._read_value_sync())
 
     def assure_sync(self, /) -> None:
         if self.__flag.exists():
@@ -544,7 +551,7 @@ class _ReceivingQueue:
 class _WriteableBuffer:
     __slots__ = (
         '__buffersize',
-        '__truncation',
+        '__guard',
         '__queue',
         '__backup',
         '__kvfactory',
@@ -560,19 +567,19 @@ class _WriteableBuffer:
     __buffer_requested: bool
 
     def __init__(
-        self, buffersize: int, truncation: _Truncation, queue: _ReceivingQueue, loop: _Loop, /
+        self, buffersize: int, guard: _Guard, queue: _ReceivingQueue, loop: _Loop, /
     ) -> None:
         self.__buffersize = buffersize
-        self.__truncation = truncation
+        self.__guard = guard
         self.__queue = queue
-        self.__backup = self.__truncation.backup()
+        self.__backup = self.__guard.backup()
         self.__kvfactory = self.__backup.kvfactory()
         self.__loop = loop
         self.__event_loop = self.__loop.loop()
         self._clear()
 
-    def writeable(self, /) -> _Truncation:
+    def writeable(self, /) -> _Guard:
-        return self.__truncation
+        return self.__guard
 
     def loop(self, /) -> _Loop:
         return self.__loop
@@ -586,7 +593,7 @@ class _WriteableBuffer:
         return buffer
 
     def _commit_compressed_sync(self, /) -> None:
-        self.__truncation.file_write_sync(self._compressed().getvalue())
+        self.__guard.file_write_sync(self._compressed().getvalue())
 
     async def _commit_compressed(self, /) -> None:
         await self.__event_loop.run_in_executor(None, self._commit_compressed_sync)
@@ -670,7 +677,7 @@ class _WriteableBuffer:
 class _Memory:
     __slots__ = (
         '__backup',
-        '__truncation',
+        '__guard',
         '__file',
         '__kvfactory',
         '__loop',
@@ -679,9 +686,9 @@ class _Memory:
 
     __mmdb: dict
 
-    def __init__(self, truncation: _Truncation, /) -> None:
+    def __init__(self, guard: _Guard, /) -> None:
-        self.__truncation = truncation
+        self.__guard = guard
-        self.__backup = truncation.backup()
+        self.__backup = guard.backup()
         self.__file = self.__backup.file()
         self.__kvfactory = self.__backup.kvfactory()
 
@@ -689,7 +696,7 @@ class _Memory:
         self.__mmdb = self.__backup.load_mmdb_sync()
 
     def _load_from_file_sync(self, /) -> None:
-        self.__truncation.assure_sync()
+        self.__guard.assure_sync()
         self._initialize_sync()
         self.__file.open_sync()
 
@@ -811,17 +818,17 @@ class _DbConnection(
 
     async def _initialize_running(self, /) -> None:
         self.__loop = _Loop(asyncio.get_running_loop())
-        truncation = _Truncation(
+        guard = _Guard(
             _Backup(self.__path, self.__kvfactory, self.__loop),
             _Errors(self.__path, self.__loop),
         )
         queue: asyncio.Queue[Request] = asyncio.Queue()
         self.__queue = _ReceivingQueue(queue)
-        self.__mmdb = _Memory(truncation)
+        self.__mmdb = _Memory(guard)
         await self.__mmdb._load_from_file()
         self.__task = _QueueTask(
             queue,
-            _WriteableBuffer(self.__buffersize, truncation, self.__queue, self.__loop)
+            _WriteableBuffer(self.__buffersize, guard, self.__queue, self.__loop)
         )
         self.__task.start()