coupons 1.1.0__tar.gz

coupons-1.1.0/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.

coupons-1.1.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include LICENSE
+include README.md
+recursive-include coupons/migrations *.py

coupons-1.1.0/PKG-INFO

@@ -0,0 +1,246 @@
+Metadata-Version: 2.4
+Name: coupons
+Version: 1.1.0
+Summary: Django coupon and discount code system with validation rules — by Nitesh Kumar Singh (nkscoder)
+Author-email: Nitesh Kumar Singh <nkscoder@gmail.com>
+Maintainer-email: Nitesh Kumar Singh <nkscoder@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/nkscoder/coupons
+Project-URL: Documentation, https://github.com/nkscoder/coupons#readme
+Project-URL: Repository, https://github.com/nkscoder/coupons
+Project-URL: Bug Tracker, https://github.com/nkscoder/coupons/issues
+Project-URL: Author GitHub, https://github.com/nkscoder
+Keywords: django,coupons,coupon,discount,promo-code,promotional-code,ecommerce,nkscoder,nitesh-kumar-singh,python,django-coupons,coupon-validation,discount-code
+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: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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
+Dynamic: license-file
+
+# Coupons — Django Coupon & Discount Code System
+
+[![PyPI version](https://badge.fury.io/py/coupons.svg)](https://pypi.org/project/coupons/)
+[![Python](https://img.shields.io/pypi/pyversions/coupons.svg)](https://pypi.org/project/coupons/)
+[![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 reusable **Django coupons app** for managing promotional codes, discount rules, and coupon validation in Python web applications. Built by **Nitesh Kumar Singh (nkscoder)** for e-commerce, SaaS, and any Django project that needs flexible coupon functionality.
+
+> **Keywords:** django coupons · python coupon system · discount code · promo code · coupon validation · nkscoder · nitesh kumar singh
+
+---
+
+## Features
+
+- **Percentage or fixed-amount discounts** on any order total
+- **User-specific or global coupons** — restrict codes to selected users or allow all
+- **Usage limits** — max total uses, uses per user, or unlimited
+- **Expiration & active/inactive rules** with datetime-based validity
+- **Django Admin integration** with bulk actions (reset usage, delete expired)
+- **Simple validation API** — one function call to check any coupon code
+- **Configurable coupon code length** via `DSC_COUPON_CODE_LENGTH` setting
+
+---
+
+## Requirements
+
+- Python 3.8+
+- Django 3.2+
+
+---
+
+## Installation
+
+### From PyPI (recommended)
+
+```bash
+pip install coupons
+```
+
+### From GitHub
+
+```bash
+pip install git+https://github.com/nkscoder/coupons.git
+```
+
+---
+
+## Setup
+
+### Step 1 — Add to `INSTALLED_APPS`
+
+```python
+# settings.py
+INSTALLED_APPS = [
+    ...
+    "coupons",
+]
+```
+
+### Step 2 — Run migrations
+
+```bash
+python manage.py migrate coupons
+```
+
+### Step 3 — Create coupons in Django Admin
+
+Go to `/admin/` and create:
+
+1. **Discount** — set value and type (percentage or fixed)
+2. **Allowed Users Rule** — select users or enable "All users"
+3. **Max Uses Rule** — set limits or enable infinite uses
+4. **Validity Rule** — set expiration date and active status
+5. **Ruleset** — link the three rules above
+6. **Coupon** — assign discount and ruleset (code auto-generated)
+
+### Step 4 (optional) — Custom coupon code length
+
+```python
+# settings.py
+DSC_COUPON_CODE_LENGTH = 16  # default is 12
+```
+
+---
+
+## Usage
+
+### Validate a coupon
+
+```python
+from coupons.validations import validate_coupon
+
+coupon_code = "COUPONTEST01"
+user = User.objects.get(username="nitesh")
+
+status = validate_coupon(coupon_code=coupon_code, user=user)
+# {'valid': True}
+
+if status["valid"]:
+    print("Coupon is valid!")
+else:
+    print(status["message"])  # e.g. "Coupon does not exist!"
+```
+
+### Apply a coupon (record usage)
+
+```python
+from coupons.models import Coupon
+
+coupon = Coupon.objects.get(code=coupon_code)
+coupon.use_coupon(user=user)
+```
+
+### Get discount details
+
+```python
+coupon = Coupon.objects.get(code=coupon_code)
+discount = coupon.get_discount()
+# {'value': 50, 'is_percentage': True}
+```
+
+### Calculate discounted price
+
+```python
+discounted = coupon.get_discounted_value(initial_value=100.0)
+# Returns 50.0 for 50% off, or 80.0 for $20 off
+```
+
+---
+
+## Validation Rules
+
+| Rule | Description |
+|------|-------------|
+| **Allowed Users** | Coupon valid only for selected users, or all users |
+| **Max Uses** | Global usage cap, per-user limit, or infinite |
+| **Validity** | Active flag + expiration datetime |
+
+Invalid responses include a human-readable `message` key:
+
+```python
+validate_coupon("DUMMYCODE", user)
+# {'valid': False, 'message': 'Coupon does not exist!'}
+```
+
+---
+
+## REST API Example
+
+See [`examples/`](examples/) for a Django REST Framework integration sample (`ajax_views.py`, `ajax_urls.py`).
+
+---
+
+## Development
+
+```bash
+git clone git@github.com:nkscoder/coupons.git
+cd coupons
+pip install -e ".[dev]"
+python manage.py migrate
+python manage.py runserver
+```
+
+### Build & publish to PyPI
+
+```bash
+pip install build twine
+python -m build
+twine upload dist/*
+```
+
+Or tag a release on GitHub — the included GitHub Action publishes automatically.
+
+---
+
+## Changelog
+
+### 1.1.0
+- Modernized for Django 3.2–5.x and Python 3.8+
+- Added PyPI packaging (`pyproject.toml`)
+- Fixed per-coupon usage validation bug
+- Fixed template mutation in validation responses
+- SEO & documentation update by **Nitesh Kumar Singh (nkscoder)**
+
+### 1.0.0
+- Initial release
+
+---
+
+## Author & Links
+
+| | |
+|---|---|
+| **Author** | Nitesh Kumar Singh |
+| **GitHub** | [github.com/nkscoder](https://github.com/nkscoder) |
+| **Repository** | [github.com/nkscoder/coupons](https://github.com/nkscoder/coupons) |
+| **PyPI** | [pypi.org/project/coupons](https://pypi.org/project/coupons) |
+
+---
+
+## License
+
+MIT License — Copyright (c) 2020-2026 [Nitesh Kumar Singh (nkscoder)](https://github.com/nkscoder)

coupons-1.1.0/README.md

@@ -0,0 +1,206 @@
+# Coupons — Django Coupon & Discount Code System
+
+[![PyPI version](https://badge.fury.io/py/coupons.svg)](https://pypi.org/project/coupons/)
+[![Python](https://img.shields.io/pypi/pyversions/coupons.svg)](https://pypi.org/project/coupons/)
+[![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 reusable **Django coupons app** for managing promotional codes, discount rules, and coupon validation in Python web applications. Built by **Nitesh Kumar Singh (nkscoder)** for e-commerce, SaaS, and any Django project that needs flexible coupon functionality.
+
+> **Keywords:** django coupons · python coupon system · discount code · promo code · coupon validation · nkscoder · nitesh kumar singh
+
+---
+
+## Features
+
+- **Percentage or fixed-amount discounts** on any order total
+- **User-specific or global coupons** — restrict codes to selected users or allow all
+- **Usage limits** — max total uses, uses per user, or unlimited
+- **Expiration & active/inactive rules** with datetime-based validity
+- **Django Admin integration** with bulk actions (reset usage, delete expired)
+- **Simple validation API** — one function call to check any coupon code
+- **Configurable coupon code length** via `DSC_COUPON_CODE_LENGTH` setting
+
+---
+
+## Requirements
+
+- Python 3.8+
+- Django 3.2+
+
+---
+
+## Installation
+
+### From PyPI (recommended)
+
+```bash
+pip install coupons
+```
+
+### From GitHub
+
+```bash
+pip install git+https://github.com/nkscoder/coupons.git
+```
+
+---
+
+## Setup
+
+### Step 1 — Add to `INSTALLED_APPS`
+
+```python
+# settings.py
+INSTALLED_APPS = [
+    ...
+    "coupons",
+]
+```
+
+### Step 2 — Run migrations
+
+```bash
+python manage.py migrate coupons
+```
+
+### Step 3 — Create coupons in Django Admin
+
+Go to `/admin/` and create:
+
+1. **Discount** — set value and type (percentage or fixed)
+2. **Allowed Users Rule** — select users or enable "All users"
+3. **Max Uses Rule** — set limits or enable infinite uses
+4. **Validity Rule** — set expiration date and active status
+5. **Ruleset** — link the three rules above
+6. **Coupon** — assign discount and ruleset (code auto-generated)
+
+### Step 4 (optional) — Custom coupon code length
+
+```python
+# settings.py
+DSC_COUPON_CODE_LENGTH = 16  # default is 12
+```
+
+---
+
+## Usage
+
+### Validate a coupon
+
+```python
+from coupons.validations import validate_coupon
+
+coupon_code = "COUPONTEST01"
+user = User.objects.get(username="nitesh")
+
+status = validate_coupon(coupon_code=coupon_code, user=user)
+# {'valid': True}
+
+if status["valid"]:
+    print("Coupon is valid!")
+else:
+    print(status["message"])  # e.g. "Coupon does not exist!"
+```
+
+### Apply a coupon (record usage)
+
+```python
+from coupons.models import Coupon
+
+coupon = Coupon.objects.get(code=coupon_code)
+coupon.use_coupon(user=user)
+```
+
+### Get discount details
+
+```python
+coupon = Coupon.objects.get(code=coupon_code)
+discount = coupon.get_discount()
+# {'value': 50, 'is_percentage': True}
+```
+
+### Calculate discounted price
+
+```python
+discounted = coupon.get_discounted_value(initial_value=100.0)
+# Returns 50.0 for 50% off, or 80.0 for $20 off
+```
+
+---
+
+## Validation Rules
+
+| Rule | Description |
+|------|-------------|
+| **Allowed Users** | Coupon valid only for selected users, or all users |
+| **Max Uses** | Global usage cap, per-user limit, or infinite |
+| **Validity** | Active flag + expiration datetime |
+
+Invalid responses include a human-readable `message` key:
+
+```python
+validate_coupon("DUMMYCODE", user)
+# {'valid': False, 'message': 'Coupon does not exist!'}
+```
+
+---
+
+## REST API Example
+
+See [`examples/`](examples/) for a Django REST Framework integration sample (`ajax_views.py`, `ajax_urls.py`).
+
+---
+
+## Development
+
+```bash
+git clone git@github.com:nkscoder/coupons.git
+cd coupons
+pip install -e ".[dev]"
+python manage.py migrate
+python manage.py runserver
+```
+
+### Build & publish to PyPI
+
+```bash
+pip install build twine
+python -m build
+twine upload dist/*
+```
+
+Or tag a release on GitHub — the included GitHub Action publishes automatically.
+
+---
+
+## Changelog
+
+### 1.1.0
+- Modernized for Django 3.2–5.x and Python 3.8+
+- Added PyPI packaging (`pyproject.toml`)
+- Fixed per-coupon usage validation bug
+- Fixed template mutation in validation responses
+- SEO & documentation update by **Nitesh Kumar Singh (nkscoder)**
+
+### 1.0.0
+- Initial release
+
+---
+
+## Author & Links
+
+| | |
+|---|---|
+| **Author** | Nitesh Kumar Singh |
+| **GitHub** | [github.com/nkscoder](https://github.com/nkscoder) |
+| **Repository** | [github.com/nkscoder/coupons](https://github.com/nkscoder/coupons) |
+| **PyPI** | [pypi.org/project/coupons](https://pypi.org/project/coupons) |
+
+---
+
+## License
+
+MIT License — Copyright (c) 2020-2026 [Nitesh Kumar Singh (nkscoder)](https://github.com/nkscoder)

coupons-1.1.0/coupons/__init__.py

@@ -0,0 +1,3 @@
+"""Django coupons app by Nitesh Kumar Singh (nkscoder)."""
+
+__version__ = "1.1.0"

coupons-1.1.0/coupons/actions.py

@@ -0,0 +1,31 @@
+
+from django.contrib.admin import ModelAdmin
+from django.utils import timezone
+
+
+# Create your actions here
+# ========================
+def reset_coupon_usage(modeladmin, request, queryset):
+    for coupon_user in queryset:
+        coupon_user.times_used = 0
+        coupon_user.save()
+
+    ModelAdmin.message_user(modeladmin, request, "Coupons reseted!")
+
+
+def delete_expired_coupons(modeladmin, request, queryset):
+    count = 0
+    for coupon in queryset:
+        expiration_date = coupon.ruleset.validity.expiration_date
+        if timezone.now() >= expiration_date:
+            coupon.delete()
+            count += 1
+
+    ModelAdmin.message_user(modeladmin, request, "{0} Expired coupons deleted!".format(count))
+
+
+# Actions short descriptions
+# ==========================
+reset_coupon_usage.short_description = "Reset coupon usage"
+delete_expired_coupons.short_description = "Delete expired coupons"
+

coupons-1.1.0/coupons/admin.py

@@ -0,0 +1,53 @@
+from django.contrib import admin
+
+from .models import (Coupon,
+                                          Discount,
+                                          Ruleset,
+                                          CouponUser,
+                                          AllowedUsersRule,
+                                          MaxUsesRule,
+                                          ValidityRule)
+
+from .actions import (reset_coupon_usage, delete_expired_coupons)
+
+
+# Register your models here.
+# ==========================
+@admin.register(Coupon)
+class CouponAdmin(admin.ModelAdmin):
+    list_display = ('code', 'discount', 'ruleset', 'times_used', 'created', )
+    actions = [delete_expired_coupons]
+
+
+@admin.register(Discount)
+class DiscountAdmin(admin.ModelAdmin):
+    pass
+
+
+@admin.register(Ruleset)
+class RulesetAdmin(admin.ModelAdmin):
+    list_display = ('__str__', 'allowed_users', 'max_uses', 'validity', )
+
+
+@admin.register(CouponUser)
+class CouponUserAdmin(admin.ModelAdmin):
+    list_display = ('user', 'coupon', 'times_used', )
+    actions = [reset_coupon_usage]
+
+
+@admin.register(AllowedUsersRule)
+class AllowedUsersRuleAdmin(admin.ModelAdmin):
+    def get_model_perms(self, request):
+        return {}
+
+
+@admin.register(MaxUsesRule)
+class MaxUsesRuleAdmin(admin.ModelAdmin):
+    def get_model_perms(self, request):
+        return {}
+
+
+@admin.register(ValidityRule)
+class ValidityRuleAdmin(admin.ModelAdmin):
+    def get_model_perms(self, request):
+        return {}

coupons-1.1.0/coupons/apps.py

@@ -0,0 +1,7 @@
+from django.apps import AppConfig
+
+
+class CouponsConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "coupons"
+    verbose_name = "Coupons"

coupons-1.1.0/coupons/helpers.py

@@ -0,0 +1,19 @@
+import string
+import random
+
+from django.conf import settings
+
+
+def get_coupon_code_length(length=12):
+    return settings.DSC_COUPON_CODE_LENGTH if hasattr(settings, 'DSC_COUPON_CODE_LENGTH') else length
+
+
+def get_user_model():
+    return settings.AUTH_USER_MODEL
+
+
+def get_random_code(length=12):
+    length = get_coupon_code_length(length=length)
+    return ''.join(random.SystemRandom().choice(string.ascii_uppercase + string.digits) for _ in range(length))
+
+

coupons-1.1.0/coupons/migrations/0001_initial.py

@@ -0,0 +1,112 @@
+# Generated by Django 3.0.8 on 2023-01-13 12:57
+
+import coupons.helpers
+from django.conf import settings
+from django.db import migrations, models
+import django.db.models.deletion
+
+
+class Migration(migrations.Migration):
+
+    initial = True
+
+    dependencies = [
+        migrations.swappable_dependency(settings.AUTH_USER_MODEL),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='AllowedUsersRule',
+            fields=[
+                ('id', models.AutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('all_users', models.BooleanField(default=False, verbose_name='All users?')),
+                ('users', models.ManyToManyField(blank=True, to=settings.AUTH_USER_MODEL, verbose_name='Users')),
+            ],
+            options={
+                'verbose_name': 'Allowed User Rule',
+                'verbose_name_plural': 'Allowed User Rules',
+            },
+        ),
+        migrations.CreateModel(
+            name='Coupon',
+            fields=[
+                ('id', models.AutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('code', models.CharField(default=coupons.helpers.get_random_code, max_length=12, unique=True, verbose_name='Coupon Code')),
+                ('times_used', models.IntegerField(default=0, editable=False, verbose_name='Times used')),
+                ('created', models.DateTimeField(editable=False, verbose_name='Created')),
+            ],
+        ),
+        migrations.CreateModel(
+            name='Discount',
+            fields=[
+                ('id', models.AutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('value', models.IntegerField(default=0, verbose_name='Value')),
+                ('is_percentage', models.BooleanField(default=False, verbose_name='Is percentage?')),
+            ],
+            options={
+                'verbose_name': 'Discount',
+                'verbose_name_plural': 'Discounts',
+            },
+        ),
+        migrations.CreateModel(
+            name='MaxUsesRule',
+            fields=[
+                ('id', models.AutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('max_uses', models.BigIntegerField(default=0, verbose_name='Maximum uses')),
+                ('is_infinite', models.BooleanField(default=False, verbose_name='Infinite uses?')),
+                ('uses_per_user', models.IntegerField(default=1, verbose_name='Uses per user')),
+            ],
+            options={
+                'verbose_name': 'Max Uses Rule',
+                'verbose_name_plural': 'Max Uses Rules',
+            },
+        ),
+        migrations.CreateModel(
+            name='ValidityRule',
+            fields=[
+                ('id', models.AutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('expiration_date', models.DateTimeField(verbose_name='Expiration date')),
+                ('is_active', models.BooleanField(default=False, verbose_name='Is active?')),
+            ],
+            options={
+                'verbose_name': 'Validity Rule',
+                'verbose_name_plural': 'Validity Rules',
+            },
+        ),
+        migrations.CreateModel(
+            name='Ruleset',
+            fields=[
+                ('id', models.AutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('allowed_users', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, to='coupons.AllowedUsersRule', verbose_name='Allowed users rule')),
+                ('max_uses', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, to='coupons.MaxUsesRule', verbose_name='Max uses rule')),
+                ('validity', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, to='coupons.ValidityRule', verbose_name='Validity rule')),
+            ],
+            options={
+                'verbose_name': 'Ruleset',
+                'verbose_name_plural': 'Rulesets',
+            },
+        ),
+        migrations.CreateModel(
+            name='CouponUser',
+            fields=[
+                ('id', models.AutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('times_used', models.IntegerField(default=0, editable=False, verbose_name='Times used')),
+                ('coupon', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, to='coupons.Coupon', verbose_name='Coupon')),
+                ('user', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, to=settings.AUTH_USER_MODEL, verbose_name='User')),
+            ],
+            options={
+                'verbose_name': 'Coupon User',
+                'verbose_name_plural': 'Coupon Users',
+            },
+        ),
+        migrations.AddField(
+            model_name='coupon',
+            name='discount',
+            field=models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, to='coupons.Discount'),
+        ),
+        migrations.AddField(
+            model_name='coupon',
+            name='ruleset',
+            field=models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, to='coupons.Ruleset', verbose_name='Ruleset'),
+        ),
+    ]

coupons-1.1.0/coupons/models.py

@@ -0,0 +1,135 @@
+from django.db import models
+from django.utils import timezone
+
+from .helpers import (get_random_code,
+                                           get_coupon_code_length,
+                                           get_user_model)
+
+
+# Create your models here.
+# ========================
+class Ruleset(models.Model):
+    allowed_users = models.ForeignKey('AllowedUsersRule', on_delete=models.CASCADE, verbose_name="Allowed users rule")
+    max_uses = models.ForeignKey('MaxUsesRule', on_delete=models.CASCADE, verbose_name="Max uses rule")
+    validity = models.ForeignKey('ValidityRule', on_delete=models.CASCADE, verbose_name="Validity rule")
+
+    def __str__(self):
+        return "Ruleset Nº{0}".format(self.id)
+
+    class Meta:
+        verbose_name = "Ruleset"
+        verbose_name_plural = "Rulesets"
+
+
+class AllowedUsersRule(models.Model):
+    user_model = get_user_model()
+
+    users = models.ManyToManyField(user_model, verbose_name="Users", blank=True)
+    all_users = models.BooleanField(default=False, verbose_name="All users?")
+
+    def __str__(self):
+        return "AllowedUsersRule Nº{0}".format(self.id)
+
+    class Meta:
+        verbose_name = "Allowed User Rule"
+        verbose_name_plural = "Allowed User Rules"
+
+
+class MaxUsesRule(models.Model):
+    max_uses = models.BigIntegerField(default=0, verbose_name="Maximum uses")
+    is_infinite = models.BooleanField(default=False, verbose_name="Infinite uses?")
+    uses_per_user = models.IntegerField(default=1, verbose_name="Uses per user")
+
+    def __str__(self):
+        return "MaxUsesRule Nº{0}".format(self.id)
+
+    class Meta:
+        verbose_name = "Max Uses Rule"
+        verbose_name_plural = "Max Uses Rules"
+
+
+class ValidityRule(models.Model):
+    expiration_date = models.DateTimeField(verbose_name="Expiration date")
+    is_active = models.BooleanField(default=False, verbose_name="Is active?")
+
+    def __str__(self):
+        return "ValidityRule Nº{0}".format(self.id)
+
+    class Meta:
+        verbose_name = "Validity Rule"
+        verbose_name_plural = "Validity Rules"
+
+
+class CouponUser(models.Model):
+    user_model = get_user_model()
+
+    user = models.ForeignKey(user_model, on_delete=models.CASCADE, verbose_name="User")
+    coupon = models.ForeignKey('Coupon', on_delete=models.CASCADE, verbose_name="Coupon")
+    times_used = models.IntegerField(default=0, editable=False, verbose_name="Times used")
+
+    def __str__(self):
+        return str(self.user)
+
+    class Meta:
+        verbose_name = "Coupon User"
+        verbose_name_plural = "Coupon Users"
+
+
+class Discount(models.Model):
+    value = models.IntegerField(default=0, verbose_name="Value")
+    is_percentage = models.BooleanField(default=False, verbose_name="Is percentage?")
+
+    def __str__(self):
+        if self.is_percentage:
+            return "{0}% - Discount".format(self.value)
+
+        return "${0} - Discount".format(self.value)
+
+    class Meta:
+        verbose_name = "Discount"
+        verbose_name_plural = "Discounts"
+
+
+class Coupon(models.Model):
+    code_length = get_coupon_code_length()
+
+    code = models.CharField(max_length=code_length, default=get_random_code, verbose_name="Coupon Code", unique=True)
+    discount = models.ForeignKey('Discount', on_delete=models.CASCADE)
+    times_used = models.IntegerField(default=0, editable=False, verbose_name="Times used")
+    created = models.DateTimeField(editable=False, verbose_name="Created")
+
+    ruleset = models.ForeignKey('Ruleset', on_delete=models.CASCADE, verbose_name="Ruleset")
+
+    def __str__(self):
+        return self.code
+
+    def use_coupon(self, user):
+        coupon_user, created = CouponUser.objects.get_or_create(user=user, coupon=self)
+        coupon_user.times_used += 1
+        coupon_user.save()
+
+        self.times_used += 1
+        self.save()
+
+    def get_discount(self):
+        return {
+            "value": self.discount.value,
+            "is_percentage": self.discount.is_percentage
+        }
+    
+    def get_discounted_value(self, initial_value):
+        discount = self.get_discount()
+
+        if discount['is_percentage']:
+            new_price = initial_value - ((initial_value * discount['value']) / 100)
+            new_price = new_price if new_price >= 0.0 else 0.0
+        else:
+            new_price = initial_value - discount['value']
+            new_price = new_price if new_price >= 0.0 else 0.0
+
+        return new_price
+
+    def save(self, *args, **kwargs):
+        if not self.id:
+            self.created = timezone.now()
+        return super().save(*args, **kwargs)

coupons-1.1.0/coupons/tests.py

@@ -0,0 +1,59 @@
+from django.test import TestCase
+from django.contrib.auth import get_user_model
+from django.utils import timezone
+from datetime import timedelta
+
+from coupons.models import (
+    AllowedUsersRule,
+    Coupon,
+    Discount,
+    MaxUsesRule,
+    Ruleset,
+    ValidityRule,
+)
+from coupons.validations import validate_coupon
+
+
+User = get_user_model()
+
+
+class CouponValidationTests(TestCase):
+    def setUp(self):
+        self.user = User.objects.create_user(username="testuser", password="pass")
+        self.discount = Discount.objects.create(value=10, is_percentage=True)
+        self.allowed = AllowedUsersRule.objects.create(all_users=True)
+        self.max_uses = MaxUsesRule.objects.create(
+            max_uses=100, is_infinite=False, uses_per_user=1
+        )
+        self.validity = ValidityRule.objects.create(
+            expiration_date=timezone.now() + timedelta(days=30),
+            is_active=True,
+        )
+        self.ruleset = Ruleset.objects.create(
+            allowed_users=self.allowed,
+            max_uses=self.max_uses,
+            validity=self.validity,
+        )
+        self.coupon = Coupon.objects.create(
+            code="TESTCODE1234",
+            discount=self.discount,
+            ruleset=self.ruleset,
+        )
+
+    def test_valid_coupon(self):
+        result = validate_coupon("TESTCODE1234", self.user)
+        self.assertTrue(result["valid"])
+
+    def test_invalid_coupon_code(self):
+        result = validate_coupon("NOTEXIST", self.user)
+        self.assertFalse(result["valid"])
+        self.assertEqual(result["message"], "Coupon does not exist!")
+
+    def test_get_discounted_value_percentage(self):
+        self.assertEqual(self.coupon.get_discounted_value(100.0), 90.0)
+
+    def test_get_discounted_value_fixed(self):
+        self.discount.is_percentage = False
+        self.discount.value = 20
+        self.discount.save()
+        self.assertEqual(self.coupon.get_discounted_value(100.0), 80.0)

coupons-1.1.0/coupons/validations.py

@@ -0,0 +1,74 @@
+from .models import Coupon, CouponUser
+from django.utils import timezone
+
+
+INVALID_TEMPLATE = {
+    "valid": False,
+    "message": ""
+}
+
+VALID_TEMPLATE = {
+    "valid": True
+}
+
+
+def assemble_invalid_message(message=""):
+    return {"valid": False, "message": message}
+
+
+def validate_allowed_users_rule(coupon_object, user):
+    allowed_users_rule = coupon_object.ruleset.allowed_users
+    if user not in allowed_users_rule.users.all():
+        return False if not allowed_users_rule.all_users else True
+
+    return True
+
+
+def validate_max_uses_rule(coupon_object, user):
+    max_uses_rule = coupon_object.ruleset.max_uses
+    if coupon_object.times_used >= max_uses_rule.max_uses and not max_uses_rule.is_infinite:
+        return False
+
+    try:
+        coupon_user = CouponUser.objects.get(user=user, coupon=coupon_object)
+        if coupon_user.times_used >= max_uses_rule.uses_per_user:
+            return False
+    except CouponUser.DoesNotExist:
+        pass
+
+    return True
+
+
+def validate_validity_rule(coupon_object):
+    validity_rule = coupon_object.ruleset.validity
+    if timezone.now() > validity_rule.expiration_date:
+        return False
+
+    return validity_rule.is_active
+
+
+def validate_coupon(coupon_code, user):
+    if not coupon_code:
+        return assemble_invalid_message(message="No coupon code provided!")
+
+    if not user:
+        return assemble_invalid_message(message="No user provided!")
+
+    try:
+        coupon_object = Coupon.objects.get(code=coupon_code)
+    except Coupon.DoesNotExist:
+        return assemble_invalid_message(message="Coupon does not exist!")
+
+    valid_allowed_users_rule = validate_allowed_users_rule(coupon_object=coupon_object, user=user)
+    if not valid_allowed_users_rule:
+        return assemble_invalid_message(message="Invalid coupon for this user!")
+
+    valid_max_uses_rule = validate_max_uses_rule(coupon_object=coupon_object, user=user)
+    if not valid_max_uses_rule:
+        return assemble_invalid_message(message="Coupon uses exceeded for this user!")
+
+    valid_validity_rule = validate_validity_rule(coupon_object=coupon_object)
+    if not valid_validity_rule:
+        return assemble_invalid_message(message="Invalid coupon!")
+
+    return VALID_TEMPLATE

coupons-1.1.0/coupons/views.py

@@ -0,0 +1 @@
+# Create your views here.

coupons-1.1.0/coupons.egg-info/PKG-INFO

@@ -0,0 +1,246 @@
+Metadata-Version: 2.4
+Name: coupons
+Version: 1.1.0
+Summary: Django coupon and discount code system with validation rules — by Nitesh Kumar Singh (nkscoder)
+Author-email: Nitesh Kumar Singh <nkscoder@gmail.com>
+Maintainer-email: Nitesh Kumar Singh <nkscoder@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/nkscoder/coupons
+Project-URL: Documentation, https://github.com/nkscoder/coupons#readme
+Project-URL: Repository, https://github.com/nkscoder/coupons
+Project-URL: Bug Tracker, https://github.com/nkscoder/coupons/issues
+Project-URL: Author GitHub, https://github.com/nkscoder
+Keywords: django,coupons,coupon,discount,promo-code,promotional-code,ecommerce,nkscoder,nitesh-kumar-singh,python,django-coupons,coupon-validation,discount-code
+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: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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
+Dynamic: license-file
+
+# Coupons — Django Coupon & Discount Code System
+
+[![PyPI version](https://badge.fury.io/py/coupons.svg)](https://pypi.org/project/coupons/)
+[![Python](https://img.shields.io/pypi/pyversions/coupons.svg)](https://pypi.org/project/coupons/)
+[![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 reusable **Django coupons app** for managing promotional codes, discount rules, and coupon validation in Python web applications. Built by **Nitesh Kumar Singh (nkscoder)** for e-commerce, SaaS, and any Django project that needs flexible coupon functionality.
+
+> **Keywords:** django coupons · python coupon system · discount code · promo code · coupon validation · nkscoder · nitesh kumar singh
+
+---
+
+## Features
+
+- **Percentage or fixed-amount discounts** on any order total
+- **User-specific or global coupons** — restrict codes to selected users or allow all
+- **Usage limits** — max total uses, uses per user, or unlimited
+- **Expiration & active/inactive rules** with datetime-based validity
+- **Django Admin integration** with bulk actions (reset usage, delete expired)
+- **Simple validation API** — one function call to check any coupon code
+- **Configurable coupon code length** via `DSC_COUPON_CODE_LENGTH` setting
+
+---
+
+## Requirements
+
+- Python 3.8+
+- Django 3.2+
+
+---
+
+## Installation
+
+### From PyPI (recommended)
+
+```bash
+pip install coupons
+```
+
+### From GitHub
+
+```bash
+pip install git+https://github.com/nkscoder/coupons.git
+```
+
+---
+
+## Setup
+
+### Step 1 — Add to `INSTALLED_APPS`
+
+```python
+# settings.py
+INSTALLED_APPS = [
+    ...
+    "coupons",
+]
+```
+
+### Step 2 — Run migrations
+
+```bash
+python manage.py migrate coupons
+```
+
+### Step 3 — Create coupons in Django Admin
+
+Go to `/admin/` and create:
+
+1. **Discount** — set value and type (percentage or fixed)
+2. **Allowed Users Rule** — select users or enable "All users"
+3. **Max Uses Rule** — set limits or enable infinite uses
+4. **Validity Rule** — set expiration date and active status
+5. **Ruleset** — link the three rules above
+6. **Coupon** — assign discount and ruleset (code auto-generated)
+
+### Step 4 (optional) — Custom coupon code length
+
+```python
+# settings.py
+DSC_COUPON_CODE_LENGTH = 16  # default is 12
+```
+
+---
+
+## Usage
+
+### Validate a coupon
+
+```python
+from coupons.validations import validate_coupon
+
+coupon_code = "COUPONTEST01"
+user = User.objects.get(username="nitesh")
+
+status = validate_coupon(coupon_code=coupon_code, user=user)
+# {'valid': True}
+
+if status["valid"]:
+    print("Coupon is valid!")
+else:
+    print(status["message"])  # e.g. "Coupon does not exist!"
+```
+
+### Apply a coupon (record usage)
+
+```python
+from coupons.models import Coupon
+
+coupon = Coupon.objects.get(code=coupon_code)
+coupon.use_coupon(user=user)
+```
+
+### Get discount details
+
+```python
+coupon = Coupon.objects.get(code=coupon_code)
+discount = coupon.get_discount()
+# {'value': 50, 'is_percentage': True}
+```
+
+### Calculate discounted price
+
+```python
+discounted = coupon.get_discounted_value(initial_value=100.0)
+# Returns 50.0 for 50% off, or 80.0 for $20 off
+```
+
+---
+
+## Validation Rules
+
+| Rule | Description |
+|------|-------------|
+| **Allowed Users** | Coupon valid only for selected users, or all users |
+| **Max Uses** | Global usage cap, per-user limit, or infinite |
+| **Validity** | Active flag + expiration datetime |
+
+Invalid responses include a human-readable `message` key:
+
+```python
+validate_coupon("DUMMYCODE", user)
+# {'valid': False, 'message': 'Coupon does not exist!'}
+```
+
+---
+
+## REST API Example
+
+See [`examples/`](examples/) for a Django REST Framework integration sample (`ajax_views.py`, `ajax_urls.py`).
+
+---
+
+## Development
+
+```bash
+git clone git@github.com:nkscoder/coupons.git
+cd coupons
+pip install -e ".[dev]"
+python manage.py migrate
+python manage.py runserver
+```
+
+### Build & publish to PyPI
+
+```bash
+pip install build twine
+python -m build
+twine upload dist/*
+```
+
+Or tag a release on GitHub — the included GitHub Action publishes automatically.
+
+---
+
+## Changelog
+
+### 1.1.0
+- Modernized for Django 3.2–5.x and Python 3.8+
+- Added PyPI packaging (`pyproject.toml`)
+- Fixed per-coupon usage validation bug
+- Fixed template mutation in validation responses
+- SEO & documentation update by **Nitesh Kumar Singh (nkscoder)**
+
+### 1.0.0
+- Initial release
+
+---
+
+## Author & Links
+
+| | |
+|---|---|
+| **Author** | Nitesh Kumar Singh |
+| **GitHub** | [github.com/nkscoder](https://github.com/nkscoder) |
+| **Repository** | [github.com/nkscoder/coupons](https://github.com/nkscoder/coupons) |
+| **PyPI** | [pypi.org/project/coupons](https://pypi.org/project/coupons) |
+
+---
+
+## License
+
+MIT License — Copyright (c) 2020-2026 [Nitesh Kumar Singh (nkscoder)](https://github.com/nkscoder)

coupons-1.1.0/coupons.egg-info/SOURCES.txt

@@ -0,0 +1,20 @@
+LICENSE
+MANIFEST.in
+README.md
+pyproject.toml
+coupons/__init__.py
+coupons/actions.py
+coupons/admin.py
+coupons/apps.py
+coupons/helpers.py
+coupons/models.py
+coupons/tests.py
+coupons/validations.py
+coupons/views.py
+coupons.egg-info/PKG-INFO
+coupons.egg-info/SOURCES.txt
+coupons.egg-info/dependency_links.txt
+coupons.egg-info/requires.txt
+coupons.egg-info/top_level.txt
+coupons/migrations/0001_initial.py
+coupons/migrations/__init__.py

coupons-1.1.0/coupons.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

coupons-1.1.0/coupons.egg-info/requires.txt

@@ -0,0 +1 @@
+Django>=3.2

coupons-1.1.0/coupons.egg-info/top_level.txt

@@ -0,0 +1 @@
+coupons

coupons-1.1.0/pyproject.toml

@@ -0,0 +1,71 @@
+[build-system]
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "coupons"
+version = "1.1.0"
+description = "Django coupon and discount code system with validation rules — by Nitesh Kumar Singh (nkscoder)"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [
+    { name = "Nitesh Kumar Singh", email = "nkscoder@gmail.com" },
+]
+maintainers = [
+    { name = "Nitesh Kumar Singh", email = "nkscoder@gmail.com" },
+]
+keywords = [
+    "django",
+    "coupons",
+    "coupon",
+    "discount",
+    "promo-code",
+    "promotional-code",
+    "ecommerce",
+    "nkscoder",
+    "nitesh-kumar-singh",
+    "python",
+    "django-coupons",
+    "coupon-validation",
+    "discount-code",
+]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Environment :: Web Environment",
+    "Framework :: Django",
+    "Framework :: Django :: 3.2",
+    "Framework :: Django :: 4.0",
+    "Framework :: Django :: 4.1",
+    "Framework :: Django :: 4.2",
+    "Framework :: Django :: 5.0",
+    "Framework :: Django :: 5.1",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Internet :: WWW/HTTP :: Dynamic Content",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+requires-python = ">=3.8"
+dependencies = [
+    "Django>=3.2",
+]
+
+[project.urls]
+Homepage = "https://github.com/nkscoder/coupons"
+Documentation = "https://github.com/nkscoder/coupons#readme"
+Repository = "https://github.com/nkscoder/coupons"
+"Bug Tracker" = "https://github.com/nkscoder/coupons/issues"
+"Author GitHub" = "https://github.com/nkscoder"
+
+[tool.setuptools.packages.find]
+include = ["coupons*"]
+
+[tool.setuptools.package-data]
+coupons = ["migrations/*.py"]

coupons-1.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+