Metadata-Version: 1.1
Name: password_strength
Version: 0.0.2-0
Summary:  Password strength and validation 
Home-page: https://github.com/kolypto/py-password-strength
Author: Mark Vartanyan
Author-email: kolypto@gmail.com
License: BSD
Description: |Build Status|
        
        Password Strength
        =================
        
        Password strength and validation.
        
        PasswordPolicy
        ==============
        
        Perform tests on a password.
        
        Init Policy
        -----------
        
        .. code:: python
        
            PasswordPolicy(*tests)
        
        Init password policy with a list of tests
        
        Alternatively:
        
        .. code:: python
        
            PasswordPolicy.from_names(**tests)
        
        Init password policy from a dictionary of test definitions.
        
        A test definition is simply:
        
        ::
        
            { test-name: argument } or { test-name: [arguments] }
        
        Test name is just a lowercased class name.
        
        Example:
        
        ::
        
            PasswordPolicy.from_names(
                length=8,
                strength=(0.33, 30),
            )
        
        Bundled Tests
        -------------
        
        These objects perform individual tests on a password, and report
        ``True`` of ``False``.
        
        tests.Strength(strength, weak\_bits=30)
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        
        Test whether the password has >= ``strength`` strength.
        
        A password is evaluated to the strength of 0.333 when it has
        ``weak_bits`` entropy bits, which is considered to be a weak password.
        Strong passwords start at 0.666.
        
        tests.Special(count)
        ^^^^^^^^^^^^^^^^^^^^
        
        Test whether the password has >= ``count`` special characters
        
        tests.Uppercase(count)
        ^^^^^^^^^^^^^^^^^^^^^^
        
        Test whether the password has >= ``count`` uppercase characters
        
        tests.EntropyBits(bits)
        ^^^^^^^^^^^^^^^^^^^^^^^
        
        Test whether the password has >= ``bits`` entropy bits
        
        tests.Length(length)
        ^^^^^^^^^^^^^^^^^^^^
        
        Tests whether password length >= ``length``
        
        tests.Numbers(count)
        ^^^^^^^^^^^^^^^^^^^^
        
        Test whether the password has >= ``count`` numeric characters
        
        tests.NonLetters(count)
        ^^^^^^^^^^^^^^^^^^^^^^^
        
        Test whether the password has >= ``count`` non-letter characters
        
        tests.NonLettersLc(count)
        ^^^^^^^^^^^^^^^^^^^^^^^^^
        
        Test whether the password has >= ``count`` non-lowercase characters
        
        Testing
        -------
        
        After the ``PasswordPolicy`` is initialized, there are two methods to
        test:
        
        PasswordPolicy.password
        ~~~~~~~~~~~~~~~~~~~~~~~
        
        .. code:: python
        
            password(password)
        
        Get password stats bound to the tests declared in this policy.
        
        If in addition to tests you need to get statistics (e.g. strength) --
        use this object to double calculations.
        
        See ```PasswordStats`` <#passwordstats>`__ for more details.
        
        PasswordPolicy.test
        ~~~~~~~~~~~~~~~~~~~
        
        .. code:: python
        
            test(password)
        
        Perform tests on a password.
        
        Shortcut for: ``PasswordPolicy.password(password).test()``.
        
        Custom Tests
        ------------
        
        ATest is a base class for password tests.
        
        To create a custom test, just subclass it and implement the following
        methods:
        
        -  **init**\ () that takes configuration arguments
        -  test(ps) that tests a password, where ``ps`` is a ``PasswordStats``
           object.
        
        PasswordStats
        -------------
        
        PasswordStats allows to calculate statistics on a password.
        
        It considers a password as a unicode string, and all statistics are
        unicode-based.
        
        Constructor:
        
        .. code:: python
        
            from password_strength import PasswordStats
            PasswordStats(password)
        
        PasswordStats.alphabet\_cardinality
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        
        Get alphabet cardinality: alphabet length
        
        PasswordStats.count(\*categories) Count characters of the specified classes only
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        
        PasswordStats.entropy\_bits
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^
        
        Get information entropy bits: log2 of the number of possible passwords
        
        https://en.wikipedia.org/wiki/Password\_strength
        
        PasswordStats.strength(weak\_bits=30)
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        
        Get password strength as a number normalized to range {0 .. 1}.
        
        Normalization is done in the following fashion:
        
        1. If entropy\_bits <= weak\_bits -- linear in range{0.0 .. 0.33} (weak)
        2. If entropy\_bits <= weak\_bits\*2 -- almost linear in range{0.33 ..
           0.66} (medium)
        3. If entropy\_bits > weak\_bits\*3 -- asymptotic towards 1.0 (strong)
        
        PasswordStats.letters
        ^^^^^^^^^^^^^^^^^^^^^
        
        Count all letters
        
        PasswordStats.sequences\_length
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        
        Detect and return the length of used sequences:
        
        -  Alphabet letters: abcd...
        -  Keyboard letters: qwerty, etc
        -  Keyboard special characters in the top row: ~!@#$%^&\*()\_+
        -  Numbers: 0123456
        
        PasswordStats.letters\_uppercase
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        
        Count uppercase letters
        
        PasswordStats.alphabet
        ^^^^^^^^^^^^^^^^^^^^^^
        
        Get alphabet: set of used characters
        
        PasswordStats.weakness\_factor
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        
        Get weakness factor as a float in range {0 .. 1}
        
        This detects the portion of the string that contains: \* repeated
        patterns \* sequences
        
        E.g. a value of 1.0 means the whole string is weak, and 0.5 means half
        of the string is weak.
        
        Typical usage:
        
        password\_strength = (1 - weakness\_factor) \* strength
        
        PasswordStats.char\_categories
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        
        Character count per top-level category
        
        The following top-level categories are defined:
        
        -  L: letter
        -  M: Mark
        -  N: Number
        -  P: Punctuation
        -  S: Symbol
        -  Z: Separator
        -  C: Other
        
        PasswordStats.length
        ^^^^^^^^^^^^^^^^^^^^
        
        Get password length
        
        PasswordStats.repeated\_patterns\_length
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        
        Detect and return the length of repeated patterns.
        
        You will probably be comparing it with the length of the password itself
        and ban if it's longer than 10%
        
        PasswordStats.letters\_lowercase
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        
        Count lowercase letters
        
        PasswordStats.combinations
        ^^^^^^^^^^^^^^^^^^^^^^^^^^
        
        The number of possible combinations with the current alphabet
        
        PasswordStats.special\_characters
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        
        Count special characters
        
        Special characters is everything that's not a letter or a number
        
        PasswordStats.numbers
        ^^^^^^^^^^^^^^^^^^^^^
        
        Count numbers
        
        PasswordStats.count\_except(\*categories) Count characters of all classes except the specified ones
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        
        PasswordStats.test(tests)
        ^^^^^^^^^^^^^^^^^^^^^^^^^
        
        Test the password against a list of tests
        
        PasswordStats.entropy\_density
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        
        Get information entropy density factor, ranged {0 .. 1}.
        
        This is ratio of entropy\_bits() to max bits a password of this length
        could have. E.g. if all characters are unique -- then it's 1.0. If half
        of the characters are reused once -- then it's 0.5.
        
        PasswordStats.char\_categories\_detailed
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        
        Character count per unicode category, detailed format.
        
        See: http://www.unicode.org/reports/tr44/#GC\_Values\_Table
        
        .. |Build Status| image:: https://api.travis-ci.org/kolypto/py-password-strength.png?branch=master
           :target: https://travis-ci.org/kolypto/py-password-strength
        
Keywords: password,strength,policy,security
Platform: any
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 2
Classifier: Topic :: Software Development :: Libraries :: Python Modules
