# Byte-compiled / optimized / DLL files

__pycache__/

*.py[cod]

*$py.class

# C extensions

*.so

# Distribution / packaging

.Python

env/

build/

develop-eggs/

dist/

downloads/

eggs/

.eggs/

lib/

lib64/

parts/

sdist/

var/

*.egg-info/

.installed.cfg

*.egg

# PyInstaller

#  Usually these files are written by a python script from a template

#  before PyInstaller builds the exe, so as to inject date/other infos into it.

*.manifest

*.spec

# Installer logs

pip-log.txt

pip-delete-this-directory.txt

# Unit test / coverage reports

htmlcov/

.tox/

.coverage

.coverage.*

.cache

nosetests.xml

coverage.xml

*,cover

.hypothesis/

# Translations

*.mo

*.pot

# Django stuff:

*.log

# Sphinx documentation

docs/_build/

# PyBuilder

target/

# Grumble OSX Grumble

.DS_Store

*/.DS_Store

	commit = c1e194aef92e4c06a8855fad22ca819c08736dad

	parent = dd8a42e9f67cfebc39347cb87bacf79046bfbfec

Contributing to Registrasion

============================

I'm glad that you're interested in helping make Registrasion better! Thanks! This guide is meant to help make sure your contributions to the project fit in well.

Making a contribution

---------------------

This project makes use of GitHub issues to track pending work, so new features that need implementation can be found there. If you think a new feature needs to be added, raise an issue for discussion before submitting a Pull Request.

Code Style

----------

We use PEP8. Your code should pass checks by ``flake8`` with no errors or warnings before it will be merged.

We use `Google-style docstrings <http://sphinxcontrib-napoleon.readthedocs.org/en/latest/example_google.html>`_, primarily because they're far far more readable than ReST docstrings. New functions should have complete docstrings, so that new contributors have a chance of understanding how the API works.

Structure

---------

Django Models live in ``registrasion/models``; we separate our models out into separate files, because there's a lot of them. Models are grouped by logical functionality.

Actions that operate on Models live in ``registrasion/controllers``.

Testing

-------

Functionality that lives in ``regsistrasion/controllers`` was developed in a test-driven fashion, which is sensible, given it's where most of the business logic for registrasion lives. If you're changing behaviour of a controller, either submit a test with your pull request, or modify an existing test.

Documentation

-------------

Registrasion aims towards high-quality documentation, so that conference registration managers can understand how the system works, and so that webmasters working for conferences understand how the system fits together. Make sure that you have docstrings :)

The documentation is written in Australian English: *-ise* and not *-ize*, *-our* and not *-or*; *vegemite* and not *peanut butter*, etc etc etc.

Registrasion

============

**Registra** (tion for Sympo) **sion**. A conference registration app for Django,

letting conferences big and small sell tickets from within Symposion.

Symposion

---------

``symposion`` is an Open Source conference management solution built with Pinax

apps for Django. For more information, see https://github.com/pinax/symposion.

registrasion

------------

``registrasion`` is a registration package that you use alongside Symposion. It

handles inventory management, as well as complex product inclusions, automatic

calculation of discounts, and invoicing. Payment of invoices can be faciliated

by manual filings of payments by staff, or through plugging in a payment app.

Initial development of ``registrasion`` was funded with the generous support of

the Python Software Foundation.

Quickstart

----------

``registrasion`` is a Django app. You will need to create a Django project to

customize and manage your Registrasion and Symposion installation. A

demonstration app project with templates is available at

https://github.com/chrisjrn/registrasion-demo

Documentation

-------------

The documentation for ``registrasion`` is available at

http://registrasion.readthedocs.org/

# Logic

## Definitions

- User has one 'active Cart' at a time. The Cart remains active until a paid Invoice is attached to it.

- A 'paid Cart' is a Cart with a paid Invoice attached to it, where the Invoice has not been voided.

