Metadata-Version: 2.1
Name: django-simple-coupons
Version: 0.1
Summary: A Django app that makes the use of coupons a simple task!
Home-page: https://github.com/Wolfterro/django-simple-coupons
Author: Wolfgang Almeida
Author-email: wolfgang.almeida@yahoo.com
License: MIT License
Description: # django-simple-coupons
        ##  A Django app that makes the use of coupons a simple task!
        
        django-simple-coupons is a simple Django app to create and use promotional coupons in your website.
        
        Creating the coupons is a simple task, but first, follow the instructions to install the app in your project:
        
        ### Installing:
        
        1 - Add ```django_simple_coupons``` inside INSTALLED_APPS in settings.py:
        
        ```python
        INSTALLED_APPS = [
                ...
                'django_simple_coupons',
        ]
        ```
        
        2 - (Optional) If you want to use more than 12 chars (default) for your coupon code, add ```DSC_COUPON_CODE_LENGTH``` variable in settings.py:
        
        ```python
        DSC_COUPON_CODE_LENGTH = 16
        ```
        
        3 - (Optional) If you make use of another User model in your project, add ```DSC_USER_MODEL``` variable in settings.py:
        
        ```python
        DSC_USER_MODEL = 'custom_auth.models.User'  # app.module.class format (example)
        ```
        
        4 - Run the migrations:
        
        ```bash
        $ python manage.py makemigrations
        $ python manage.py migrate
        ```
        
        And that's it! django-simple-coupons should appear in your admin as ```Simple Coupons```.
        
        ### Coupons:
        
        Each coupon has a ***code***, ***discount*** and set of rules (known as ***ruleset*** in the admin).
        
        Every time you click ```Add Coupon```, a new coupon code will be generated randomly for you. Don't worry, you can set your own personal code if you wish.
        
        ![create-coupon](docs/images/coupon-create.png)
        
        Each ruleset has three basic rules that you need to supply: ***Allowed user rule***, ***Max uses rule*** and ***Validity rule***.
        
        ### Ruleset:
        
        Every coupon needs a set of rules to make it valid and useable.
        For now, django-simple-coupons use three basic rules:
        
        ##### Allowed user rule:
        
        Defines which users are allowed to use the coupon.
        
        ![allowed-user-rule](docs/images/allowed-users-rule.png)
        
        ##### Max uses rule:
        
        Defines how many uses the coupon should have in general and for each user.
        
        ![max-uses-rule](docs/images/max-uses-rule.png)
        
        ##### Validity rule:
        
        Defines the expiration date for the coupon and if it's active or not.
        
        ![validity-rule](docs/images/validity-rule.png)
        
        ### Coupon User:
        
        Every time a user uses a coupon, he will be added to a list called ```Coupon Users``` in admin.
        
        ![coupon-user](docs/images/coupon-user.png)
        
        
        ### Usage Example:
        
        ```python
        # views.py - Example only
        # /use-coupon/?coupon_code=COUPONTEST01
        
        from django.contrib.auth.models import User
        from django.http import HttpResponse
        
        from django_simple_coupons.validations import validate_coupon
        from django_simple_coupons.models import Coupon
        
        class UseCouponView(View):
            def get(self, request, *args, **kwargs):
                coupon_code = request.GET.get("coupon_code")
                user = User.objects.get(username=request.user.username)
                
                status = validate_coupon(coupon_code=coupon_code, user=user)
                if status['valid']:
                    coupon = Coupon.objects.get(code=coupon_code)
                    coupon.use_coupon(user=user)
                
                    return HttpResponse("OK")
                
                return HttpResponse(status['message'])
        ```
        
        To use django-simple-coupons accordingly, you'll need to validate the coupon first with the coupon code and the user that will use the coupon.
        
        To validate the coupon, use the method ```validate_coupon()``` from ```django_simple_coupons.validators```. This method returns a dict with one key (if valid) or two keys (if not valid):
        
        ```python
        VALID = {
            "valid": True
        }
        
        INVALID = {
            "valid": False,
            "message": "Some message telling why it's not valid"
        }
        ```
        
        If it's valid, you can safely call the function ```use_coupon()``` from the Coupon instance.
        
        Please note that I used the default User model from Django in this example. If you use a custom authentication system, you'll need to use the proper User model from your custom auth app!
        
Platform: UNKNOWN
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Description-Content-Type: text/markdown
