nkscoder-courier 1.1.1__py3-none-any.whl

courier/__init__.py

@@ -0,0 +1,19 @@
+"""Django zone-based courier shipping calculator by Nitesh Kumar Singh (nkscoder)."""
+
+__version__ = "1.1.1"
+__author__ = "Nitesh Kumar Singh"
+__author_handle__ = "nkscoder"
+
+__all__ = ["__version__", "calculate_courier_cost", "courier_cost", "CourierCalculationError"]
+
+
+def __getattr__(name):
+    if name in {"calculate_courier_cost", "courier_cost", "CourierCalculationError"}:
+        from .calculator import (
+            CourierCalculationError,
+            calculate_courier_cost,
+            courier_cost,
+        )
+
+        return locals()[name]
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

courier/admin.py

@@ -0,0 +1,44 @@
+from django.contrib import admin
+
+from .models import CourierCountry, CourierRegion, WeightCost, Zone, ZoneConnection
+
+try:
+    from import_export.admin import ImportExportModelAdmin
+
+    AdminBase = ImportExportModelAdmin
+except ImportError:
+    AdminBase = admin.ModelAdmin
+
+
+@admin.register(CourierCountry)
+class CourierCountryAdmin(AdminBase):
+    list_display = ("name", "code", "is_domestic")
+    list_filter = ("is_domestic",)
+    search_fields = ("name", "code")
+
+
+@admin.register(CourierRegion)
+class CourierRegionAdmin(AdminBase):
+    list_display = ("name", "country", "code")
+    list_filter = ("country",)
+    search_fields = ("name", "code", "country__name")
+
+
+@admin.register(Zone)
+class ZoneAdmin(AdminBase):
+    list_display = ("name",)
+    search_fields = ("name",)
+
+
+@admin.register(ZoneConnection)
+class ZoneConnectionAdmin(AdminBase):
+    list_display = ("zone",)
+    filter_horizontal = ("countries", "regions")
+    search_fields = ("zone__name", "countries__name", "regions__name")
+
+
+@admin.register(WeightCost)
+class WeightCostAdmin(AdminBase):
+    list_display = ("zone", "weight", "amount")
+    list_filter = ("zone",)
+    search_fields = ("zone__name",)

courier/apps.py

@@ -0,0 +1,7 @@
+from django.apps import AppConfig
+
+
+class CourierConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "courier"
+    verbose_name = "Courier Shipping"

courier/calculator.py

