Tree-Mendous

Tree-Mendous is a Python library for managing available integer ranges with interchangeable Python and native CPU backends. It also ships 50 concrete, process-local application engines for partitioning, scheduling, overlap catalogs, allocation, and numeric leasing. The range API models half-open ranges: [start, end) includes start and excludes end.

Install

Tree-Mendous supports Python 3.11–3.13.

pip install treemendous

or:

uv add treemendous

Quickstart

create_range_set requires an explicit managed domain for canonical use. The domain starts fully available unless initially_available=False is supplied.

from treemendous import Span, create_range_set

ranges = create_range_set(domain=(0, 24), backend="py_boundary")
ranges.discard(Span(0, 9))
ranges.discard(Span(17, 24))
booking = ranges.allocate(2, not_before=9, not_after=17)
assert booking is not None
assert (booking.start, booking.end) == (9, 11)
next_fit = ranges.first_fit(2, not_before=11, not_after=17)
assert next_fit is not None and (next_fit.start, next_fit.end) == (11, 13)
assert ranges.snapshot().total_free == 6

This CPU scheduling example atomically finds and removes [9, 11). allocate returns None when no fit exists. not_after is an exclusive scheduling boundary: the allocated end may equal it. Empty or reversed spans and non-positive lengths raise ValueError; non-integer coordinates raise TypeError. Mutations outside the managed domain fail before changing state.

Payload algebra belongs to RangeSet, not to a backend. Supply an explicit policy whenever values are attached; the same policy behaves identically on Python and native geometry backends:

from treemendous import Span, UniformPayloadPolicy, create_range_set

cpus = create_range_set(
    domain=(0, 8),
    backend="py_boundary",
    initially_available=False,
    payload_policy=UniformPayloadPolicy(),
)
cpus.add(Span(0, 8), payload="cpu")
assert cpus.first_fit(2, not_before=0).data == "cpu"

See API and payload policies for join and ordered policies. All raw backends store geometry only.

Stable exact batches

Version 1.1 adds treemendous.exact_batch, a specialized native CPU API for exact, ordered, whole-batch-atomic geometry mutation. It is deliberately not exported from treemendous, is not a backend or protocol capability, and does not support payloads, allocation, or generic queries.

from treemendous import Span
from treemendous.exact_batch import (
    BatchLimits,
    BatchMutation,
    ExactBatchRangeSet,
    MutationOpcode,
)

limits = BatchLimits(max_operations=2)
ranges = ExactBatchRangeSet((0, 64), initially_available=False, limits=limits)
results = ranges.mutate([
    BatchMutation(MutationOpcode.ADD, 8, 20),
    BatchMutation(MutationOpcode.DISCARD_REQUIRE_COVERED, 10, 14),
])
assert [result.changed for result in results] == [(Span(8, 20),), (Span(10, 14),)]
assert [result.changed_length for result in results] == [12, 4]

Rows run in input order and either the complete batch publishes or the exact pre-batch snapshot remains visible. Per-instance BatchLimits bound operation count, live intervals, changed spans, packed-result bytes, and staging work. See the exact-batch contract, the API summary, and the executable example.

Application engines

The application registry is an explicit namespace and is not re-exported from the stable treemendous root. Use treemendous.applications.create_application for scenario-ID dispatch, or import a concrete type from its scenario module. The application index documents all five packages, every engine and example, shared kernels, guarantees, and process-local boundaries. The use-case matrix distinguishes these 50 engines from the separate 50 legacy generic backend traces.

Backend maturity

Availability is probed at runtime; an explicit unavailable or invalid backend raises a reasoned error. Automatic selection uses only stable backends that pass semantic probes and satisfy the requested capabilities and coordinate width.

Backend ID Runtime Width Maturity Notes
py_boundary Python/CPU 64-bit Stable Core geometry
py_avl_earliest Python/CPU 64-bit Stable Core geometry
py_summary Python/CPU 64-bit Stable Native analytics and best fit
py_treap Python/CPU 64-bit Stable Native random sampling
py_boundary_summary Python/CPU 64-bit Stable Native analytics and best fit
cpp_boundary C++/CPU 64-bit Stable when built Core geometry
cpp_treap C++/CPU 32-bit Experimental Not selectable
cpp_boundary_summary C++/CPU 32-bit Experimental Not selectable
cpp_boundary_summary_optimized C++/CPU 32-bit Experimental Not selectable
gpu_boundary_summary CUDA/GPU 32-bit Experimental Not selectable
metal_boundary_summary Metal/GPU 32-bit Experimental Not selectable

Details and probe behavior are in Backends.

Maintained documentation

Development

uv sync --all-extras
just check
just build