- An unpaid Cart is 'reserved' if

 - CURRENT_TIME - "Time last updated" <= max(reservation duration of Products in Cart),

 - A Voucher was added and CURRENT_TIME - "Time last updated" < VOUCHER_RESERVATION_TIME (15 minutes?)

- An Item is 'reserved' if:

  - it belongs to a reserved Cart

  - it belongs to a paid Cart

- A Cart can have any number of Items added to it, subject to limits.

## Entering Vouchers

- Vouchers are attached to Carts

- A user can enter codes for as many different Vouchers as they like.

- A Voucher is added to the Cart if the number of paid or reserved Carts containing the Voucher is less than the "total available" for the voucher.

- A cart is invalid if it contains a voucher that has been overused

## Are products available?

- Availability is determined by the number of items we want to add to the cart: items_to_add

- If items_to_add + count(Product in their active and paid Carts) > "Limit per user" for the Product, the Product is "unavailable".

- If the Product belongs to an exhausted Ceiling, the Product is "unavailable".

- Otherwise, the product is available

## Displaying Products:

- If there is at least one mandatory EnablingCondition attached to the Product, display it only if all EnablingConditions are met

- If there is at least one EnablingCondition attached to the Product, display it only if at least one EnablingCondition is met

- If there are zero EnablingConditions attached to the Product, display it

- If the product is not available for items_to_add=0, mark it as "unavailable"

- If the Product is displayed and available, its price is the price for the Product, minus the greatest Discount available to this Cart and Product

- The product is displayed per the rendering characteristics of the Category it belongs to

## Displaying Categories

- If the Category contains only "unavailable" Products, mark it as "unavailable"

- If the Category contains no displayed Products, do not display the Category

- If the Category contains at least one EnablingCondition, display it only if at least one EnablingCondition is met

- If the Category contains no EnablingConditions, display it

## Exhausting Ceilings

- Exhaustion is determined by the number of items we want to add to the cart: items_to_add

- A ceiling is exhausted if:

 - Its start date has not yet been reached

 - Its end date has been exceeded

 - items_to_add + sum(paid and reserved Items for each Product in the ceiling) > Total available

## Applying Discounts

- Discounts only apply to the current cart

- Discounts can be applied to multiple carts until the user has exhausted the quantity for each product attached to the discount.

- Only one discount discount can be applied to each single item. Discounts are applied as follows:

 - All non-exhausted discounts for the product or its category are ordered by value

 - The highest discount is applied for the lower of the quantity of the product in the cart, or the remaining quantity from this discount

 - If the quantity remaining is non-zero, apply the next available discount

- Individual discount objects should not contain more than one DiscountForProduct for the same product

- Individual discount objects should not contain more than one DiscountForCategory for the same category

- Individual discount objects should not contain a discount for both a product and its category

## Adding Items to the Cart

- Products that are not displayed may not be added to a Cart

- The requested number of items must be available for those items to be added to a Cart

- If a different price applies to a Product when it is added to a cart, add at the new price, and display an alert to the user

- If a discount is used when adding a Product to the cart, add the discount as well

- Adding an item resets the "Time last updated" for the cart

- Each time carts have items added or removed, the revision number is updated

## Generating an invoice

- User can ask to 'check out' the active Cart. Doing so generates an Invoice. The invoice corresponds to a revision number of the cart.

- Checking out the active Cart resets the "Time last updated" for the cart.

- The invoice represents the current state of the cart.

- If the revision number for the cart is different to the cart's revision number for the invoice, the invoice is void.

- The invoice is void if

## Paying an invoice

- A payment can only be attached to an invoice if all of the items in it are available at the time payment is processed

### One-Shot

- Update the "Time last updated" for the cart based on the expected time it takes for a payment to complete

- Verify that all items are available, and if so:

- Proceed to make payment

- Apply payment record from amount received

### Authorization-based approach:

- Capture an authorization on the card

- Verify that all items are available, and if so:

- Apply payment record

- Take payment

# Registration workflow:

## User has not taken a guided registration yet:

User is shown two options:

1. Undertake guided registration ("for current user")

1. Purchase vouchers

