dot-parser 2.0.0__tar.gz

dot_parser-2.0.0/.gitignore

@@ -0,0 +1,119 @@
+# --- Project-specific ---
+working-notes/
+# Scratch parse/benchmark runs. Tracked fixtures live in benchmark/input and
+# benchmark/output/md, so only these throwaway locations are ignored.
+scratch/
+tmp/
+out/
+*.local.*
+
+# --- Secrets / local config ---
+.env
+.env.*
+!.env.example
+*.pem
+*.key
+credentials.json
+secrets.yaml
+secrets.yml
+
+# --- Python bytecode / build artifacts ---
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+build/
+dist/
+sdist/
+wheels/
+develop-eggs/
+eggs/
+.eggs/
+*.egg-info/
+*.egg
+MANIFEST
+pip-wheel-metadata/
+share/python-wheels/
+
+# --- Virtual environments ---
+.venv/
+venv/
+env/
+ENV/
+.uv/
+
+# --- Testing / coverage / type checking ---
+.pytest_cache/
+.cache/
+.tox/
+.nox/
+htmlcov/
+.coverage
+.coverage.*
+coverage.xml
+*.cover
+nosetests.xml
+.hypothesis/
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.pyre/
+.pytype/
+.ruff_cache/
+.ty_cache/
+
+# --- Notebooks ---
+.ipynb_checkpoints/
+profile_default/
+ipython_config.py
+
+# --- Docs ---
+docs/_build/
+site/
+
+# --- Logs & databases ---
+*.log
+logs/
+*.sqlite
+*.sqlite3
+*.db
+
+# --- Editors / IDEs ---
+.idea/
+.vscode/
+!.vscode/settings.json
+!.vscode/extensions.json
+*.swp
+*.swo
+*~
+.spyderproject
+.spyproject
+.ropeproject
+
+# --- OS cruft ---
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+Thumbs.db
+ehthumbs.db
+Desktop.ini
+
+# --- Agent config ---
+.agents/
+.claude/
+
+# --- Local scratch ---
+local/
+sources/
+working-notes/
+
+# --- Pin Python: versioned on purpose, overrides the global ignore ---
+!.python-version
+
+# --- CI caches (UV_CACHE_DIR / PRE_COMMIT_HOME point here in .gitlab-ci.yml) ---
+# Not just local hygiene: hatchling would otherwise pull them into the sdist,
+# and a cached virtualenv carries absolute symlinks that break the build.
+.uv-cache/
+.pre-commit-cache/

dot_parser-2.0.0/.gitlab-ci.yml

