Metadata-Version: 2.4
Name: wadaya-moving-kit
Version: 0.1.0
Summary: Volumes and CSV inventories for the contents of a storage unit, by Wadaya Self Storage in Bahrain
Author-email: Wadaya Self Storage <hello@wadayaselfstorage.com>
License-Expression: MIT
Project-URL: Homepage, https://www.wadayaselfstorage.com/
Keywords: self storage,storage units,inventory,volume calculator,cubic metres,csv,bahrain
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# Self storage space and inventory in Python

Calculate packed volume and keep an inventory of belongings going into storage. The package takes each item's outer measurements in centimetres, returns its volume in cubic metres, totals the volume by room and reads or writes the list as CSV. It uses Python 3.10 or newer, calculates with `Decimal`, has no dependencies and makes no network calls.

We built it at Wadaya Self Storage, an air-conditioned [self storage facility in Tubli, Bahrain](https://www.wadayaselfstorage.com/). A measured inventory helps people choose a unit and find their things later. Each item has an ID for its label, measurements are validated, and CSV exports protect text fields from being interpreted as spreadsheet formulas.

## Install

```bash
pip install wadaya-moving-kit
```

You get the `wadaya_moving_kit` library and a `wadaya-moving-kit` command.

## How much space an item takes

```python
from wadaya_moving_kit import packed_volume_m3

packed_volume_m3(75, 50, 30)              # Decimal('0.1125'): one suitcase
packed_volume_m3(75, 50, 30, quantity=2)  # Decimal('0.225'): two of them
```

Length, width and height are in centimetres, as ints, floats, `Decimal`s or numeric strings, so values from a form or a CSV can go straight in. Take them from the item as it will be stored: boxed, wrapped or taken apart. Anything that isn't a positive, finite number raises `ValueError`, with a message plain enough to show the person who typed it.

## Keep a storage inventory

`InventoryItem` is one row of an inventory: an ID, the room it belongs to, a description, three measurements and a quantity. Each item checks itself when it's created, and `summarize` adds a list of them up.

```python
from wadaya_moving_kit import InventoryItem, summarize

items = [
    InventoryItem("GR-1", "Guest room", "Suitcases", 75, 50, 30, quantity=2),
    InventoryItem("GR-2", "Guest room", "Rolled rug", 200, 30, 30),
    InventoryItem("MJ-1", "Majlis", "Floor cushions", 60, 60, 20, quantity=6),
]

totals = summarize(items)
totals["rows"]              # 3
totals["items"]             # 9
totals["packed_volume_m3"]  # Decimal('0.837')
totals["rooms"]             # {'Guest room': Decimal('0.405'), 'Majlis': Decimal('0.432')}
```

`quantity` lets one row stand for several identical things. Anything someone may want to find on its own later deserves a row and an ID of its own. A single item's volume is `item.volume_m3`.

## Read and write CSV

`read_inventory` turns a CSV text stream into a list of `InventoryItem`, and `write_inventory` writes a list back out with a calculated `packed_volume_m3` column.

```python
from wadaya_moving_kit import read_inventory, summarize, write_inventory

with open("inventory.csv", encoding="utf-8-sig", newline="") as source:
    items = read_inventory(source)

print(summarize(items)["packed_volume_m3"])

with open("with-volumes.csv", "w", encoding="utf-8", newline="") as target:
    write_inventory(items, target)
```

The same inventory as a file:

```csv
item_id,room,description,length_cm,width_cm,height_cm,quantity
GR-1,Guest room,Suitcases,75,50,30,2
GR-2,Guest room,Rolled rug,200,30,30,1
MJ-1,Majlis,Floor cushions,60,60,20,6
```

An `item_id` is up to 32 letters, digits, hyphens and underscores, starts with a letter or digit, and can't repeat within a file. Rooms and descriptions can be written in Arabic or English; the column names stay in English. On reading, any `packed_volume_m3` column is ignored and every volume is worked out again from the measurements, so a hand-edited file can't carry a stale total. To keep a spreadsheet from treating text as a formula, a room or description beginning with `=`, `+`, `-` or `@` is saved with a leading apostrophe.

## Command line

```bash
wadaya-moving-kit volume 75 50 30 --quantity 2           # 0.225 m³ for the two suitcases
wadaya-moving-kit summary inventory.csv                  # counts, total and a subtotal per room
wadaya-moving-kit summary inventory.csv --json           # the same, as JSON
wadaya-moving-kit export inventory.csv with-volumes.csv  # a copy with volumes added
```

With `--json`, volumes are returned as strings to preserve decimal precision. `export` will not overwrite an existing file. You can also run the commands with `python -m wadaya_moving_kit` if the script is not on your `PATH`.

## From cubic metres to a storage unit

Storage units are rented by floor area. For stackable boxes, divide packed volume by the planned stacking height to estimate that area: 3 m³ stacked 1.5 m high covers about 2 m² before gaps and access space. Furniture may need a separate floor layout because it cannot always be stacked.

Our units in Tubli range from 1.5 to 25 m². If you build a size estimate using this package, allow for safe stacking, door dimensions and space to collect items. The library calculates volume; it does not check whether a load fits a particular unit.

MIT License. Write to [hello@wadayaselfstorage.com](mailto:hello@wadayaselfstorage.com) with questions or suggestions.
