pistributer 0.2.0__py3-none-any.whl

pistributer-0.2.0.dist-info/METADATA

@@ -0,0 +1,333 @@
+Metadata-Version: 2.4
+Name: pistributer
+Version: 0.2.0
+Summary: A local-first file-backed FIFO queue with jsonl, txt, and sqlite drivers.
+Author: Yeong
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/yeongdev/pistributer
+Project-URL: Repository, https://github.com/yeongdev/pistributer
+Project-URL: Issues, https://github.com/yeongdev/pistributer/issues
+Project-URL: Changelog, https://github.com/yeongdev/pistributer/blob/main/CHANGELOG.md
+Keywords: queue,file,fifo,jsonl,streaming
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# pistributer
+
+`pistributer` is a local-first FIFO queue toolkit for file-based workflows.
+
+**Hard position:** `pistributer` exists for developers who want a usable queue across servers or local jobs without standing up Redis, Kafka, or another heavy service.
+
+**Performance contract:** this project prefers faster write/read throughput over a larger or more polished interface. The core value is still the same: write, read, high concurrency, multi-file workloads, and as little extra overhead as possible.
+
+It started as a high-throughput local queue used on large datasets, and it now ships three practical drivers instead of pretending one storage format is ideal for every workload:
+
+- `txt` for the shortest raw file path
+- `jsonl` for structured, inspectable records
+- `sqlite` for stronger integrity under contention
+
+## When to use each driver
+
+| Driver | Use it when | Avoid it when |
+| --- | --- | --- |
+| `txt` | You want the shortest plain-text file path and staged or single-writer-friendly queueing | You need structured records or stronger overlap correctness |
+| `jsonl` | You want readable structured payloads and the default publishable workflow | You need the rawest append path or heavy overlapping write/read integrity |
+| `sqlite` | You want stronger local correctness under contention | You want the lightest append-heavy file path |
+
+## Project background
+
+The earliest version of this tool was not created as a polished open-source package. It was created by a developer who wanted a queue but did not want to install or operate a heavier system such as Redis or Kafka.
+
+The original approach was simple: use the filesystem itself as the message layer and use plain `.txt` files for data exchange. That early code was not cleaned up for publication, but the underlying queue logic was already useful in practice and was used on large amounts of real data.
+
+Later, after the developer started building AI-oriented workflows with `nanobot`, the need for a cleaner installable package became more obvious. That is what pushed the repackaging effort: not a rewrite for the sake of novelty, but a practical need for `pip` installability, clearer docs, and a structured default format.
+
+That is why the project now has two historical truths at the same time:
+
+- the `0.1.x` line represents long-used file-queue logic that existed before the packaging cleanup
+- the `0.2.0` line makes `.jsonl` the default public driver and adds wider tests, benchmarks, and release tooling
+
+The current repository keeps that history visible instead of hiding it. The old behavior is preserved for comparison in `benchmarks/pistributer_bak.py`, while the main package is documented and tested as the public installable tool.
+
+## `0.1.x` and `0.2.0` in practice
+
+The simplest way to understand the version difference is this:
+
+- `0.1.x` means the long-used plain-text file-queue era
+- `0.2.0` means the public packaged era with `.jsonl` as the default driver
+
+What changed:
+
+- `0.1.x` was centered on the shortest `.txt` path and real-world usage before packaging cleanup
+- `0.2.0` keeps the same basic file-queue idea but makes `.jsonl` the default public format
+- `0.2.0` adds tests, benchmark documentation, packaging, and a clearer boundary for when to use `txt`, `jsonl`, and `sqlite`
+
+What did **not** change:
+
+- the project still values write/read throughput over interface growth
+- the core file-queue idea is still append, rotate into `.in_use`, and consume with a small API
+- the hot path is still expected to stay small and fast
+
+Measured conclusion from the current benchmark work:
+
+- the visible slowdown from `0.1.x` to `0.2.0` is real, but it is not mostly caused by the `.jsonl` extension itself
+- most of the remaining overhead comes from the modern hot path doing a little more work around path validation and file-operation safeguards
+- JSON serialization adds a smaller extra cost when callers pass Python objects instead of already-serialized strings
+
+In short: `0.2.0` is slower than the historical plain-text path, but the gap is now mostly the cost of a cleaner public default and structured serialization, not a dramatic penalty from JSONL as a format.
+
+## Design priorities
+
+The author's preference is very explicit:
+
+1. keep the queue fast under heavy write/read workloads
+2. keep the public surface small
+3. avoid changes that reduce throughput unless the trade-off is clearly worth it
+
+That means this project does **not** try to win by offering a large interface. It tries to win by doing a very small number of things well:
+
+- append records fast
+- read records fast
+- handle many files
+- stay useful under high write pressure
+
+The current `.jsonl` default is accepted even though it is slower than the historical `.txt` path, because the measured overhead is still within an acceptable range for the intended workflows. Outside of that specific trade-off, performance regressions are treated as unacceptable.
+
+## Project position
+
+`pistributer` is best positioned as a lightweight local queue for scripts, batch jobs, and single-host pipelines.
+
+It is a good fit when:
+
+- your workload is file-centric
+- you want simple deployment with no external service
+- you care about readable queue state on disk
+- you want to choose between throughput-first and integrity-first local drivers
+- your file-driver usage is staged or single-writer-friendly
+
+It is not the best fit when:
+
+- you need a multi-node distributed queue
+- you need strict correctness under heavy overlapping readers and writers with the file drivers
+- you want managed persistence, replication, or cross-host coordination
+
+## Why use it
+
+Use `pistributer` when you want a small queue abstraction for a local or single-host pipeline without introducing Redis, Kafka, or a separate database service.
+
+What it is good at:
+
+- append-heavy local workloads
+- high-concurrency write-focused workloads
+- simple batch pipelines and scripts
+- readable on-disk data formats
+- lightweight deployment with minimal operational overhead
+
+The file-based drivers rotate active data into `.in_use`, which helps reduce direct producer/consumer contention on the same file.
+
+The two file drivers, `Pistributer` and `PistributerTxt`, are best documented as staged or single-writer-friendly. They work well when appends and reads are mostly separated, but they are not the strongest option for heavy overlapping writer and reader contention.
+
+For hot-path performance, `put()` in the two file drivers assumes the parent directory already exists. Directory preparation is intentionally kept outside the hot path.
+
+The intent is not to keep adding more actions and more surface area. The intent is to keep the important path small: write, read, and move a lot of data without unnecessary slowdown.
+
+## Driver modes
+
+### `jsonl` driver
+
+```python
+from pistributer import Pistributer
+```
+
+Use this as the default mode when you want structured records and a modern `.jsonl` workflow.
+
+### `txt` driver
+
+```python
+from pistributer_txt import PistributerTxt
+```
+
+Use this when raw text throughput matters more than structure.
+
+### `sqlite` driver
+
+```python
+from pistributer_sqlite import PistributerSqlite
+```
+
+Use this when queue correctness matters more than the shortest append path.
+
+See `DRIVERS.md` for a full comparison.
+
+See `EXAMPLES.md` for small copyable examples for all three drivers.
+
+The Python docstrings are written to be `help()`-friendly, so `help(Pistributer)`, `help(Pistributer.put)`, and the equivalent driver methods should now give usable inline guidance.
+
+## Choose a driver
+
+| Driver | Best for | Main trade-off |
+| --- | --- | --- |
+| `Pistributer` (`jsonl`) | Structured local queues and readable payloads | More overhead than raw text |
+| `PistributerTxt` | Fast plain-text append-heavy workloads | Least structured format |
+| `PistributerSqlite` | Stronger local correctness under contention | Higher transaction overhead |
+
+## API naming note
+
+Public API names stay stable on purpose.
+
+- `Pistributer` and `PistributerTxt` keep the historical camelCase names such as `isEmpty()` and `getIndex()`.
+- `PistributerSqlite` keeps its newer snake_case method `is_empty()`.
+
+The naming is not perfectly uniform, but the project keeps the existing public contract instead of breaking working code.
+
+## Install
+
+```bash
+pip install pistributer
+```
+
+## Quick start
+
+```python
+from pistributer import Pistributer
+
+Pistributer.put("channel.jsonl", {"value": "hello"})
+Pistributer.put("channel.jsonl", {"value": "world"})
+
+queue = Pistributer("channel.jsonl")
+
+print(queue.next())
+print(queue.next())
+print(queue.isEmpty())
+```
+
+## Core API
+
+The practical core of the project is intentionally small: append with `put()` and consume with `next()`.
+
+The other methods exist to support queue lifecycle and compatibility, not to turn the library into a broad interface framework.
+
+- `Pistributer(path)`: open a queue backed by a `.jsonl` file
+- `Pistributer.put(path, value)`: append one message; the parent directory must already exist
+- `Pistributer.new(path, value, overwrite=False, sep="")`: create a file with initial content
+- `Pistributer.next()`: return the next message, or raise `StopIteration` if empty
+- `Pistributer.isEmpty()`: return whether unread messages remain
+- `Pistributer.size()`: count queued messages across active files
+- `Pistributer.remaining()`: count unread messages
+- `Pistributer.getIndex()`: return the consumed message count
+
+## Validation
+
+The repository includes both correctness tests and direct benchmarks against the preserved backup implementation at `benchmarks/pistributer_bak.py`.
+
+### Functional tests
+
+The main regression test writes `300` `.jsonl` files, each with `30` distinct JSON rows, and then consumes everything through `next()`.
+
+That covers `9000` records and checks:
+
+- FIFO ordering
+- empty-queue behavior
+- remaining-count behavior
+- reopen/index persistence
+- rotated `.in_use` files plus newly appended data
+
+Run the test suite with:
+
+```bash
+python -m unittest discover -s tests -v
+```
+
+### Staged benchmark
+
+The staged benchmark compares:
+
+- `benchmarks/pistributer_bak.py` with `300` `.txt` files × `30` rows
+- `pistributer.py` with `300` `.jsonl` files × `30` rows
+
+Latest measured result in this workspace:
+
+- backup total: about `0.956s`
+- current total: about `1.020s`
+- current write ratio: about `1.18x` of backup
+- current read ratio: about `1.02x` of backup
+- current total ratio: about `1.07x` of backup
+
+In this staged workload, the current `jsonl` rewrite is slightly slower than the backup `txt` path, which is expected because the structured driver pays extra serialization and validation overhead.
+
+That overhead is currently accepted because the repository intentionally chose `.jsonl` as the public default. Beyond that known trade-off, the project should resist changes that make the hot path slower.
+
+The important version-difference detail is that this benchmark compares the historical backup implementation against the current public package. It is not a pure `jsonl` vs `txt` format test in isolation.
+
+After moving parent-directory preparation out of the file-driver `put()` hot path, a focused write-only microbenchmark in this workspace produced these averages over five runs of `20000` appends:
+
+- backup `txt` string append: about `0.617s`
+- current `txt` string append: about `0.586s`
+- current `jsonl` string append: about `0.608s`
+- current `jsonl` dictionary append: about `0.652s`
+
+That means the current `jsonl` hot path is now much closer to the historical reference point when the caller passes pre-serialized strings, and the remaining extra cost mainly shows up when the caller asks the driver to serialize Python objects.
+
+Run it with:
+
+```bash
+python benchmarks/compare_versions.py
+```
+
+Detailed notes are in `BENCHMARKS.md`.
+
+### Interleaved write/read stress benchmark
+
+The repository also includes a heavier benchmark where writes and reads overlap:
+
+- `300` writer threads
+- `64` consumer threads
+- `30` logical file assignments per writer
+- `10` shared files per writer
+- `300` rows per file assignment
+- `2,700,000` total rows attempted
+- `6010` physical files after shared-path collapse
+
+Latest measured result in this workspace:
+
+- backup `.txt` consumed `2,699,852 / 2,700,000`
+- current `.jsonl` consumed `2,699,351 / 2,700,000`
+- both modes produced `0` malformed JSON rows
+- both file drivers failed full integrity under simultaneous write/read pressure
+
+That is the practical reason the `sqlite` driver exists: once the workload shifts from staged local queueing to stronger overlapping write/read correctness, a transactional driver becomes the better fit.
+
+Run it with:
+
+```bash
+python benchmarks/threaded_interleaved_compare.py
+```
+
+## Release
+
+Release steps and commands are documented in `RELEASE.md`.
+
+Project history is tracked in `CHANGELOG.md`.
+
+## Contributing
+
+Small, focused contributions are welcome. Start with `CONTRIBUTING.md` for development and review expectations.
+
+## Notes
+
+- Messages are stored as one JSON object per line in the default driver.
+- Files rotate from `data` to `.in_use` so new appends stay separate from active consumption.
+- `txt` and `jsonl` are strongest in local staged workloads where writes and reads are mostly separated.
+- `sqlite` targets a different optimization goal: stronger correctness under concurrency.
+- The project is intentionally lightweight and local-first.

