Add new features for 0.3.0, improve hash handling

ef1500 · ef1500 · commit 8d5c150fe076 · 2026-01-19T18:04:39.000-07:00
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1,3 @@
+**/__pycache__/
+.venv/
+**/build/
diff --git a/libbbf/__init__.py b/libbbf/__init__.py
@@ -0,0 +1,19 @@
+# libbbf/__init__.py
+from ._bbf import BBFReader, BBFBuilder
+
+from .exceptions import (
+    BBFError, 
+    BBFNotFoundError, 
+    BBFInvalidFormatError, 
+    BBFCorruptionError
+)
+
+__all__ = [
+    "BBFReader", 
+    "BBFBuilder",
+    # Export exceptions
+    "BBFError",
+    "BBFNotFoundError",
+    "BBFInvalidFormatError",
+    "BBFCorruptionError"
+]
diff --git a/libbbf/bbf2cbx.py b/libbbf/bbf2cbx.py
diff --git a/libbbf/cbx2bbf.py b/libbbf/cbx2bbf.py
diff --git a/libbbf/exceptions.py b/libbbf/exceptions.py
@@ -0,0 +1,19 @@
+# libbbf/exceptions.py
+
+class BBFError(Exception):
+    """Base class for all exceptions in the libbbf library."""
+    pass
+
+class BBFNotFoundError(BBFError, FileNotFoundError):
+    """Raised when the BBF file cannot be found."""
+    pass
+
+class BBFInvalidFormatError(BBFError):
+    """Raised when the file exists but isn't a valid BBF (wrong magic/header)."""
+    pass
+
+class BBFCorruptionError(BBFError):
+    """Raised when a hash check fails."""
+    def __init__(self, message: str, asset_index: int = -1):
+        super().__init__(message)
+        self.asset_index = asset_index
diff --git a/libbbf_tools/__init__.py b/libbbf_tools/__init__.py
diff --git a/setup.py b/setup.py
@@ -21,7 +21,7 @@
 # Define the C++ extension
 ext_modules = [
     Pybind11Extension(
-        "libbbf",
+        "libbbf._bbf",
         [
             "src/bindings.cpp",
             "src/libbbf.cpp",
@@ -34,7 +34,7 @@
 
 setup(
     name="libbbf",
-    version="0.2.13",
+    version="0.3.0",
     author="EF1500",
     author_email="rosemilovelockofficial@proton.me",
     description="Bound Book Format (BBF) tools and bindings",
@@ -48,8 +48,8 @@
     
     entry_points={
         "console_scripts": [
-            "cbx2bbf=libbbf_tools.cbx2bbf:main",
-            "bbf2cbx=libbbf_tools.bbf2cbx:main",
+            "cbx2bbf=libbbf.cbx2bbf:main",
+            "bbf2cbx=libbbf.bbf2cbx:main",
         ],
     },
     
diff --git a/src/bbf_reader.h b/src/bbf_reader.h
@@ -76,7 +76,8 @@ struct MemoryMappedFile {
     ~MemoryMappedFile() { unmap(); }
 };
 
-class BBFReader {
+class BBFReader 
+{
 private:
     const char* data_ptr = nullptr;
     const BBFSection* sections_ = nullptr;
@@ -92,7 +93,8 @@ class BBFReader {
     MemoryMappedFile mmap;
     bool isValid = false;
 
-    BBFReader(const std::string& path) {
+    BBFReader(const std::string& path) 
+    {
         if (!mmap.map(path)) return;
         data_ptr = static_cast<const char*>(mmap.data);
 
@@ -121,24 +123,31 @@ class BBFReader {
         isValid = true;
     }
 
-    std::string_view getStringView(uint32_t offset) const {
+    // Get string view
+    std::string_view getStringView(uint32_t offset) const 
+    {
         if (offset >= stringPoolSize_) return {};
         return std::string_view(stringPool_ + offset);
     }
 
-    struct PySection {
+    struct PySection 
+    {
         std::string title;
         uint32_t startPage;
         uint32_t parent;
     };
 
-    std::vector<PySection> getSections() const {
+    // Get sections
+    std::vector<PySection> getSections() const 
+    {
         std::vector<PySection> result;
         if (!isValid) return result;
         
         result.reserve(footer.sectionCount);
-        for (uint32_t i = 0; i < footer.sectionCount; i++) {
-            result.push_back({
+        for (uint32_t i = 0; i < footer.sectionCount; i++) 
+        {
+            result.push_back(
+                {
                 std::string(getStringView(sections_[i].sectionTitleOffset)), 
                 sections_[i].sectionStartIndex, 
                 sections_[i].parentSectionIndex
@@ -147,12 +156,15 @@ class BBFReader {
         return result;
     }
 
-    std::vector<std::pair<std::string, std::string>> getMetadata() const {
+    // Get metadata
+    std::vector<std::pair<std::string, std::string>> getMetadata() const 
+    {
         std::vector<std::pair<std::string, std::string>> result;
         if (!isValid) return result;
 
         result.reserve(footer.keyCount);
-        for (uint32_t i = 0; i < footer.keyCount; i++) {
+        for (uint32_t i = 0; i < footer.keyCount; i++) 
+        {
             result.emplace_back(
                 getStringView(meta_[i].keyOffset), 
                 getStringView(meta_[i].valOffset)
@@ -161,7 +173,9 @@ class BBFReader {
         return result;
     }
 
-    std::pair<const char*, size_t> getPageRaw(uint32_t pageIndex) const {
+    // Get page raw
+    std::pair<const char*, size_t> getPageRaw(uint32_t pageIndex) const 
+    {
         if (!isValid || pageIndex >= footer.pageCount) return {nullptr, 0};
         
         const auto& asset = assets_[pages_[pageIndex].assetIndex];
@@ -171,7 +185,36 @@ class BBFReader {
         return { data_ptr + asset.offset, static_cast<size_t>(asset.length) };
     }
 
-    std::map<std::string, uint64_t> getPageInfo(uint32_t pageIndex) const {
+    // Get footer info
+    std::map<std::string, uint64_t> getFooterInfo() const
+    {
+        // If invalid, return empty set.
+        if (!isValid) return {};
+
+        // Otherwise return all this juicy information!
+        return 
+        {
+            {"stringPoolOffset", footer.stringPoolOffset},
+            {"assetTableOffset", footer.assetTableOffset},
+            {"assetCount", static_cast<uint64_t>(footer.assetCount)},
+
+            {"pageTableOffset", footer.pageTableOffset},
+            {"pageCount", static_cast<uint64_t>(footer.pageCount)},
+
+            {"sectionTableOffset", footer.sectionTableOffset},
+            {"sectionCount", footer.sectionCount},
+
+            {"metaTableOffset", footer.metaTableOffset},
+            {"keyCount", static_cast<uint64_t>(footer.keyCount)},
+
+            {"extraOffset", footer.extraOffset},
+            {"indexHash", footer.indexHash}
+        };
+    }
+
+    // Get page info
+    std::map<std::string, uint64_t> getPageInfo(uint32_t pageIndex) const 
+    {
         if (!isValid || pageIndex >= footer.pageCount) return {};
 
         const auto& asset = assets_[pages_[pageIndex].assetIndex];
@@ -180,12 +223,29 @@ class BBFReader {
             {"offset", asset.offset},
             {"hash", asset.xxh3Hash},
             {"type", asset.type},
+            {"flags", asset.flags}, // Add flags
             {"decodedLength", asset.decodedLength} // ADDED: v1.1 Spec
         };
     }
 
+    // verify a specific page
+    std::map<uint64_t, bool> verifyPage(uint32_t pageIndex)
+    {
+        if (!isValid || pageIndex >= footer.pageCount) return {};
+        // Get page
+        const auto& asset = assets_[pages_[pageIndex].assetIndex];
+        // Check mmap length
+        if (asset.offset + asset.length > mmap.size) return {};
+        // hash
+        uint64_t xxhHash = XXH3_64bits((const uint8_t*)data_ptr + asset.offset, asset.length);
+
+        bool match = (xxhHash == asset.xxh3Hash);
+        return {{xxhHash, match}};
+    }
+
     // Returns -1 for Success, -2 for Directory Error, or >=0 for Asset Index Error
-    int64_t verify() const {
+    int64_t verify() const 
+    {
         if (!isValid) return -2;
         
         // 1. Directory Hash Check
@@ -200,13 +260,16 @@ class BBFReader {
         size_t max_size = mmap.size;
 
         // Lambda returns -1 if OK, or the index if Bad
-        auto verifyRange = [local_assets, local_data, max_size](size_t start, size_t end) -> int64_t {
-            for (size_t i = start; i < end; ++i) {
+        auto verifyRange = [local_assets, local_data, max_size](size_t start, size_t end) -> int64_t 
+        {
+            for (size_t i = start; i < end; ++i) 
+            {
                 const auto& a = local_assets[i];
                 // Bounds check before hash
                 if (a.offset + a.length > max_size) return (int64_t)i;
                 
-                if (XXH3_64bits((const uint8_t*)local_data + a.offset, a.length) != a.xxh3Hash) {
+                if (XXH3_64bits((const uint8_t*)local_data + a.offset, a.length) != a.xxh3Hash) 
+                {
                     return (int64_t)i; // Return the corrupted index
                 }
             }
@@ -216,22 +279,25 @@ class BBFReader {
         size_t numThreads = std::thread::hardware_concurrency();
         if (numThreads == 0) numThreads = 1;
 
-        if (count < 128 || numThreads == 1) {
+        if (count < 128 || numThreads == 1) 
+        {
             return verifyRange(0, count);
         }
 
         size_t chunkSize = count / numThreads;
         std::vector<std::future<int64_t>> futures; // Changed from bool to int64_t
         futures.reserve(numThreads);
 
-        for (size_t i = 0; i < numThreads; ++i) {
+        for (size_t i = 0; i < numThreads; ++i) 
+        {
             size_t start = i * chunkSize;
             size_t end = (i == numThreads - 1) ? count : start + chunkSize;
             futures.push_back(std::async(std::launch::async, verifyRange, start, end));
         }
 
         // Check results
-        for (auto& f : futures) {
+        for (auto& f : futures) 
+        {
             int64_t result = f.get();
             if (result != -1) return result; // Bubble up the error index
         }
diff --git a/src/bindings.cpp b/src/bindings.cpp
@@ -5,7 +5,7 @@
 
 namespace py = pybind11;
 
-PYBIND11_MODULE(libbbf, m) {
+PYBIND11_MODULE(_bbf, m) {
     m.doc() = "Bound Book Format (BBF) Python Bindings";
 
     // --- BBFBuilder (Writer) ---
@@ -26,15 +26,24 @@ PYBIND11_MODULE(libbbf, m) {
     py::class_<BBFReader>(m, "BBFReader")
         .def(py::init<const std::string &>())
         .def_readonly("is_valid", &BBFReader::isValid)
-        // We don't need to expose footer struct directly unless you wrote a binding for BBFFooter
+        .def("close", [](BBFReader& r) 
+        { 
+          r.mmap.unmap(); 
+          r.isValid = false; // Prevent further reads
+        }, "Unmaps the file immediately.")
+
         .def("get_page_count", [](BBFReader& r) { return r.footer.pageCount; })
         .def("get_asset_count", [](BBFReader& r) { return r.footer.assetCount; })
         
         .def("verify", &BBFReader::verify, 
              py::call_guard<py::gil_scoped_release>(), 
              "Verify integrity. Returns: -1 (Success), -2 (Directory Fail), or >=0 (Index of corrupt asset).")
+     
+        .def("verify_page", &BBFReader::verifyPage,
+             "Verify a single page, returns a dict <uint64_t, bool>, {calculated hash, match?}.")
 
-        .def("get_sections", [](BBFReader& r) {
+        .def("get_sections", [](BBFReader& r) 
+        {
             py::list result;
             const auto sections = r.getSections();
             for (const auto& s : sections) {
@@ -47,19 +56,24 @@ PYBIND11_MODULE(libbbf, m) {
             return result;
         }, "Returns sections as [{'title': str, 'startPage': int, 'parent': int}]")
         
+        .def("get_footer", &BBFReader::getFooterInfo, 
+             "Returns a dict representing the footer.")
+
         .def("get_metadata", &BBFReader::getMetadata,
              "Returns a list of (Key, Value) tuples.")
              
         .def("get_page_info", &BBFReader::getPageInfo,
              "Returns dict with keys: length, offset, hash, type, decodedLength")
 
-        .def("get_page_data", [](BBFReader& r, uint32_t idx) {
+        .def("get_page_data", [](BBFReader& r, uint32_t idx) 
+        {
              auto raw = r.getPageRaw(idx);
              if (!raw.first) return py::bytes("");
              return py::bytes(raw.first, raw.second);
         }, "Returns the raw bytes of the page asset (1-Copy).")
 
-        .def("get_page_view", [](BBFReader& r, uint32_t idx) {
+        .def("get_page_view", [](BBFReader& r, uint32_t idx) 
+        {
              auto raw = r.getPageRaw(idx);
              if (!raw.first) return py::memoryview(py::bytes("")); 
              

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+**/__pycache__/`
	`2`	`+.venv/`
	`3`	`+**/build/`