@@ -0,0 +1,136 @@
+"""Generic courier pricing logic — usable from views, checkout, or Celery tasks."""
+
+from decimal import Decimal, ROUND_HALF_UP
+
+from django.db.models import Q
+
+from .conf import get_country_model, get_region_model, get_setting
+from .models import WeightCost, ZoneConnection
+
+GRAMS_PER_LB = Decimal("453.592")
+GRAMS_PER_KG = Decimal("1000")
+
+
+class CourierCalculationError(Exception):
+    """Raised when shipping cost cannot be calculated."""
+
+
+def normalize_weight(weight, weight_unit):
+    unit = (weight_unit or get_setting("DEFAULT_WEIGHT_UNIT")).lower()
+    supported = get_setting("SUPPORTED_WEIGHT_UNITS")
+    if unit not in supported:
+        raise CourierCalculationError(
+            f"Unknown weight unit {weight_unit!r}. Supported: {', '.join(supported)}"
+        )
+
+    value = Decimal(str(weight))
+    if unit == "lbs":
+        return value * GRAMS_PER_LB
+    if unit == "kgs":
+        return value * GRAMS_PER_KG
+    return value
+
+
+def is_domestic_country(country):
+    if hasattr(country, "is_domestic"):
+        return bool(country.is_domestic)
+    return country.name.lower() == get_setting("DOMESTIC_COUNTRY_NAME").lower()
+
+
+def resolve_zone_connection(country_id, region_id=None):
+    custom = get_setting("ZONE_RESOLVER")
+    if custom:
+        return custom(country_id, region_id)
+
+    country_model = get_country_model()
+    country = country_model.objects.get(pk=country_id)
+    domestic = is_domestic_country(country)
+
+    if domestic and region_id:
+        region_model = get_region_model()
+        region = region_model.objects.get(pk=region_id)
+        connection = ZoneConnection.objects.filter(regions=region).first()
+        if connection:
+            return connection, False
+
+    connection = ZoneConnection.objects.filter(countries=country).first()
+    if not connection:
+        raise CourierCalculationError(
+            f"No shipping zone configured for country id={country_id}."
+        )
+    return connection, not domestic
+
+
+def billable_weight_kg(total_weight_grams):
+    threshold = Decimal(str(get_setting("HEAVY_WEIGHT_THRESHOLD_KG")))
+    padding = Decimal(str(get_setting("WEIGHT_PADDING_KG")))
+    total_kg = total_weight_grams / GRAMS_PER_KG
+
+    if total_kg > threshold:
+        return total_kg + padding
+    return total_kg + padding
+
+
+def lookup_weight_cost(zone, weight_kg):
+    increment = Decimal(str(get_setting("WEIGHT_INCREMENT_KG")))
+    qst = Q(weight__lt=weight_kg + increment) & Q(weight__gte=weight_kg)
+    return WeightCost.objects.filter(zone=zone).filter(qst).first()
+
+
+def apply_pricing(weight_kg, cost, *, domestic_pricing, apply_surcharge):
+    amount = Decimal("0")
+    if not cost:
+        return amount
+
+    if domestic_pricing and get_setting("DOMESTIC_USE_WEIGHT_MULTIPLIER"):
+        increment = Decimal(str(get_setting("WEIGHT_INCREMENT_KG")))
+        multiplier = Decimal(str(weight_kg)) / increment
+        amount = cost.amount * multiplier
+    else:
+        amount = cost.amount
+        if apply_surcharge:
+            percent = Decimal(str(get_setting("INTERNATIONAL_SURCHARGE_PERCENT")))
+            amount = amount + (amount * percent / Decimal("100"))
+    return amount
+
+
+def calculate_courier_cost(
+    *,
+    weight,
+    quantity=1,
+    weight_unit=None,
+    country_id,
+    region_id=None,
+):
+    """
+    Generic shipping cost calculator.
+
+    Returns integer total (rounded) for the given destination and weight.
+    """
+    grams = normalize_weight(weight, weight_unit or get_setting("DEFAULT_WEIGHT_UNIT"))
+    quantity = int(quantity)
+    if quantity < 1:
+        raise CourierCalculationError("Quantity must be at least 1.")
+
+    connection, apply_surcharge = resolve_zone_connection(country_id, region_id)
+    domestic_pricing = not apply_surcharge
+    weight_kg = billable_weight_kg(grams * quantity)
+    cost = lookup_weight_cost(connection.zone, weight_kg)
+    total = apply_pricing(
+        weight_kg,
+        cost,
+        domestic_pricing=domestic_pricing,
+        apply_surcharge=apply_surcharge,
+    )
+    return int(total.quantize(Decimal("1"), rounding=ROUND_HALF_UP))
+
+
+def courier_cost(weight, quantity, weight_unit, country, state=None):
+    """Backward-compatible alias used by existing integrations."""
+    return calculate_courier_cost(
+        weight=weight,
+        quantity=quantity,
+        weight_unit=weight_unit,
+        country_id=country,
+        region_id=state,
+    )

courier/conf.py

