crabxl 0.1.0__tar.gz

crabxl-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,46 @@
+name: Bug report
+description: CrabXL gives an incorrect result, an error or a crash.
+labels: [bug]
+body:
+  - type: input
+    id: version
+    attributes:
+      label: CrabXL version
+      description: Run `python -c "import crabxl; print(crabxl.__version__)"`.
+      placeholder: 0.1.0
+    validations:
+      required: true
+  - type: input
+    id: environment
+    attributes:
+      label: Python version and platform
+      placeholder: CPython 3.13, Linux x86_64
+    validations:
+      required: true
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What did CrabXL do? Include the full traceback.
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected result
+      description: What did you expect? If openpyxl gives a different result, tell us.
+    validations:
+      required: true
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Steps to reproduce
+      description: Give the smallest code that shows the problem.
+      render: python
+    validations:
+      required: true
+  - type: textarea
+    id: file
+    attributes:
+      label: Input file
+      description: Attach the smallest .xlsx file that shows the problem. Remove confidential data first.

crabxl-0.1.0/.github/ISSUE_TEMPLATE/compatibility.yml

@@ -0,0 +1,32 @@
+name: Difference from openpyxl
+description: Code that works with openpyxl 3.1.5 fails or gives a different result with CrabXL.
+labels: [compatibility]
+body:
+  - type: textarea
+    id: code
+    attributes:
+      label: Code
+      description: Give the smallest code that shows the difference.
+      render: python
+    validations:
+      required: true
+  - type: textarea
+    id: openpyxl
+    attributes:
+      label: openpyxl result
+    validations:
+      required: true
+  - type: textarea
+    id: crabxl
+    attributes:
+      label: CrabXL result
+      description: For example, a NotImplementedError or a different value.
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: CrabXL version
+      placeholder: 0.1.0
+    validations:
+      required: true

crabxl-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Rust core problem
+    url: https://github.com/crabxl/crabxl/issues/new/choose
+    about: Report problems with the Rust API in the crabxl repository.
+  - name: Security vulnerability
+    url: https://github.com/crabxl/crabxl-python/security/advisories/new
+    about: Report a vulnerability privately. Do not open a public issue.

crabxl-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,16 @@
+name: Feature request
+description: Suggest a new capability or an API improvement.
+labels: [enhancement]
+body:
+  - type: textarea
+    id: need
+    attributes:
+      label: Need
+      description: What do you want to do? Why can you not do it now?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposal
+      description: How could the API look? Give example code if possible.

crabxl-0.1.0/.github/actions/setup-supported-python/action.yml

@@ -0,0 +1,42 @@
+name: Set up supported CPython versions
+description: Install all supported interpreters on one runner; leave Python 3.14 as the builder.
+outputs:
+  python-311:
+    description: CPython 3.11 executable
+    value: ${{ steps.py311.outputs.python-path }}
+  python-312:
+    description: CPython 3.12 executable
+    value: ${{ steps.py312.outputs.python-path }}
+  python-313:
+    description: CPython 3.13 executable
+    value: ${{ steps.py313.outputs.python-path }}
+  python-314:
+    description: CPython 3.14 executable
+    value: ${{ steps.py314.outputs.python-path }}
+  python-315:
+    description: CPython 3.15 executable
+    value: ${{ steps.py315.outputs.python-path }}
+runs:
+  using: composite
+  steps:
+    - uses: actions/setup-python@v7
+      id: py311
+      with:
+        python-version: '3.11'
+    - uses: actions/setup-python@v7
+      id: py312
+      with:
+        python-version: '3.12'
+    - uses: actions/setup-python@v7
+      id: py313
+      with:
+        python-version: '3.13'
+    - uses: actions/setup-python@v7
+      id: py315
+      with:
+        python-version: '3.15'
+        allow-prereleases: true
+    - uses: actions/setup-python@v7
+      id: py314
+      with:
+        python-version: '3.14'

