logisticspy 0.1.0__tar.gz

logisticspy-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 krishnanz550i-cmyk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

logisticspy-0.1.0/PKG-INFO

@@ -0,0 +1,220 @@
+Metadata-Version: 2.4
+Name: logisticspy
+Version: 0.1.0
+Summary: A Python toolkit for logistics and supply chain calculations
+Author: krishnanz550i-cmyk
+License: MIT
+Project-URL: Homepage, https://github.com/krishnanz550i-cmyk/logisticspy
+Project-URL: Issues, https://github.com/krishnanz550i-cmyk/logisticspy/issues
+Keywords: logistics,supply chain,freight,chargeable weight
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Dynamic: license-file
+
+# logisticspy
+
+A Python toolkit for logistics and supply chain calculations.
+
+`logisticspy` is a growing collection of clean, well-tested tools for
+common logistics and supply chain problems. The first module,
+**`logisticspy.weight`**, calculates volumetric (dimensional) weight and
+chargeable weight for air, courier, sea, road, and rail freight shipments.
+More tools (volume, freight, inventory, and others) will be added over
+time.
+
+## Install
+
+```bash
+pip install logisticspy
+```
+
+## Quick start
+
+You can use the chargeable weight tools either via the top-level package
+or via the `weight` module:
+
+```python
+# Option 1: top-level import
+import logisticspy
+
+result = logisticspy.calculate(
+    length=60, width=40, height=40, unit="cm",
+    actual_weight=18, weight_unit="kg",
+    mode="air",
+)
+
+# Option 2: import the weight module
+from logisticspy.weight import chargeable_weight
+
+result = chargeable_weight.calculate(
+    length=60, width=40, height=40, unit="cm",
+    actual_weight=18, weight_unit="kg",
+    mode="air",
+)
+
+print(result.volumetric_weight_kg)   # 19.2
+print(result.chargeable_weight_kg)   # 19.2
+print(result.basis)                  # "volumetric"
+```
+
+## The `weight` module: chargeable weight
+
+Carriers bill shipments based on whichever is greater: the **actual
+weight** or the **volumetric weight** (calculated from package
+dimensions). This module implements that calculation cleanly, with
+support for multiple units, transport modes, named divisor presets, and
+multi-package consignments.
+
+### Supported modes and default divisors
+
+| Mode      | Default divisor (cm³/kg) |
+|-----------|---------------------------|
+| `air`     | 6000 |
+| `courier` | 5000 |
+| `road`    | 3000 |
+| `rail`    | 3000 |
+| `sea`     | N/A (uses CBM × 1000, see below) |
+
+These are sensible starting defaults based on common conventions seen
+across the freight and parcel industry. They are **not** tied to any
+specific carrier - always confirm the applicable divisor with your own
+carrier or contract for billing-critical calculations.
+
+### Divisor presets
+
+Two divisor values - 5000 and 6000 - are both widely used across the
+industry, often for different services, regions, or contracts (sometimes
+even by the same carrier depending on the product). Rather than guessing
+which one applies to your situation, you can refer to them by generic
+preset labels and swap between them easily:
+
+| Preset | Divisor |
+|--------|---------|
+| `"a"`  | 5000 |
+| `"b"`  | 6000 |
+
+```python
+import logisticspy
+
+# Same package, two different divisor conventions
+pkg = dict(length=60, width=40, height=40, actual_weight=10, mode="air")
+
+result_a = logisticspy.calculate(**pkg, divisor_preset="a")  # divisor 5000
+result_b = logisticspy.calculate(**pkg, divisor_preset="b")  # divisor 6000
+
+print(result_a.volumetric_weight_kg)  # 19.2
+print(result_b.volumetric_weight_kg)  # 16.0
+```
+
+This makes it easy to compare "what would this shipment cost under each
+convention" without hardcoding either value, and to plug in your own
+carrier's documented divisor (whether that happens to be 5000, 6000, or
+something else entirely) via `divisor_preset` or a raw `divisor=` value.
+
+You can also pass an explicit divisor directly, which overrides any preset:
+
+```python
+result = logisticspy.calculate(**pkg, divisor=4500)
+```
+
+### Units
+
+#### Input units
+
+Dimensions accept `cm`, `m`, `mm`, `in`, `ft` (default `cm`).
+Weights accept `kg`, `g`, `lb`, `oz` (default `kg`).
+
+```python
+result = logisticspy.calculate(
+    length=20, width=15, height=10, unit="in",
+    actual_weight=5, weight_unit="lb",
+    mode="courier",
+)
+```
+
+#### Output units (always normalized)
+
+Regardless of the input units you choose, **all results are returned in
+a single fixed unit system**:
+
+| Field | Unit |
+|-------|------|
+| `actual_weight_kg`, `volumetric_weight_kg`, `chargeable_weight_kg` | kilograms (kg) |
+| `volume_m3` | cubic meters (m³) |
+
+The input units (`unit`, `weight_unit`) are only used to *interpret* the
+numbers you pass in - they are converted to centimeters and kilograms
+internally before any calculation happens. The output is never expressed
+back in the input units.
+
+If you need the result in a different unit (e.g. pounds), convert the
+returned kg value yourself - the library does not provide unit conversion
+on outputs.
+
+### Sea freight (CBM)
+
+Sea freight chargeable weight is derived from volume in cubic meters
+(CBM), using the common 1 CBM ≈ 1000 kg convention:
+
+```python
+result = logisticspy.calculate(
+    length=1, width=1, height=1, unit="m",
+    actual_weight=500, mode="sea",
+)
+print(result.volumetric_weight_kg)  # 1000.0
+```
+
+Divisor presets are ignored for sea mode, since it uses a CBM-based
+calculation rather than a divisor.
+
+### Multi-package consignments
+
+```python
+import logisticspy
+
+packages = [
+    {"length": 50, "width": 40, "height": 40, "actual_weight": 10},
+    {"length": 60, "width": 40, "height": 40, "actual_weight": 25, "quantity": 2},
+]
+
+result = logisticspy.calculate_consignment(packages, mode="air")
+
+print(result.total_actual_weight_kg)
+print(result.total_volumetric_weight_kg)
+print(result.total_chargeable_weight_kg)
+```
+
+By default, totals are compared (`sum(actual)` vs `sum(volumetric)`).
+Some couriers calculate chargeable weight per package and sum those - use
+`per_piece=True` for that behavior:
+
+```python
+result = logisticspy.calculate_consignment(packages, mode="air", per_piece=True)
+```
+
+## Roadmap
+
+`logisticspy` is designed to grow into a broader logistics toolkit.
+`chargeable_weight` is the first module; additional tools (e.g. volume,
+freight, and inventory calculations) will be added over time.
+
+## Disclaimer
+
+This library implements widely-used industry conventions for
+illustrative and estimation purposes. Divisors and CBM ratios vary by
+carrier, service level, region, and contract terms. Always confirm exact
+billing methodology with your carrier or freight forwarder for
+invoicing-critical calculations.
+
+## License
+
+MIT

