DOCS / TUTORIAL

Getting started in Python

Install packvium, build items and containers as Python objects, run Packer.pack(), and read why an item was left out rather than guessing.

Docs for Packvium 1.11.x · contract stable since 1.0

01Install#

Pure Python, zero runtime dependencies, Python 3.9 or newer.

pip install packvium

02Build items and containers#

Dimensions.mm and Dimensions.inches keep every length exact, fractional inches included. A quantity on Item.create expands to that many identical instances — no loop to write.

from packvium import Container, Dimensions, Item, Packer, PackingConfig

items = [Item.create("book", Dimensions.mm("210", "140", "30"), quantity=4)]
containers = [Container.create("box", Dimensions.mm("400", "300", "250"))]

03Run pack() and read the result#

PackingConfig.balanced() is a reasonable default profile. The result carries a status — proven, best_found or infeasible — before you look at a single placement.

result = Packer(PackingConfig.balanced()).pack(items=items, containers=containers)

print(result.status)
for container in result.containers:
    for placement in container.placements:
        print(placement.item_id, placement.position, placement.orientation)

04Handle items the engine could not place#

An incomplete answer is not silent. Every entry in result.unpacked carries a reason code, and explain_unpacked_item turns it into a sentence without requiring you to learn the reason vocabulary first.

from packvium import explain_unpacked_item

for unpacked in result.unpacked:
    print(unpacked.instance.item.id, explain_unpacked_item(unpacked))

05What is already checked before you see it#

Every placement pack() returns has been re-checked by validation logic independent of the search that found it. The fixture pages on this site show that validator's verdict next to the engine's for the same request, so a wrong placement is not something you have to take on trust.

06Check a result yourself#

From 1.7.0 the reference validator ships in the package. validate(request, result) reads the request and result as JSON documents, shares no code with the engine that packed them, and returns every issue it finds, each with a code and a detail; an empty list means the result is valid. A result without the documented shape raises MalformedResult.

from packvium import pack_from_dict, validate

# request is the same dict the JSON contract describes.
result = pack_from_dict(request)
for issue in validate(request, result):
    print(issue.code, issue.detail)

07Next steps#

Read the request and result contract for every public field, run your own dimensions in the Playground, or open examples/constraints.py for stacking, tags and top-load limits using this same reason-reading pattern.