## User has not purchased a ticket, and wishes to:

This gives the user a guided registration process.

1. Take list of categories, sorted by display order, and display the next lowest enabled & available category

1. Take user to category page

1. User can click "back" to go to previous screen, or "next" to go the next lowest enabled & available category

Once all categories have been seen:

1. Ask for badge information -- badge information is *not* the same as the invoicee.

1. User is taken to the "user has purchased a ticket" workflow

## User is buying vouchers

TODO: Consider separate workflow for purchasing ticket vouchers.

## User has completed a guided registration or purchased vouchers

1. Show list of products that are pending purchase.

1. Show list of categories + badge information, as well as 'checkout' button if the user has items in their current cart

## Category page

- User can enter a voucher at any time

- User is shown the list of products that have been paid for

- User has the option to add/remove products that are in the current cart

## Checkout

1. Ask for invoicing details (pre-fill from previous invoice?)

1. Ask for payment

# User Models

- Profile:

 - User

 - Has done guided registration?

 - Badge

 -

## Transaction Models

- Cart:

 - User

 - {Items}

 - {Voucher}

 - {DiscountItems}

 - Time last updated

 - Revision Number

 - Active?

- Item

 - Product

 - Quantity

- DiscountItem

 - Product

 - Discount

 - Quantity

- Invoice:

 - Invoice number

 - User

 - Cart

 - Cart Revision

 - {Line Items}

 - (Invoice Details)

 - {Payments}

 - Voided?

- LineItem

 - Description

 - Quantity

 - Price

- Payment

 - Time

 - Amount

 - Reference

## Inventory Model

- Product:

 - Name

 - Description

 - Category

 - Price

 - Limit per user

 - Reservation duration

 - Display order

 - {Ceilings}

- Voucher

 - Description

 - Code

 - Total available

- Category?

 - Name

 - Description

 - Display Order

 - Rendering Style

## Product Modifiers

- Discount:

 - Description

 - {DiscountForProduct}

 - {DiscountForCategory}

 - Discount Types:

    - TimeOrStockLimitDiscount:

     * A discount that is available for a limited amount of time, e.g. Early Bird sales *

     - Start date

     - End date

     - Total available

    - VoucherDiscount:

     * A discount that is available to a specific voucher *

     - Voucher

    - RoleDiscount

     * A discount that is available to a specific role *

     - Role

    - IncludedProductDiscount:

     * A discount that is available because another product has been purchased *

     - {Parent Product}

- DiscountForProduct

 - Product

 - Amount

 - Percentage

 - Quantity

- DiscountForCategory

 - Category

 - Percentage

 - Quantity

- EnablingCondition:

 - Description

 - Mandatory?

 - {Products}

 - {Categories}

 - EnablingCondition Types:

   - ProductEnablingCondition:

    * Enabling because the user has purchased a specific product *

    - {Products that enable}

   - CategoryEnablingCondition:

    * Enabling because the user has purchased a product in a specific category *

    - {Categories that enable}

   - VoucherEnablingCondition:

    * Enabling because the user has entered a voucher code *

     - Voucher

   - RoleEnablingCondition:

     * Enabling because the user has a specific role *

     - Role

   - TimeOrStockLimitEnablingCondition:

    * Enabling because a time condition has been met, or a number of items underneath it have not been sold *

    - Start date

    - End date

    - Total available

# Registrasion

## What

