pyrex-rocksdb 0.1.0__cp312-cp312-macosx_14_0_arm64.whl → 0.1.4__cp312-cp312-macosx_14_0_arm64.whl

pyrex/_pyrex.cpp

@@ -1,9 +1,14 @@
-// rocksdb_wrapper.cpp
 #include <pybind11/pybind11.h>
 #include <pybind11/stl.h>
 
-// NEW: Include for std::unique_ptr
 #include <memory>
+#include <vector>
+#include <map>
+#include <set>
+#include <string>
+#include <mutex>
+#include <atomic>
+#include <iostream>
 
 #include "rocksdb/db.h"
 #include "rocksdb/options.h"
@@ -14,289 +19,734 @@
 #include "rocksdb/write_batch.h"
 #include "rocksdb/iterator.h"
 
-#include <iostream>
-#include <string>
-#include <cstring>
-
 namespace py = pybind11;
 
-// Define a custom exception for RocksDB errors
+// --- Custom Exception ---
 class RocksDBException : public std::runtime_error {
 public:
     explicit RocksDBException(const std::string& msg) : std::runtime_error(msg) {}
 };
 
-// --- PyOptions class to wrap rocksdb::Options ---
+// --- Forward Declarations ---
+class PyRocksDB;
+
+// --- PyReadOptions Wrapper ---
+class PyReadOptions {
+public:
+    rocksdb::ReadOptions options_;
+
+    PyReadOptions() = default;
+
+    // Expose properties to Python
+    bool get_fill_cache() const { return options_.fill_cache; }
+    void set_fill_cache(bool value) { options_.fill_cache = value; }
+
+    bool get_verify_checksums() const { return options_.verify_checksums; }
+    void set_verify_checksums(bool value) { options_.verify_checksums = value; }
+};
+
+// --- PyWriteOptions Wrapper ---
+class PyWriteOptions {
+public:
+    rocksdb::WriteOptions options_;
+
+    PyWriteOptions() = default;
+
+    // Expose properties to Python
+    bool get_sync() const { return options_.sync; }
+    void set_sync(bool value) { options_.sync = value; }
+
+    bool get_disable_wal() const { return options_.disableWAL; }
+    void set_disable_wal(bool value) { options_.disableWAL = value; }
+};
+
+
+// --- PyOptions Wrapper ---
 class PyOptions {
 public:
     rocksdb::Options options_;
+    rocksdb::ColumnFamilyOptions cf_options_;
 
-    PyOptions() : options_() {}
-
+    PyOptions() {
+        options_.compression = rocksdb::kSnappyCompression;
+        cf_options_.compression = rocksdb::kSnappyCompression;
+    }
     bool get_create_if_missing() const { return options_.create_if_missing; }
     void set_create_if_missing(bool value) { options_.create_if_missing = value; }
-
     bool get_error_if_exists() const { return options_.error_if_exists; }
     void set_error_if_exists(bool value) { options_.error_if_exists = value; }
-
     int get_max_open_files() const { return options_.max_open_files; }
     void set_max_open_files(int value) { options_.max_open_files = value; }
-
     size_t get_write_buffer_size() const { return options_.write_buffer_size; }
     void set_write_buffer_size(size_t value) { options_.write_buffer_size = value; }
-
     rocksdb::CompressionType get_compression() const { return options_.compression; }
     void set_compression(rocksdb::CompressionType value) { options_.compression = value; }
-
     int get_max_background_jobs() const { return options_.max_background_jobs; }
     void set_max_background_jobs(int value) { options_.max_background_jobs = value; }
-
-    void increase_parallelism(int total_threads) {
-        options_.IncreaseParallelism(total_threads);
-    }
-
-    void optimize_for_small_db() {
-        options_.OptimizeForSmallDb();
-    }
-
+    void increase_parallelism(int total_threads) { options_.IncreaseParallelism(total_threads); }
+    void optimize_for_small_db() { options_.OptimizeForSmallDb(); }
     void use_block_based_bloom_filter(double bits_per_key = 10.0) {
-        if (options_.table_factory == nullptr ||
-            std::strcmp(options_.table_factory->Name(), "BlockBasedTable") != 0) {
-            options_.table_factory.reset(rocksdb::NewBlockBasedTableFactory());
-        }
-
         rocksdb::BlockBasedTableOptions table_options;
-        // NOTE: This part assumes we are creating a new policy, not modifying an existing one.
-        // This is a reasonable simplification for a wrapper.
-        
-        // Create a new bloom filter policy
         table_options.filter_policy.reset(rocksdb::NewBloomFilterPolicy(bits_per_key));
         options_.table_factory.reset(rocksdb::NewBlockBasedTableFactory(table_options));
+        cf_options_.table_factory.reset(rocksdb::NewBlockBasedTableFactory(table_options));
     }
+    size_t get_cf_write_buffer_size() const { return cf_options_.write_buffer_size; }
+    void set_cf_write_buffer_size(size_t value) { cf_options_.write_buffer_size = value; }
+    rocksdb::CompressionType get_cf_compression() const { return cf_options_.compression; }
+    void set_cf_compression(rocksdb::CompressionType value) { cf_options_.compression = value; }
 };
 
