This instance was upgraded to Heptapod 0.20.1 today

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

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

18
* See the `changelog <https://passlib.readthedocs.io/en/stable/history>`_
Eli Collins's avatar
Eli Collins committed
19
  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
* Visit `PyPI <https://pypi.python.org/pypi/passlib>`_
  for the latest stable release.
  All releases are signed with the gpg key
24
  `4D8592DF4CE1ED31 <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
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...
37
    >>> hash = pwd_context.hash("somepass")
Eli Collins's avatar
Eli Collins committed
38 39 40 41 42 43 44 45 46 47 48
    >>> 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
53 54
* Documentation - https://passlib.readthedocs.io
* Mailing list - https://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.