logisticspy-0.1.0/README.md

@@ -0,0 +1,198 @@
+# logisticspy
+
+A Python toolkit for logistics and supply chain calculations.
+
+`logisticspy` is a growing collection of clean, well-tested tools for
+common logistics and supply chain problems. The first module,
+**`logisticspy.weight`**, calculates volumetric (dimensional) weight and
+chargeable weight for air, courier, sea, road, and rail freight shipments.
+More tools (volume, freight, inventory, and others) will be added over
+time.
+
+## Install
+
+```bash
+pip install logisticspy
+```
+
+## Quick start
+
+You can use the chargeable weight tools either via the top-level package
+or via the `weight` module:
+
+```python
+# Option 1: top-level import
+import logisticspy
+
+result = logisticspy.calculate(
+    length=60, width=40, height=40, unit="cm",
+    actual_weight=18, weight_unit="kg",
+    mode="air",
+)
+
+# Option 2: import the weight module
+from logisticspy.weight import chargeable_weight
+
+result = chargeable_weight.calculate(
+    length=60, width=40, height=40, unit="cm",
+    actual_weight=18, weight_unit="kg",
+    mode="air",
+)
+
+print(result.volumetric_weight_kg)   # 19.2
+print(result.chargeable_weight_kg)   # 19.2
+print(result.basis)                  # "volumetric"
+```
+
+## The `weight` module: chargeable weight
+
+Carriers bill shipments based on whichever is greater: the **actual
+weight** or the **volumetric weight** (calculated from package
+dimensions). This module implements that calculation cleanly, with
+support for multiple units, transport modes, named divisor presets, and
+multi-package consignments.
+
+### Supported modes and default divisors
+
+| Mode      | Default divisor (cm³/kg) |
+|-----------|---------------------------|
+| `air`     | 6000 |
+| `courier` | 5000 |
+| `road`    | 3000 |
+| `rail`    | 3000 |
+| `sea`     | N/A (uses CBM × 1000, see below) |
+
+These are sensible starting defaults based on common conventions seen
+across the freight and parcel industry. They are **not** tied to any
+specific carrier - always confirm the applicable divisor with your own
+carrier or contract for billing-critical calculations.
+
+### Divisor presets
+
+Two divisor values - 5000 and 6000 - are both widely used across the
+industry, often for different services, regions, or contracts (sometimes
+even by the same carrier depending on the product). Rather than guessing
+which one applies to your situation, you can refer to them by generic
+preset labels and swap between them easily:
+
+| Preset | Divisor |
+|--------|---------|
+| `"a"`  | 5000 |
+| `"b"`  | 6000 |
+
+```python
+import logisticspy
+
+# Same package, two different divisor conventions
+pkg = dict(length=60, width=40, height=40, actual_weight=10, mode="air")
+
+result_a = logisticspy.calculate(**pkg, divisor_preset="a")  # divisor 5000
+result_b = logisticspy.calculate(**pkg, divisor_preset="b")  # divisor 6000
+
+print(result_a.volumetric_weight_kg)  # 19.2
+print(result_b.volumetric_weight_kg)  # 16.0
+```
+
+This makes it easy to compare "what would this shipment cost under each
+convention" without hardcoding either value, and to plug in your own
+carrier's documented divisor (whether that happens to be 5000, 6000, or
+something else entirely) via `divisor_preset` or a raw `divisor=` value.
+
+You can also pass an explicit divisor directly, which overrides any preset:
+
+```python
+result = logisticspy.calculate(**pkg, divisor=4500)
+```
+
+### Units
+
+#### Input units
+
+Dimensions accept `cm`, `m`, `mm`, `in`, `ft` (default `cm`).
+Weights accept `kg`, `g`, `lb`, `oz` (default `kg`).
+
+```python
+result = logisticspy.calculate(
+    length=20, width=15, height=10, unit="in",
+    actual_weight=5, weight_unit="lb",
+    mode="courier",
+)
+```
+
+#### Output units (always normalized)
+
+Regardless of the input units you choose, **all results are returned in
+a single fixed unit system**:
+
+| Field | Unit |
+|-------|------|
+| `actual_weight_kg`, `volumetric_weight_kg`, `chargeable_weight_kg` | kilograms (kg) |
+| `volume_m3` | cubic meters (m³) |
+
+The input units (`unit`, `weight_unit`) are only used to *interpret* the
+numbers you pass in - they are converted to centimeters and kilograms
+internally before any calculation happens. The output is never expressed
+back in the input units.
+
+If you need the result in a different unit (e.g. pounds), convert the
+returned kg value yourself - the library does not provide unit conversion
+on outputs.
+
+### Sea freight (CBM)
+
+Sea freight chargeable weight is derived from volume in cubic meters
+(CBM), using the common 1 CBM ≈ 1000 kg convention:
+
+```python
+result = logisticspy.calculate(
+    length=1, width=1, height=1, unit="m",
+    actual_weight=500, mode="sea",
+)
+print(result.volumetric_weight_kg)  # 1000.0
+```
+
+Divisor presets are ignored for sea mode, since it uses a CBM-based
+calculation rather than a divisor.
+
+### Multi-package consignments
+
+```python
+import logisticspy
+
+packages = [
+    {"length": 50, "width": 40, "height": 40, "actual_weight": 10},
+    {"length": 60, "width": 40, "height": 40, "actual_weight": 25, "quantity": 2},
+]
+
+result = logisticspy.calculate_consignment(packages, mode="air")
+
+print(result.total_actual_weight_kg)
+print(result.total_volumetric_weight_kg)
+print(result.total_chargeable_weight_kg)
+```
+
+By default, totals are compared (`sum(actual)` vs `sum(volumetric)`).
+Some couriers calculate chargeable weight per package and sum those - use
+`per_piece=True` for that behavior:
+
+```python
+result = logisticspy.calculate_consignment(packages, mode="air", per_piece=True)
+```
+
+## Roadmap
+
+`logisticspy` is designed to grow into a broader logistics toolkit.
+`chargeable_weight` is the first module; additional tools (e.g. volume,
+freight, and inventory calculations) will be added over time.
+
+## Disclaimer
+
+This library implements widely-used industry conventions for
+illustrative and estimation purposes. Divisors and CBM ratios vary by
+carrier, service level, region, and contract terms. Always confirm exact
+billing methodology with your carrier or freight forwarder for
+invoicing-critical calculations.
+
+## License
+
+MIT