A registration package that sits on top of the Symposion conference management system. It aims to be able to model complex events, such as those used by [Linux Australia events](http://lca2016.linux.org.au/register/info?_code=301).

## Planned features

### KEY:

- _(MODEL)_: these have model/controller functionality, and tests, and needs UI

- _(ADMIN)_: these have admin functionality

### Inventory

- Allow conferences to manage complex inventories of products, including tickets, t-shirts, dinner tickets, and accommodation _(MODEL)_ _(ADMIN)_

- Reports of available inventory and progressive sales for conference staff

- Restrict sales of products to specific classes of users

- Restrict sales of products based to users who've purchased specific products _(MODEL)_ _(ADMIN)_

- Restrict sales of products based on time/inventory limits _(MODEL)_ _(ADMIN)_

- Restrict sales of products to users with a voucher _(MODEL)_ _(ADMIN)_

### Tickets

- Sell multiple types of tickets, each with different included products _(MODEL)_ _(ADMIN)_

- Allow for early bird-style discounts _(MODEL)_ _(ADMIN)_

- Allow attendees to purchase products after initial registration is complete _(MODEL)_

 - Offer included products if they have not yet been claimed _(MODEL)_

- Automatically offer free tickets to speakers and team

- Offer free tickets for sponsor attendees by voucher _(MODEL)_ _(ADMIN)_

### Vouchers

- Vouchers for arbitrary discounts off visible products _(MODEL)_ _(ADMIN)_

- Vouchers that enable secret products _(MODEL)_ _(ADMIN)_

### Invoicing

- Automatic invoicing including discount calculation _(MODEL)_

- Manual invoicing for arbitrary products by organisers _(MODEL)_

- Refunds

### Payments

- Allow multiple payment gateways (so that conferences are not locked into specific payment providers)

- Allow payment of registrations by unauthenticated users (allow business admins to pay for registrations)

- Allow payment of multiple registrations at once

### Attendee profiles

- Attendees can enter information to be shown on their badge/dietary requirements etc

- Profile can be changed until check-in, allowing for badge/company updates

### At the conference

- Badge generation, in batches, or on-demand during check-in

- Registration manifests for each attendee including purchased products

- Check-in process at registration desk allowing manifested items to be claimed

### Tooling

- Generate simple registration cases (ones that don't have complex inventory requirements)

- Generate complex registration cases from spreadsheets

# Makefile for Sphinx documentation

#

# You can set these variables from the command line.

SPHINXOPTS    =

SPHINXBUILD   = sphinx-build

PAPER         =

BUILDDIR      = _build

# User-friendly check for sphinx-build

ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)

	$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don\'t have Sphinx installed, grab it from http://sphinx-doc.org/)

endif

# Internal variables.

PAPEROPT_a4     = -D latex_paper_size=a4

PAPEROPT_letter = -D latex_paper_size=letter

ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .

# the i18n builder cannot share the environment and doctrees with the others

I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .

.PHONY: help

help:

	@echo "Please use \`make <target>' where <target> is one of"

	@echo "  html       to make standalone HTML files"

	@echo "  dirhtml    to make HTML files named index.html in directories"

	@echo "  singlehtml to make a single large HTML file"

	@echo "  pickle     to make pickle files"

	@echo "  json       to make JSON files"

	@echo "  htmlhelp   to make HTML files and a HTML help project"

	@echo "  qthelp     to make HTML files and a qthelp project"

	@echo "  applehelp  to make an Apple Help Book"

	@echo "  devhelp    to make HTML files and a Devhelp project"

	@echo "  epub       to make an epub"

	@echo "  epub3      to make an epub3"

	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"

	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"

	@echo "  latexpdfja to make LaTeX files and run them through platex/dvipdfmx"

	@echo "  text       to make text files"

	@echo "  man        to make manual pages"

	@echo "  texinfo    to make Texinfo files"

	@echo "  info       to make Texinfo files and run them through makeinfo"

	@echo "  gettext    to make PO message catalogs"

	@echo "  changes    to make an overview of all changed/added/deprecated items"

	@echo "  xml        to make Docutils-native XML files"

	@echo "  pseudoxml  to make pseudoxml-XML files for display purposes"

	@echo "  linkcheck  to check all external links for integrity"

	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"

	@echo "  coverage   to run coverage check of the documentation (if enabled)"

	@echo "  dummy      to check syntax errors of document sources"

.PHONY: clean

clean:

	rm -rf $(BUILDDIR)/*

.PHONY: html

html:

	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html

	@echo

	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."

.PHONY: dirhtml

dirhtml:

	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml

	@echo

	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."

.PHONY: singlehtml

singlehtml:

	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml

	@echo

	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."

.PHONY: pickle

pickle:

	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle

	@echo

	@echo "Build finished; now you can process the pickle files."

.PHONY: json

json:

	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json

	@echo

	@echo "Build finished; now you can process the JSON files."

.PHONY: htmlhelp

htmlhelp:

	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp

	@echo

	@echo "Build finished; now you can run HTML Help Workshop with the" \

	      ".hhp project file in $(BUILDDIR)/htmlhelp."

.PHONY: qthelp

qthelp:

	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp

	@echo

	@echo "Build finished; now you can run "qcollectiongenerator" with the" \

	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"

	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/Registrasion.qhcp"

	@echo "To view the help file:"

	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/Registrasion.qhc"

.PHONY: applehelp

applehelp:

	$(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp

	@echo

	@echo "Build finished. The help book is in $(BUILDDIR)/applehelp."

	@echo "N.B. You won't be able to view it unless you put it in" \

	      "~/Library/Documentation/Help or install it in your application" \

	      "bundle."

.PHONY: devhelp

devhelp:

	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp

	@echo

	@echo "Build finished."

	@echo "To view the help file:"

	@echo "# mkdir -p $$HOME/.local/share/devhelp/Registrasion"

	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/Registrasion"

	@echo "# devhelp"

.PHONY: epub

epub:

	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub

	@echo

	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."

.PHONY: epub3

epub3:

	$(SPHINXBUILD) -b epub3 $(ALLSPHINXOPTS) $(BUILDDIR)/epub3

	@echo

	@echo "Build finished. The epub3 file is in $(BUILDDIR)/epub3."

.PHONY: latex

latex:

	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex

	@echo

	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."

	@echo "Run \`make' in that directory to run these through (pdf)latex" \

	      "(use \`make latexpdf' here to do that automatically)."

.PHONY: latexpdf

latexpdf:

	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex

	@echo "Running LaTeX files through pdflatex..."

	$(MAKE) -C $(BUILDDIR)/latex all-pdf

	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."

.PHONY: latexpdfja

latexpdfja:

	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex

	@echo "Running LaTeX files through platex and dvipdfmx..."

	$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja

	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."

.PHONY: text

text:

	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text

	@echo

	@echo "Build finished. The text files are in $(BUILDDIR)/text."

.PHONY: man

man:

	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man

	@echo

	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."

.PHONY: texinfo

texinfo:

	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo

	@echo

	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."

	@echo "Run \`make' in that directory to run these through makeinfo" \

	      "(use \`make info' here to do that automatically)."

.PHONY: info

info:

	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo

	@echo "Running Texinfo files through makeinfo..."

	make -C $(BUILDDIR)/texinfo info

	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."

.PHONY: gettext

gettext:

	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale

	@echo

	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."

.PHONY: changes

changes:

	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes

	@echo

	@echo "The overview file is in $(BUILDDIR)/changes."

.PHONY: linkcheck

linkcheck:

	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck

	@echo

	@echo "Link check complete; look for any errors in the above output " \

	      "or in $(BUILDDIR)/linkcheck/output.txt."

.PHONY: doctest

doctest:

	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest

	@echo "Testing of doctests in the sources finished, look at the " \

	      "results in $(BUILDDIR)/doctest/output.txt."

.PHONY: coverage

coverage:

	$(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage

	@echo "Testing of coverage in the sources finished, look at the " \

	      "results in $(BUILDDIR)/coverage/python.txt."

.PHONY: xml

xml:

	$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml

	@echo

	@echo "Build finished. The XML files are in $(BUILDDIR)/xml."

.PHONY: pseudoxml

pseudoxml:

	$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml

	@echo

	@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."

.PHONY: dummy

dummy:

	$(SPHINXBUILD) -b dummy $(ALLSPHINXOPTS) $(BUILDDIR)/dummy

	@echo

	@echo "Build finished. Dummy builder generates no files."