plocate2 0.1.0__tar.gz

plocate2-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+/dist/
+
+__pycache__/
+
+/.python-version

plocate2-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dustin Oprea
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

plocate2-0.1.0/PKG-INFO

@@ -0,0 +1,297 @@
+Metadata-Version: 2.4
+Name: plocate2
+Version: 0.1.0
+Summary: Python library and tools for reading plocate database files
+Project-URL: Homepage, https://github.com/dsoprea/PyPlocate
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: zstandard>=0.22.0
+Provides-Extra: build
+Requires-Dist: build; extra == 'build'
+Requires-Dist: twine; extra == 'build'
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# plocate
+
+[![PyPI version](https://img.shields.io/pypi/v/plocate2)](https://pypi.org/project/plocate2/)
+
+## Overview
+
+Python library and command-line tools for reading [plocate](https://plocate.sesse.net) database files (`plocate.db`), the default 'locate' implementation of Arch, Debian, Ubuntu, and other Linux distributions.
+
+This can enable an application to have immediate and optimized access to a reasonably up-to-date catalog of the complete filesystem and to *avoid the overhead of manually scanning every file*.
+
+This not only requires a Linux system that has *plocate* installed and running, but that you can wait, or manage the reality of having to wait, for the next plocate update before you can see new files.
+
+## Installation
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e .
+```
+
+## Usage Via Library
+
+Examples use the checked-in fixture at `asset/test/test.db` unless noted otherwise. That file is an `updatedb` snapshot of this repository, so paths in the output below are shown relative to the repository root (`./...`).
+
+Search via the trigram index on a healthy database (substring or glob patterns):
+
+```python
+import plocate
+
+with plocate.PlocateDatabase.open("asset/test/test.db") as database:
+    options = plocate.SearchOptions(force_indexed_search=True)
+    for path in plocate.search_database(database, "*.py", options=options):
+        print(path)
+```
+
+```
+./src/plocate/__init__.py
+./src/plocate/binary_reader.py
+./src/plocate/config.py
+...
+(37 paths)
+```
+
+Search via a full scan when the on-disk index is unreadable (for example, a truncated database):
+
+```python
+import plocate
+
+with plocate.PlocateDatabase.open("truncated-plocate.db") as database:
+    options = plocate.SearchOptions(force_linear_search=True)
+    for path in plocate.search_database(database, "readme", options=options):
+        print(path)
+```
+
+```
+/tmp/example/readme.txt
+```
+
+`search_database` also scans every filename block on healthy databases when the pattern cannot use the index, such as regex searches:
+
+```python
+import plocate
+
+options = plocate.SearchOptions(use_regex=True)
+with plocate.PlocateDatabase.open("asset/test/test.db") as database:
+    for path in plocate.search_database(database, r"\.py$", options=options):
+        print(path)
+```
+
+```
+./src/plocate/__init__.py
+./src/plocate/binary_reader.py
+./src/plocate/config.py
+...
+(37 paths)
+```
+
+Export indexed records:
+
+```python
+import plocate
+
+options = plocate.ExportOptions(include_pattern="*.py")
+with plocate.PlocateDatabase.open("asset/test/test.db") as database:
+    for record in plocate.iter_export_records(database, options=options):
+        print(record.to_dict())
+```
+
+```
+{'path': './src/plocate/__init__.py', 'docid': 0, 'block_index': 21, 'database_version': 1, 'max_version': 2, 'check_visibility': True, 'is_directory': False}
+{'path': './src/plocate/binary_reader.py', 'docid': 0, 'block_index': 22, 'database_version': 1, 'max_version': 2, 'check_visibility': True, 'is_directory': False}
+...
+(37 records)
+```
+
+Inspect indexed entries with metadata:
+
+```python
+import plocate
+
+# Synthetic example database with /tmp/example/... paths.
+with plocate.PlocateDatabase.open("example.db") as database:
+    for entry in database.iter_indexed_entries():
+        print(entry.path, entry.docid, entry.directory_time)
+```
+
+```
+/tmp/example/.catalog-repository.yaml 0 None
+/tmp/example/readme.txt 0 None
+/var/log/syslog 0 None
+```
+
+The `plocate.db` format does not store a dedicated "last updated" timestamp. The closest equivalent is the on-disk modification time of the database file itself.
+
+```python
+import plocate
+
+with plocate.PlocateDatabase.open("asset/test/test.db") as database:
+    modification_time = database.file_mtime()
+    print(modification_time)
+```
+
+```
+1779677352.9139218
+```
+
+The package also reads configuration blocks, directory timestamp streams, and trigram posting lists from real `plocate.db` files produced by upstream `updatedb` / `plocate-build`.
+
+## Usage Via Commandline
+
+The project is primarily meant to be used as a library. The command-line tools (`pl_stats`, `pl_search`, `pl_export`) are provided for testing, diagnosing, and general convenience; they wrap the same APIs documented above.
+
+Examples use `asset/test/test.db` unless noted otherwise. Paths are shown relative to the repository root where applicable.
+
+Print database statistics:
+
+```bash
+pl_stats /var/lib/plocate/plocate.db
+pl_stats --json asset/test/test.db
+```
+
+```
+$ pl_stats /var/lib/plocate/plocate.db
+database: /var/lib/plocate/plocate.db
+file size: ...
+indexed paths: ...
+...
+
+$ pl_stats --json asset/test/test.db
+{
+  "database_path": "asset/test/test.db",
+  "path_count": 104,
+  "num_docids": 4,
+  "version": 1,
+  "max_version": 2,
+  ...
+}
+```
+
+Search for paths:
+
+```bash
+pl_search asset/test/test.db pyproject.toml
+pl_search /var/lib/plocate/plocate.db -c '*.py'
+pl_search asset/test/test.db --regex 'pyproject\.toml$'
+pl_search asset/test/test.db -i readme
+pl_search asset/test/test.db -l 10 '*.py'
+```
+
+```
+$ pl_search asset/test/test.db pyproject.toml
+./pyproject.toml
+
+$ pl_search /var/lib/plocate/plocate.db -c '*.py'
+12345
+
+$ pl_search asset/test/test.db --regex 'pyproject\.toml$'
+./pyproject.toml
+
+$ pl_search asset/test/test.db -i readme
+./README.md
+./.pytest_cache/README.md
+
+$ pl_search asset/test/test.db -l 10 '*.py'
+./src/plocate/__init__.py
+./src/plocate/binary_reader.py
+./src/plocate/config.py
+./src/plocate/constants.py
+./src/plocate/database.py
+./src/plocate/directory_data.py
+./src/plocate/errors.py
+./src/plocate/export.py
+./src/plocate/filename_index.py
+./src/plocate/formatting.py
+```
+
+`pl_search` uses the database trigram index on healthy `plocate.db` files. Upstream `updatedb` / `plocate-build` always write the hash table and posting lists, so a complete database normally has an index. Substring and glob searches narrow candidate filename blocks through that hash table, then verify matches in those blocks.
+
+If the file is truncated or header metadata points past EOF, the reader treats the index as absent and falls back to a full scan of every filename block. Results can still be correct, but the search is slower. Use `--scan` to force that path, or `--indexed` to require trigram-index search. Regex searches (`-r` / `--regex`) always use a full scan, even on healthy databases, because patterns are not indexed the same way.
+
+Indexed search on a healthy database (typical case):
+
+```bash
+pl_search /var/lib/plocate/plocate.db '*.py'
+pl_search asset/test/test.db --indexed '*.py'
+```
+
+```
+$ pl_search asset/test/test.db --indexed '*.py'
+./src/plocate/__init__.py
+./src/plocate/binary_reader.py
+./src/plocate/config.py
+...
+(37 paths)
+```
+
+Full-scan fallback when the on-disk index is unreadable (for example, a truncated copy of the same file):
+
+```bash
+# Same command; pl_search scans all path blocks instead of the hash table.
+pl_search truncated-plocate.db readme
+pl_search asset/test/test.db --scan '*.py'
+```
+
+```
+$ pl_search truncated-plocate.db readme
+/tmp/example/readme.txt
+
+$ pl_search asset/test/test.db --scan '*.py'
+./src/plocate/__init__.py
+./src/plocate/binary_reader.py
+./src/plocate/config.py
+...
+(37 paths)
+```
+
+Export indexed paths as JSON Lines:
+
+```bash
+pl_export asset/test/test.db
+pl_export asset/test/test.db --include './src/plocate/*'
+pl_export /var/lib/plocate/plocate.db --include '*.py'
+```
+
+```
+$ pl_export asset/test/test.db | head -n 1
+{"block_index": 0, "check_visibility": true, "database_version": 1, "directory_time_nanoseconds": ..., "directory_time_seconds": ..., "docid": 0, "is_directory": true, "max_version": 2, "path": "./.cursor"}
+
+$ pl_export asset/test/test.db --include './src/plocate/*' | head -n 1
+{"block_index": 21, "check_visibility": true, "database_version": 1, "docid": 0, "is_directory": false, "max_version": 2, "path": "./src/plocate/__init__.py"}
+
+$ pl_export /var/lib/plocate/plocate.db --include '*.py' | head -n 1
+{"block_index": ..., "path": "/usr/lib/python3.14/...", ...}
+```
+
+Each export row includes the path plus index and header metadata. When the database stores directory timestamps, directory entries also include `is_directory` and `directory_time_*` fields. Regular files include `is_directory: false` but do not store per-file timestamps.
+
+Example export row:
+
+```json
+{
+  "block_index": 1,
+  "check_visibility": false,
+  "database_version": 1,
+  "docid": 0,
+  "max_version": 1,
+  "path": "/tmp/example/readme.txt"
+}
+```
+
+## Layout
+
+- Library modules: `src/plocate/`
+- CLI entrypoints: `src/plocate/entrypoint/` (`pl_stats`, `pl_search`, `pl_export`)
+- Tests mirror library paths under `tests/`
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+Reading the database requires permission to open the file. On many systems `/var/lib/plocate/plocate.db` is readable only by the `locate` group or via the setgid `plocate` binary.

plocate2-0.1.0/README.md

@@ -0,0 +1,282 @@
+# plocate
+
+[![PyPI version](https://img.shields.io/pypi/v/plocate2)](https://pypi.org/project/plocate2/)
+
+## Overview
+
+Python library and command-line tools for reading [plocate](https://plocate.sesse.net) database files (`plocate.db`), the default 'locate' implementation of Arch, Debian, Ubuntu, and other Linux distributions.
+
+This can enable an application to have immediate and optimized access to a reasonably up-to-date catalog of the complete filesystem and to *avoid the overhead of manually scanning every file*.
+
+This not only requires a Linux system that has *plocate* installed and running, but that you can wait, or manage the reality of having to wait, for the next plocate update before you can see new files.
+
+## Installation
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e .
+```
+
+## Usage Via Library
+
+Examples use the checked-in fixture at `asset/test/test.db` unless noted otherwise. That file is an `updatedb` snapshot of this repository, so paths in the output below are shown relative to the repository root (`./...`).
+
+Search via the trigram index on a healthy database (substring or glob patterns):
+
+```python
+import plocate
+
+with plocate.PlocateDatabase.open("asset/test/test.db") as database:
+    options = plocate.SearchOptions(force_indexed_search=True)
+    for path in plocate.search_database(database, "*.py", options=options):
+        print(path)
+```
+
+```
+./src/plocate/__init__.py
+./src/plocate/binary_reader.py
+./src/plocate/config.py
+...
+(37 paths)
+```
+
+Search via a full scan when the on-disk index is unreadable (for example, a truncated database):
+
+```python
+import plocate
+
+with plocate.PlocateDatabase.open("truncated-plocate.db") as database:
+    options = plocate.SearchOptions(force_linear_search=True)
+    for path in plocate.search_database(database, "readme", options=options):
+        print(path)
+```
+
+```
+/tmp/example/readme.txt
+```
+
+`search_database` also scans every filename block on healthy databases when the pattern cannot use the index, such as regex searches:
+
+```python
+import plocate
+
+options = plocate.SearchOptions(use_regex=True)
+with plocate.PlocateDatabase.open("asset/test/test.db") as database:
+    for path in plocate.search_database(database, r"\.py$", options=options):
+        print(path)
+```
+
+```
+./src/plocate/__init__.py
+./src/plocate/binary_reader.py
+./src/plocate/config.py
+...
+(37 paths)
+```
+
+Export indexed records:
+
+```python
+import plocate
+
+options = plocate.ExportOptions(include_pattern="*.py")
+with plocate.PlocateDatabase.open("asset/test/test.db") as database:
+    for record in plocate.iter_export_records(database, options=options):
+        print(record.to_dict())
+```
+
+```
+{'path': './src/plocate/__init__.py', 'docid': 0, 'block_index': 21, 'database_version': 1, 'max_version': 2, 'check_visibility': True, 'is_directory': False}
+{'path': './src/plocate/binary_reader.py', 'docid': 0, 'block_index': 22, 'database_version': 1, 'max_version': 2, 'check_visibility': True, 'is_directory': False}
+...
+(37 records)
+```
+
+Inspect indexed entries with metadata:
+
+```python
+import plocate
+
+# Synthetic example database with /tmp/example/... paths.
+with plocate.PlocateDatabase.open("example.db") as database:
+    for entry in database.iter_indexed_entries():
+        print(entry.path, entry.docid, entry.directory_time)
+```
+
+```
+/tmp/example/.catalog-repository.yaml 0 None
+/tmp/example/readme.txt 0 None
+/var/log/syslog 0 None
+```
+
+The `plocate.db` format does not store a dedicated "last updated" timestamp. The closest equivalent is the on-disk modification time of the database file itself.
+
+```python
+import plocate
+
+with plocate.PlocateDatabase.open("asset/test/test.db") as database:
+    modification_time = database.file_mtime()
+    print(modification_time)
+```
+
+```
+1779677352.9139218
+```
+
+The package also reads configuration blocks, directory timestamp streams, and trigram posting lists from real `plocate.db` files produced by upstream `updatedb` / `plocate-build`.
+
+## Usage Via Commandline
+
+The project is primarily meant to be used as a library. The command-line tools (`pl_stats`, `pl_search`, `pl_export`) are provided for testing, diagnosing, and general convenience; they wrap the same APIs documented above.
+
+Examples use `asset/test/test.db` unless noted otherwise. Paths are shown relative to the repository root where applicable.
+
+Print database statistics:
+
+```bash
+pl_stats /var/lib/plocate/plocate.db
+pl_stats --json asset/test/test.db
+```
+
+```
+$ pl_stats /var/lib/plocate/plocate.db
+database: /var/lib/plocate/plocate.db
+file size: ...
+indexed paths: ...
+...
+
+$ pl_stats --json asset/test/test.db
+{
+  "database_path": "asset/test/test.db",
+  "path_count": 104,
+  "num_docids": 4,
+  "version": 1,
+  "max_version": 2,
+  ...
+}
+```
+
+Search for paths:
+
+```bash
+pl_search asset/test/test.db pyproject.toml
+pl_search /var/lib/plocate/plocate.db -c '*.py'
+pl_search asset/test/test.db --regex 'pyproject\.toml$'
+pl_search asset/test/test.db -i readme
+pl_search asset/test/test.db -l 10 '*.py'
+```
+
+```
+$ pl_search asset/test/test.db pyproject.toml
+./pyproject.toml
+
+$ pl_search /var/lib/plocate/plocate.db -c '*.py'
+12345
+
+$ pl_search asset/test/test.db --regex 'pyproject\.toml$'
+./pyproject.toml
+
+$ pl_search asset/test/test.db -i readme
+./README.md
+./.pytest_cache/README.md
+
+$ pl_search asset/test/test.db -l 10 '*.py'
+./src/plocate/__init__.py
+./src/plocate/binary_reader.py
+./src/plocate/config.py
+./src/plocate/constants.py
+./src/plocate/database.py
+./src/plocate/directory_data.py
+./src/plocate/errors.py
+./src/plocate/export.py
+./src/plocate/filename_index.py
+./src/plocate/formatting.py
+```
+
+`pl_search` uses the database trigram index on healthy `plocate.db` files. Upstream `updatedb` / `plocate-build` always write the hash table and posting lists, so a complete database normally has an index. Substring and glob searches narrow candidate filename blocks through that hash table, then verify matches in those blocks.
+
+If the file is truncated or header metadata points past EOF, the reader treats the index as absent and falls back to a full scan of every filename block. Results can still be correct, but the search is slower. Use `--scan` to force that path, or `--indexed` to require trigram-index search. Regex searches (`-r` / `--regex`) always use a full scan, even on healthy databases, because patterns are not indexed the same way.
+
+Indexed search on a healthy database (typical case):
+
+```bash
+pl_search /var/lib/plocate/plocate.db '*.py'
+pl_search asset/test/test.db --indexed '*.py'
+```
+
+```
+$ pl_search asset/test/test.db --indexed '*.py'
+./src/plocate/__init__.py
+./src/plocate/binary_reader.py
+./src/plocate/config.py
+...
+(37 paths)
+```
+
+Full-scan fallback when the on-disk index is unreadable (for example, a truncated copy of the same file):
+
+```bash
+# Same command; pl_search scans all path blocks instead of the hash table.
+pl_search truncated-plocate.db readme
+pl_search asset/test/test.db --scan '*.py'
+```
+
+```
+$ pl_search truncated-plocate.db readme
+/tmp/example/readme.txt
+
+$ pl_search asset/test/test.db --scan '*.py'
+./src/plocate/__init__.py
+./src/plocate/binary_reader.py
+./src/plocate/config.py
+...
+(37 paths)
+```
+
+Export indexed paths as JSON Lines:
+
+```bash
+pl_export asset/test/test.db
+pl_export asset/test/test.db --include './src/plocate/*'
+pl_export /var/lib/plocate/plocate.db --include '*.py'
+```
+
+```
+$ pl_export asset/test/test.db | head -n 1
+{"block_index": 0, "check_visibility": true, "database_version": 1, "directory_time_nanoseconds": ..., "directory_time_seconds": ..., "docid": 0, "is_directory": true, "max_version": 2, "path": "./.cursor"}
+
+$ pl_export asset/test/test.db --include './src/plocate/*' | head -n 1
+{"block_index": 21, "check_visibility": true, "database_version": 1, "docid": 0, "is_directory": false, "max_version": 2, "path": "./src/plocate/__init__.py"}
+
+$ pl_export /var/lib/plocate/plocate.db --include '*.py' | head -n 1
+{"block_index": ..., "path": "/usr/lib/python3.14/...", ...}
+```
+
+Each export row includes the path plus index and header metadata. When the database stores directory timestamps, directory entries also include `is_directory` and `directory_time_*` fields. Regular files include `is_directory: false` but do not store per-file timestamps.
+
+Example export row:
+
+```json
+{
+  "block_index": 1,
+  "check_visibility": false,
+  "database_version": 1,
+  "docid": 0,
+  "max_version": 1,
+  "path": "/tmp/example/readme.txt"
+}
+```
+
+## Layout
+
+- Library modules: `src/plocate/`
+- CLI entrypoints: `src/plocate/entrypoint/` (`pl_stats`, `pl_search`, `pl_export`)
+- Tests mirror library paths under `tests/`
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+Reading the database requires permission to open the file. On many systems `/var/lib/plocate/plocate.db` is readable only by the `locate` group or via the setgid `plocate` binary.

plocate2-0.1.0/development/build.sh

@@ -0,0 +1,5 @@
+#!/bin/bash -ex
+
+cd "$(dirname "$0")/.."
+
+python3 -m build

plocate2-0.1.0/development/generate.sh

@@ -0,0 +1,4 @@
+#!/bin/bash -ex
+
+updatedb -o test.db --database-root ./
+

plocate2-0.1.0/development/push.sh

@@ -0,0 +1,5 @@
+#!/bin/bash -ex
+
+cd "$(dirname "$0")/.."
+
+python3 -m twine upload dist/*

plocate2-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "plocate2"
+version = "0.1.0"
+description = "Python library and tools for reading plocate database files"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "zstandard>=0.22.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/dsoprea/PyPlocate"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+]
+build = [
+    "build",
+    "twine",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[project.scripts]
+pl_stats = "plocate.entrypoint.stats:main"
+pl_search = "plocate.entrypoint.search:main"
+pl_export = "plocate.entrypoint.export:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/plocate"]
+
+[tool.hatch.build.targets.wheel.sources]
+"src" = ""

plocate2-0.1.0/src/plocate/__init__.py

@@ -0,0 +1,21 @@
+"""Read and search plocate.db index files."""
+
+import plocate.database
+import plocate.export
+import plocate.search
+
+
+PlocateDatabase = plocate.database.PlocateDatabase
+ExportOptions = plocate.export.ExportOptions
+SearchOptions = plocate.search.SearchOptions
+
+iter_export_records = plocate.export.iter_export_records
+search_database = plocate.search.search_database
+
+__all__ = [
+    "ExportOptions",
+    "PlocateDatabase",
+    "SearchOptions",
+    "iter_export_records",
+    "search_database",
+]