logisticspy-0.1.0/logisticspy/__init__.py

@@ -0,0 +1,43 @@
+"""
+logisticspy: A Python toolkit for logistics and supply chain calculations.
+
+The first module, ``logisticspy.weight``, calculates volumetric (dimensional)
+and chargeable weight for air, courier, sea, road, and rail freight shipments.
+More tools will be added over time.
+
+Top-level convenience imports let you do either of:
+
+    import logisticspy
+    logisticspy.calculate(...)
+
+    from logisticspy.weight import chargeable_weight
+    chargeable_weight.calculate(...)
+"""
+
+from .weight import (
+    calculate,
+    calculate_consignment,
+    WeightResult,
+    ConsolidatedResult,
+    Mode,
+    DEFAULT_DIVISORS,
+    DIVISOR_PRESETS,
+    UnsupportedUnitError,
+    UnsupportedModeError,
+    UnsupportedPresetError,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "calculate",
+    "calculate_consignment",
+    "WeightResult",
+    "ConsolidatedResult",
+    "Mode",
+    "DEFAULT_DIVISORS",
+    "DIVISOR_PRESETS",
+    "UnsupportedUnitError",
+    "UnsupportedModeError",
+    "UnsupportedPresetError",
+]

logisticspy-0.1.0/logisticspy/weight/__init__.py

@@ -0,0 +1,28 @@
+"""
+logisticspy.weight: Calculate volumetric (dimensional) and chargeable weight
+for air, courier, sea, road, and rail freight shipments.
+"""
+
+from .chargeable_weight import (
+    calculate,
+    calculate_consignment,
+    WeightResult,
+    ConsolidatedResult,
+    UnsupportedUnitError,
+    UnsupportedModeError,
+    UnsupportedPresetError,
+)
+from .divisors import Mode, DEFAULT_DIVISORS, DIVISOR_PRESETS
+
+__all__ = [
+    "calculate",
+    "calculate_consignment",
+    "WeightResult",
+    "ConsolidatedResult",
+    "Mode",
+    "DEFAULT_DIVISORS",
+    "DIVISOR_PRESETS",
+    "UnsupportedUnitError",
+    "UnsupportedModeError",
+    "UnsupportedPresetError",
+]