@@ -0,0 +1,60 @@
+"""Configurable settings for the courier Django app — Nitesh Kumar Singh (nkscoder)."""
+
+from django.apps import apps
+from django.conf import settings
+from django.core.exceptions import ImproperlyConfigured
+
+
+DEFAULTS = {
+    "AUTHOR_NAME": "Nitesh Kumar Singh",
+    "AUTHOR_HANDLE": "nkscoder",
+    "GITHUB_URL": "https://github.com/nkscoder/courier",
+    "PYPI_URL": "https://pypi.org/project/nkscoder-courier/",
+    "SEO_SITE_NAME": "Django Courier Shipping Calculator",
+    "SEO_DESCRIPTION": (
+        "Generic open-source Django courier and shipping cost calculator with "
+        "zone-based weight pricing, domestic region zones, and international "
+        "surcharge support. Built by Nitesh Kumar Singh (nkscoder)."
+    ),
+    "SEO_KEYWORDS": (
+        "django courier, shipping cost calculator, zone-based shipping, "
+        "weight-based courier pricing, generic django shipping, django shipping app, "
+        "nkscoder, nitesh kumar singh, python courier, ecommerce shipping"
+    ),
+    # Location models (override to plug into your own Country/State tables)
+    "COUNTRY_MODEL": "courier.CourierCountry",
+    "REGION_MODEL": "courier.CourierRegion",
+    # Pricing defaults
+    "DOMESTIC_COUNTRY_NAME": "India",
+    "INTERNATIONAL_SURCHARGE_PERCENT": 22,
+    "HEAVY_WEIGHT_THRESHOLD_KG": 20,
+    "WEIGHT_PADDING_KG": "0.500",
+    "WEIGHT_INCREMENT_KG": "0.500",
+    "DEFAULT_WEIGHT_UNIT": "gram",
+    "SUPPORTED_WEIGHT_UNITS": ("gram", "kgs", "lbs"),
+    "DOMESTIC_USE_WEIGHT_MULTIPLIER": True,
+    # Optional hook: callable(country_id, region_id) -> (zone_connection, apply_surcharge)
+    "ZONE_RESOLVER": None,
+}
+
+
+def get_setting(name):
+    key = f"COURIER_{name}"
+    if hasattr(settings, key):
+        return getattr(settings, key)
+    return DEFAULTS[name]
+
+
+def get_model(label):
+    try:
+        return apps.get_model(label)
+    except (LookupError, ValueError) as exc:
+        raise ImproperlyConfigured(f"COURIER model {label!r} is not installed.") from exc
+
+
+def get_country_model():
+    return get_model(get_setting("COUNTRY_MODEL"))
+
+
+def get_region_model():
+    return get_model(get_setting("REGION_MODEL"))

courier/migrations/0001_initial.py