-// --- PyWriteBatch class to wrap rocksdb::WriteBatch ---
-class PyWriteBatch {
+// --- PyColumnFamilyHandle Wrapper ---
+class PyColumnFamilyHandle {
 public:
-    rocksdb::WriteBatch wb_;
+    rocksdb::ColumnFamilyHandle* cf_handle_;
+    std::string name_;
 
-    PyWriteBatch() : wb_() {}
-
-    void put(const py::bytes& key_bytes, const py::bytes& value_bytes) {
-        wb_.Put(static_cast<std::string>(key_bytes), static_cast<std::string>(value_bytes));
+    PyColumnFamilyHandle(rocksdb::ColumnFamilyHandle* handle, const std::string& name)
+        : cf_handle_(handle), name_(name) {
+        if (!cf_handle_) {
+            throw RocksDBException("Invalid ColumnFamilyHandle received.");
+        }
     }
+    const std::string& get_name() const { return name_; }
+    bool is_valid() const { return cf_handle_ != nullptr; }
+};
 
-    void del(const py::bytes& key_bytes) {
-        wb_.Delete(static_cast<std::string>(key_bytes));
+// --- PyWriteBatch Wrapper ---
+class PyWriteBatch {
+public:
+    rocksdb::WriteBatch wb_;
+    PyWriteBatch() = default;
+    void put(const py::bytes& key, const py::bytes& value) { wb_.Put(static_cast<std::string>(key), static_cast<std::string>(value)); }
+    void put_cf(PyColumnFamilyHandle& cf, const py::bytes& key, const py::bytes& value) {
+        if (!cf.is_valid()) throw RocksDBException("ColumnFamilyHandle is invalid.");
+        rocksdb::Slice key_slice(static_cast<std::string_view>(key));
+        rocksdb::Slice value_slice(static_cast<std::string_view>(value));
+        wb_.Put(cf.cf_handle_, key_slice, value_slice);
     }
-
-    void clear() {
-        wb_.Clear();
+    void del(const py::bytes& key) { 
+        rocksdb::Slice key_slice(static_cast<std::string_view>(key));
+        wb_.Delete(key_slice); 
     }
+    void del_cf(PyColumnFamilyHandle& cf, const py::bytes& key) {
+        if (!cf.is_valid()) throw RocksDBException("ColumnFamilyHandle is invalid.");
+        rocksdb::Slice key_slice(static_cast<std::string_view>(key));
+        wb_.Delete(cf.cf_handle_, key_slice);
+    }
+    void merge(const py::bytes& key, const py::bytes& value) { 
+        rocksdb::Slice key_slice(static_cast<std::string_view>(key));
+        rocksdb::Slice value_slice(static_cast<std::string_view>(value));
+        wb_.Merge(key_slice, value_slice); 
+    }
+    void merge_cf(PyColumnFamilyHandle& cf, const py::bytes& key, const py::bytes& value) {
+        if (!cf.is_valid()) throw RocksDBException("ColumnFamilyHandle is invalid.");
+        rocksdb::Slice key_slice(static_cast<std::string_view>(key));
+        rocksdb::Slice value_slice(static_cast<std::string_view>(value));
+        wb_.Merge(cf.cf_handle_, key_slice, value_slice);
+    }
+    void clear() { wb_.Clear(); }
 };
 
-// --- PyRocksDBIterator class to wrap rocksdb::Iterator ---
+// --- PyRocksDBIterator Class Declaration ---
 class PyRocksDBIterator {
+private:
+    rocksdb::Iterator* it_raw_ptr_;
+    std::shared_ptr<PyRocksDB> parent_db_ptr_;
+    void check_parent_db_is_open() const;
+
 public:
-    // Raw pointer to the RocksDB Iterator.
-    // The lifetime of this pointer is managed by this class's constructor/destructor.
-    rocksdb::Iterator* it_;
+    explicit PyRocksDBIterator(rocksdb::Iterator* it, std::shared_ptr<PyRocksDB> parent_db);
+    ~PyRocksDBIterator();
+    bool valid();
+    void seek_to_first();
+    void seek_to_last();
+    void seek(const py::bytes& key);
+    void next();
+    void prev();
+    py::object key();
+    py::object value();
+    void check_status();
+};
+
+// --- PyRocksDB Class (Base) ---
+class PyRocksDB : public std::enable_shared_from_this<PyRocksDB> {
+protected:
+    rocksdb::DB* db_ = nullptr;
+    rocksdb::ColumnFamilyHandle* default_cf_handle_ = nullptr;
+    PyOptions opened_options_;
+    std::string path_;
+    std::map<std::string, std::shared_ptr<PyColumnFamilyHandle>> cf_handles_;
+    std::atomic<bool> is_closed_{false};
+    std::atomic<bool> is_read_only_{false};
+    std::mutex active_iterators_mutex_;
+    std::set<rocksdb::Iterator*> active_rocksdb_iterators_;
+
+    // Default options for read/write operations
+    std::shared_ptr<PyReadOptions> default_read_options_;
+    std::shared_ptr<PyWriteOptions> default_write_options_;
+
+
+    friend class PyRocksDBIterator;
+
+    void check_db_open() const {
+        if (is_closed_ || db_ == nullptr) {
+            throw RocksDBException("Database is not open or has been closed.");
+        }
+    }
 
-    explicit PyRocksDBIterator(rocksdb::Iterator* it) : it_(it) {
-        if (!it_) {
-            throw RocksDBException("Failed to create RocksDB iterator: null pointer received.");
+    void check_read_only() const {
+        if (is_read_only_.load()) {
+            throw RocksDBException("Cannot perform put/write/delete operation: Database opened in read-only mode.");
         }
-        // std::cout << "DEBUG: Creating RocksDB iterator." << std::endl; // Optional: for debugging
     }
 
-    // Destructor: Ensures the C++ iterator is deleted when this object is destroyed.
-    ~PyRocksDBIterator() {
-        if (it_ != nullptr) {
-            std::cout << "DEBUG: Deleting RocksDB iterator." << std::endl;
-            delete it_;
-            it_ = nullptr;
+    rocksdb::ColumnFamilyHandle* get_default_cf_handle() const {
+        auto it = cf_handles_.find(rocksdb::kDefaultColumnFamilyName);
+        if (it == cf_handles_.end() || !it->second->is_valid()) {
+            throw RocksDBException("Default column family handle is not available.");
         }
+        return it->second->cf_handle_;
     }
 
-    bool valid() const {
-        return it_->Valid();
+public:
+    // Default constructor for inheritance
+    PyRocksDB() 
+        : default_read_options_(std::make_shared<PyReadOptions>()),
+          default_write_options_(std::make_shared<PyWriteOptions>())
+    {}
+
+    // Public constructor for the simple interface
+    PyRocksDB(const std::string& path, PyOptions* py_options,  bool read_only = false) 
+        : default_read_options_(std::make_shared<PyReadOptions>()),
+          default_write_options_(std::make_shared<PyWriteOptions>())
+    {
+        this->path_ = path;
+        this->is_read_only_.store(read_only);
+        rocksdb::Options options;
+        if (py_options) {
+            options = py_options->options_;
+            this->opened_options_ = *py_options;
+        } else {
+            options.create_if_missing = true;
+            this->opened_options_.options_ = options;
+        }
+
+        rocksdb::Status s;
+        if (read_only) { 
+            s = rocksdb::DB::OpenForReadOnly(options, path, &this->db_);
+        } else {
+            s = rocksdb::DB::Open(options, path, &this->db_);
+        }
+        if (!s.ok()) {
+            throw RocksDBException("Failed to open RocksDB at " + path + ": " + s.ToString());
+        }
+        this->default_cf_handle_ = this->db_->DefaultColumnFamily();
+        this->cf_handles_[rocksdb::kDefaultColumnFamilyName] = std::make_shared<PyColumnFamilyHandle>(this->default_cf_handle_, rocksdb::kDefaultColumnFamilyName);
     }
 
-    void seek_to_first() {
-        it_->SeekToFirst();
+    virtual ~PyRocksDB() {
+        close();
     }
 
-    void seek_to_last() {
-        it_->SeekToLast();
+    void close() {
+        if (!is_closed_.exchange(true)) {
+            {
+                std::lock_guard<std::mutex> lock(active_iterators_mutex_);
+                for (rocksdb::Iterator* iter_raw_ptr : active_rocksdb_iterators_) {
+                    delete iter_raw_ptr;
+                }
+                active_rocksdb_iterators_.clear();
+            }
+            for (auto const& [name, handle_ptr] : cf_handles_) {
+                handle_ptr->cf_handle_ = nullptr; 
+            }
+            cf_handles_.clear();
+            if (db_) {
+                delete db_;
+                db_ = nullptr;
+            }
+        }
     }
 
-    void seek(const py::bytes& key_bytes) {
-        it_->Seek(static_cast<std::string>(key_bytes));
+    void put(const py::bytes& key, const py::bytes& value, std::shared_ptr<PyWriteOptions> write_options = nullptr) {
+        check_db_open();
+        check_read_only(); 
+        
+        rocksdb::Slice key_slice(static_cast<std::string_view>(key));
+        rocksdb::Slice value_slice(static_cast<std::string_view>(value));
+        
+        const auto& opts = write_options ? write_options->options_ : default_write_options_->options_;
+        rocksdb::Status s = db_->Put(opts, default_cf_handle_, key_slice, value_slice);
+        if (!s.ok()) throw RocksDBException("Put failed: " + s.ToString());
+    }    
+
+    py::object get(const py::bytes& key, std::shared_ptr<PyReadOptions> read_options = nullptr) {
+        check_db_open();
+        std::string value_str;
+        rocksdb::Status s;
+        
+        const auto& opts = read_options ? read_options->options_ : default_read_options_->options_;
+
+        {
+            py::gil_scoped_release release;
+            rocksdb::Slice key_slice(static_cast<std::string_view>(key));
+            s = db_->Get(opts, default_cf_handle_, key_slice, &value_str);
+        }
+        if (s.ok()) return py::bytes(value_str);
+        if (s.IsNotFound()) return py::none();
+        throw RocksDBException("Get failed: " + s.ToString());
     }
 
-    void next() {
-        it_->Next();
+    void del(const py::bytes& key, std::shared_ptr<PyWriteOptions> write_options = nullptr) {
+        check_db_open();
+        check_read_only();
+        rocksdb::Slice key_slice(static_cast<std::string_view>(key));
+        const auto& opts = write_options ? write_options->options_ : default_write_options_->options_;
+        rocksdb::Status s = db_->Delete(opts, default_cf_handle_, key_slice);
+        if (!s.ok()) throw RocksDBException("Delete failed: " + s.ToString());
     }
 
-    void prev() {
-        it_->Prev();
+    void write(PyWriteBatch& batch, std::shared_ptr<PyWriteOptions> write_options = nullptr) {
+        check_db_open();
+        check_read_only();
+        const auto& opts = write_options ? write_options->options_ : default_write_options_->options_;
+        rocksdb::Status s = db_->Write(opts, &batch.wb_);
+        if (!s.ok()) throw RocksDBException("Write failed: " + s.ToString());
     }
 
-    py::object key() {
-        if (it_->Valid()) {
-            return py::bytes(it_->key().ToString());
+    std::shared_ptr<PyRocksDBIterator> new_iterator(std::shared_ptr<PyReadOptions> read_options = nullptr) {
+        check_db_open();
+        const auto& opts = read_options ? read_options->options_ : default_read_options_->options_;
+        rocksdb::Iterator* raw_iter = db_->NewIterator(opts, default_cf_handle_);
+        {
+            std::lock_guard<std::mutex> lock(active_iterators_mutex_);
+            active_rocksdb_iterators_.insert(raw_iter);
         }
-        return py::none();
+        return std::make_shared<PyRocksDBIterator>(raw_iter, shared_from_this());
     }
 
-    py::object value() {
-        if (it_->Valid()) {
-            return py::bytes(it_->value().ToString());
-        }
-        return py::none();
+    PyOptions get_options() const { return opened_options_; }
+
+    // Getters and setters for default options
+    std::shared_ptr<PyReadOptions> get_default_read_options() { return default_read_options_; }
+    void set_default_read_options(std::shared_ptr<PyReadOptions> opts) {
+        if (!opts) throw RocksDBException("ReadOptions cannot be None.");
+        default_read_options_ = opts;
     }
 
-    void check_status() {
-        rocksdb::Status status = it_->status();
-        if (!status.ok()) {
-            throw RocksDBException("RocksDB Iterator error: " + status.ToString());
-        }
+    std::shared_ptr<PyWriteOptions> get_default_write_options() { return default_write_options_; }
+    void set_default_write_options(std::shared_ptr<PyWriteOptions> opts) {
+        if (!opts) throw RocksDBException("WriteOptions cannot be None.");
+        default_write_options_ = opts;
     }
 };
 
-// --- PyRocksDB class to wrap rocksdb::DB ---
-class PyRocksDB {
+// --- PyRocksDBExtended Class (Derived) ---
+class PyRocksDBExtended : public PyRocksDB {
 public:
-    rocksdb::DB* db_;
-    PyOptions opened_options_; // Store the options used to open the DB
-    std::string path_;         // IMPROVEMENT: Store the path for accurate debug messages
-
-    PyRocksDB(const std::string& path, PyOptions* py_options = nullptr) : db_(nullptr), path_(path) {
-        rocksdb::Options actual_options;
+    // Constructor for the extended interface with CF support
+    PyRocksDBExtended(const std::string& path, PyOptions* py_options, bool read_only = false) {
+        this->path_ = path;
+        this->is_read_only_ = read_only; 
+        rocksdb::Options options;
+        if (py_options) {
+            options = py_options->options_;
+            this->opened_options_ = *py_options;
+        } else {
+            options.create_if_missing = true;
+            this->opened_options_.options_ = options;
+            this->opened_options_.cf_options_.compression = rocksdb::kSnappyCompression;
+        }
 
-        if (py_options != nullptr) {
-            actual_options = py_options->options_;
+        std::vector<std::string> cf_names;
+        rocksdb::Status s = rocksdb::DB::ListColumnFamilies(options, path, &cf_names);
+
+        std::vector<rocksdb::ColumnFamilyDescriptor> cf_descriptors;
+        if (s.IsNotFound() || s.IsIOError()) {
+            if (options.create_if_missing) {
+                cf_descriptors.push_back(rocksdb::ColumnFamilyDescriptor(rocksdb::kDefaultColumnFamilyName, this->opened_options_.cf_options_));
+            } else {
+                throw RocksDBException("Database not found at " + path + " and create_if_missing is false.");
+            }
+        } else if (s.ok()) {
+            for (const auto& name : cf_names) {
+                cf_descriptors.push_back(rocksdb::ColumnFamilyDescriptor(name, this->opened_options_.cf_options_));
+            }
         } else {
-            actual_options.create_if_missing = true;
+            throw RocksDBException("Failed to list column families at " + path + ": " + s.ToString());
         }
 
-        opened_options_.options_ = actual_options;
+        std::vector<rocksdb::ColumnFamilyHandle*> handles;
+        rocksdb::Status s_open;
 
-        rocksdb::Status status = rocksdb::DB::Open(actual_options, path_, &db_);
+        if (read_only) { 
+            s_open = rocksdb::DB::OpenForReadOnly(options, path, cf_descriptors, &handles, &this->db_);
+        } else {
+            s_open = rocksdb::DB::Open(options, path, cf_descriptors, &handles, &this->db_);
+        }
+        
+        if (!s_open.ok()) {
+            throw RocksDBException("Failed to open RocksDB at " + path + ": " + s.ToString());
+        }
 
-        if (!status.ok()) {
-            throw RocksDBException("Failed to open RocksDB at " + path_ + ": " + status.ToString());
+        for (size_t i = 0; i < handles.size(); ++i) {
+            const std::string& cf_name = cf_descriptors[i].name;
+            this->cf_handles_[cf_name] = std::make_shared<PyColumnFamilyHandle>(handles[i], cf_name);
+            
+            if (cf_name == rocksdb::kDefaultColumnFamilyName) {
+                this->default_cf_handle_ = handles[i];
+            }
         }
+        
+        if (!this->default_cf_handle_) {
+            throw RocksDBException("Default column family not found after opening.");
+        }
+    }
 
-        std::cout << "RocksDB opened successfully at: " << path_ << std::endl;
+    void put_cf(PyColumnFamilyHandle& cf, const py::bytes& key, const py::bytes& value, std::shared_ptr<PyWriteOptions> write_options = nullptr) {
+        check_db_open();
+        check_read_only();
+        if (!cf.is_valid()) throw RocksDBException("ColumnFamilyHandle is invalid.");
+        rocksdb::Slice key_slice(static_cast<std::string_view>(key));
+        rocksdb::Slice value_slice(static_cast<std::string_view>(value));
+        const auto& opts = write_options ? write_options->options_ : default_write_options_->options_;
+        rocksdb::Status s = db_->Put(opts, cf.cf_handle_, key_slice, value_slice);
+        if (!s.ok()) throw RocksDBException("put_cf failed: " + s.ToString());
     }
 
-    ~PyRocksDB() {
-        if (db_ != nullptr) {
-            // IMPROVEMENT: Use the stored path_ member for a reliable close message.
-            std::cout << "DEBUG: Closing RocksDB database at " << path_ << std::endl;
-            delete db_;
-            db_ = nullptr;
+    py::object get_cf(PyColumnFamilyHandle& cf, const py::bytes& key, std::shared_ptr<PyReadOptions> read_options = nullptr) {
+        check_db_open();
+        if (!cf.is_valid()) throw RocksDBException("ColumnFamilyHandle is invalid.");
+        rocksdb::Slice key_slice(static_cast<std::string_view>(key));
+        std::string value_str;
+        const auto& opts = read_options ? read_options->options_ : default_read_options_->options_;
+        rocksdb::Status s = db_->Get(opts, cf.cf_handle_, key_slice, &value_str);
+        if (s.ok()) return py::bytes(value_str);
+        if (s.IsNotFound()) return py::none();
+        throw RocksDBException("get_cf failed: " + s.ToString());
+    }
+
+    void del_cf(PyColumnFamilyHandle& cf, const py::bytes& key, std::shared_ptr<PyWriteOptions> write_options = nullptr) {
+        check_db_open();
+        check_read_only();
+        if (!cf.is_valid()) throw RocksDBException("ColumnFamilyHandle is invalid.");
+        rocksdb::Slice key_slice(static_cast<std::string_view>(key));
+        const auto& opts = write_options ? write_options->options_ : default_write_options_->options_;
+        rocksdb::Status s = db_->Delete(opts, cf.cf_handle_, key_slice);
+        if (!s.ok()) throw RocksDBException("del_cf failed: " + s.ToString());
+    }
+
+    std::vector<std::string> list_column_families() {
+        check_db_open();
+        std::vector<std::string> names;
+        for (const auto& pair : cf_handles_) {
+            names.push_back(pair.first);
         }
+        return names;
     }
 
-    void put(const py::bytes& key_bytes, const py::bytes& value_bytes) {
-        rocksdb::Status status = db_->Put(rocksdb::WriteOptions(),
-                                         static_cast<std::string>(key_bytes),
-                                         static_cast<std::string>(value_bytes));
-        if (!status.ok()) {
-            throw RocksDBException("Failed to put key-value pair: " + status.ToString());
+    std::shared_ptr<PyColumnFamilyHandle> create_column_family(const std::string& name, PyOptions* cf_py_options) {
+        check_db_open();
+	    check_read_only();
+        if (cf_handles_.count(name)) {
+            throw RocksDBException("Column family '" + name + "' already exists.");
         }
+        rocksdb::ColumnFamilyOptions cf_opts = cf_py_options ? cf_py_options->cf_options_ : opened_options_.cf_options_;
+        rocksdb::ColumnFamilyHandle* cf_handle;
+        rocksdb::Status s = db_->CreateColumnFamily(cf_opts, name, &cf_handle);
+        if (!s.ok()) throw RocksDBException("Failed to create column family '" + name + "': " + s.ToString());
+        
+        auto new_handle = std::make_shared<PyColumnFamilyHandle>(cf_handle, name);
+        cf_handles_[name] = new_handle;
+        return new_handle;
     }
 
-    py::object get(const py::bytes& key_bytes) {
-        std::string value_str;
-        rocksdb::Status status = db_->Get(rocksdb::ReadOptions(), static_cast<std::string>(key_bytes), &value_str);
+    void drop_column_family(PyColumnFamilyHandle& cf_handle) {
+        check_db_open();
+        check_read_only();
+        if (!cf_handle.is_valid()) throw RocksDBException("ColumnFamilyHandle is invalid.");
+        if (cf_handle.get_name() == rocksdb::kDefaultColumnFamilyName) throw RocksDBException("Cannot drop the default column family.");
 
-        if (status.ok()) {
-            return py::bytes(value_str);
-        } else if (status.IsNotFound()) {
-            return py::none();
-        } else {
-            throw RocksDBException("Failed to get value for key: " + status.ToString());
+        rocksdb::ColumnFamilyHandle* raw_handle = cf_handle.cf_handle_;
+        std::string cf_name = cf_handle.get_name();
+
+        rocksdb::Status s = db_->DropColumnFamily(raw_handle);
+        if (!s.ok()) throw RocksDBException("Failed to drop column family '" + cf_name + "': " + s.ToString());
+
+        s = db_->DestroyColumnFamilyHandle(raw_handle);
+        if (!s.ok()) throw RocksDBException("Dropped CF but failed to destroy handle: " + s.ToString());
+
+        cf_handles_.erase(cf_name);
+        cf_handle.cf_handle_ = nullptr;
+    }
+
+    std::shared_ptr<PyColumnFamilyHandle> get_column_family(const std::string& name) {
+        check_db_open();
+        auto it = cf_handles_.find(name);
+        return (it == cf_handles_.end()) ? nullptr : it->second;
+    }
+
+    std::shared_ptr<PyColumnFamilyHandle> get_default_cf() {
+        check_db_open();
+        return get_column_family(rocksdb::kDefaultColumnFamilyName);
+    }
+
+    std::shared_ptr<PyRocksDBIterator> new_cf_iterator(PyColumnFamilyHandle& cf_handle, std::shared_ptr<PyReadOptions> read_options = nullptr) {
+        check_db_open();
+        if (!cf_handle.is_valid()) throw RocksDBException("ColumnFamilyHandle is invalid.");
+        
+        const auto& opts = read_options ? read_options->options_ : default_read_options_->options_;
+        rocksdb::Iterator* raw_iter = db_->NewIterator(opts, cf_handle.cf_handle_);
+        {
+            std::lock_guard<std::mutex> lock(active_iterators_mutex_);
+            active_rocksdb_iterators_.insert(raw_iter);
         }
+        return std::make_shared<PyRocksDBIterator>(raw_iter, shared_from_this());
     }
+};
 
-    // This method is safe to return by value, as PyOptions is a simple
-    // wrapper around a copyable rocksdb::Options object.
-    PyOptions get_options() const {
-        return opened_options_;
+// --- PyRocksDBIterator Method Implementations ---
+PyRocksDBIterator::PyRocksDBIterator(rocksdb::Iterator* it, std::shared_ptr<PyRocksDB> parent_db)
+    : it_raw_ptr_(it), parent_db_ptr_(std::move(parent_db)) {
+    if (!it_raw_ptr_) {
+        throw RocksDBException("Failed to create iterator: null pointer received.");
     }
+}
 
-    void write(PyWriteBatch& py_write_batch) {
-        rocksdb::Status status = db_->Write(rocksdb::WriteOptions(), &py_write_batch.wb_);
-        if (!status.ok()) {
-            throw RocksDBException("Failed to write batch: " + status.ToString());
+PyRocksDBIterator::~PyRocksDBIterator() {
+    if (parent_db_ptr_) {
+        std::lock_guard<std::mutex> lock(parent_db_ptr_->active_iterators_mutex_);
+        if (it_raw_ptr_ && parent_db_ptr_->active_rocksdb_iterators_.count(it_raw_ptr_)) {
+            parent_db_ptr_->active_rocksdb_iterators_.erase(it_raw_ptr_);
+            delete it_raw_ptr_;
         }
     }
+    it_raw_ptr_ = nullptr;
+}
+
+void PyRocksDBIterator::check_parent_db_is_open() const {
+    if (!parent_db_ptr_ || parent_db_ptr_->is_closed_.load()) {
+        throw RocksDBException("Database is closed.");
+    }
+}
 
-    // **FIXED**: Return a unique_ptr to transfer ownership to pybind11.
-    // This prevents the temporary iterator object from being destroyed prematurely.
-    std::unique_ptr<PyRocksDBIterator> new_iterator() {
-        rocksdb::ReadOptions read_options;
-        return std::make_unique<PyRocksDBIterator>(db_->NewIterator(read_options));
+bool PyRocksDBIterator::valid() { check_parent_db_is_open(); return it_raw_ptr_->Valid(); }
+void PyRocksDBIterator::seek_to_first() { check_parent_db_is_open(); it_raw_ptr_->SeekToFirst(); }
+void PyRocksDBIterator::seek_to_last() { check_parent_db_is_open(); it_raw_ptr_->SeekToLast(); }
+void PyRocksDBIterator::seek(const py::bytes& key) { check_parent_db_is_open(); it_raw_ptr_->Seek(static_cast<std::string>(key)); }
+void PyRocksDBIterator::next() { check_parent_db_is_open(); it_raw_ptr_->Next(); }
+void PyRocksDBIterator::prev() { check_parent_db_is_open(); it_raw_ptr_->Prev(); }
+
+py::object PyRocksDBIterator::key() {
+    check_parent_db_is_open();
+    if (it_raw_ptr_ && it_raw_ptr_->Valid()) {
+        return py::bytes(it_raw_ptr_->key().ToString());
     }
-};
+    return py::none();
+}
+
+py::object PyRocksDBIterator::value() {
+    check_parent_db_is_open();
+    if (it_raw_ptr_ && it_raw_ptr_->Valid()) {
+        return py::bytes(it_raw_ptr_->value().ToString());
+    }
+    return py::none();
+}
+
+void PyRocksDBIterator::check_status() {
+    check_parent_db_is_open();
+    if (it_raw_ptr_) {
+        rocksdb::Status s = it_raw_ptr_->status();
+        if (!s.ok()) throw RocksDBException("Iterator error: " + s.ToString());
+    }
+}
 
 // --- PYBIND11 MODULE DEFINITION ---
 PYBIND11_MODULE(_pyrex, m) {
-    m.doc() = "pybind11 RocksDB wrapper";
-
-    py::register_exception<RocksDBException>(m, "RocksDBException");
-
-    py::enum_<rocksdb::CompressionType>(m, "CompressionType")
-        .value("kNoCompression", rocksdb::kNoCompression)
-        .value("kSnappyCompression", rocksdb::kSnappyCompression)
-        .value("kBZip2Compression", rocksdb::kBZip2Compression)
-        .value("kLZ4Compression", rocksdb::kLZ4Compression)
-        .value("kLZ4HCCompression", rocksdb::kLZ4HCCompression)
-        .value("kXpressCompression", rocksdb::kXpressCompression)
-        .value("kZSTD", rocksdb::kZSTD)
-        .value("kDisableCompressionOption", rocksdb::kDisableCompressionOption)
-        .export_values();
-
-    py::class_<PyOptions>(m, "PyOptions")
-        .def(py::init<>())
-        .def_property("create_if_missing", &PyOptions::get_create_if_missing, &PyOptions::set_create_if_missing)
-        .def_property("error_if_exists", &PyOptions::get_error_if_exists, &PyOptions::set_error_if_exists)
-        .def_property("max_open_files", &PyOptions::get_max_open_files, &PyOptions::set_max_open_files)
-        .def_property("write_buffer_size", &PyOptions::get_write_buffer_size, &PyOptions::set_write_buffer_size)
-        .def_property("compression", &PyOptions::get_compression, &PyOptions::set_compression)
-        .def_property("max_background_jobs", &PyOptions::get_max_background_jobs, &PyOptions::set_max_background_jobs)
-        .def("increase_parallelism", &PyOptions::increase_parallelism, py::arg("total_threads"))
-        .def("optimize_for_small_db", &PyOptions::optimize_for_small_db)
-        .def("use_block_based_bloom_filter", &PyOptions::use_block_based_bloom_filter, py::arg("bits_per_key") = 10.0);
-
-    py::class_<PyWriteBatch>(m, "PyWriteBatch")
-        .def(py::init<>())
-        .def("put", &PyWriteBatch::put, py::arg("key"), py::arg("value"))
-        .def("delete", &PyWriteBatch::del, py::arg("key"))
-        .def("clear", &PyWriteBatch::clear);
-
-    py::class_<PyRocksDBIterator>(m, "PyRocksDBIterator")
-        .def("valid", &PyRocksDBIterator::valid)
-        .def("seek_to_first", &PyRocksDBIterator::seek_to_first)
-        .def("seek_to_last", &PyRocksDBIterator::seek_to_last)
-        .def("seek", &PyRocksDBIterator::seek, py::arg("key"))
-        .def("next", &PyRocksDBIterator::next)
-        .def("prev", &PyRocksDBIterator::prev)
-        .def("key", &PyRocksDBIterator::key)
-        .def("value", &PyRocksDBIterator::value)
-        .def("check_status", &PyRocksDBIterator::check_status);
-
-    py::class_<PyRocksDB>(m, "PyRocksDB")
-        .def(py::init<const std::string&, PyOptions*>(), py::arg("path"), py::arg("options") = nullptr)
-        .def("put", &PyRocksDB::put, py::arg("key"), py::arg("value"))
-        .def("get", &PyRocksDB::get, py::arg("key"))
-        .def("get_options", &PyRocksDB::get_options)
-        .def("write", &PyRocksDB::write, py::arg("write_batch"))
-        .def("new_iterator", &PyRocksDB::new_iterator,
-             "Creates and returns a new RocksDB iterator.",
-             py::keep_alive<0, 1>()
-        ); 
+    m.doc() = R"doc(
+        A robust, high-performance Python wrapper for the RocksDB key-value store.
+
+        This module provides two main classes for interacting with RocksDB:
+        1. PyRocksDB: A simple interface for standard key-value operations on a
+           database with a single (default) column family.
+        2. PyRocksDBExtended: An advanced interface that inherits from PyRocksDB and
+           adds full support for creating, managing, and using multiple Column Families.
+    )doc";
+
+    // 1. Create the Python exception type and give it a docstring.
+    static py::exception<RocksDBException> rocksdb_exception(m, "RocksDBException", PyExc_RuntimeError);
+    rocksdb_exception.doc() = R"doc(
+        Custom exception raised for RocksDB-specific operational errors.
+
+        This exception is raised when a RocksDB operation fails for reasons
+        such as I/O errors, corruption, invalid arguments, or when an operation
+        is attempted on a closed database.
+    )doc";
+
+    // 2. Register a translator that maps the C++ exception to the Python one.
+    py::register_exception_translator([](std::exception_ptr p) {
+        try {
+            if (p) {
+                std::rethrow_exception(p);
+            }
+        } catch (const RocksDBException &e) {
+            // Use PyErr_SetString to set the Python error object correctly.
+            // 'rocksdb_exception' is a static variable and accessible without capture.
+            PyErr_SetString(rocksdb_exception.ptr(), e.what());
+        }
+    });
+
+
+    py::enum_<rocksdb::CompressionType>(m, "CompressionType", R"doc(
+        Enum for different compression types supported by RocksDB.
+    )doc")
+        .value("kNoCompression", rocksdb::kNoCompression, "No compression.")
+        .value("kSnappyCompression", rocksdb::kSnappyCompression, "Snappy compression (default).")
+        .value("kBZip2Compression", rocksdb::kBZip2Compression, "BZip2 compression.")
+        .value("kLZ4Compression", rocksdb::kLZ4Compression, "LZ4 compression.")
+        .value("kLZ4HCCompression", rocksdb::kLZ4HCCompression, "LZ4HC (high compression) compression.")
+        .value("kXpressCompression", rocksdb::kXpressCompression, "Xpress compression.")
+        .value("kZSTD", rocksdb::kZSTD, "Zstandard compression.");
+        
+    py::class_<PyReadOptions, std::shared_ptr<PyReadOptions>>(m, "ReadOptions", R"doc(
+        Configuration options for read operations (Get, Iterator).
+    )doc")
+        .def(py::init<>(), "Constructs a new ReadOptions object with default settings.")
+        .def_property("fill_cache", &PyReadOptions::get_fill_cache, &PyReadOptions::set_fill_cache, "If True, reads will fill the block cache. Defaults to True.")
+        .def_property("verify_checksums", &PyReadOptions::get_verify_checksums, &PyReadOptions::set_verify_checksums, "If True, all data read from underlying storage will be verified against its checksums. Defaults to True.");
+
+    py::class_<PyWriteOptions, std::shared_ptr<PyWriteOptions>>(m, "WriteOptions", R"doc(
+        Configuration options for write operations (Put, Delete, Write).
+    )doc")
+        .def(py::init<>(), "Constructs a new WriteOptions object with default settings.")
+        .def_property("sync", &PyWriteOptions::get_sync, &PyWriteOptions::set_sync, "If True, the write will be flushed from the OS buffer cache before the write is considered complete. Defaults to False.")
+        .def_property("disable_wal", &PyWriteOptions::get_disable_wal, &PyWriteOptions::set_disable_wal, "If True, writes will not be written to the Write Ahead Log. Defaults to False.");
+
+    py::class_<PyOptions>(m, "PyOptions", R"doc(
+        Configuration options for opening and managing a RocksDB database.
+
+        This class wraps `rocksdb::Options` and `rocksdb::ColumnFamilyOptions`
+        to provide a convenient way to configure database behavior from Python.
+    )doc")
+        .def(py::init<>(), "Constructs a new PyOptions object with default settings.")
+        .def_property("create_if_missing", &PyOptions::get_create_if_missing, &PyOptions::set_create_if_missing, "If True, the database will be created if it is missing. Defaults to True.")
+        .def_property("error_if_exists", &PyOptions::get_error_if_exists, &PyOptions::set_error_if_exists, "If True, an error is raised if the database already exists. Defaults to False.")
+        .def_property("max_open_files", &PyOptions::get_max_open_files, &PyOptions::set_max_open_files, "Number of open files that can be used by the DB. Defaults to -1 (unlimited).")
+        .def_property("write_buffer_size", &PyOptions::get_write_buffer_size, &PyOptions::set_write_buffer_size, "Amount of data to build up in a memory buffer (MemTable) before flushing. Defaults to 64MB.")
+        .def_property("compression", &PyOptions::get_compression, &PyOptions::set_compression, "The compression type to use for sst files. Defaults to Snappy.")
+        .def_property("max_background_jobs", &PyOptions::get_max_background_jobs, &PyOptions::set_max_background_jobs, "Maximum number of concurrent background jobs (compactions and flushes).")
+        .def("increase_parallelism", &PyOptions::increase_parallelism, py::arg("total_threads"), R"doc(
+            Increases RocksDB's parallelism by tuning background threads.
+
+            Args:
+                total_threads (int): The total number of background threads to use.
+        )doc", py::call_guard<py::gil_scoped_release>())
+        .def("optimize_for_small_db", &PyOptions::optimize_for_small_db, R"doc(
+            Optimizes RocksDB for small databases by reducing memory and CPU consumption.
+        )doc", py::call_guard<py::gil_scoped_release>())
+        .def("use_block_based_bloom_filter", &PyOptions::use_block_based_bloom_filter, py::arg("bits_per_key") = 10.0, R"doc(
+            Enables a Bloom filter for block-based tables to speed up 'Get' operations.
+
+            Args:
+                bits_per_key (float): The number of bits per key for the Bloom filter.
+                    Higher values reduce false positives but increase memory usage.
+        )doc", py::call_guard<py::gil_scoped_release>())
+        .def_property("cf_write_buffer_size", &PyOptions::get_cf_write_buffer_size, &PyOptions::set_cf_write_buffer_size, "Default write_buffer_size for newly created Column Families.")
+        .def_property("cf_compression", &PyOptions::get_cf_compression, &PyOptions::set_cf_compression, "Default compression type for newly created Column Families.");
+
+    py::class_<PyColumnFamilyHandle, std::shared_ptr<PyColumnFamilyHandle>>(m, "ColumnFamilyHandle", R"doc(
+        Represents a handle to a RocksDB Column Family.
+
+        This object is used to perform operations on a specific data partition
+        within a `PyRocksDBExtended` instance.
+    )doc")
+        .def_property_readonly("name", &PyColumnFamilyHandle::get_name, "The name of this column family.")
+        .def("is_valid", &PyColumnFamilyHandle::is_valid, "Checks if the handle is still valid (i.e., has not been dropped).");
+
+    py::class_<PyWriteBatch>(m, "PyWriteBatch", R"doc(
+        A batch of write operations (Put, Delete) that can be applied atomically.
+    )doc")
+        .def(py::init<>(), "Constructs an empty write batch.")
+        .def("put", &PyWriteBatch::put, py::arg("key"), py::arg("value"), "Adds a key-value pair to the batch for the default column family.")
+        .def("put_cf", &PyWriteBatch::put_cf, py::arg("cf_handle"), py::arg("key"), py::arg("value"), "Adds a key-value pair to the batch for a specific column family.")
+        .def("delete", &PyWriteBatch::del, py::arg("key"), "Adds a key deletion to the batch for the default column family.")
+        .def("delete_cf", &PyWriteBatch::del_cf, py::arg("cf_handle"), py::arg("key"), "Adds a key deletion to the batch for a specific column family.")
+        .def("merge", &PyWriteBatch::merge, py::arg("key"), py::arg("value"), "Adds a merge operation to the batch for the default column family.")
+        .def("merge_cf", &PyWriteBatch::merge_cf, py::arg("cf_handle"), py::arg("key"), py::arg("value"), "Adds a merge operation to the batch for a specific column family.")
+        .def("clear", &PyWriteBatch::clear, "Clears all operations from the batch.");
+
+    py::class_<PyRocksDBIterator, std::shared_ptr<PyRocksDBIterator>>(m, "PyRocksDBIterator", R"doc(
+        An iterator for traversing key-value pairs in a RocksDB database.
+    )doc")
+        .def("valid", &PyRocksDBIterator::valid, "Returns True if the iterator is currently positioned at a valid entry.", py::call_guard<py::gil_scoped_release>())
+        .def("seek_to_first", &PyRocksDBIterator::seek_to_first, "Positions the iterator at the first key.", py::call_guard<py::gil_scoped_release>())
+        .def("seek_to_last", &PyRocksDBIterator::seek_to_last, "Positions the iterator at the last key.", py::call_guard<py::gil_scoped_release>())
+        .def("seek", &PyRocksDBIterator::seek, py::arg("key"), "Positions the iterator at the first key >= the given key.", py::call_guard<py::gil_scoped_release>())
+        .def("next", &PyRocksDBIterator::next, "Moves the iterator to the next entry.", py::call_guard<py::gil_scoped_release>())
+        .def("prev", &PyRocksDBIterator::prev, "Moves the iterator to the previous entry.", py::call_guard<py::gil_scoped_release>())
+        .def("key", &PyRocksDBIterator::key, "Returns the current key as bytes, or None if invalid.")
+        .def("value", &PyRocksDBIterator::value, "Returns the current value as bytes, or None if invalid.")
+        .def("check_status", &PyRocksDBIterator::check_status, "Raises RocksDBException if an error occurred during iteration.", py::call_guard<py::gil_scoped_release>());
+
+    py::class_<PyRocksDB, std::shared_ptr<PyRocksDB>>(m, "PyRocksDB", R"doc(
+        A Python wrapper for RocksDB providing simple key-value storage.
+
+        This class interacts exclusively with the 'default' column family.
+        For multi-column-family support, use `PyRocksDBExtended`.
+    )doc")
+        .def(py::init<const std::string&, PyOptions*, bool>(), 
+            py::arg("path"), 
+            py::arg("options") = nullptr,
+            py::arg("read_only") = false,
+            R"doc(
+            Opens a RocksDB database at the specified path.
+
+            Args:
+                path (str): The file system path to the database.
+                options (PyOptions, optional): Custom options for configuration.
+                read_only (bool, optional): If True, opens the database in read-only mode.
+                                            Defaults to False.
+        )doc", py::call_guard<py::gil_scoped_release>())
+        .def("put", &PyRocksDB::put, py::arg("key"), py::arg("value"), py::arg("write_options") = nullptr, "Inserts a key-value pair.", py::call_guard<py::gil_scoped_release>())
+        .def("get", &PyRocksDB::get, py::arg("key"), py::arg("read_options") = nullptr, "Retrieves the value for a key.")
+        .def("delete", &PyRocksDB::del, py::arg("key"), py::arg("write_options") = nullptr, "Deletes a key.", py::call_guard<py::gil_scoped_release>())
+        .def("write", &PyRocksDB::write, py::arg("write_batch"), py::arg("write_options") = nullptr, "Applies a batch of operations atomically.", py::call_guard<py::gil_scoped_release>())
+        .def("new_iterator", &PyRocksDB::new_iterator, py::arg("read_options") = nullptr, "Creates a new iterator.", py::keep_alive<0, 1>())
+        .def("get_options", &PyRocksDB::get_options, "Returns the options the database was opened with.")
+        .def_property("default_read_options", &PyRocksDB::get_default_read_options, &PyRocksDB::set_default_read_options, "The default ReadOptions used for get and iterator operations.")
+        .def_property("default_write_options", &PyRocksDB::get_default_write_options, &PyRocksDB::set_default_write_options, "The default WriteOptions used for put, delete, and write operations.")
+        .def("close", &PyRocksDB::close, "Closes the database, releasing resources and the lock.", py::call_guard<py::gil_scoped_release>())
+        .def("__enter__", [](PyRocksDB &db) -> PyRocksDB& { return db; })
+        .def("__exit__", [](PyRocksDB &db, py::object /* type */, py::object /* value */, py::object /* traceback */) {
+            db.close();
+        });
+
+    py::class_<PyRocksDBExtended, PyRocksDB, std::shared_ptr<PyRocksDBExtended>>(m, "PyRocksDBExtended", R"doc(
+        An advanced Python wrapper for RocksDB with full Column Family support.
+    )doc")
+        .def(py::init<const std::string&, PyOptions*, bool>(), 
+            py::arg("path"), 
+            py::arg("options") = nullptr, 
+            py::arg("read_only") = false, 
+            R"doc(
+            Opens or creates a RocksDB database with Column Family support.
+
+            Args:
+                path (str): The file system path to the database.
+                options (PyOptions, optional): Custom options for configuration.
+                read_only (bool, optional): If True, opens the database in read-only mode.
+                                            Defaults to False.
+        )doc", py::call_guard<py::gil_scoped_release>())
+
+        .def("put_cf", &PyRocksDBExtended::put_cf, py::arg("cf_handle"), py::arg("key"), py::arg("value"), py::arg("write_options") = nullptr, "Inserts a key-value pair into a specific column family.", py::call_guard<py::gil_scoped_release>())
+        .def("get_cf", &PyRocksDBExtended::get_cf, py::arg("cf_handle"), py::arg("key"), py::arg("read_options") = nullptr, "Retrieves the value for a key from a specific column family.")
+        .def("delete_cf", &PyRocksDBExtended::del_cf, py::arg("cf_handle"), py::arg("key"), py::arg("write_options") = nullptr, "Deletes a key from a specific column family.", py::call_guard<py::gil_scoped_release>())
+        .def("list_column_families", &PyRocksDBExtended::list_column_families, "Lists the names of all existing column families.")
+        .def("create_column_family", &PyRocksDBExtended::create_column_family, py::arg("name"), py::arg("cf_options") = nullptr, "Creates a new column family.", py::call_guard<py::gil_scoped_release>())
+        .def("drop_column_family", &PyRocksDBExtended::drop_column_family, py::arg("cf_handle"), "Drops a column family.", py::call_guard<py::gil_scoped_release>())
+        .def("new_cf_iterator", &PyRocksDBExtended::new_cf_iterator, py::arg("cf_handle"), py::arg("read_options") = nullptr, "Creates a new iterator for a specific column family.", py::keep_alive<0, 1>())
+        .def("get_column_family", &PyRocksDBExtended::get_column_family, py::arg("name"), "Retrieves a ColumnFamilyHandle by its name.")
+        .def_property_readonly("default_cf", &PyRocksDBExtended::get_default_cf, "Returns the handle for the default column family.");
 }
+

pyrex_rocksdb-0.1.4.dist-info/METADATA

@@ -0,0 +1,121 @@
+Metadata-Version: 2.4
+Name: pyrex-rocksdb
+Version: 0.1.4
+Summary: A fast RocksDB wrapper for Python using pybind11.
+Author-email: Charilaos Mylonas <mylonas.charilaos@gmail.com>
+Project-URL: Homepage, https://github.com/mylonasc/pyrex
+Project-URL: Repository, https://github.com/mylonasc/pyrex
+Keywords: rocksdb,database,key-value,pybind11
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+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: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Database
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: sphinx; extra == "dev"
+Requires-Dist: sphinx-rtd-theme; extra == "dev"
+Requires-Dist: cibuildwheel; extra == "dev"
+Requires-Dist: pybind11-stubgen~=2.5.4; extra == "dev"
+Requires-Dist: mypy~=1.10; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+
+[![PyPI version](https://img.shields.io/pypi/v/pyrex-rocksdb.svg)](https://pypi.org/project/pyrex-rocksdb/)
+[![Python versions](https://img.shields.io/pypi/pyversions/pyrex-rocksdb.svg)](https://img.shields.io/pypi/pyversions/pyrex-rocksdb/)
+
+
+![pyrex](https://raw.githubusercontent.com/mylonasc/pyrex/main/assets/logo.png)
+
+# Installation
+
+
+# pyrex-rocksdb
+A python wrapper for the original (C++) version of RocksDB.
+
+## Installation
+
+For linux systems, wheels are provided and can be installed from pypi using:
+
+```bash
+pip install pyrex-rocksdb
+```
+
+For Windows and MacOS I have built an earlier version of the library.
+I will re-build once I include certain other important features in the API that are not yet implemented.
+
+
+
+## Motivation
+
+This library is intended for providing a fast, write-optimized, in-process key value (KV) store in python. Therefore the "big brothers" of the database are the likes of MongoDB and Cassandra. The difference is that you don't need a separate server to run this (hence "in-process") and it is designed to be fairly portable. 
+
+RocksDB, which is the underlying storage engine of this database, is an LSM-tree engine. An LSM-tree is different from the ballanced tree index databases (e.g., [B-tree](https://en.wikipedia.org/wiki/B-tree)/ and [B+tree](https://en.wikipedia.org/wiki/B%2B_tree) databases). LSM-tree databases offer very high write throughputs and better space efficiency. See more about the motivation for LSM-tree databases (and RocksDB in particular) in [this talk](https://www.youtube.com/watch?v=V_C-T5S-w8g).
+
+### LSM-tree + SSTable engine basics
+To understand where `pyrex` provides efficiency gains, it is important to understand some basics about the underlying `RocksDB` engine. 
+
+RocksDB and LevelDB are **key-value stores** with a **Log-Structured Merge-tree (LSM-tree)** architecture. 
+
+The key components of LSM-tree architectures are 
+* A **MemTable** that stores in-memory sorted data
+* A set of **Sorted-String tables (SSTables)** which are immutable sorted files on disk where data from the MemTable is flushed
+* The process of **Compaction**, which is a background process that merges the SSTables to remove redundant data and keep read performance high.
+
+In such databases, fast writes create many small, sorted data files called SSTables. To prevent reads from slowing down by checking too many files, a background process called compaction merges these SSTables together. This process organizes the data into levels, where newer, overlapping files sit in Level 0 and are progressively merged into higher levels (Level 1, Level 2, etc.). Each higher level contains larger, non-overlapping files, which ensures that finding a key remains efficient and old data is purged to save space. There are several optimizations and configurations possible for these processes (configurability and "pluggability" are commonly cited RocksDB advantages). 
+
+However the main big advantage of RocksDB over LevelDB is its **multi-threaded compaction support** (LevelDB supports only single threaded compaction, which comes with significant performance limitations). 
+There are several other configurability advantages RocksDB offers over LevelDB. For a more elaborate enumaration of RocksDB advantages please refer to the [RocksDB wiki](https://github.com/facebook/rocksdb/wiki/Features-Not-in-LevelDB). 
+
+Not all are currently supported by the `pyrex` API, but I'm working on supporting more of them. Feel free to open an issue if there is a feature you want to see (or open a pull request).
+
+
+## Example usage:
+
+Here is a simple example showing the usage of put/get in the DB:
+
+```python
+import pyrex
+import os
+import shutil
+
+DB_PATH = "./test_rocksdb_minimal"
+
+with pyrex.PyRocksDB(DB_PATH) as db:
+    db.put(b"my_key", b"my_value")
+    retrieved_value = db.get(b"my_key")
+
+print(f"Retrieved: {retrieved_value.decode()}") # Output: Retrieved: my_value
+
+```
+
+for more examples check the relevant folder and the documentation.
+
+## Installation
+
+<details>
+  <summary>Note on CICD</summary>
+The wheels provided are not completely platform-independent at the moment. 
+I heavily rely on github actions to develop since I don't own mac or windows machines.
+The CICD workflow for package builds is under development A windows/macos/linux build was successful, but further development is needed.
+</details>
+
+## Benchmarks
+
+`Pyrex` was benchmarked against [plyvel](https://github.com/wbolster/plyvel) and [lmdb](https://github.com/jnwatson/py-lmdb/) (which is based on a B+tree -- based architecture and relies on OS's block cache). 
+
+Initial benchmarks are promissing and to be reported soon.
+
+

{pyrex_rocksdb-0.1.0.dist-info → pyrex_rocksdb-0.1.4.dist-info}/RECORD

@@ -1,13 +1,13 @@
 pyrex/__init__.py,sha256=zshmllNLYDo3znwRaknHeAd4obEkjS3jK6UkcXAsvw4,831
-pyrex/_pyrex.cpython-312-darwin.so,sha256=hkoAwtprFoZamx3W55FLQUTnZMD77RfPQjxiV6UEo6E,540080
-pyrex/_pyrex.cpp,sha256=mgzrP3PpeDVylK7pkjts2L8hv_tuiQ_Mfy-80r39o8I,10986
+pyrex/_pyrex.cpython-312-darwin.so,sha256=p_vRANlbMHWUpKJBM5XNe0wOdv_aJ87UfPVCxPdvHkQ,821024
+pyrex/_pyrex.cpp,sha256=rTj0pKRt3M1ttRYOhN53kTCoRnetmnuS93c9MMdtGvQ,38172
 pyrex/.dylibs/libsnappy.1.2.2.dylib,sha256=RtFJkVOnmB0FU6L5PGz-SRdNhutch4TzcNi-wB13m_0,79184
 pyrex/.dylibs/liblz4.1.10.0.dylib,sha256=k7TzQdjquM1GQIEVgXlSdUc9wfXAF7lCCMVqOWU0l2o,176960
 pyrex/.dylibs/librocksdb.10.4.2.dylib,sha256=ybpmZR-J9Hr88Nf_Bkl7ae8siEQPfn8A20dmzJl-X7U,11266240
 pyrex/.dylibs/libgflags.2.2.2.dylib,sha256=uiE_yjZcs48WAx0cx5VsLtCi-Jf1tip-QamzYNGTG70,172336
 pyrex/.dylibs/libzstd.1.5.7.dylib,sha256=c-Z4ifatarhfQRED6aESDQIMTHw8XxG_OYBBdVYdDVg,670240
-pyrex_rocksdb-0.1.0.dist-info/RECORD,,
-pyrex_rocksdb-0.1.0.dist-info/WHEEL,sha256=VrhWOWJdu4wN9IKhAFBqWPMo6yuww-SFg9GbWc0qbmI,136
-pyrex_rocksdb-0.1.0.dist-info/top_level.txt,sha256=0YbfttFoNSJjWKBullYqKklNMzgq7obw3oD751OmOOo,6
-pyrex_rocksdb-0.1.0.dist-info/METADATA,sha256=-5O5YaIogXmPdAxSHCo-XlghhcZzMAJyAcN-gYnfYf8,2830
-pyrex_rocksdb-0.1.0.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+pyrex_rocksdb-0.1.4.dist-info/RECORD,,
+pyrex_rocksdb-0.1.4.dist-info/WHEEL,sha256=VrhWOWJdu4wN9IKhAFBqWPMo6yuww-SFg9GbWc0qbmI,136
+pyrex_rocksdb-0.1.4.dist-info/top_level.txt,sha256=Hyct9jOureNtYbpQ0AUae8uzaC--sgtHGo5Kevyspgg,14
+pyrex_rocksdb-0.1.4.dist-info/METADATA,sha256=EHT-tw_oAdy20FnOW2UAr6_N1CbK7ksowdUyyUef6qY,6050
+pyrex_rocksdb-0.1.4.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358

pyrex_rocksdb-0.1.4.dist-info/top_level.txt

@@ -0,0 +1,2 @@
+pyrex
+rocksdb

pyrex_rocksdb-0.1.0.dist-info/METADATA

@@ -1,76 +0,0 @@
-Metadata-Version: 2.4
-Name: pyrex-rocksdb
-Version: 0.1.0
-Summary: A fast RocksDB wrapper for Python using pybind11.
-Author-email: Charilaos Mylonas <mylonas.charilaos@gmail.com>
-Project-URL: Homepage, https://github.com/mylonasc/pyrex
-Project-URL: Repository, https://github.com/mylonasc/pyrex
-Keywords: rocksdb,database,key-value,pybind11
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.8
-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: License :: OSI Approved :: Apache Software License
-Classifier: Operating System :: POSIX :: Linux
-Classifier: Operating System :: MacOS :: MacOS X
-Classifier: Operating System :: Microsoft :: Windows
-Classifier: Development Status :: 3 - Alpha
-Classifier: Intended Audience :: Developers
-Classifier: Topic :: Database
-Requires-Python: >=3.8
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Provides-Extra: dev
-Requires-Dist: pytest; extra == "dev"
-Requires-Dist: sphinx; extra == "dev"
-Requires-Dist: sphinx-rtd-theme; extra == "dev"
-Requires-Dist: cibuildwheel; extra == "dev"
-Requires-Dist: twine; extra == "dev"
-Dynamic: license-file
-
-[![Build Status](https://github.com/mylonasc/pyrex/actions/workflows/build_wheels.yml/badge.svg)](https://github.com/mylonasc/pyrex/actions/workflows/build_wheels.yml)
-
-# pyrex
-a python rocksdb wrapper
-
-## Motivation
-rocksdb python wrappers are broken. This is yet another attempt to create a working python wrapper for rocksdb.
-
-## Example usage:
-Check the `test.py` file.
-
-## Installation
-
-On Linux/macOS: Open your terminal, navigate to the parent directory of my_rocksdb_wrapper, and run:
-
-
-Build and Use the Wrapper:
-After saving the files, follow these steps to build and use your Python wrapper:
-
-### Prerequisites:
-
-* RocksDB C++ Library Installed (headers and libraries accessible). (in Ubuntu `sudo apt-get install librocksdb` may suffice)
-* C++11 compatible compiler (e.g., g++ or clang++).
-* Python 3.7+ and its development headers.    
-
-* Python pybind11 package: `pip install pybind11`
-
-Python setuptools package: `pip install --upgrade setuptools`
-
-### Adjust setup.py (if needed):
-
-Open setup.py and verify that `include_dirs` and `library_dirs` correctly point to your RocksDB installation paths. 
-If RocksDB is not in `/usr/local/include` or `/usr/local/lib`, update these paths.
-
-If RocksDB was built with specific compression libraries (like Snappy, Zlib, LZ4, Zstandard), add their corresponding names (e.g., 'snappy', 'z') to the libraries list.
-
-Compile the Wrapper:
-Navigate to the directory containing rocksdb_wrapper.cpp and setup.py in your terminal, and run:
-
-```Bash
-
-python setup.py install
-```
-

pyrex_rocksdb-0.1.0.dist-info/top_level.txt

@@ -1 +0,0 @@
-pyrex