just check enforces Ruff lint and formatting, mypy, branch coverage, docs contracts, and bytecode/artifact-policy sanity. The generic backend suites are just benchmark-smoke, just benchmark-standard, and just benchmark-large. The concrete engine suites are just benchmark-applications-smoke and just benchmark-applications-standard. just benchmark runs both standard suites, and just run-examples executes all 50 application examples plus the basic, exact-batch, and multidimensional examples. All benchmark recipes write JSON, Markdown, and checksum artifacts. See Benchmarking and Contributing.

License: BSD-3-Clause.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (1.2.0)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for josephjohncox from gravatar.com josephjohncox

Credits

Author: Joseph Cox

License expression

BSD-3-Clause
View SPDX License List

Requires

Python >=3.11

Provides Extra

build quality test

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

treemendous-1.1.0.tar.gz (603.1 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

treemendous-1.1.0-cp313-cp313-win_amd64.whl (808.0 kB view details)

Uploaded CPython 3.13Windows x86-64

treemendous-1.1.0-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (1.0 MB view details)

Uploaded CPython 3.13manylinux: glibc 2.17+ x86-64

treemendous-1.1.0-cp313-cp313-macosx_12_0_universal2.whl (1.7 MB view details)

Uploaded CPython 3.13macOS 12.0+ universal2 (ARM64, x86-64)

treemendous-1.1.0-cp312-cp312-win_amd64.whl (807.9 kB view details)

Uploaded CPython 3.12Windows x86-64

treemendous-1.1.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (1.0 MB view details)

Uploaded CPython 3.12manylinux: glibc 2.17+ x86-64

treemendous-1.1.0-cp312-cp312-macosx_12_0_universal2.whl (1.7 MB view details)

Uploaded CPython 3.12macOS 12.0+ universal2 (ARM64, x86-64)

treemendous-1.1.0-cp311-cp311-win_amd64.whl (801.0 kB view details)

Uploaded CPython 3.11Windows x86-64

treemendous-1.1.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (1.0 MB view details)

Uploaded CPython 3.11manylinux: glibc 2.17+ x86-64

treemendous-1.1.0-cp311-cp311-macosx_12_0_universal2.whl (1.7 MB view details)

Uploaded CPython 3.11macOS 12.0+ universal2 (ARM64, x86-64)

File details

Details for the file treemendous-1.1.0.tar.gz.

File metadata

  • Download URL: treemendous-1.1.0.tar.gz
  • Upload date:
  • Size: 603.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for treemendous-1.1.0.tar.gz
Algorithm Hash digest
SHA256 98574696c9465d461f5e2d5286fc55d17fc50e27b835d5fde94e29c4da5405aa
MD5 a2aadbccbf592cc5787ed0558e1fa1e4
BLAKE2b-256 38ac25ba231e94fbdb3c0de1a954ae5d23d124d10c46c5f67a9d2966067ce499

See more details on using hashes here.

Provenance

The following attestation bundles were made for treemendous-1.1.0.tar.gz:

Publisher: release.yml on josephjohncox/TreeMendous

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file treemendous-1.1.0-cp313-cp313-win_amd64.whl.

File metadata

  • Download URL: treemendous-1.1.0-cp313-cp313-win_amd64.whl
  • Upload date:
  • Size: 808.0 kB
  • Tags: CPython 3.13, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for treemendous-1.1.0-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 9836b37f72090b3ae8a21fae0f723e25dd142f2b44b89c8a2942971ad4f46ed6
MD5 1007a66a206fbe8cceb5ee2955b63ffc
BLAKE2b-256 70690813462ac8b8fab6bec85d37a0f170ce41bfbed92cc98e209b815935b8c9

See more details on using hashes here.

Provenance

The following attestation bundles were made for treemendous-1.1.0-cp313-cp313-win_amd64.whl:

Publisher: release.yml on josephjohncox/TreeMendous

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file treemendous-1.1.0-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for treemendous-1.1.0-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 e8791413e35ceff4a6fbd919b095b8a372cf24090e2768d1c06b85b8142e5a1f
MD5 aaebfabcc48b1d4d3eb360cd6d4ffe0a
BLAKE2b-256 7687f36f4b12273d3d3b37d646bd3e66311955f40d4c0182f6a041387505c960

See more details on using hashes here.

Provenance

The following attestation bundles were made for treemendous-1.1.0-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: release.yml on josephjohncox/TreeMendous

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file treemendous-1.1.0-cp313-cp313-macosx_12_0_universal2.whl.

File metadata

File hashes

Hashes for treemendous-1.1.0-cp313-cp313-macosx_12_0_universal2.whl
Algorithm Hash digest
SHA256 2ca522336af80b65e8a9affdb32a119ee3feb5434517d7600350feeedd4e8ad7
MD5 98eca1b6fabf44c896018c5a3b4046f6
BLAKE2b-256 a7339e2e889da2ed5d2d2cab66f3b6e472412b82eb66909d5c7d2149017d81a2

See more details on using hashes here.

Provenance

The following attestation bundles were made for treemendous-1.1.0-cp313-cp313-macosx_12_0_universal2.whl:

Publisher: release.yml on josephjohncox/TreeMendous

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file treemendous-1.1.0-cp312-cp312-win_amd64.whl.

File metadata

  • Download URL: treemendous-1.1.0-cp312-cp312-win_amd64.whl
  • Upload date:
  • Size: 807.9 kB
  • Tags: CPython 3.12, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for treemendous-1.1.0-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 0565e3fe0fc191640850b7c57e5d2d07633a04be544648f5884227f35ee28756
MD5 0f2400df74cad51d49dc5edb37887878
BLAKE2b-256 716c488d16105cd0a0671376c728d19d2d7a177d99b865b1a4fef91d4277d9dd

See more details on using hashes here.

Provenance

The following attestation bundles were made for treemendous-1.1.0-cp312-cp312-win_amd64.whl:

Publisher: release.yml on josephjohncox/TreeMendous

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file treemendous-1.1.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for treemendous-1.1.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 978ca221968687328106f1ba7650b8ca3beecafd100f1636cb3ce2de6a0cdfa2
MD5 c4722400a107556aeea2883bb768f161
BLAKE2b-256 a6652301a21bf22511dae30079048524a688921374948df946ee056e7d5e5095

See more details on using hashes here.

Provenance

The following attestation bundles were made for treemendous-1.1.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: release.yml on josephjohncox/TreeMendous

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file treemendous-1.1.0-cp312-cp312-macosx_12_0_universal2.whl.

File metadata

File hashes

Hashes for treemendous-1.1.0-cp312-cp312-macosx_12_0_universal2.whl
Algorithm Hash digest
SHA256 864fef5d07de10a4a4e104335618c5c16a55c478e0b75351eb6d52ec7c1ac60a
MD5 d6f1d867059912e91ee0bf79e2d859d6
BLAKE2b-256 6826d02fec0509d2b977acb81d369400c94c7aab3fd33564687d8826acd645d9

See more details on using hashes here.

Provenance

The following attestation bundles were made for treemendous-1.1.0-cp312-cp312-macosx_12_0_universal2.whl:

Publisher: release.yml on josephjohncox/TreeMendous

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file treemendous-1.1.0-cp311-cp311-win_amd64.whl.

File metadata

  • Download URL: treemendous-1.1.0-cp311-cp311-win_amd64.whl
  • Upload date:
  • Size: 801.0 kB
  • Tags: CPython 3.11, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for treemendous-1.1.0-cp311-cp311-win_amd64.whl
Algorithm Hash digest
SHA256 e19e87c08ae0a4077eb54efc74ef5963cba2c7959d1fcd87a315f95236bf7045
MD5 b875b935f33d52e4fefc6c3e92d68f21
BLAKE2b-256 e8a5917dd391afa91ede1df7ea0c4fcfcbf41164b5abdcf436b4053c6a56ed60

See more details on using hashes here.

Provenance

The following attestation bundles were made for treemendous-1.1.0-cp311-cp311-win_amd64.whl:

Publisher: release.yml on josephjohncox/TreeMendous

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file treemendous-1.1.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for treemendous-1.1.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 1d41d4d1ec8a4eadf8efca8bbb3a73e229bd646beb3b1ea14e76251d4a6d9486
MD5 6eed30ff1347cef69b504f040a6d85f6
BLAKE2b-256 f5a352591dab046926eb604b5d30aef8e9a36b0553b222c224bb26d8d807d1ca

See more details on using hashes here.

Provenance

The following attestation bundles were made for treemendous-1.1.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: release.yml on josephjohncox/TreeMendous

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file treemendous-1.1.0-cp311-cp311-macosx_12_0_universal2.whl.

File metadata

File hashes

Hashes for treemendous-1.1.0-cp311-cp311-macosx_12_0_universal2.whl
Algorithm Hash digest
SHA256 e9daca49f507f20a47c75f8bf70d6d2669491cb3ae5836f100e3ba5be9eb5407
MD5 80080b832b3fa5af675e80cc436261f7
BLAKE2b-256 8d31bd2b4229c2ec2d616b3cbe7716b5e2afe820fbef5e760616541541240a88

See more details on using hashes here.

Provenance

The following attestation bundles were made for treemendous-1.1.0-cp311-cp311-macosx_12_0_universal2.whl:

Publisher: release.yml on josephjohncox/TreeMendous

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

1.2.0

10 files

1.1.1

10 files

This release

1.1.0 This release

10 files

0.1.0

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page