dbzero 0.3.0__tar.gz → 0.3.2__tar.gz

dbzero-0.3.2/.github/workflows/build-and-test.yml

@@ -0,0 +1,141 @@
+name: Build and test
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+  workflow_dispatch:
+
+jobs:
+  build-linux:
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+    uses: ./.github/workflows/build-linux-wheel.yml
+    with:
+      python-version: ${{ matrix.python-version }}
+
+  build-windows:
+    uses: ./.github/workflows/build-windows-wheel.yml
+    with:
+      python-version: "3.12"
+      python-tag: "312"
+      architecture: "AMD64"
+
+  build-macos:
+    uses: ./.github/workflows/build-mac-wheel.yml
+    with:
+      python-version: "3.12"
+  
+  test-wheels-linux:
+    needs: build-linux
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+    uses: ./.github/workflows/test-linux-wheel.yml
+    with:
+      python-version: ${{ matrix.python-version }}
+
+  test-wheels-windows:
+    needs: build-windows
+    uses: ./.github/workflows/test-windows-wheel.yml
+    with:
+      python-version: "3.12"
+
+  test-wheels-macos:
+    needs: build-macos
+    uses: ./.github/workflows/test-mac-wheel.yml
+    with:
+      python-version: "3.12"
+
+  stress-test-linux:
+    needs: build-linux
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+    uses: ./.github/workflows/test-linux-wheel.yml
+    with:
+      python-version: ${{ matrix.python-version }}
+      pytest-markers: "-m 'stress_test'"
+      timeout-minutes: 60
+
+  test-external-crm:
+    needs: build-linux
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      
+      - name: Download wheel artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: wheels-linux-3.11
+          path: ./wheels/
+      
+      - name: Clone external CRM repository
+        uses: actions/checkout@v4
+        with:
+          repository: adrian-zawadzki/crm
+          token: ${{ secrets.PAT_TOKEN }}
+          path: crm
+      
+      - name: Install requirements and wheel
+        run: |
+          cd crm
+          pip install -r requirements.txt
+          pip install --force-reinstall ../wheels/*.whl
+          pip install --force-reinstall packages/*.whl 
+      
+      - name: Run tests
+        run: |
+          cd crm
+          ./run_tests.sh > /dev/null 2>&1
+  build-and-test-cpp:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ${{ github.event_name == 'workflow_dispatch' && fromJSON(format('["{0}"]', inputs.python-version)) || fromJSON('["3.9", "3.10", "3.11", "3.12", "3.13"]') }}
+    env:
+      REQUIREMENTS_FILE: ${{ matrix.python-version == '3.9' && 'requirements.3.9.txt' || 'requirements.txt' }}
+    
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      
+      - name: Install dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y meson ninja-build
+          pip install -r $REQUIREMENTS_FILE
+      
+      - name: Generate meson files
+        run: |
+          python3 scripts/generate_meson.py ./src/dbzero/ core
+          python3 scripts/generate_meson_tests.py tests/
+          python3 scripts/generate_meson_dbzero.py dbzero/
+      
+      - name: Configure build with tests enabled
+        run: |
+          meson setup --buildtype=release -Dbuild_tests=true build/release
+      
+      - name: Build project
+        run: |
+          cd build/release
+          ninja
+      
+      - name: Run C++ tests
+        run: |
+          cd build/release
+          ./tests.x

dbzero-0.3.2/AGENTS.md

@@ -0,0 +1,82 @@
+# dbzero
+
+dbzero is a state management system for persisting process state without a database. It lets Python processes keep their in-memory state durable across restarts — no separate DB server, schemas, or ORM. The core is C++ with Python bindings. See https://docs.dbzero.io for user-facing documentation.
+
+## Development workflow
+
+### TDD is required
+
+When implementing new features, follow test-driven development:
+
+1. Write a failing test first (Python tests in `python_tests/`, C++ tests under `tests/` / `subprojects/`).
+2. Implement the minimum code to make the test pass.
+3. Refactor while keeping tests green.
+
+All tests must pass before a change is considered complete.
+
+### Building
+
+- Debug build: `./scripts/build.sh -d` (equivalent to `./scripts/build.sh`; debug is the default)
+- Release build: `./scripts/build.sh -r`
+- Release build with C++ unit test binary: `./scripts/build.sh -r -t`
+
+### Running tests
+
+- Python tests: `./scripts/run_tests.sh`
+- Final Python test checks: `./scripts/run_tests.sh -j 6`
+- C++ tests after a `-t` build: `./build/release/tests.x`
+- Before final handoff, also verify the code in debug mode with a debug build (`./scripts/build.sh -d`) and the relevant Python tests against that debug build. Debug assertions are part of the required validation, not optional diagnostics.
+- During development, do not run stress tests by default; they are intentionally slow. Run focused tests specific to the feature or refactor being worked on before finalization.
+- If any C++ source under the native/core part of the project was modified, also run the C++ test suite (do not rely on the Python tests alone to cover native changes).
+
+Never mark a task done while tests are failing.
+
+## Implementation notes
+
+### Scope discipline
+
+Never make cosmetic changes unless they are explicitly requested by the task.
+
+### Temporary immutable objects design
+
+When working on immutable objects, use `design/IMMUTABLE_OBJECTS_DESIGN.md` as the implementation design reference. This file is temporary and should be removed after the feature is complete.
+
+### v_object constructor conventions
+
+Types derived from `v_object` should follow the project-wide constructor pattern:
+
+- New durable instances are constructed from `Memspace &` plus any type-specific creation arguments.
+- Existing durable instances are reopened from `mptr` plus any type-specific runtime dependencies.
+
+### Overlaid type inheritance
+
+Variable-size overlaid types that derive from another overlaid type must use `db0::o_ext<Derived, BaseOverlay, VER, STORE_VER>` rather than directly inheriting from an `o_base`-derived overlay such as `o_list`. Direct inheritance bypasses `o_ext` sizing, version, and dynamic-area handling and can corrupt overlaid layout assumptions.
+
+### C++ style
+
+- Use snake_case for parameter names and local variable names in C++ code. Parameter names should be concise yet informative. Keep method names consistent with the surrounding code.
+- Project types often avoid implicit bool conversion because it can hide subtle ownership, state, and null-check bugs. Use explicit double-negation checks such as `if (!!obj)` or `while (!!item)` when a type supports `operator!()`.
+
+### Python binding wrapper access
+
+When accessing a C++ object stored inside a Python wrapper, use `ext()` for read-only operations and for operations that are explicitly documented as non-mutating wrapper/runtime attachment updates.
+
+Use `modifyExt()` for real object mutations, especially durable state changes. Do not use `const_cast` on `ext()` to call a mutating method. If a wrapper currently exposes only a const object but needs a mutating API, change the wrapper type or access path so the mutation can go through `modifyExt()`.
+
+### Python C API safety helpers
+
+When iterating over Python objects in C++, use `Py_FOR(item, iterator)` from `PySafeAPI.hpp` with an owned iterator, for example `auto iterator = Py_OWN(PyObject_GetIter(obj));`. The loop owns each yielded item and avoids manual `Py_DECREF` paths.
+
+For Python container/object writes, use the `PySafe_*` helpers from `PySafeAPI.hpp` instead of the raw C API when a helper exists, such as `PySafeList_SetItem`, `PySafeTuple_SetItem`, `PySafeDict_SetItem`, `PySafeDict_SetItemString`, `PySafeSet_Add`, and `PySafeModule_AddObject`.
+
+### MorphingBIndex: address and type can change on mutation
+
+A `MorphingBIndex` does not behave like a typical container. On mutation (`insert`, `erase`) it may morph into a different internal storage variant (itty / array_2..4 / vector / bindex), and the morph can change both its **address** and its **type**.
+
+Consequences for any code that mutates a `MorphingBIndex`:
+
+- Any externally stored `{address, type}` pair referring to the bindex is potentially invalidated after every `insert` or `erase` call. Lookups through a stale pair read pre-mutation storage and return wrong data.
+- A live handle to the bindex remains valid across the mutation and reflects the new storage; prefer re-reading `bindex.getAddress()` / `bindex.getIndexType()` from the handle over trusting any previously captured copy.
+- Destructive shortcuts (destroying and rebuilding the whole bindex, or erasing it entirely from its parent) avoid the issue since no stale reference remains.
+
+When adding a new mutating path that operates on a `MorphingBIndex`, treat re-syncing any externally held `{address, type}` as mandatory, not an optimization. Collection-specific handling (where these pairs live, which paths must re-sync) is documented at the top of the relevant `.cpp` files.

dbzero-0.3.2/CONTRIBUTING.md

@@ -0,0 +1,371 @@
+# Contributing to dbzero
+
+Thank you for your interest in contributing to dbzero! We welcome contributions from the community and are grateful for your support.
+
+## Table of Contents
+
+- [Code of Conduct](#code-of-conduct)
+- [Getting Started](#getting-started)
+- [Development Setup](#development-setup)
+- [How to Contribute](#how-to-contribute)
+- [Coding Standards](#coding-standards)
+- [Testing Guidelines](#testing-guidelines)
+- [Commit Message Guidelines](#commit-message-guidelines)
+- [Pull Request Process](#pull-request-process)
+- [Reporting Bugs](#reporting-bugs)
+- [Suggesting Enhancements](#suggesting-enhancements)
+- [Documentation](#documentation)
+- [Contributor License Agreement](#contributor-license-agreement)
+- [License](#license)
+
+## Code of Conduct
+
+This project adheres to a code of conduct that all contributors are expected to follow. Please be respectful, inclusive, and considerate in all interactions.
+
+## Getting Started
+
+1. **Fork the repository** on GitHub
+2. **Clone your fork** locally:
+   ```bash
+   git clone https://github.com/YOUR_USERNAME/dbzero.git
+   cd dbzero
+   ```
+3. **Add the upstream repository** as a remote:
+   ```bash
+   git remote add upstream https://github.com/dbzero-software/dbzero.git
+   ```
+
+## Development Setup
+
+### Prerequisites
+
+- C++ compiler (GCC 13+ or Microsoft C/C++ Optimizing Compiler 19.41+)
+- Meson
+- Ninja build system
+- Git
+- Python 3.9 or higher (for Python components and tooling)
+- A virtual environment tool (venv, virtualenv, or conda) for Python dependencies
+
+### Setting Up Your Environment
+
+1. **Build the C++ components**:
+   ```bash
+   # Build debug version without tests
+   ./scripts/build.sh
+   
+   # Build debug version with tests
+   ./scripts/build.sh -t
+   
+   # Build release version
+   ./scripts/build.sh -r
+   
+   # Build release version with tests
+   ./scripts/build.sh -r -t
+   ```
+   
+   Alternatively, you can use Meson directly:
+   ```bash
+   meson setup build
+   meson compile -C build
+   ```
+
+2. **Create a Python virtual environment** (for Python components):
+   ```bash
+   python -m venv venv
+   source venv/bin/activate  # On Windows: venv\Scripts\activate
+   ```
+
+3. **Install Python dependencies**:
+   ```bash
+   pip install -r requirements.txt  # Install dependencies
+   ```
+
+4. **Verify the installation**:
+   ```bash
+   # Run C++ tests (debug build)
+   ./build/debug/testsD.x
+   
+   # Run C++ tests (release build)
+   ./build/release/tests.x
+   
+   # Or use Meson test runner
+   meson test -C build
+   
+   # Run Python tests (excludes stress tests)
+   ./scripts/run_tests.sh
+   
+   # Run Python tests in parallel
+   ./scripts/run_tests.sh -j 6
+   
+   # Run specific Python test
+   ./scripts/run_tests.sh -k=test_name
+   
+   # Run stress tests only (takes longer)
+   ./scripts/run_stress_tests.sh
+   
+   # Run specific stress test
+   ./scripts/run_stress_tests.sh -k=test_name
+   ```
+
+## How to Contribute
+
+### Types of Contributions
+
+We welcome various types of contributions:
+
+- **Bug fixes** - Fix issues and improve stability
+- **New features** - Add new functionality
+- **Documentation** - Improve or add documentation
+- **Tests** - Add or improve test coverage
+- **Performance improvements** - Optimize existing code
+- **Code refactoring** - Improve code quality and maintainability
+
+### Finding Something to Work On
+
+- Check the [issue tracker](https://github.com/dbzero-software/dbzero/issues) for open issues
+- Look for issues labeled `good first issue` or `help wanted`
+- Review the roadmap and feature requests
+- If you have a new idea, open an issue to discuss it first
+
+## Coding Standards
+
+### C++ Style Guide (Primary)
+
+Since the project is predominantly C++ (85%), these are our primary coding standards:
+
+- Follow **Modern C++** best practices
+- Use **meaningful variable and function names** with clear intent
+- Follow **RAII principles** for resource management
+- Prefer **smart pointers** over raw pointers
+- Use **const correctness** throughout
+- Keep functions small and focused on a single task
+- Maximum line length: 120 characters
+
+#### C++ Code Quality
+
+- **Naming Conventions**:
+  - Classes/Structs: `PascalCase`
+  - Functions/Methods: `camelCase`
+  - Variables: `snake_case`
+  - Constants: `UPPER_SNAKE_CASE`
+  - Namespaces: `lowercase`
+
+- **Documentation**: Use Doxygen-style comments for all public APIs
+  ```cpp
+  /**
+   * @brief Brief description of the function
+   * @param param1 Description of parameter
+   * @return Description of return value
+   */
+  ```
+
+- **Error Handling**: Use exceptions for exceptional cases, return values for expected errors
+- **Comments**: Write clear comments for complex logic, algorithms, and non-obvious decisions
+- **DRY Principle**: Extract common code into reusable functions and templates
+
+### Python Style Guide (Additional)
+
+For the Python components (~15% of the project):
+
+- Follow [PEP 8](https://www.python.org/dev/peps/pep-0008/) style guidelines
+- Use meaningful variable and function names
+- Keep functions small and focused on a single task
+- Maximum line length: 100 characters
+
+#### Python Code Quality
+
+- **Type hints**: Use type annotations where appropriate
+- **Docstrings**: Document all public modules, functions, classes, and methods using NumPy style
+- **Comments**: Write clear comments for complex logic
+- **DRY principle**: Extract common code into reusable functions
+
+## Testing Guidelines
+
+### Writing Tests
+
+- Write tests for all new features and bug fixes
+- Aim for high test coverage (>80%)
+- Use descriptive test names that explain what is being tested
+- Keep tests independent and isolated
+
+### C++ Testing
+
+We use Google Test (gtest) for C++ unit tests:
+
+```cpp
+TEST(TestSuiteName, TestName) {
+    // Arrange
+    auto test_data = SetupTestData();
+    
+    // Act
+    auto result = FunctionUnderTest(test_data);
+    
+    // Assert
+    EXPECT_EQ(result, expected_value);
+    ASSERT_TRUE(condition) << "Error message if fails";
+}
+```
+
+## Commit Message Guidelines
+
+Write clear and meaningful commit messages explaining scope and purpose of changes you are making.
+If your contributions are related to a submitted issue on the github repository, please include issue number(s) at the beginning of the commit message.
+
+## Pull Request Process
+
+### Before Submitting
+
+1. **Update your fork** with the latest upstream changes:
+   ```bash
+   git fetch upstream
+   git rebase upstream/main
+   ```
+
+2. **Create a feature branch**:
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+
+3. **Make your changes** following the coding standards
+
+4. **Add tests** for your changes
+
+5. **Run the test suite** to ensure everything passes
+
+6. **Update documentation** if needed
+
+### Submitting the Pull Request
+
+1. **Push your branch** to your fork:
+   ```bash
+   git push origin feature/your-feature-name
+   ```
+
+2. **Open a Pull Request** on GitHub with:
+   - Clear title describing the change
+   - Description of what and why
+   - Reference to related issues (e.g., "Closes #123")
+   - Screenshots or examples if applicable
+
+3. **Respond to feedback** - Be open to suggestions and make requested changes promptly
+
+### PR Review Criteria
+
+Your PR will be reviewed for:
+
+- Code quality and style compliance
+- Test coverage
+- Documentation completeness
+- Backward compatibility
+- Performance implications
+- Security considerations
+
+## Reporting Bugs
+
+### Before Reporting
+
+- Check if the bug has already been reported in the issue tracker
+- Verify the bug exists in the latest version
+- Collect relevant information about your environment
+
+### Bug Report Template
+
+When reporting bugs, please include:
+
+- **Description**: Clear description of the issue
+- **Steps to Reproduce**: Minimal steps to reproduce the problem
+- **Expected Behavior**: What you expected to happen
+- **Actual Behavior**: What actually happened
+- **Environment**:
+  - C++ compiler and version (e.g., GCC 13.3.0)
+  - dbzero version
+  - Operating system
+  - Python version (if relevant)
+  - Relevant dependencies
+- **Code Sample**: Minimal code that reproduces the issue
+- **Error Messages**: Full error messages and stack traces
+- **Screenshots**: If applicable
+
+## Suggesting Enhancements
+
+We welcome feature suggestions! When proposing enhancements:
+
+1. **Check existing issues** to avoid duplicates
+2. **Open an issue** with the `enhancement` label
+3. **Provide context**:
+   - What problem does this solve?
+   - Who would benefit from this feature?
+   - How should it work?
+   - Are there alternative approaches?
+4. **Be open to discussion** about implementation details
+
+## Documentation
+
+Good documentation is crucial. When contributing:
+
+### Code Documentation
+
+- Add docstrings to all public APIs
+- Include examples in docstrings where helpful
+- Keep documentation up-to-date with code changes
+
+### User Documentation
+
+- Update README.md for user-facing changes
+- Add tutorials or guides for new features
+- Update API reference documentation
+
+### Documentation Style
+
+- Use clear, concise language
+- Provide practical examples
+- Explain both the "how" and the "why"
+- Keep formatting consistent
+
+## Contributor License Agreement
+
+**Important**: Before your start contributing please make sure you read and agree to our Contributor License Agreement (CLA): [CLA.md](./CLA.md)
+
+### Why We Have a CLA
+
+dbzero is primarily licensed under LGPL-2.1, but we want to reserve the right to offer the software under alternative licenses to support different use cases and our business model.
+
+To enable this flexible licensing approach while maintaining our commitment to open source, we need contributors to grant us additional rights to use their contributions.
+
+### What You're Agreeing To
+
+By contributing to dbzero, you agree that:
+
+1. **Your contribution will be licensed under LGPL-2.1** in the open-source dbzero Community Edition
+2. **You grant the dbzero project maintainers** a perpetual, worldwide, non-exclusive, royalty-free, irrevocable license to:
+   - Use, modify, and distribute your contributions in any form
+   - Include your contributions in the open-source project and any alternative licensing options we may offer
+   - Sublicense your contributions under different license terms, including proprietary licenses
+   - Create derivative works based on your contributions
+3. **You retain full copyright** to your contributions and can use them in your own projects
+4. **You confirm** that:
+   - You have the legal right to grant this license
+   - Your contribution is your original work (or properly attributed if based on others' work)
+   - Your contribution doesn't violate any third-party intellectual property rights
+
+### How It Works
+
+When you submit your first pull request:
+1. Our CLA Assistant bot will prompt you to review and accept the CLA
+2. Your acceptance is recorded (this is a one-time process)
+3. Your PR will be marked as ready for review
+4. All future contributions will be covered under the same agreement
+
+### Questions About the CLA?
+
+If you have questions or concerns about the CLA, please open an issue to discuss before contributing. We're happy to clarify any points.
+
+## License
+
+By contributing to dbzero, you agree that your contributions will be:
+- Licensed under the **GNU Lesser General Public License v2.1** (LGPL-2.1) for the open-source dbzero Community Edition
+- Subject to the additional rights grant specified in our Contributor License Agreement: [CLA.md](./CLA.md)
+
+---
+
+Thank you for contributing to dbzero! Your efforts help make this project better for everyone. 🎉