@@ -0,0 +1,174 @@
+# Generated by Django 3.0.8 on 2023-01-13 12:57
+
+import django.db.models.deletion
+import django.utils.timezone
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    initial = True
+
+    dependencies = []
+
+    operations = [
+        migrations.CreateModel(
+            name="CourierCountry",
+            fields=[
+                (
+                    "id",
+                    models.AutoField(
+                        auto_created=True,
+                        primary_key=True,
+                        serialize=False,
+                        verbose_name="ID",
+                    ),
+                ),
+                ("created_at", models.DateTimeField(default=django.utils.timezone.now)),
+                ("updated_at", models.DateTimeField(auto_now=True)),
+                ("name", models.CharField(max_length=150, unique=True)),
+                ("code", models.CharField(blank=True, max_length=10)),
+                (
+                    "is_domestic",
+                    models.BooleanField(
+                        default=False,
+                        help_text="Domestic destinations can use region-level zones and weight multipliers.",
+                    ),
+                ),
+            ],
+            options={
+                "verbose_name": "Courier Country",
+                "verbose_name_plural": "Courier Countries",
+                "ordering": ("name",),
+            },
+        ),
+        migrations.CreateModel(
+            name="Zone",
+            fields=[
+                (
+                    "id",
+                    models.AutoField(
+                        auto_created=True,
+                        primary_key=True,
+                        serialize=False,
+                        verbose_name="ID",
+                    ),
+                ),
+                ("created_at", models.DateTimeField(default=django.utils.timezone.now)),
+                ("updated_at", models.DateTimeField(auto_now=True)),
+                ("name", models.CharField(max_length=150)),
+            ],
+            options={
+                "verbose_name": "Zone",
+                "verbose_name_plural": "Zones",
+                "ordering": ("name",),
+            },
+        ),
+        migrations.CreateModel(
+            name="CourierRegion",
+            fields=[
+                (
+                    "id",
+                    models.AutoField(
+                        auto_created=True,
+                        primary_key=True,
+                        serialize=False,
+                        verbose_name="ID",
+                    ),
+                ),
+                ("created_at", models.DateTimeField(default=django.utils.timezone.now)),
+                ("updated_at", models.DateTimeField(auto_now=True)),
+                ("name", models.CharField(max_length=150)),
+                ("code", models.CharField(blank=True, max_length=10)),
+                (
+                    "country",
+                    models.ForeignKey(
+                        on_delete=django.db.models.deletion.CASCADE,
+                        related_name="regions",
+                        to="courier.couriercountry",
+                    ),
+                ),
+            ],
+            options={
+                "verbose_name": "Courier Region",
+                "verbose_name_plural": "Courier Regions",
+                "ordering": ("country__name", "name"),
+                "unique_together": {("country", "name")},
+            },
+        ),
+        migrations.CreateModel(
+            name="ZoneConnection",
+            fields=[
+                (
+                    "id",
+                    models.AutoField(
+                        auto_created=True,
+                        primary_key=True,
+                        serialize=False,
+                        verbose_name="ID",
+                    ),
+                ),
+                ("created_at", models.DateTimeField(default=django.utils.timezone.now)),
+                ("updated_at", models.DateTimeField(auto_now=True)),
+                (
+                    "countries",
+                    models.ManyToManyField(
+                        blank=True,
+                        related_name="zone_connections",
+                        to="courier.couriercountry",
+                    ),
+                ),
+                (
+                    "regions",
+                    models.ManyToManyField(
+                        blank=True,
+                        related_name="zone_connections",
+                        to="courier.courierregion",
+                    ),
+                ),
+                (
+                    "zone",
+                    models.ForeignKey(
+                        on_delete=django.db.models.deletion.CASCADE,
+                        related_name="connections",
+                        to="courier.zone",
+                    ),
+                ),
+            ],
+            options={
+                "verbose_name": "Zone Connection",
+                "verbose_name_plural": "Zone Connections",
+            },
+        ),
+        migrations.CreateModel(
+            name="WeightCost",
+            fields=[
+                (
+                    "id",
+                    models.AutoField(
+                        auto_created=True,
+                        primary_key=True,
+                        serialize=False,
+                        verbose_name="ID",
+                    ),
+                ),
+                ("created_at", models.DateTimeField(default=django.utils.timezone.now)),
+                ("updated_at", models.DateTimeField(auto_now=True)),
+                ("weight", models.DecimalField(decimal_places=3, max_digits=20)),
+                ("amount", models.DecimalField(decimal_places=6, max_digits=20)),
+                (
+                    "zone",
+                    models.ForeignKey(
+                        on_delete=django.db.models.deletion.CASCADE,
+                        related_name="weight_costs",
+                        to="courier.zone",
+                    ),
+                ),
+            ],
+            options={
+                "verbose_name": "Weight Cost",
+                "verbose_name_plural": "Weight Costs",
+                "ordering": ("zone__name", "weight"),
+            },
+        ),
+    ]

courier/models.py

@@ -0,0 +1,96 @@
+from django.db import models
+from django.utils import timezone
+
+class Base(models.Model):
+    created_at = models.DateTimeField(default=timezone.now)
+    updated_at = models.DateTimeField(auto_now=True)
+
+    class Meta:
+        abstract = True
+
+
+class CourierCountry(Base):
+    """Generic country/destination used for zone mapping."""
+
+    name = models.CharField(max_length=150, unique=True)
+    code = models.CharField(max_length=10, blank=True)
+    is_domestic = models.BooleanField(
+        default=False,
+        help_text="Domestic destinations can use region-level zones and weight multipliers.",
+    )
+
+    class Meta:
+        verbose_name = "Courier Country"
+        verbose_name_plural = "Courier Countries"
+        ordering = ("name",)
+
+    def __str__(self):
+        return self.name
+
+
+class CourierRegion(Base):
+    """Generic state/province/region under a country."""
+
+    name = models.CharField(max_length=150)
+    code = models.CharField(max_length=10, blank=True)
+    country = models.ForeignKey(
+        CourierCountry,
+        on_delete=models.CASCADE,
+        related_name="regions",
+    )
+
+    class Meta:
+        verbose_name = "Courier Region"
+        verbose_name_plural = "Courier Regions"
+        ordering = ("country__name", "name")
+        unique_together = ("country", "name")
+
+    def __str__(self):
+        return f"{self.name}, {self.country.name}"
+
+
+class Zone(Base):
+    name = models.CharField(max_length=150)
+
+    class Meta:
+        verbose_name = "Zone"
+        verbose_name_plural = "Zones"
+        ordering = ("name",)
+
+    def __str__(self):
+        return self.name
+
+
+class ZoneConnection(Base):
+    zone = models.ForeignKey(Zone, on_delete=models.CASCADE, related_name="connections")
+    countries = models.ManyToManyField(
+        "courier.CourierCountry",
+        blank=True,
+        related_name="zone_connections",
+    )
+    regions = models.ManyToManyField(
+        "courier.CourierRegion",
+        blank=True,
+        related_name="zone_connections",
+    )
+
+    class Meta:
+        verbose_name = "Zone Connection"
+        verbose_name_plural = "Zone Connections"
+
+    def __str__(self):
+        return str(self.zone)
+
+
+class WeightCost(Base):
+    zone = models.ForeignKey(Zone, on_delete=models.CASCADE, related_name="weight_costs")
+    weight = models.DecimalField(max_digits=20, decimal_places=3)
+    amount = models.DecimalField(max_digits=20, decimal_places=6)
+
+    class Meta:
+        verbose_name = "Weight Cost"
+        verbose_name_plural = "Weight Costs"
+        ordering = ("zone__name", "weight")
+
+    def __str__(self):
+        return f"{self.zone} @ {self.weight} = {self.amount}"

