Merge branch 'refs/heads/master' into docs

Conflicts:
	README.md

CONTRIBUTE.md

@@ -0,0 +1,52 @@
+# How to contribute
+
+We love pull requests. Here's a quick guide:
+
+## Getting Started
+
+* Make sure you have a [GitHub account](https://github.com/signup/free)
+* Submit a ticket for your issue, assuming one does not already exist.
+  * Clearly describe the issue including steps to reproduce when it is a bug.
+  * Make sure you fill in the earliest version that you know has the issue.
+* Fork the repository on GitHub
+
+## Making Changes
+
+* Create a topic branch from where you want to base your work.
+  * This is usually the master branch.
+  * Only target release branches if you are certain your fix must be on that
+    branch.
+  * To quickly create a topic branch based on master; `git branch
+    fix/master/my_contribution master` then checkout the new branch with `git
+    checkout fix/master/my_contribution`.  Please avoid working directly on the
+    `master` branch.
+* Make commits of logical units.
+* Check for unnecessary whitespace with `git diff --check` before committing.
+* Make sure your commit messages are in the proper format.
+
+````
+    Make the example in CONTRIBUTING imperative and concrete
+
+    Without this patch applied the example commit message in the CONTRIBUTING
+    document is not a concrete example.  This is a problem because the
+    contributor is left to imagine what the commit message should look like
+    based on a description rather than an example.  This patch fixes the
+    problem by making the example concrete and imperative.
+
+    The first line is a real life imperative statement with a ticket number
+    from our issue tracker.  The body describes the behavior without the patch,
+    why this is a problem, and how the patch fixes the problem when applied.
+````
+
+* Make sure you have added the necessary tests for your changes.
+* Run _all_ the tests to assure nothing else was accidentally broken.
+
+## Submitting Changes
+
+* Push your changes to a topic branch in your fork of the repository.
+* Submit a pull request to the repository.
+
+# Additional Resources
+
+* [General GitHub documentation](http://help.github.com/)
+* [GitHub pull request documentation](http://help.github.com/send-pull-requests/)

NEWS.txt

@@ -1,6 +1,12 @@
 News
 ====
 
+0.3.3
+---
+
+* Modified en_US person.py to ouput female and male names. Thanks Adrian Klaver.
+* Added SSN provider for en_US and en_CA. Thanks Scott (@milliquet).
+
 0.3.2
 ---
 

faker/__init__.py

@@ -1,41 +1,43 @@
 AVAILABLE_LOCALES = [
-    'en_US',
-    'it_IT',
-    'fr_FR',
-    'pt_BR',
+    'cs_CZ',
+    'de_DE',
+    'dk_DK',
     'el_GR',
     'en_CA',
     'en_GB',
-    'de_DE',
-    'ru_RU',
-    'cs_CZ',
-    'fi_FI',
-    'dk_DK',
-    'es_MX',
+    'en_US',
     'es_ES',
-    'pl_PL',
+    'es_MX',
+    'fa_IR',
+    'fi_FI',
+    'fr_FR',
+    'it_IT',
     'ko_KR',
-    'zh_CN'
+    'pl_PL',
+    'pt_BR',
+    'ru_RU',
+    'zh_CN',
 ]
 
 DEFAULT_LOCALE = AVAILABLE_LOCALES[0]
 
 DEFAULT_PROVIDERS = (
-    'lorem',
     'address',
-    'person',
-    'date_time',
+    'color',
     'company',
+    'credit_card',
+    'date_time',
+    'file',
     'internet',
+    'job',
+    'lorem',
     'misc',
+    'person',
+    'profile',
+    'python',
     'phone_number',
+    'ssn',
     'user_agent',
-    'file',
-    'python',
-    'credit_card',
-    'profile',
-    'job',
-    'color',
 )
 
 from faker.generator import Generator

faker/providers/en_CA/ssn.py

@@ -0,0 +1,38 @@
+# coding=utf-8
+from __future__ import unicode_literals
+from ..ssn import Provider as SsnProvider
+import random
+
+class Provider(SsnProvider):
+
+    #in order to create a valid SIN we need to provide a number that passes a simple modified Luhn Algorithmn checksum
+    #this function essentially reverses the checksum steps to create a random valid SIN (Social Insurance Number)    
+    @classmethod
+    def ssn(cls):
+
+        #create an array of 8 elements initialized randomly
+        digits = random.sample(range(10), 8)
+
+        # All of the digits must sum to a multiple of 10.  
+        # sum the first 8 and set 9th to the value to get to a multiple of 10
+        digits.append(10 - (sum(digits) % 10))
+
+        #digits is now the digital root of the number we want multiplied by the magic number 121 212 121
+        #reverse the multiplication which occurred on every other element
+        for i in range(1, len(digits), 2):
+            if digits[i] % 2 == 0:
+                digits[i] = (digits[i] / 2) 
+            else:  
+                digits[i] = (digits[i] + 9) / 2 
+
+        #build the resulting SIN string
+        sin = "" 
+        for i in range(0, len(digits), 1):
+            sin += str(digits[i])
+            #add a space to make it conform to normal standards in Canada
+            if i % 3 == 2: 
+                sin += " "
+
+        #finally return our random but valid SIN 
+        return sin
+