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.