courier/test_settings.py

@@ -0,0 +1,12 @@
+SECRET_KEY = "test-secret-key"
+INSTALLED_APPS = [
+    "django.contrib.contenttypes",
+    "courier",
+]
+DATABASES = {
+    "default": {
+        "ENGINE": "django.db.backends.sqlite3",
+        "NAME": ":memory:",
+    }
+}
+USE_TZ = True

courier/tests.py

@@ -0,0 +1,46 @@
+from decimal import Decimal
+from unittest.mock import MagicMock, patch
+
+from django.test import SimpleTestCase, override_settings
+
+from courier.calculator import apply_pricing, normalize_weight
+
+
+class NormalizeWeightTests(SimpleTestCase):
+    def test_grams(self):
+        self.assertEqual(normalize_weight(500, "gram"), Decimal("500"))
+
+    def test_kgs(self):
+        self.assertEqual(normalize_weight(1.5, "kgs"), Decimal("1500"))
+
+    def test_lbs(self):
+        self.assertEqual(normalize_weight(1, "lbs"), Decimal("453.592"))
+
+
+@override_settings(
+    COURIER_DOMESTIC_USE_WEIGHT_MULTIPLIER=True,
+    COURIER_WEIGHT_INCREMENT_KG="0.500",
+    COURIER_INTERNATIONAL_SURCHARGE_PERCENT=22,
+)
+class ApplyPricingTests(SimpleTestCase):
+    def test_domestic_multiplier(self):
+        cost = MagicMock()
+        cost.amount = Decimal("10")
+        amount = apply_pricing(
+            Decimal("2.0"),
+            cost,
+            domestic_pricing=True,
+            apply_surcharge=False,
+        )
+        self.assertEqual(amount, Decimal("40"))
+
+    def test_international_surcharge(self):
+        cost = MagicMock()
+        cost.amount = Decimal("100")
+        amount = apply_pricing(
+            Decimal("1.0"),
+            cost,
+            domestic_pricing=False,
+            apply_surcharge=True,
+        )
+        self.assertEqual(amount, Decimal("122"))

courier/urls.py

@@ -0,0 +1,7 @@
+from django.urls import path
+
+from .views import courier
+
+urlpatterns = [
+    path("", courier, name="courier_view"),
+]

courier/views.py

@@ -0,0 +1,28 @@
+import json
+
+from django.http import HttpResponse, JsonResponse
+
+from .calculator import CourierCalculationError, calculate_courier_cost
+from .conf import get_setting
+
+
+def courier(request):
+    """JSON endpoint: calculate shipping cost from query params."""
+    try:
+        total = calculate_courier_cost(
+            weight=request.GET.get("weight", 0),
+            quantity=request.GET.get("quantity", 1),
+            weight_unit=request.GET.get("weight_unit") or get_setting("DEFAULT_WEIGHT_UNIT"),
+            country_id=request.GET.get("country"),
+            region_id=request.GET.get("state") or request.GET.get("region"),
+        )
+    except CourierCalculationError as exc:
+        return JsonResponse({"error": str(exc)}, status=400)
+    except Exception as exc:
+        return JsonResponse({"error": str(exc)}, status=400)
+
+    return HttpResponse(
+        json.dumps({"total": total}),
+        content_type="application/json",
+        status=200,
+    )