pistributer-0.2.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+pistributer.py,sha256=skDir-SAA9ZpoJCC69wrpZNSydLFCGkTDOEP0B08pUY,10969
+pistributer_sqlite.py,sha256=DJ2KdM5rsLGvzad1-6pnTAiGGv0i-1miBCZIcH5youA,6641
+pistributer_txt.py,sha256=icpLYhFxCjNiNwyWUMb0BSmTiUBpOCfYDW-51k6XxgQ,9081
+pistributer-0.2.0.dist-info/licenses/LICENSE,sha256=p361mXIV7Nqk4udtvxN66X4YwsMRE29fBUWrQxH5DlY,9334
+pistributer-0.2.0.dist-info/METADATA,sha256=fmtxsUyNlKO7GB9NMh_qnVIyPG8RIIZXrYlBFfWzZ4c,14481
+pistributer-0.2.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+pistributer-0.2.0.dist-info/top_level.txt,sha256=oF_7r2SHma_zOSFaEXtwgDMkF3kWDxn6kSBEN1lwBCM,47
+pistributer-0.2.0.dist-info/RECORD,,

pistributer-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pistributer-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,160 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and
+ distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the copyright
+ owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other entities
+ that control, are controlled by, or are under common control with that entity.
+ For the purposes of this definition, "control" means (i) the power, direct or
+ indirect, to cause the direction or management of such entity, whether by
+ contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the
+ outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising
+ permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications, including
+ but not limited to software source code, documentation source, and
+ configuration files.
+
+"Object" form shall mean any form resulting from mechanical transformation or
+ translation of a Source form, including but not limited to compiled object
+ code, generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form,
+ made available under the License, as indicated by a copyright notice that is
+ included in or attached to the work (an example is provided in the Appendix
+ below).
+
+"Derivative Works" shall mean any work, whether in Source or Object form, that
+ is based on (or derived from) the Work and for which the editorial revisions,
+ annotations, elaborations, or other modifications represent, as a whole, an
+ original work of authorship. For the purposes of this License, Derivative Works
+ shall not include works that remain separable from, or merely link (or bind by
+ name) to the interfaces of, the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including the original version
+ of the Work and any modifications or additions to that Work or Derivative Works
+ thereof, that is intentionally submitted to Licensor for inclusion in the Work
+ by the copyright owner or by an individual or Legal Entity authorized to submit
+ on behalf of the copyright owner. For the purposes of this definition,
+ "submitted" means any form of electronic, verbal, or written communication sent
+ to the Licensor or its representatives, including but not limited to
+ communication on electronic mailing lists, source code control systems, and
+ issue tracking systems that are managed by, or on behalf of, the Licensor for
+ the purpose of discussing and improving the Work, but excluding communication
+ that is conspicuously marked or otherwise designated in writing by the copyright
+ owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on behalf
+ of whom a Contribution has been received by Licensor and subsequently
+ incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this
+ License, each Contributor hereby grants to You a perpetual, worldwide,
+ non-exclusive, no-charge, royalty-free, irrevocable copyright license to
+ reproduce, prepare Derivative Works of, publicly display, publicly perform,
+ sublicense, and distribute the Work and such Derivative Works in Source or
+ Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of this License,
+ each Contributor hereby grants to You a perpetual, worldwide, non-exclusive,
+ no-charge, royalty-free, irrevocable (except as stated in this section) patent
+ license to make, have made, use, offer to sell, sell, import, and otherwise
+ transfer the Work, where such license applies only to those patent claims
+ licensable by such Contributor that are necessarily infringed by their
+ Contribution(s) alone or by combination of their Contribution(s) with the Work
+ to which such Contribution(s) was submitted. If You institute patent litigation
+ against any entity (including a cross-claim or counterclaim in a lawsuit)
+ alleging that the Work or a Contribution incorporated within the Work
+ constitutes direct or contributory patent infringement, then any patent
+ licenses granted to You under this License for that Work shall terminate as of
+ the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the Work or
+ Derivative Works thereof in any medium, with or without modifications, and in
+ Source or Object form, provided that You meet the following conditions:
+
+ (a) You must give any other recipients of the Work or Derivative Works a copy
+     of this License; and
+
+ (b) You must cause any modified files to carry prominent notices stating that
+     You changed the files; and
+
+ (c) You must retain, in the Source form of any Derivative Works that You
+     distribute, all copyright, patent, trademark, and attribution notices from
+     the Source form of the Work, excluding those notices that do not pertain to
+     any part of the Derivative Works; and
+
+ (d) If the Work includes a "NOTICE" text file as part of its distribution, then
+     any Derivative Works that You distribute must include a readable copy of the
+     attribution notices contained within such NOTICE file, excluding those
+     notices that do not pertain to any part of the Derivative Works, in at least
+     one of the following places: within a NOTICE text file distributed as part
+     of the Derivative Works; within the Source form or documentation, if
+     provided along with the Derivative Works; or, within a display generated by
+     the Derivative Works, if and wherever such third-party notices normally
+     appear. The contents of the NOTICE file are for informational purposes only
+     and do not modify the License. You may add Your own attribution notices
+     within Derivative Works that You distribute, alongside or as an addendum to
+     the NOTICE text from the Work, provided that such additional attribution
+     notices cannot be construed as modifying the License.
+
+ You may add Your own copyright statement to Your modifications and may provide
+ additional or different license terms and conditions for use, reproduction, or
+ distribution of Your modifications, or for any such Derivative Works as a
+ whole, provided Your use, reproduction, and distribution of the Work otherwise
+ complies with the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise, any
+ Contribution intentionally submitted for inclusion in the Work by You to the
+ Licensor shall be under the terms and conditions of this License, without any
+ additional terms or conditions. Notwithstanding the above, nothing herein shall
+ supersede or modify the terms of any separate license agreement you may have
+ executed with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade names,
+ trademarks, service marks, or product names of the Licensor, except as required
+ for reasonable and customary use in describing the origin of the Work and
+ reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or agreed to in
+ writing, Licensor provides the Work (and each Contributor provides its
+ Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied, including, without limitation, any warranties
+ or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+ PARTICULAR PURPOSE. You are solely responsible for determining the
+ appropriateness of using or redistributing the Work and assume any risks
+ associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory, whether in
+ tort (including negligence), contract, or otherwise, unless required by
+ applicable law (such as deliberate and grossly negligent acts) or agreed to in
+ writing, shall any Contributor be liable to You for damages, including any
+ direct, indirect, special, incidental, or consequential damages of any
+ character arising as a result of this License or out of the use or inability to
+ use the Work (including but not limited to damages for loss of goodwill, work
+ stoppage, computer failure or malfunction, or any and all other commercial
+ damages or losses), even if such Contributor has been advised of the
+ possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing the Work or
+ Derivative Works thereof, You may choose to offer, and charge a fee for,
+ acceptance of support, warranty, indemnity, or other liability obligations
+ and/or rights consistent with this License. However, in accepting such
+ obligations, You may act only on Your own behalf and on Your sole
+ responsibility, not on behalf of any other Contributor, and only if You agree
+ to indemnify, defend, and hold each Contributor harmless for any liability
+ incurred by, or claims asserted against, such Contributor by reason of your
+ accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS

pistributer-0.2.0.dist-info/top_level.txt

@@ -0,0 +1,3 @@
+pistributer
+pistributer_sqlite
+pistributer_txt

pistributer.py

@@ -0,0 +1,348 @@
+"""JSONL-first `pistributer` driver.
+
+This module is the default public delivery of `pistributer`.
+
+It keeps the original local file-queue model: append records to a data file,
+rotate that file into `.in_use`, and track read progress in a sidecar index.
+
+Use this driver when you want structured payloads and a small local queue API.
+The file driver is best for staged workflows or single-writer-friendly usage.
+It is not the strongest choice for heavy overlapping write and read contention.
+The hot write path assumes the parent directory already exists.
+
+Example:
+    >>> from pistributer import Pistributer
+    >>> Pistributer.put("events.jsonl", {"event": "start"})
+    True
+    >>> queue = Pistributer("events.jsonl")
+    >>> isinstance(queue.next(), str)
+    True
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+__all__ = ["Pistributer"]
+__version__ = "0.2.0"
+
+
+class Pistributer:
+    """Queue interface for newline-delimited JSON files.
+
+    The public method names intentionally preserve the historical API, including
+    `isEmpty()` and `getIndex()`, so existing code keeps working.
+
+    Example:
+        >>> queue = Pistributer("events.jsonl")
+        >>> queue.isEmpty()
+        True
+    """
+
+    def __init__(self, path: str | Path):
+        """Open a queue backed by a `.jsonl` channel file.
+
+        Args:
+            path: Path to the queue file. The path must end with `.jsonl`.
+
+        Returns:
+            None.
+
+        Raises:
+            ValueError: If `path` does not end with `.jsonl`.
+
+        Example:
+            >>> Pistributer("events.jsonl")
+        """
+        channel_path = self._normalize_channel_name(path)
+        self.abspath = "" if os.sep not in channel_path else os.path.abspath(".")
+        self.path = {
+            "data": os.path.abspath(os.path.join(self.abspath, channel_path)),
+            "index": os.path.abspath(os.path.join(self.abspath, f"{channel_path}.index")),
+            "in_use": os.path.abspath(os.path.join(self.abspath, f"{channel_path}.in_use")),
+        }
+        self.q: list[str] = []
+        self.__index = {"index": 0}
+        self.__initialQueue()
+
+    @staticmethod
+    def new(target_path: str | Path, string, overwrite: bool = False, sep: str = "") -> bool:
+        """Create a new queue file with one serialized record.
+
+        Args:
+            target_path: Destination `.jsonl` file.
+            string: Record to write. Strings are written as-is; other values are
+                serialized to compact JSON.
+            overwrite: When `True`, allow replacing an existing file.
+            sep: Optional trailing separator to append after the payload.
+
+        Returns:
+            True when the file is created successfully.
+
+        Raises:
+            ValueError: If `target_path` does not end with `.jsonl`.
+            IsADirectoryError: If `target_path` points to a directory.
+            FileExistsError: If the file already exists and `overwrite` is `False`.
+
+        Example:
+            >>> Pistributer.new("events.jsonl", {"event": "start"}, overwrite=True)
+            True
+        """
+        file_path = Pistributer._normalize_channel_name(target_path)
+        if os.path.isdir(file_path):
+            raise IsADirectoryError(f'This is a folder, require a file to write "{file_path}"')
+        if os.path.isfile(file_path) and overwrite is not True:
+            raise FileExistsError(f'File exists "{file_path}"')
+
+        payload = Pistributer._serialize_record(string)
+        parent_dir = os.path.dirname(file_path)
+        if parent_dir and not os.path.isdir(parent_dir):
+            os.makedirs(parent_dir, exist_ok=True)
+
+        with open(file_path, "w+", encoding="utf-8") as handle:
+            handle.write(f"{payload}{sep}")
+            handle.flush()
+
+        return True
+
+    @staticmethod
+    def put(target_path: str | Path, string) -> bool:
+        """Append one record to a `.jsonl` queue file.
+
+        Args:
+            target_path: Destination `.jsonl` file.
+            string: Record to append. Strings are written as-is; other values are
+                serialized to compact JSON.
+
+        Returns:
+            True when the record is appended successfully.
+
+        Raises:
+            ValueError: If `target_path` does not end with `.jsonl`.
+            FileNotFoundError: If the parent directory does not already exist.
+
+        Example:
+            >>> Pistributer.put("events.jsonl", {"event": "finish"})
+            True
+        """
+        file_path = Pistributer._normalize_channel_name(target_path)
+        payload = Pistributer._serialize_record(string)
+
+        with open(file_path, "a+", encoding="utf-8") as handle:
+            handle.write(f"{payload}\n")
+            handle.flush()
+
+        return True
+
+    def next(self) -> str:
+        """Return the next unread record.
+
+        Returns:
+            The next stored line as a string.
+
+        Raises:
+            StopIteration: If the queue is empty.
+
+        Example:
+            >>> queue = Pistributer("events.jsonl")
+            >>> queue.next()
+        """
+        if self.isEmpty():
+            raise StopIteration("Pistributer queue is empty")
+
+        data = self.q[self.__index["index"]]
+        self.increaseIndex()
+        return data
+
+    def isEmpty(self) -> bool:
+        """Report whether the queue has unread records.
+
+        This historical camelCase name is kept for compatibility.
+
+        Returns:
+            True when no unread records remain, otherwise False.
+
+        Example:
+            >>> queue = Pistributer("events.jsonl")
+            >>> queue.isEmpty()
+            True
+        """
+        if self.__index["index"] >= len(self.q):
+            if os.path.isfile(self.path["index"]):
+                os.remove(self.path["index"])
+            if os.path.isfile(self.path["in_use"]):
+                os.remove(self.path["in_use"])
+
+            if os.path.isfile(self.path["data"]):
+                self.__initialQueue()
+                return False
+
+            return True
+
+        return False
+
+    def size(self) -> int:
+        """Count records across the active data and `.in_use` files.
+
+        Returns:
+            The total number of stored records for the channel.
+
+        Example:
+            >>> queue = Pistributer("events.jsonl")
+            >>> isinstance(queue.size(), int)
+            True
+        """
+        paths = self.path["data"], self.path["in_use"]
+        size = 0
+        for file_path in paths:
+            if os.path.isfile(file_path):
+                with open(file_path, encoding="utf-8") as handle:
+                    for _ in handle:
+                        size += 1
+        return size
+
+    def remaining(self) -> int:
+        """Count unread records.
+
+        Returns:
+            The number of records that have not been consumed yet.
+
+        Example:
+            >>> queue = Pistributer("events.jsonl")
+            >>> isinstance(queue.remaining(), int)
+            True
+        """
+        return max(0, self.size() - self.getIndex()["index"])
+
+    def getIndex(self) -> dict[str, int]:
+        """Return the persisted read index.
+
+        Returns:
+            A dictionary with one key, `index`, storing the consumed count.
+
+        Example:
+            >>> queue = Pistributer("events.jsonl")
+            >>> "index" in queue.getIndex()
+            True
+        """
+        if os.path.isfile(self.path["index"]):
+            with open(self.path["index"], "r+", encoding="utf-8") as json_file:
+                try:
+                    output = json.load(json_file)
+                except Exception:
+                    return {"index": 0}
+            return output
+
+        with open(self.path["index"], "w+", encoding="utf-8") as handle:
+            json.dump({"index": 0}, handle)
+
+        return {"index": 0}
+
+    def updateIndex(self, count: int) -> None:
+        """Persist a new read index value.
+
+        Args:
+            count: Desired consumed count. Negative values are clamped to zero.
+
+        Returns:
+            None.
+
+        Example:
+            >>> queue = Pistributer("events.jsonl")
+            >>> queue.updateIndex(0)
+        """
+        self.__index["index"] = max(0, count)
+        with open(self.path["index"], "w+", encoding="utf-8") as handle:
+            json.dump(self.__index, handle)
+
+    def increaseIndex(self, count: int = 1) -> None:
+        """Advance the persisted read index.
+
+        Args:
+            count: Number of consumed records to add.
+
+        Returns:
+            None.
+
+        Example:
+            >>> queue = Pistributer("events.jsonl")
+            >>> queue.increaseIndex()
+        """
+        self.updateIndex(self.__index["index"] + count)
+
+    def decreaseIndex(self, count: int = 1) -> None:
+        """Move the persisted read index backward.
+
+        Args:
+            count: Number of consumed records to subtract.
+
+        Returns:
+            None.
+
+        Example:
+            >>> queue = Pistributer("events.jsonl")
+            >>> queue.decreaseIndex()
+        """
+        self.updateIndex(self.__index["index"] - count)
+
+    def __initialQueue(self) -> None:
+        self.__index = self.getIndex()
+
+        if os.path.isfile(self.path["in_use"]):
+            self.q = list(self.__readInUse())
+            return
+
+        if os.path.isfile(self.path["data"]):
+            os.rename(self.path["data"], self.path["in_use"])
+            self.q = list(self.__readInUse())
+            self.updateIndex(0)
+            return
+
+        self.q = []
+        if os.path.isfile(self.path["index"]):
+            os.remove(self.path["index"])
+
+    def __readInUse(self):
+        if os.path.isfile(self.path["in_use"]):
+            return [item for item in self.__read_file_by_line(self.path["in_use"]) if item != ""]
+        return []
+
+    def __read_file_by_line(self, file_path: str):
+        if os.path.isfile(file_path):
+            with open(file_path, "r", encoding="utf-8") as handle:
+                return handle.read().split("\n")
+        return []
+
+    @staticmethod
+    def _normalize_channel_name(path: str | Path) -> str:
+        """Validate a `.jsonl` channel path.
+
+        Args:
+            path: Candidate file path.
+
+        Returns:
+            The normalized filesystem path string.
+
+        Raises:
+            ValueError: If the file name does not end with `.jsonl`.
+        """
+        file_path = os.fspath(path)
+        if not file_path.endswith(".jsonl"):
+            raise ValueError(f'Path must end with ".jsonl" > "{file_path}"')
+        return file_path
+
+    @staticmethod
+    def _serialize_record(record) -> str:
+        """Convert a record to the line format stored by this driver.
+
+        Args:
+            record: String or JSON-serializable value.
+
+        Returns:
+            A single-line string ready to append to the queue file.
+        """
+        if isinstance(record, str):
+            return record
+        return json.dumps(record, ensure_ascii=False, separators=(",", ":"))

pistributer_sqlite.py

@@ -0,0 +1,210 @@
+"""SQLite-backed `pistributer` driver.
+
+This module is the integrity-first local queue in the project.
+
+Use it when correctness matters more than the shortest append path.
+It has a different public naming style for `is_empty()` because it was added as
+the newer SQLite-specific driver, but the existing name is kept stable.
+
+Example:
+    >>> from pistributer_sqlite import PistributerSqlite
+    >>> queue = PistributerSqlite("events.db")
+    >>> queue.put("start")
+    True
+    >>> queue.close()
+"""
+
+from __future__ import annotations
+
+import os
+import sqlite3
+from pathlib import Path
+
+__all__ = ["PistributerSqlite"]
+
+
+class PistributerSqlite:
+    """Queue interface backed by a local SQLite database."""
+
+    def __init__(self, path: str | Path):
+        """Open or create a `.db` queue file.
+
+        Args:
+            path: Path to the SQLite database file. The path must end with `.db`.
+
+        Returns:
+            None.
+
+        Raises:
+            ValueError: If `path` does not end with `.db`.
+
+        Example:
+            >>> PistributerSqlite("events.db")
+        """
+        self.path = self._normalize_db_path(path)
+        parent_dir = os.path.dirname(self.path)
+        if parent_dir and not os.path.isdir(parent_dir):
+            os.makedirs(parent_dir, exist_ok=True)
+        self.connection = sqlite3.connect(self.path, timeout=30, isolation_level=None)
+        self.connection.execute("PRAGMA journal_mode=WAL")
+        self.connection.execute("PRAGMA synchronous=FULL")
+        self.connection.execute(
+            "CREATE TABLE IF NOT EXISTS pistributer_queue (id INTEGER PRIMARY KEY AUTOINCREMENT, payload TEXT NOT NULL, consumed INTEGER NOT NULL DEFAULT 0)"
+        )
+        self.connection.execute(
+            "CREATE INDEX IF NOT EXISTS idx_pistributer_queue_consumed_id ON pistributer_queue(consumed, id)"
+        )
+
+    @staticmethod
+    def new(target_path: str | Path, rows, overwrite: bool = False) -> bool:
+        """Create a new SQLite queue and preload rows.
+
+        Args:
+            target_path: Destination `.db` file.
+            rows: Iterable of payloads to insert.
+            overwrite: When `True`, allow replacing an existing database file.
+
+        Returns:
+            True when the database is created and populated successfully.
+
+        Raises:
+            ValueError: If `target_path` does not end with `.db`.
+            FileExistsError: If the file already exists and `overwrite` is `False`.
+
+        Example:
+            >>> PistributerSqlite.new("events.db", ["start"], overwrite=True)
+            True
+        """
+        db_path = PistributerSqlite._normalize_db_path(target_path)
+        if os.path.exists(db_path) and not overwrite:
+            raise FileExistsError(f'File exists "{db_path}"')
+        if os.path.exists(db_path) and overwrite:
+            os.remove(db_path)
+        queue = PistributerSqlite(db_path)
+        queue.put_many(rows)
+        queue.close()
+        return True
+
+    def put(self, payload: str) -> bool:
+        """Append one payload to the queue.
+
+        Args:
+            payload: Value to store. It is converted to string before insert.
+
+        Returns:
+            True when the insert succeeds.
+
+        Example:
+            >>> queue = PistributerSqlite("events.db")
+            >>> queue.put("finish")
+            True
+        """
+        self.connection.execute("INSERT INTO pistributer_queue (payload) VALUES (?)", (str(payload),))
+        return True
+
+    def put_many(self, payloads) -> bool:
+        """Append many payloads in one transaction.
+
+        Args:
+            payloads: Iterable of values to store.
+
+        Returns:
+            True when the batch insert succeeds.
+
+        Example:
+            >>> queue = PistributerSqlite("events.db")
+            >>> queue.put_many(["a", "b"])
+            True
+        """
+        with self.connection:
+            self.connection.executemany(
+                "INSERT INTO pistributer_queue (payload) VALUES (?)",
+                [(str(payload),) for payload in payloads],
+            )
+        return True
+
+    def next(self) -> str:
+        """Return the next unread payload.
+
+        Returns:
+            The next stored payload as a string.
+
+        Raises:
+            StopIteration: If the queue is empty.
+
+        Example:
+            >>> queue = PistributerSqlite("events.db")
+            >>> queue.next()
+        """
+        with self.connection:
+            row = self.connection.execute(
+                "SELECT id, payload FROM pistributer_queue WHERE consumed = 0 ORDER BY id LIMIT 1"
+            ).fetchone()
+            if row is None:
+                raise StopIteration("PistributerSqlite queue is empty")
+            self.connection.execute("UPDATE pistributer_queue SET consumed = 1 WHERE id = ?", (row[0],))
+        return row[1]
+
+    def is_empty(self) -> bool:
+        """Report whether unread payloads remain.
+
+        Returns:
+            True when no unread rows remain, otherwise False.
+
+        Example:
+            >>> queue = PistributerSqlite("events.db")
+            >>> queue.is_empty()
+            True
+        """
+        row = self.connection.execute(
+            "SELECT 1 FROM pistributer_queue WHERE consumed = 0 LIMIT 1"
+        ).fetchone()
+        return row is None
+
+    def size(self) -> int:
+        """Count all rows in the queue table.
+
+        Returns:
+            The total number of stored rows.
+        """
+        row = self.connection.execute("SELECT COUNT(*) FROM pistributer_queue").fetchone()
+        return int(row[0]) if row else 0
+
+    def remaining(self) -> int:
+        """Count unread rows in the queue table.
+
+        Returns:
+            The number of rows that have not been consumed yet.
+        """
+        row = self.connection.execute("SELECT COUNT(*) FROM pistributer_queue WHERE consumed = 0").fetchone()
+        return int(row[0]) if row else 0
+
+    def close(self) -> None:
+        """Close the SQLite connection.
+
+        Returns:
+            None.
+
+        Example:
+            >>> queue = PistributerSqlite("events.db")
+            >>> queue.close()
+        """
+        self.connection.close()
+
+    @staticmethod
+    def _normalize_db_path(path: str | Path) -> str:
+        """Validate a `.db` queue path.
+
+        Args:
+            path: Candidate database file path.
+
+        Returns:
+            The normalized filesystem path string.
+
+        Raises:
+            ValueError: If the file name does not end with `.db`.
+        """
+        file_path = os.fspath(path)
+        if not file_path.endswith(".db"):
+            raise ValueError(f'Path must end with ".db" > "{file_path}"')
+        return file_path

pistributer_txt.py

@@ -0,0 +1,281 @@
+"""Text-first `pistributer` driver.
+
+This module preserves the shortest file-backed queue path in the project.
+
+Use it when you want raw text throughput and simple append-heavy local queueing.
+Like the JSONL file driver, it is best for staged workflows or
+single-writer-friendly usage. It is not designed for strong overlapping
+writer and reader integrity.
+The hot write path assumes the parent directory already exists.
+
+Example:
+    >>> from pistributer_txt import PistributerTxt
+    >>> PistributerTxt.put("events.txt", "start")
+    True
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+__all__ = ["PistributerTxt"]
+
+
+class PistributerTxt:
+    """Queue interface for plain-text channel files.
+
+    The public method names intentionally preserve the historical file-driver
+    API, including `isEmpty()` and `getIndex()`.
+    """
+
+    def __init__(self, path: str | Path):
+        """Open a queue backed by a `.txt` file.
+
+        Args:
+            path: Path to the queue file. The path must end with `.txt`.
+
+        Returns:
+            None.
+
+        Raises:
+            ValueError: If `path` does not end with `.txt`.
+
+        Example:
+            >>> PistributerTxt("events.txt")
+        """
+        channel_path = self._normalize_channel_name(path)
+        self.abspath = "" if os.sep not in channel_path else os.path.abspath(".")
+        self.path = {
+            "data": os.path.abspath(os.path.join(self.abspath, channel_path)),
+            "index": os.path.abspath(os.path.join(self.abspath, f"{channel_path}.index")),
+            "in_use": os.path.abspath(os.path.join(self.abspath, f"{channel_path}.in_use")),
+        }
+        self.q: list[str] = []
+        self.__index = {"index": 0}
+        self.__initial_queue()
+
+    @staticmethod
+    def new(target_path: str | Path, string, overwrite: bool = False, sep: str = "") -> bool:
+        """Create a new `.txt` queue file with one initial line.
+
+        Args:
+            target_path: Destination `.txt` file.
+            string: Text payload to write.
+            overwrite: When `True`, allow replacing an existing file.
+            sep: Optional trailing separator to append.
+
+        Returns:
+            True when the file is created successfully.
+
+        Raises:
+            ValueError: If `target_path` does not end with `.txt`.
+            IsADirectoryError: If `target_path` points to a directory.
+            FileExistsError: If the file already exists and `overwrite` is `False`.
+
+        Example:
+            >>> PistributerTxt.new("events.txt", "start", overwrite=True)
+            True
+        """
+        file_path = PistributerTxt._normalize_channel_name(target_path)
+        if os.path.isdir(file_path):
+            raise IsADirectoryError(f'This is a folder, require a file to write "{file_path}"')
+        if os.path.isfile(file_path) and overwrite is not True:
+            raise FileExistsError(f'File exists "{file_path}"')
+
+        parent_dir = os.path.dirname(file_path)
+        if parent_dir and not os.path.isdir(parent_dir):
+            os.makedirs(parent_dir, exist_ok=True)
+
+        with open(file_path, "w+", encoding="utf-8") as handle:
+            handle.write(f"{string}{sep}")
+            handle.flush()
+        return True
+
+    @staticmethod
+    def put(target_path: str | Path, string) -> bool:
+        """Append one text line to a `.txt` queue file.
+
+        Args:
+            target_path: Destination `.txt` file.
+            string: Text payload to append.
+
+        Returns:
+            True when the line is appended successfully.
+
+        Raises:
+            ValueError: If `target_path` does not end with `.txt`.
+            FileNotFoundError: If the parent directory does not already exist.
+
+        Example:
+            >>> PistributerTxt.put("events.txt", "finish")
+            True
+        """
+        file_path = PistributerTxt._normalize_channel_name(target_path)
+
+        with open(file_path, "a+", encoding="utf-8") as handle:
+            handle.write(f"{string}\n")
+            handle.flush()
+        return True
+
+    def next(self) -> str:
+        """Return the next unread text line.
+
+        Returns:
+            The next stored line.
+
+        Raises:
+            StopIteration: If the queue is empty.
+
+        Example:
+            >>> queue = PistributerTxt("events.txt")
+            >>> queue.next()
+        """
+        if self.isEmpty():
+            raise StopIteration("PistributerTxt queue is empty")
+        data = self.q[self.__index["index"]]
+        self.increaseIndex()
+        return data
+
+    def isEmpty(self) -> bool:
+        """Report whether the queue has unread text lines.
+
+        This historical camelCase name is kept for compatibility.
+
+        Returns:
+            True when no unread records remain, otherwise False.
+
+        Example:
+            >>> queue = PistributerTxt("events.txt")
+            >>> queue.isEmpty()
+            True
+        """
+        if self.__index["index"] >= len(self.q):
+            if os.path.isfile(self.path["index"]):
+                os.remove(self.path["index"])
+            if os.path.isfile(self.path["in_use"]):
+                os.remove(self.path["in_use"])
+            if os.path.isfile(self.path["data"]):
+                self.__initial_queue()
+                return False
+            return True
+        return False
+
+    def size(self) -> int:
+        """Count records across the active data and `.in_use` files.
+
+        Returns:
+            The total number of stored text lines for the channel.
+        """
+        size = 0
+        for file_path in (self.path["data"], self.path["in_use"]):
+            if os.path.isfile(file_path):
+                with open(file_path, encoding="utf-8") as handle:
+                    for _ in handle:
+                        size += 1
+        return size
+
+    def remaining(self) -> int:
+        """Count unread text lines.
+
+        Returns:
+            The number of records that have not been consumed yet.
+        """
+        return max(0, self.size() - self.getIndex()["index"])
+
+    def getIndex(self) -> dict[str, int]:
+        """Return the persisted read index.
+
+        Returns:
+            A dictionary with one key, `index`, storing the consumed count.
+        """
+        if os.path.isfile(self.path["index"]):
+            with open(self.path["index"], "r+", encoding="utf-8") as json_file:
+                try:
+                    output = json.load(json_file)
+                except Exception:
+                    return {"index": 0}
+            return output
+
+        with open(self.path["index"], "w+", encoding="utf-8") as handle:
+            json.dump({"index": 0}, handle)
+        return {"index": 0}
+
+    def updateIndex(self, count: int) -> None:
+        """Persist a new read index value.
+
+        Args:
+            count: Desired consumed count. Negative values are clamped to zero.
+
+        Returns:
+            None.
+        """
+        self.__index["index"] = max(0, count)
+        with open(self.path["index"], "w+", encoding="utf-8") as handle:
+            json.dump(self.__index, handle)
+
+    def increaseIndex(self, count: int = 1) -> None:
+        """Advance the persisted read index.
+
+        Args:
+            count: Number of consumed records to add.
+
+        Returns:
+            None.
+        """
+        self.updateIndex(self.__index["index"] + count)
+
+    def decreaseIndex(self, count: int = 1) -> None:
+        """Move the persisted read index backward.
+
+        Args:
+            count: Number of consumed records to subtract.
+
+        Returns:
+            None.
+        """
+        self.updateIndex(self.__index["index"] - count)
+
+    def __initial_queue(self) -> None:
+        self.__index = self.getIndex()
+        if os.path.isfile(self.path["in_use"]):
+            self.q = list(self.__read_in_use())
+            return
+        if os.path.isfile(self.path["data"]):
+            os.rename(self.path["data"], self.path["in_use"])
+            self.q = list(self.__read_in_use())
+            self.updateIndex(0)
+            return
+        self.q = []
+        if os.path.isfile(self.path["index"]):
+            os.remove(self.path["index"])
+
+    def __read_in_use(self):
+        if os.path.isfile(self.path["in_use"]):
+            return [item for item in self.__read_file_by_line(self.path["in_use"]) if item != ""]
+        return []
+
+    def __read_file_by_line(self, file_path: str):
+        if os.path.isfile(file_path):
+            with open(file_path, "r", encoding="utf-8") as handle:
+                return handle.read().split("\n")
+        return []
+
+    @staticmethod
+    def _normalize_channel_name(path: str | Path) -> str:
+        """Validate a `.txt` channel path.
+
+        Args:
+            path: Candidate file path.
+
+        Returns:
+            The normalized filesystem path string.
+
+        Raises:
+            ValueError: If the file name does not end with `.txt`.
+        """
+        file_path = os.fspath(path)
+        if not file_path.endswith(".txt"):
+            raise ValueError(f'Path must end with ".txt" > "{file_path}"')
+        return file_path