README 2.56 KB
Newer Older
Eli Collins's avatar
Eli Collins committed
1 2
.. -*- restructuredtext -*-

Eli Collins's avatar
Eli Collins committed
3
==========================
4
The Passlib Python Library
Eli Collins's avatar
Eli Collins committed
5
==========================
Eli Collins's avatar
Eli Collins committed
6

Eli Collins's avatar
Eli Collins committed
7 8
Welcome
=======
9 10 11 12 13
Passlib is a password hashing library for Python 2 & 3, which provides
cross-platform implementations of over 30 password hashing algorithms, as well
as a framework for managing existing password hashes. It's designed to be useful
for a wide range of tasks, from verifying a hash found in /etc/shadow, to
providing full-strength password hashing for multi-user application.
Eli Collins's avatar
Eli Collins committed
14

Eli Collins's avatar
Eli Collins committed
15 16
* See the `documentation <http://packages.python.org/passlib>`_
  for details, installation instructions, and examples.
Eli Collins's avatar
Eli Collins committed
17

Eli Collins's avatar
Eli Collins committed
18 19
* See the `changelog <http://packages.python.org/passlib/history.html>`_
  for a description of what's new in Passlib.
Eli Collins's avatar
Eli Collins committed
20

Eli Collins's avatar
Eli Collins committed
21 22 23 24
* Visit `PyPI <https://pypi.python.org/pypi/passlib>`_
  for the latest stable release.
  All releases are signed with the gpg key
  `4CE1ED31 <http://pgp.mit.edu:11371/pks/lookup?op=get&search=0x4D8592DF4CE1ED31>`_.
Eli Collins's avatar
Eli Collins committed
25

Eli Collins's avatar
Eli Collins committed
26 27
* Additional questions about usage or features? Feel free to post on our
  `mailing list <http://groups.google.com/group/passlib-users>`_.
Eli Collins's avatar
Eli Collins committed
28

Eli Collins's avatar
Eli Collins committed
29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48
Usage
=====
A quick example of using passlib to integrate into a new application::

    >>> # import the context under an app-specific name (so it can easily be replaced later)
    >>> from passlib.apps import custom_app_context as pwd_context

    >>> # encrypting a password...
    >>> hash = pwd_context.encrypt("somepass")
    >>> hash
    '$6$rounds=36122$kzMjVFTjgSVuPoS.$zx2RoZ2TYRHoKn71Y60MFmyqNPxbNnTZdwYD8y2atgoRIp923WJSbcbQc6Af3osdW96MRfwb5Hk7FymOM6D7J1'

    >>> # verifying a password...
    >>> ok = pwd_context.verify("somepass", hash)
    True
    >>> ok = pwd_context.verify("letmein", hash)
    False

For more details and an extended set of examples, see the full documentation;
This example barely touches on the range of features available.
Eli Collins's avatar
Eli Collins committed
49 50 51

Online Resources
================
Eli Collins's avatar
Eli Collins committed
52
* Homepage -   https://bitbucket.org/ecollins/passlib
Eli Collins's avatar
Eli Collins committed
53 54
* Documentation - http://packages.python.org/passlib
* Mailing list - http://groups.google.com/group/passlib-users
Eli Collins's avatar
Eli Collins committed
55

Eli Collins's avatar
Eli Collins committed
56 57
* Downloads -  https://pypi.python.org/pypi/passlib
* Source -     https://bitbucket.org/ecollins/passlib/src
Eli Collins's avatar
Eli Collins committed
58 59 60 61 62 63 64 65
* Issues -     https://bitbucket.org/ecollins/passlib/issues

Source
=========
Passlib's source repository uses Mercurial.  When building Passlib from an hg clone, note that there are two main branches: ``default`` and ``stable``.

* ``default`` is the bleeding edge of the next major release. It may sometimes be of alpha quality. 
* ``stable`` is the latest released version plus any pending bugfixes, and should be safe to use in production.