nkscoder_courier-1.1.1.dist-info/METADATA

@@ -0,0 +1,272 @@
+Metadata-Version: 2.4
+Name: nkscoder-courier
+Version: 1.1.1
+Summary: Django zone-based courier shipping cost calculator — by Nitesh Kumar Singh (nkscoder)
+Author-email: Nitesh Kumar Singh <nkscoder@gmail.com>
+Maintainer-email: Nitesh Kumar Singh <nkscoder@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/nkscoder/courier
+Project-URL: Documentation, https://github.com/nkscoder/courier#readme
+Project-URL: Repository, https://github.com/nkscoder/courier
+Project-URL: Bug Tracker, https://github.com/nkscoder/courier/issues
+Project-URL: Author GitHub, https://github.com/nkscoder
+Project-URL: PyPI, https://pypi.org/project/nkscoder-courier/
+Keywords: django,courier,shipping,shipping-calculator,zone-based-shipping,weight-based-pricing,india-courier,ecommerce,logistics,nkscoder,nitesh-kumar-singh,python,django-courier,shipping-cost,delivery-pricing
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Web Environment
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 3.2
+Classifier: Framework :: Django :: 4.0
+Classifier: Framework :: Django :: 4.1
+Classifier: Framework :: Django :: 4.2
+Classifier: Framework :: Django :: 5.0
+Classifier: Framework :: Django :: 5.1
+Classifier: Framework :: Django :: 5.2
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: Django>=3.2
+Provides-Extra: admin
+Requires-Dist: django-import-export>=3.0; extra == "admin"
+Dynamic: license-file
+
+# Courier — Generic Django Zone-Based Shipping Cost Calculator
+
+[![PyPI version](https://badge.fury.io/py/nkscoder-courier.svg)](https://pypi.org/project/nkscoder-courier/)
+[![Python](https://img.shields.io/pypi/pyversions/nkscoder-courier.svg)](https://pypi.org/project/nkscoder-courier/)
+[![Python 3.12](https://img.shields.io/badge/python-3.12-blue.svg)](https://www.python.org/downloads/)
+[![Django](https://img.shields.io/badge/Django-3.2%2B-green.svg)](https://www.djangoproject.com/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+**Author:** [Nitesh Kumar Singh](https://github.com/nkscoder) · **GitHub:** [@nkscoder](https://github.com/nkscoder)
+
+A **generic, reusable Django courier app** for calculating zone-based shipping costs by weight, quantity, and destination. Works out of the box with built-in country/region models, or plugs into your existing location tables. Built by **Nitesh Kumar Singh (nkscoder)**.
+
+> **Keywords:** django courier · generic shipping calculator · zone-based shipping · weight pricing · reusable django app · nkscoder · nitesh kumar singh · python shipping
+
+---
+
+## Features
+
+- **Generic by design** — built-in `CourierCountry` / `CourierRegion` models, no `core` app required
+- **Configurable pricing** — domestic multiplier, international surcharge %, weight units, thresholds
+- **Zone-based pricing** — map countries and regions to shipping zones
+- **Weight slab lookup** — automatic cost lookup by weight brackets
+- **Multi-unit support** — grams, kilograms, and pounds (`gram`, `kgs`, `lbs`)
+- **JSON API endpoint** — real-time shipping quotes via HTTP GET
+- **Python API** — call `calculate_courier_cost()` from checkout, cart, or background jobs
+- **Custom zone resolver** — plug in your own location models with one settings hook
+- **Django Admin** — manage countries, regions, zones, and weight costs
+
+---
+
+## Requirements
+
+- Python 3.8–3.12 (including **3.12**)
+- Django 3.2+
+
+---
+
+## Installation
+
+```bash
+pip install nkscoder-courier
+```
+
+With Django Admin CSV import/export:
+
+```bash
+pip install "nkscoder-courier[admin]"
+```
+
+From GitHub:
+
+```bash
+pip install git+https://github.com/nkscoder/courier.git
+```
+
+---
+
+## Quick start
+
+```python
+# settings.py
+INSTALLED_APPS = [
+    ...
+    "courier",
+]
+
+COURIER_DOMESTIC_COUNTRY_NAME = "India"
+COURIER_INTERNATIONAL_SURCHARGE_PERCENT = 22
+```
+
+```bash
+python manage.py migrate courier
+```
+
+```python
+# urls.py
+urlpatterns = [
+    path("courier/", include("courier.urls")),
+]
+```
+
+---
+
+## Usage
+
+### Python API (recommended)
+
+```python
+from courier.calculator import calculate_courier_cost
+
+total = calculate_courier_cost(
+    weight=1.5,
+    quantity=2,
+    weight_unit="kgs",
+    country_id=country.pk,
+    region_id=region.pk,  # optional for domestic regions
+)
+```
+
+Backward-compatible alias:
+
+```python
+from courier import courier_cost
+
+total = courier_cost(weight=500, quantity=1, weight_unit="gram", country=1, state=3)
+```
+
+### HTTP API
+
+```
+GET /courier/?weight=500&quantity=2&weight_unit=gram&country=1&region=3
+```
+
+Response:
+
+```json
+{"total": 150}
+```
+
+| Parameter | Description |
+|-----------|-------------|
+| `weight` | Package weight |
+| `quantity` | Number of packages |
+| `weight_unit` | `gram`, `kgs`, or `lbs` |
+| `country` | Country PK |
+| `region` or `state` | Region PK (for domestic destinations) |
+
+---
+
+## Configuration
+
+All settings use the `COURIER_` prefix:
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `COURIER_COUNTRY_MODEL` | `courier.CourierCountry` | Country model label |
+| `COURIER_REGION_MODEL` | `courier.CourierRegion` | Region/state model label |
+| `COURIER_DOMESTIC_COUNTRY_NAME` | `India` | Fallback domestic country name |
+| `COURIER_INTERNATIONAL_SURCHARGE_PERCENT` | `22` | Surcharge for non-domestic destinations |
+| `COURIER_HEAVY_WEIGHT_THRESHOLD_KG` | `20` | Heavy shipment threshold |
+| `COURIER_WEIGHT_PADDING_KG` | `0.500` | Padding added to billable weight |
+| `COURIER_WEIGHT_INCREMENT_KG` | `0.500` | Domestic weight multiplier increment |
+| `COURIER_DEFAULT_WEIGHT_UNIT` | `gram` | Default unit for API requests |
+| `COURIER_DOMESTIC_USE_WEIGHT_MULTIPLIER` | `True` | Per-increment pricing for domestic |
+| `COURIER_ZONE_RESOLVER` | `None` | Custom `(country_id, region_id) -> (connection, surcharge)` |
+
+### Plug into your own location models
+
+```python
+# settings.py
+COURIER_COUNTRY_MODEL = "myapp.Country"
+COURIER_REGION_MODEL = "myapp.State"
+
+def resolve_courier_zone(country_id, region_id):
+    from courier.models import ZoneConnection
+    # your lookup logic
+    return connection, apply_surcharge
+
+COURIER_ZONE_RESOLVER = resolve_courier_zone
+```
+
+Mark domestic countries with `is_domestic=True` on your model, or rely on `COURIER_DOMESTIC_COUNTRY_NAME`.
+
+---
+
+## Admin setup
+
+1. **Courier Country** — add destinations; mark domestic with `is_domestic`
+2. **Courier Region** — add states/provinces under domestic countries
+3. **Zone** — create shipping zones (Zone A, Zone B, …)
+4. **Zone Connection** — link zones to countries and/or regions
+5. **Weight Cost** — set price per weight slab for each zone
+
+---
+
+## How pricing works
+
+1. Resolve the destination **zone** from country/region via `ZoneConnection`
+2. Normalize weight to grams and compute total billable weight
+3. Look up the matching **WeightCost** slab for that zone
+4. **Domestic**: multiply slab rate by weight increments (configurable)
+5. **International**: apply configurable **surcharge %** on the base rate
+
+---
+
+## Development
+
+```bash
+git clone git@github.com:nkscoder/courier.git
+cd courier
+pip install -e ".[admin]"
+python manage.py migrate
+python manage.py test courier
+```
+
+---
+
+## Changelog
+
+### 1.1.1
+- Renamed PyPI package to `nkscoder-courier` (name `courier` was taken on PyPI)
+- Fixed GitHub Actions publish workflow with `PYPI_API_TOKEN`
+
+### 1.1.0
+- Generic built-in `CourierCountry` / `CourierRegion` models (no `core` dependency)
+- New `calculate_courier_cost()` service API
+- Configurable settings via `COURIER_*` prefix
+- Optional custom `COURIER_ZONE_RESOLVER` hook
+- Improved admin with search and filters
+
+### 1.0.0
+- Initial PyPI release by **Nitesh Kumar Singh (nkscoder)**
+
+---
+
+## Author & Links
+
+| | |
+|---|---|
+| **Author** | Nitesh Kumar Singh |
+| **GitHub** | [github.com/nkscoder](https://github.com/nkscoder) |
+| **Repository** | [github.com/nkscoder/courier](https://github.com/nkscoder/courier) |
+| **PyPI** | [pypi.org/project/nkscoder-courier](https://pypi.org/project/nkscoder-courier) |
+
+---
+
+## License
+
+MIT License — Copyright (c) 2020-2026 [Nitesh Kumar Singh (nkscoder)](https://github.com/nkscoder)

nkscoder_courier-1.1.1.dist-info/RECORD

@@ -0,0 +1,17 @@
+courier/__init__.py,sha256=c4hYpuflDF0dhErloZVwCTmSWHSFQ_DojFHc0Tb-B0M,630
+courier/admin.py,sha256=E0GKoEL5cWOywvt9104tHmdkklnwjcJ44bwozToOhOA,1181
+courier/apps.py,sha256=QfaVOAt60KAzjtwlnwjBORl92oF5LI4rQ2BfyNUrViw,184
+courier/calculator.py,sha256=P07i0NfRf5D49jAfrwFJyaWiUPfOCidkxCtWDVCzgmU,4388
+courier/conf.py,sha256=VE7J_82YLNb8NlLDs0Lu3bwLbVbJbUakdFijABe7mww,2140
+courier/models.py,sha256=b32nFWoUfmJb0GTbVXutH3y2L5ThHmZSel4g5JvvjmY,2645
+courier/test_settings.py,sha256=pmuEqUJb9RHcAoeXCmgGM5M6CWZkfgNq10FzOmSXuEs,231
+courier/tests.py,sha256=4nr2ihsigxGW8SV5At89lzMBHAs0VkBJeue-pX9gyUo,1361
+courier/urls.py,sha256=1wcC6_KI_dWdEfBY7RYr-vB_96ftWLWhLo20b72n01k,120
+courier/views.py,sha256=GIM2p_uLOzDi_VePFH4i9dFUt6tLEx2Vwz2AyVu-GAw,967
+courier/migrations/0001_initial.py,sha256=SsAuCoc9cwNbdgDuuRjeOcWe7k3LZm_TeoskqgvzKJ0,6251
+courier/migrations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+nkscoder_courier-1.1.1.dist-info/licenses/LICENSE,sha256=q8sNgEeghCI1fwxqOLrlqOnNZeVppp_xcwNdwlKu-Qk,1091
+nkscoder_courier-1.1.1.dist-info/METADATA,sha256=6NFF93i-MAOpcNCJ1ZwEAkPM7NolNJ--6x1VGNNb6WA,8750
+nkscoder_courier-1.1.1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+nkscoder_courier-1.1.1.dist-info/top_level.txt,sha256=JCa2wS13MdVQXTpD3ijfo9rPfbHY7VWTYNBueh2imHU,8
+nkscoder_courier-1.1.1.dist-info/RECORD,,

nkscoder_courier-1.1.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

nkscoder_courier-1.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020-2026 Nitesh Kumar Singh (nkscoder)
+
+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.

nkscoder_courier-1.1.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+courier