@@ -0,0 +1,181 @@
+# Pipeline for a Python library published to PyPI.
+#
+#   quality  lint, format and type checks (pre-commit)
+#   test     pytest on every supported Python version
+#   publish  tag-only: build, then TestPyPI, then PyPI behind a manual gate
+#
+# Publishing uses PyPI Trusted Publishing (OIDC): GitLab mints a short-lived ID
+# token, PyPI exchanges it for a publish token valid for minutes. No API token
+# is stored in the project. Declare this repository as a trusted publisher at
+# https://pypi.org/manage/project/dot-parser/settings/publishing/ (and the same on
+# test.pypi.org) before the first release.
+
+workflow:
+  rules:
+    # Merge requests take priority...
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+      when: always
+    # ...release tags (vX.Y.Z, optionally -rc.N)...
+    - if: $CI_COMMIT_TAG =~ /^v\d+\.\d+\.\d+(?:-rc\.\d+)?$/
+      when: always
+    # ...and pushes to main. The MR rule above keeps this from double-firing.
+    - if: $CI_COMMIT_BRANCH == "main"
+      when: always
+    # Anything else (branch pushes without an MR, malformed tags) runs nothing.
+    - when: never
+
+stages:
+  - quality
+  - test
+  - publish
+
+variables:
+  UV_CACHE_DIR: "$CI_PROJECT_DIR/.uv-cache"
+  PRE_COMMIT_HOME: "$CI_PROJECT_DIR/.pre-commit-cache"
+  # Keep resolution reproducible: fail rather than silently relock.
+  UV_FROZEN: "1"
+
+default:
+  image: ghcr.io/astral-sh/uv:python3.12-bookworm-slim
+  cache:
+    key:
+      files:
+        - uv.lock
+    paths:
+      - .uv-cache
+      - .pre-commit-cache
+
+# --------------------------------------------------------------------------
+# quality
+# --------------------------------------------------------------------------
+
+quality:
+  stage: quality
+  before_script:
+    - apt-get update && apt-get install -y --no-install-recommends git
+    - uv sync --all-extras --all-groups
+  script:
+    - uv run pre-commit run --all-files --show-diff-on-failure
+
+# --------------------------------------------------------------------------
+# test
+# --------------------------------------------------------------------------
+
+test:
+  stage: test
+  image: ghcr.io/astral-sh/uv:python$PYTHON_VERSION-bookworm-slim
+  parallel:
+    matrix:
+      # Every version the package claims to support in requires-python.
+      - PYTHON_VERSION: ["3.12", "3.13"]
+  before_script:
+    - uv sync --all-extras --all-groups --python "$PYTHON_VERSION"
+  script:
+    - uv run --python "$PYTHON_VERSION" pytest --cov=src --cov-report=term --cov-report=xml
+  coverage: '/^TOTAL.*\s+(\d+%)$/'
+  artifacts:
+    when: always
+    reports:
+      coverage_report:
+        coverage_format: cobertura
+        path: coverage.xml
+
+# --------------------------------------------------------------------------
+# publish  (release tags only)
+# --------------------------------------------------------------------------
+
+# The tag drives the release, so it must agree with the packaged version:
+# publishing v1.2.3 from a tree that says 1.2.2 cannot be undone on PyPI.
+check_version:
+  stage: publish
+  script:
+    - VERSION="$(uv version --short)"
+    - |
+      if [ "v$VERSION" != "$CI_COMMIT_TAG" ]; then
+        echo "Tag $CI_COMMIT_TAG does not match project version v$VERSION."
+        echo "Run 'uv version <new>' and retag."
+        exit 1
+      fi
+    - echo "Tag matches version v$VERSION."
+  rules:
+    - if: $CI_COMMIT_TAG
+
+build:
+  stage: publish
+  needs: ["check_version"]
+  # No cache here on purpose: the shared cache restores .uv-cache/ and
+  # .pre-commit-cache/ into the project directory, and the sdist would pick
+  # them up — cached virtualenvs carry absolute symlinks that fail the build.
+  cache: []
+  script:
+    # --no-sources ignores tool.uv.sources, so the build matches what a user
+    # installing from PyPI will actually get.
+    - uv build --no-sources
+    - ls -l dist/
+  artifacts:
+    paths:
+      - dist/
+    expire_in: 1 week
+  rules:
+    - if: $CI_COMMIT_TAG
+
+.publish:
+  stage: publish
+  needs: ["build"]
+  before_script:
+    - apt-get update && apt-get install -y --no-install-recommends curl jq
+  script:
+    # Exchange the GitLab OIDC token for a short-lived PyPI publish token.
+    # Never echoed: it would land in the job log in clear text.
+    - |
+      MINTED="$(curl -sS -X POST "$PYPI_MINT_URL" \
+        -H 'Content-Type: application/json' \
+        -d "{\"token\":\"${PYPI_ID_TOKEN}\"}" | jq -r '.token // empty')"
+      if [ -z "$MINTED" ]; then
+        echo "Could not mint a publish token. Is this project registered as a"
+        echo "trusted publisher on $PYPI_HOST, with the right branch/tag rules?"
+        exit 1
+      fi
+      export UV_PUBLISH_TOKEN="$MINTED"
+    - uv publish --publish-url "$PYPI_PUBLISH_URL" dist/*
+
+publish_testpypi:
+  extends: .publish
+  id_tokens:
+    PYPI_ID_TOKEN:
+      aud: testpypi
+  variables:
+    PYPI_HOST: test.pypi.org
+    PYPI_MINT_URL: https://test.pypi.org/_/oidc/mint-token
+    PYPI_PUBLISH_URL: https://test.pypi.org/legacy/
+  environment:
+    name: testpypi
+    url: https://test.pypi.org/project/dot-parser/
+  rules:
+    - if: $CI_COMMIT_TAG
+
+publish_pypi:
+  extends: .publish
+  # `extends` REPLACES `needs`, it does not merge it: redeclaring the
+  # dependency on publish_testpypi drops the one on build inherited from
+  # `.publish`, and the job starts with an empty dist/ ("No files found to
+  # publish"). Both edges have to be spelled out here.
+  needs:
+    - job: build
+      artifacts: true
+    - job: publish_testpypi
+      artifacts: false
+  id_tokens:
+    PYPI_ID_TOKEN:
+      aud: pypi
+  variables:
+    PYPI_HOST: pypi.org
+    PYPI_MINT_URL: https://pypi.org/_/oidc/mint-token
+    PYPI_PUBLISH_URL: https://upload.pypi.org/legacy/
+  environment:
+    name: pypi
+    url: https://pypi.org/project/dot-parser/
+  rules:
+    # Manual on purpose: a PyPI release cannot be taken back, only yanked.
+    - if: $CI_COMMIT_TAG
+      when: manual

dot_parser-2.0.0/.pre-commit-config.yaml

@@ -0,0 +1,34 @@
+# Verbatim legal texts (the AGPL and the DCO both forbid modification) and
+# generated parser outputs, kept byte-for-byte as the backends produced them.
+exclude: '^(LICENSE\.md|DCO|benchmark/output/)'
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-merge-conflict
+      - id: check-case-conflict
+      - id: check-added-large-files
+        args: ["--maxkb=1000"]
+      - id: detect-private-key
+      - id: debug-statements
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.16.0
+    hooks:
+      - id: ruff-check
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: local
+    hooks:
+      - id: ty
+        name: ty (type check)
+        entry: uv run --frozen ty check
+        language: system
+        types: [python]
+        pass_filenames: false

dot_parser-2.0.0/.python-version

@@ -0,0 +1 @@
+3.12

dot_parser-2.0.0/AUTHORS.md

@@ -0,0 +1,13 @@
+# Authors
+
+Copyright in this project is held by **Kannon For Deep Tech**.
+This file credits the individuals who have contributed to it. Being listed
+here does not confer any ownership of, or rights in, the project.
+
+## Kannon For Deep Tech
+
+- Adrien Marjollet
+- Jean Fechter
+- Noé Malais
+
+## External contributors

dot_parser-2.0.0/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [2.0.0] - 2026-07-30
+
+First public release.
+
+### Added
+
+- `parse()` converts PDF, DOCX, PPTX, HTML, XLSX, CSV, Markdown and plain text
+  into clean Markdown.
+- Selectable PDF backends: `Pymu` (default, local and fast), `Docling` (local
+  layout-aware ML pipeline), `Mistral` (cloud OCR) and `Llama` (LlamaCloud).
+- `parse_with_images()` extracts images alongside the Markdown, with anchors
+  kept at their position in the text. Images are described either by a VLM or
+  by Mistral OCR annotations in the same call.
+- `parse_pdfs()` parses many PDFs in one batch job through the Mistral Batch
+  API, falling back to a per-file loop on backends without batch support.
+- `chunk()` splits Markdown into chunks carrying their heading hierarchy in
+  `section_path`.
+- Cost helpers: `cost_per_1k_pages()` and `estimate_cost()`, usable without
+  instantiating a backend.
+- Backend protocols (`Backend`, `ImageBackend`, `BatchBackend`,
+  `DocxImageBackend`, `PptxImageBackend`) so third-party backends can plug in.
+
+### Changed
+
+These matter only if you were installing the package straight from git before
+this release.
+
+- `LlamaTier` is a `Literal` of the four accepted tiers rather than a bare
+  `str`, and is defined once alongside the pricing table.
+- `zip()` calls over sequences that must line up now use `strict=True`: a length
+  mismatch raises instead of silently truncating.
+- `parse_with_images(backend=...)` accepts DOCX- and PPTX-capable backends in
+  its type signature, matching what the function already supported at runtime.
+
+[Unreleased]: https://gitlab.com/deepika6190303/deepika-open-toolbox/dot-parser/-/compare/v2.0.0...main
+[2.0.0]: https://gitlab.com/deepika6190303/deepika-open-toolbox/dot-parser/-/tags/v2.0.0

dot_parser-2.0.0/CONTRIBUTING.md

@@ -0,0 +1,87 @@
+# Contributing
+
+Thanks for your interest in this project. Contributions are welcome.
+
+This project is maintained by **Kannon For Deep Tech** and released under the
+GNU Affero General Public License v3.0 or later (`AGPL-3.0-or-later`).
+
+## 1. Sign off your commits (DCO)
+
+Every commit must carry a `Signed-off-by` line. Add it automatically with:
+
+```
+git commit -s
+```
+
+This appends:
+
+```
+Signed-off-by: Jane Doe <jane@example.com>
+```
+
+The name and email must be your real ones and must match your commit author
+details. By signing off, you certify the [Developer Certificate of Origin](DCO)
+(v1.1) **and** you agree to the licensing terms in section 2 below.
+
+Pull requests with unsigned commits will not be merged.
+
+## 2. Licensing of your contribution
+
+By contributing to this project, you agree to the following.
+
+**2.1 — Outbound licence.** Your contribution is licensed to the public under
+`AGPL-3.0-or-later`, the same terms as the rest of the project.
+
+**2.2 — Additional grant to the maintainer.** You additionally grant Kannon For
+Deep Tech a perpetual, worldwide, irrevocable, non-exclusive, royalty-free,
+transferable and sublicensable right to reproduce, modify, adapt, translate,
+publish, distribute and otherwise exploit your contribution, in whole or in
+part, in any form and by any means, on any medium, **under any licensing terms,
+including proprietary and commercial terms**, for the entire duration of the
+applicable copyright protection and worldwide.
+
+**2.3 — What this means in practice.** This project is dual-licensed: it is
+available to everyone under the AGPL, and Kannon For Deep Tech also sells
+commercial licences to organisations that cannot comply with the AGPL. Section
+2.2 is what makes that possible. Without it, no contribution could be included
+in a commercially licensed version.
+
+**2.4 — You keep your copyright.** This is a licence grant, not a transfer of
+ownership. You remain the author and copyright holder of your contribution and
+stay free to use and relicense it however you wish, elsewhere.
+
+**2.5 — Your warranties.** You confirm that you are entitled to grant the above
+rights, that your contribution is your original work or that you hold the
+necessary rights over it, and that it does not infringe any third-party rights.
+If you are contributing in the course of your employment or under a service
+agreement, you confirm that your employer or client has authorised you to
+contribute under these terms, or has waived any rights that would conflict with
+them.
+
+## 3. Contractors and employees of Kannon For Deep Tech
+
+If you are working for Kannon For Deep Tech as an employee or under a service
+agreement, the assignment of rights set out in your contract governs, and takes
+precedence over this file. The sign-off above does not replace it.
+
+## 4. Submitting a change
+
+1. Open an issue first for anything substantial, so we can agree on the approach.
+2. Fork, branch, and keep commits focused.
+3. Add or update tests where relevant.
+4. Add the SPDX headers to any new file:
+
+   ```
+   # SPDX-FileCopyrightText: Kannon For Deep Tech and contributors
+   # SPDX-License-Identifier: AGPL-3.0-or-later
+   ```
+
+   Do not modify the copyright lines of existing files. If you would like to be
+   credited individually, add yourself to [AUTHORS.md](AUTHORS.md) in the same pull request.
+
+5. Sign off every commit (`git commit -s`) and open a pull request.
+
+## 5. Questions
+
+For anything about licensing, including commercial licences, contact
+<louis.letarnec@deepika.ai>.

dot_parser-2.0.0/DCO

@@ -0,0 +1,34 @@
+Developer Certificate of Origin
+Version 1.1
+
+Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
+
+Everyone is permitted to copy and distribute verbatim copies of this
+license document, but changing it is not allowed.
+
+
+Developer's Certificate of Origin 1.1
+
+By making a contribution to this project, I certify that:
+
+(a) The contribution was created in whole or in part by me and I
+    have the right to submit it under the open source license
+    indicated in the file; or
+
+(b) The contribution is based upon previous work that, to the best
+    of my knowledge, is covered under an appropriate open source
+    license and I have the right under that license to submit that
+    work with modifications, whether created in whole or in part
+    by me, under the same open source license (unless I am
+    permitted to submit under a different license), as indicated
+    in the file; or
+
+(c) The contribution was provided directly to me by some other
+    person who certified (a), (b) or (c) and I have not modified
+    it.
+
+(d) I understand and agree that this project and the contribution
+    are public and that a record of the contribution (including all
+    personal information I submit with it, including my sign-off) is
+    maintained indefinitely and may be redistributed consistent with
+    this project or the open source license(s) involved.