Rewrite README and switch to Markdown

AUTHORS.md

@@ -0,0 +1,18 @@
+=======
+Credits
+=======
+
+Creator
+-------
+
+* Aaron Bassett <[email protected]>
+
+Contributors
+------------
+
+* John Sutherland - @sneeu
+* Luís Rodrigues - @lfrodrigues
+* @Zeioth
+* Max Arnold - @max-arnold
+* Marcin Zajączkowski - @szpak
+* @simaojf

CONTRIBUTING.rst → CONTRIBUTING.md

@@ -3,15 +3,15 @@ Contributing
 ============
 
 Contributions are welcome, and they are greatly appreciated! Every
-little bit helps, and credit will always be given. 
+little bit helps, and credit will always be given.
 
 You can contribute in many ways:
 
 Types of Contributions
 ----------------------
 
 Report Bugs
-~~~~~~~~~~~
+-----------
 
 Report bugs at https://github.com/aaronbassett/DisposableEmailChecker/issues.
 
@@ -22,26 +22,26 @@ If you are reporting a bug, please include:
 * Detailed steps to reproduce the bug.
 
 Fix Bugs
-~~~~~~~~
+--------
 
 Look through the GitHub issues for bugs. Anything tagged with "bug"
 is open to whoever wants to implement it.
 
 Implement Features
-~~~~~~~~~~~~~~~~~~
+------------------
 
 Look through the GitHub issues for features. Anything tagged with "feature"
 is open to whoever wants to implement it.
 
 Write Documentation
-~~~~~~~~~~~~~~~~~~~
+-------------------
 
-django-disposable-email-checker could always use more documentation, whether as part of the 
+django-disposable-email-checker could always use more documentation, whether as part of the
 official django-disposable-email-checker docs, in docstrings, or even on the web in blog posts,
 articles, and such.
 
 Submit Feedback
-~~~~~~~~~~~~~~~
+---------------
 
 The best way to send feedback is to file an issue at https://github.com/aaronbassett/DisposableEmailChecker/issues.
 
@@ -58,32 +58,32 @@ Get Started!
 Ready to contribute? Here's how to set up `DisposableEmailChecker` for local development.
 
 1. Fork the `DisposableEmailChecker` repo on GitHub.
-2. Clone your fork locally::
+2. Clone your fork locally
 
     $ git clone [email protected]:your_name_here/DisposableEmailChecker.git
 
-3. Install your local copy into a virtualenv. Assuming you have virtualenvwrapper installed, this is how you set up your fork for local development::
+3. Install your local copy into a virtualenv. Assuming you have virtualenvwrapper installed, this is how you set up your fork for local development
 
     $ mkvirtualenv DisposableEmailChecker
     $ cd DisposableEmailChecker/
     $ python setup.py develop
 
-4. Create a branch for local development::
+4. Create a branch for local development
 
     $ git checkout -b name-of-your-bugfix-or-feature
 
 Now you can make your changes locally.
 
 5. When you're done making changes, check that your changes pass flake8 and the
-tests, including testing other Python versions with tox::
+tests, including testing other Python versions with tox
 
     $ flake8 disposable_email_checker tests
     $ python setup.py test
     $ tox
 
-To get flake8 and tox, just pip install them into your virtualenv. 
+To get flake8 and tox, just pip install them into your virtualenv.
 
-6. Commit your changes and push your branch to GitHub::
+6. Commit your changes and push your branch to GitHub
 
     $ git add .
     $ git commit -m "Your detailed description of your changes."
@@ -100,13 +100,13 @@ Before you submit a pull request, check that it meets these guidelines:
 2. If the pull request adds functionality, the docs should be updated. Put
    your new functionality into a function with a docstring, and add the
    feature to the list in README.rst.
-3. The pull request should work for Python 2.6, 2.7, and 3.3, and for PyPy. Check 
+3. The pull request should work for Python 2.6, 2.7, and 3.3, and for PyPy. Check
    https://travis-ci.org/aaronbassett/DisposableEmailChecker/pull_requests
    and make sure that the tests pass for all supported Python versions.
 
 Tips
 ----
 
-To run a subset of tests::
+To run a subset of tests
 
     $ python -m unittest tests.test_disposable_email_checker