crabxl-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,15 @@
+## Change
+
+<!-- What does this pull request change, and why? -->
+
+Closes #
+
+## Checks
+
+- [ ] `ruff format --check .` and `ruff check .`
+- [ ] `cargo fmt -- --check` and `cargo clippy --all-targets --locked -- -D warnings`
+- [ ] `python -m pytest tests -q`
+- [ ] Behavior matches openpyxl 3.1.5, or the difference is an explicit error.
+- [ ] Selected openpyxl test assertions are unchanged.
+- [ ] User documentation in `docs/` is updated, if behavior changed.
+- [ ] Performance claims include measurements.

crabxl-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,30 @@
+name: Documentation
+
+on:
+  push:
+    branches: [main]
+    paths: [docs/**]
+  pull_request:
+    paths: [docs/**]
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    uses: crabxl/crabxl-docs/.github/workflows/check-docs.yml@main
+
+  rebuild-site:
+    needs: check
+    if: github.event_name == 'push'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Start a rebuild of the documentation site
+        env:
+          HOOK: ${{ secrets.DOCS_DEPLOY_HOOK }}
+        run: |
+          if [ -z "$HOOK" ]; then
+            echo "::notice::DOCS_DEPLOY_HOOK is not set. The daily rebuild includes this change."
+            exit 0
+          fi
+          curl -fsS -X POST "$HOOK"

crabxl-0.1.0/.github/workflows/python.yml

@@ -0,0 +1,62 @@
+name: Python compatibility
+on:
+  push:
+  pull_request:
+permissions:
+  contents: read
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: '3.14'
+      - run: python -m pip install 'ruff>=0.16.10,<0.17'
+      - run: ruff format --check .
+      - run: ruff check .
+  adapter:
+    needs: quality
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: rustfmt, clippy
+      - uses: ./.github/actions/setup-supported-python
+        id: pythons
+      - run: cargo fmt -- --check
+      - run: cargo clippy --all-targets --locked -- -D warnings
+      - run: python -m pip install 'maturin>=1.15,<2'
+      - name: Build all five wheels with shared Rust dependencies
+        env:
+          PYTHON_PATHS: ${{ toJSON(steps.pythons.outputs) }}
+        run: python tools/platform_wheels.py build
+      - name: Test each wheel in its matching clean Python environment
+        env:
+          PYTHON_PATHS: ${{ toJSON(steps.pythons.outputs) }}
+        run: python tools/platform_wheels.py test
+      - run: maturin sdist --out dist
+      - uses: actions/upload-artifact@v7
+        with:
+          name: python-packages-linux-x86_64
+          path: dist/*
+          if-no-files-found: error
+
+  native-platforms:
+    needs: quality
+    strategy:
+      matrix:
+        os: [windows-latest, macos-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v7
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: actions/setup-python@v7
+        with:
+          python-version: '3.14'
+      - run: python -m pip install maturin "pytest>=9.1.1,<10" "openpyxl==3.1.5" "Pillow>=12.3" "lxml>=6.1.3"
+      - run: maturin build --release --locked --out dist
+      - shell: bash
+        run: python -m pip install dist/*.whl
+      - run: python -m pytest tests -q

crabxl-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,181 @@
+name: Release Python
+
+# Push a version tag, for example 0.1.0, to release that commit.
+on:
+  push:
+    tags:
+      - '[0-9]+.[0-9]+.[0-9]+'
+
+permissions:
+  contents: read
+
+concurrency:
+  group: python-release
+  cancel-in-progress: false
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.request.outputs.version }}
+      notes: ${{ steps.request.outputs.notes }}
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v7
+        with:
+          python-version: '3.14'
+      - run: python -m pip install 'ruff>=0.16.10,<0.17'
+      - run: ruff format --check .
+      - run: ruff check .
+      - name: Validate the tag, the committed version and the changelog
+        id: request
+        env:
+          DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
+        run: python tools/release_tag.py
+
+  package:
+    needs: validate
+    runs-on: ${{ matrix.platform.runner }}
+    strategy:
+      fail-fast: false
+      matrix:
+        platform:
+          - name: linux-x86_64
+            runner: ubuntu-24.04
+            target: x86_64-unknown-linux-gnu
+          - name: linux-aarch64
+            runner: ubuntu-24.04-arm
+            target: aarch64-unknown-linux-gnu
+          - name: windows-x86_64
+            runner: windows-latest
+            target: x86_64-pc-windows-msvc
+          - name: macos-x86_64
+            runner: macos-15-intel
+            target: x86_64-apple-darwin
+          - name: macos-arm64
+            runner: macos-15
+            target: aarch64-apple-darwin
+    steps:
+      - uses: actions/checkout@v7
+      - uses: ./.github/actions/setup-supported-python
+        id: pythons
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: rustfmt, clippy
+      - run: cargo fmt -- --check
+      - run: cargo clippy --all-targets --locked -- -D warnings
+      - name: Build portable Linux wheels
+        if: runner.os == 'Linux'
+        uses: PyO3/maturin-action@v1
+        with:
+          maturin-version: 'v1.15.0'
+          rust-toolchain: 'stable'
+          target: ${{ matrix.platform.target }}
+          manylinux: '2_28'
+          args: >-
+            --release --locked --out dist --interpreter
+            /opt/python/cp311-cp311/bin/python
+            /opt/python/cp312-cp312/bin/python
+            /opt/python/cp313-cp313/bin/python
+            /opt/python/cp314-cp314/bin/python
+            /opt/python/cp315-cp315/bin/python
+      - name: Install the native package builder
+        if: runner.os != 'Linux'
+        run: python -m pip install 'maturin>=1.15,<2'
+      - name: Build Windows and macOS wheels
+        if: runner.os != 'Linux'
+        env:
+          PYTHON_PATHS: ${{ toJSON(steps.pythons.outputs) }}
+        run: python tools/platform_wheels.py build --target ${{ matrix.platform.target }}
+      - name: Test all five installed CPython wheels
+        env:
+          PYTHON_PATHS: ${{ toJSON(steps.pythons.outputs) }}
+        run: python tools/platform_wheels.py test
+      - uses: actions/upload-artifact@v7
+        with:
+          name: release-wheel-${{ matrix.platform.name }}
+          path: dist/*.whl
+          if-no-files-found: error
+
+  source:
+    needs: validate
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: '3.14'
+      - uses: dtolnay/rust-toolchain@stable
+      - run: python -m pip install 'maturin>=1.15,<2'
+      - run: maturin sdist --out dist
+      - name: Build and test from the source distribution
+        run: python tools/test_distribution.py '*.tar.gz'
+      - uses: actions/upload-artifact@v7
+        with:
+          name: release-source
+          path: dist/*.tar.gz
+          if-no-files-found: error
+
+  publish:
+    needs: [validate, package, source]
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v7
+        with:
+          python-version: '3.14'
+      - uses: actions/download-artifact@v8
+        with:
+          pattern: release-*
+          path: dist
+          merge-multiple: true
+      - name: Verify artifact identities and safe retries
+        env:
+          RELEASE_VERSION: ${{ needs.validate.outputs.version }}
+        run: python tools/check_release_files.py "$RELEASE_VERSION"
+      - name: Publish to PyPI using OIDC
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/
+          skip-existing: true
+
+  release:
+    needs: [validate, publish]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v7
+        with:
+          python-version: '3.14'
+      - uses: actions/download-artifact@v8
+        with:
+          pattern: release-*
+          path: dist
+          merge-multiple: true
+      - name: Recheck the version and create the GitHub release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          GH_REPO: ${{ github.repository }}
+          RELEASE_VERSION: ${{ needs.validate.outputs.version }}
+          RELEASE_NOTES: ${{ needs.validate.outputs.notes }}
+        run: |
+          python tools/release.py check "$RELEASE_VERSION"
+          printf '%s\n' "$RELEASE_NOTES" > "$RUNNER_TEMP/release-notes.md"
+          if gh release view "$RELEASE_VERSION" > /dev/null 2>&1; then
+            gh release upload "$RELEASE_VERSION" dist/* --clobber
+          else
+            gh release create "$RELEASE_VERSION" dist/* --verify-tag \
+              --title "$RELEASE_VERSION" --notes-file "$RUNNER_TEMP/release-notes.md"
+          fi

crabxl-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+/target/
+/dist/
+/.venv/
+__pycache__/
+.pytest_cache/
+*.egg-info/
+
+# Native extension built by maturin develop or pip install -e
+python/crabxl/*.so
+python/crabxl/*.pyd

crabxl-0.1.0/CHANGELOG.md

@@ -0,0 +1,47 @@
+# Changelog
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+Before version 1.0, a minor version can change the API.
+
+Each release uses a pinned revision of the Rust core. The core has its own
+[changelog](https://github.com/crabxl/crabxl/blob/main/CHANGELOG.md).
+
+## [0.1.0]
+
+First release. It uses the Rust core 0.1.0.
+
+### Added
+
+- `Workbook`, `load_workbook`, `Worksheet` and `Cell` with openpyxl call names,
+  in normal, `read_only` and `write_only` modes. Paths and file-like objects.
+- Values, dates, formulas with cached results and rich text.
+- Cell styles (`Font`, `PatternFill`, `GradientFill`, `Border`, `Alignment`,
+  `Protection`, number formats), named styles, themes, row and column styles,
+  `cell.quotePrefix` and `cell.pivotButton`.
+- Merged cells, row and column dimensions, outline groups and hyperlinks,
+  including in `write_only` mode.
+- Sheet create, copy, remove, rename and move; `append`, `insert_rows`,
+  `delete_rows`, `insert_cols`, `delete_cols` and `move_range`.
+- Tables, auto filters, conditional formatting, data validation, comments,
+  sheet protection, headers and footers, print areas and titles, defined
+  names, scenarios, workbook protection and document properties.
+- Images, charts, chartsheets, drawings, pivot tables, external links and
+  `wb.vba_archive`.
+- `ws.sheet_properties` and `ws.sheet_format` in all modes.
+- The openpyxl import paths, for example `crabxl.worksheet.table`,
+  `crabxl.formatting.rule` and `crabxl.comments`, and the deprecated openpyxl
+  3.1 calls such as `get_sheet_by_name`, which emit a `DeprecationWarning`.
+- `max_memory_bytes`, `ResourceOptions`, `ResourceLimits`,
+  `SharedStringOptions` and `AutoMemory` to control memory, temporary storage
+  and shared strings.
+- `save(path, compression_level=...)`. Level 0 stores without compression;
+  levels 1–9 use Deflate; the default is 6.
+- Rows of plain values (`None`, `bool`, `int`, `float`, `str` and dates and
+  times) are converted in Rust when appended.
+- `tools/run_openpyxl_suite.py` runs the unchanged openpyxl 3.1.5 test suite
+  against crabxl and checks the result against a tracked list of expected
+  failures. `--report` writes the compatibility page of the documentation.
+- The user guide, adapted from the openpyxl documentation, and pages for
+  memory limits, migration, supported features and compatibility.
+
+[0.1.0]: https://github.com/crabxl/crabxl-python/releases/tag/0.1.0

crabxl-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,146 @@
+# Contributing to CrabXL for Python
+
+## Ways to contribute
+
+- **Report a bug.** Use the [issue forms](https://github.com/crabxl/crabxl-python/issues/new/choose).
+  Give the CrabXL version, the Python version and the smallest code or `.xlsx`
+  file that shows the problem. Remove confidential data first.
+- **Report a difference from openpyxl.** CrabXL must behave like openpyxl
+  3.1.5. Give the code, the openpyxl result and the CrabXL result.
+- **Improve the documentation.** User documentation is in [docs](docs). The
+  documentation site is built from it by
+  [crabxl-docs](https://github.com/crabxl/crabxl-docs).
+- **Contribute code.** For a change that is larger than a small fix, open an
+  issue first. Agree on the design before you start the work.
+
+Do not report security problems in public issues. Read [SECURITY.md](SECURITY.md).
+
+## How this package works
+
+This package does not implement spreadsheet features itself. The Rust core in
+[crabxl](https://github.com/crabxl/crabxl) implements them. This package adapts
+the core to the openpyxl API.
+
+- If a feature is missing in the core, add it to the core first.
+- `Cargo.toml` pins the core to an exact Git revision. A change that needs a
+  new core feature also updates this revision.
+- An unsupported feature raises an explicit error, usually
+  `NotImplementedError`. The package never falls back to openpyxl.
+
+## Repository layout
+
+| Path | Contents |
+|---|---|
+| `python/crabxl` | Public Python package. Its modules follow the openpyxl module layout. |
+| `src/` | PyO3 bindings to the Rust core. |
+| `tests/` | Tests. Files named `test_upstream_*.py` contain selected openpyxl tests. |
+| `third_party/` | Provenance and licenses of the selected openpyxl tests. |
+| `docs/` | Public user documentation. |
+| `internal/` | Maintainer records: [status](internal/STATUS.md), roadmap, architecture, design decisions and release evidence. |
+| `tools/` | Release, wheel and provenance scripts. |
+
+## Development setup
+
+You need:
+
+- Python 3.11 or later.
+- Rust 1.99 or later, installed with [rustup](https://rustup.rs/). The
+  repository uses the latest stable toolchain. If the build reports that it
+  requires a newer `rustc`, run `rustup update stable`.
+
+```sh
+git clone https://github.com/crabxl/crabxl-python.git
+cd crabxl-python
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install "maturin>=1.15,<2"
+python -m pip install -e ".[test,dev]"
+```
+
+The editable install builds the native extension. After you change Rust code in
+`src/`, build it again:
+
+```sh
+maturin develop --release
+```
+
+## Checks
+
+CI runs these checks. Run them before you open a pull request:
+
+```sh
+ruff format --check .
+ruff check .
+cargo fmt -- --check
+cargo clippy --all-targets --locked -- -D warnings
+python -m pytest tests -q
+```
+
+CI also builds and tests wheels for all supported Python versions on Linux,
+Windows and macOS.
+
+## Code rules
+
+- **Match openpyxl.** Use the same call names, arguments, object access and
+  observable behavior as openpyxl 3.1.5. Extensions are permitted, but keep
+  them separate from compatible calls.
+- **Fail explicitly.** If a feature is not supported, raise an error. Do not
+  accept a property that is lost on save.
+- **Keep work in Rust.** Convert values in batches. Release the GIL during
+  native work.
+- **Write in English** in code, comments, documentation and commit messages.
+
+### Tests
+
+- Add tests that compare the CrabXL result with the openpyxl result for the
+  same public calls.
+- Do not change the assertions of the selected openpyxl tests. Their bodies are
+  recorded in `third_party/`. To verify them, run
+  `python tools/verify_python_test_provenance.py --reference-checkout <path>`
+  with a checkout of openpyxl 3.1.5.
+- Mark expected failures explicitly. Do not count them as passes.
+- Do not put timing limits in tests. Measure performance with [crabxl-benchmarks](https://github.com/crabxl/crabxl-benchmarks).
+
+### Performance changes
+
+If you claim a speed or memory improvement, include the measurements. Compare
+the same mode and the same behavior in CrabXL and openpyxl. Give the time, peak
+memory and the commands that you used.
+
+### Code from other projects
+
+You can copy code from another project, including openpyxl, if its license is
+compatible with MIT. Keep the original copyright notice and add the project to
+[third_party/](third_party).
+
+### Design decisions
+
+Explain large design changes in the pull request.
+
+## Documentation style
+
+Follow the [writing rules](https://github.com/crabxl/crabxl-docs/blob/main/WRITING.md)
+and the [page format](https://github.com/crabxl/crabxl-docs/blob/main/CONTENT-SPEC.md).
+CI checks them with Vale.
+
+## Commits and pull requests
+
+- Use [Conventional Commits](https://www.conventionalcommits.org/):
+  `<type>(<scope>): <description>`. For example:
+  `fix(worksheet): keep merged cells after a row insertion`. Common types are
+  `feat`, `fix`, `docs`, `refactor`, `perf`, `test`, `build`, `ci` and `chore`.
+- Put one coherent change in each commit. Related code, tests and documentation
+  can be in the same commit. Put unrelated changes in separate commits.
+- Describe the result, not the work process.
+- Complete the pull request template. Link the related issue. Make sure that CI
+  passes.
+
+## Releases
+
+Maintainers make releases with the release workflow. You do not need to change
+version numbers. [internal/releases.md](internal/releases.md) describes the
+process.
+
+## License
+
+You agree that your contributions are licensed under the [MIT License](LICENSE).