HISTORY.md

@@ -0,0 +1,11 @@
+History
+-------
+
+
+##### 1.0.0 (2015-10-13)
+
+* Complete rewrite and version 1 release!
+
+##### 1.2.1 (2015-11-04)
+
+* Added optional block-disposable-email.com API integration

README.md

@@ -2,29 +2,76 @@
 django-disposable-email-checker
 =============================
 
-.. image:: https://badge.fury.io/py/DisposableEmailChecker.png
-    :target: https://badge.fury.io/py/DisposableEmailChecker
+[![PyPI version](https://badge.fury.io/py/django-disposable-email-checker.png)](https://pypi.python.org/pypi/django-disposable-email-checker/)
+[![PyPI version](https://travis-ci.org/aaronbassett/DisposableEmailChecker.png?branch=master)](https://travis-ci.org/aaronbassett/DisposableEmailChecker)
+[![Requirements Status](https://requires.io/github/aaronbassett/DisposableEmailChecker/requirements.svg?branch=master)](https://requires.io/github/aaronbassett/DisposableEmailChecker/requirements/?branch=master)
 
-.. image:: https://travis-ci.org/aaronbassett/DisposableEmailChecker.png?branch=master
-    :target: https://travis-ci.org/aaronbassett/DisposableEmailChecker
+Django package to detect ~890 & ~8,600 domains used by disposable email services.
+You can validate any email against our internal list of ~890 domains used by
+disposable email services. Optionally you can also check each domain against
+the [Block-Disposable-Email.com](http://block-disposable-email.com) API. Check out
+their free tier for 200 API calls a month.
 
-Django package to detect ~890 domains used by disposable email services
+Setup
+-----
 
-Documentation
--------------
+Install the disposable email checker from PyPI
 
-The full documentation is at https://DisposableEmailChecker.readthedocs.org.
+    pip install django-disposable-email-checker
 
-Quickstart
-----------
+The disposable email checker comes with a list of ~890 emails. If you would like
+to provide your own email list create a function which returns a list of domains
+to block.
 
-First install the package from pypi
+    from disposable_email_checker.emails import email_domain_loader
 
-    pip install django-disposable-email-checker
+    def custom_email_domain_loader():
+        # Anyone still using AOL will be too much of a customer service burden
+        return [
+            "aol.com",
+        ] + email_domain_loader()
+
+Then add the complete path including function name to your settings
+
+    DEC_LOADER = "my.package.custom_email_domain_loader"
+
+If you would like to use the [BDE](http://block-disposable-email.com)
+integration add your API key to your Django settings
+
+    BDEA_APIKEY = "abcnotarealkey123"
+
+optionally you can configure the BDE API timeout in seconds (default 5)
+
+    BDEA_TIMEOUT = 2
 
-then in your app's models file:
+Adding to your models
+---------------------
+
+Once you have completed setup add the `DisposableEmailField` to your models.
 
     from disposable_email_checker.fields import DisposableEmailField
 
     class MyModel(models.Model):
         email = DisposableEmailField()
+
+The `DisposableEmailField` has a few optional arguments
+
+* **whitelist** - A list of emails which will always be allowed. Defaults
+to `[]`
+* **message** - The error message used by ValidationError if validation
+fails. Defaults to `_('Blocked email provider.')`
+* **code** - The error code used by ValidationError if validation fails.
+Defaults to "invalid".
+
+Using the validator
+-------------------
+
+If you want to use the validator by itself
+
+    from django.core.exceptions import ValidationError
+    from disposable_email_checker.validators import validate_disposable_email
+
+    try:
+        validate_disposable_email(email)
+    except ValidationError:
+        pass

setup.py

@@ -24,14 +24,13 @@
     os.system("git push --tags")
     sys.exit()
 
-readme = open('README.rst').read()
-history = open('HISTORY.rst').read().replace('.. :changelog:', '')
+readme = open('README.md').read()
 
 setup(
     name='django-disposable-email-checker',
     version=version,
     description="""Django package to detect ~890 domains used by disposable email services""",
-    long_description=readme + '\n\n' + history,
+    long_description=readme,
     author='Aaron Bassett',
     author_email='[email protected]',
     url='https://github.com/aaronbassett/DisposableEmailChecker',