README.rst

   1 xkcdpass
   2 ========
   3
   4 A flexible and scriptable password generator which generates strong passphrases, inspired by `XKCD 936 <http://xkcd.com/936/>`_::
   5
   6     $ xkcdpass
   7     > correct horse battery staple
   8
   9 .. image:: http://imgs.xkcd.com/comics/password_strength.png
  10
  11
  12
  13 Install
  14 =======
  15
  16 ``xkcdpass`` can be easily installed using pip::
  17
  18     pip install xkcdpass
  19
  20 or manually::
  21
  22     python setup.py install
  23
  24
  25
  26 Source
  27 ~~~~~~
  28 The latest development version can be found on github: https://github.com/redacted/XKCD-password-generator
  29
  30 Contributions welcome and gratefully appreciated!
  31
  32
  33
  34 Requirements
  35 ============
  36
  37 Python 2.4+ (Python 3.x compatible)
  38
  39
  40
  41 Running ``xkcdpass``
  42 ====================
  43
  44 ``xkcdpass`` can be called with no arguments::
  45
  46     $ xkcdpass
  47     > pinball previous deprive militancy bereaved numeric
  48
  49 which returns a single password, using the default dictionary and default settings. Or you can mix whatever arguments you want::
  50
  51     $ xkcdpass --count=5 --acrostic='chaos' --delimiter='|' --min=5 --max=6 --valid_chars='[a-z]'
  52     > collar|highly|asset|ovoid|sultan
  53     > caper|hangup|addle|oboist|scroll
  54     > couple|honcho|abbot|obtain|simple
  55     > cutler|hotly|aortae|outset|stool
  56     > cradle|helot|axial|ordure|shale
  57
  58 which returns
  59
  60 * ``--count=5``   5 passwords to choose from
  61 * ``--acrostic='chaos'``   the first letters of which spell 'chaos'
  62 * ``--delimiter='|'``   joined using '|'
  63 * ``--min=5 --max=6``  with words between 5 and 6 characters long
  64 * ``--valid_chars='[a-z]'``   using only lower-case letters (via regex).
  65
  66
  67 A concise overview of the available ``xkcdpass`` options can be accessed via::
  68
  69     xkcdpass --help
  70
  71     Usage: xkcdpass [options]
  72
  73     Options:
  74         -h, --help
  75                                     show this help message and exit
  76         -w WORDFILE, --wordfile=WORDFILE
  77                                     List of valid words for password
  78         --min=MIN_LENGTH
  79                                     Minimum length of words to make password
  80         --max=MAX_LENGTH
  81                                     Maximum length of words to make password
  82         -n NUMWORDS, --numwords=NUMWORDS
  83                                     Number of words to make password
  84         -i, --interactive
  85                                     Interactively select a password
  86         -v VALID_CHARS, --valid_chars=VALID_CHARS
  87                                     Valid chars, using regexp style (e.g. '[a-z]')
  88         -V, --verbose
  89                                     Report various metrics for given options
  90         -a ACROSTIC, --acrostic=ACROSTIC
  91                                     Acrostic to constrain word choices
  92         -c COUNT, --count=COUNT
  93                                     number of passwords to generate
  94         -d DELIM, --delimiter=DELIM
  95                                     separator character between words
  96
  97
  98 A large wordlist is provided (courtesy of `12Dicts <http://wordlist.aspell.net/12dicts/>`_) for convenience, but the generator can be used with any word file of the correct format: a file containing one 'word' per line. The default word file can be found in ``xkcdpass/static/default.txt``.
  99
 100
 101
 102 Advanced Usage
 103 ==============
 104
 105 The built-in functionality of ``xkcdpass`` can be extended by importing the module into custom python scripts.
 106 An example of this usage is provided in `example_import.py <https://github.com/redacted/XKCD-password-generator/blob/master/xkcdpass/example_import.py>`_, which randomly capitalises the letters in a generated password.
 107
 108 A simple use of import::
 109
 110     import xkcdpass.xkcd_password as xp
 111
 112     ## create a wordlist from the default wordfile
 113     ## use words between 5 and 8 letters long
 114     wordfile = xp.locate_wordfile()
 115     mywords = xp.generate_wordlist(wordfile=wordfile, min_length=5, max_length=8)
 116
 117     ## create a password with the acrostic "face"
 118     print(xp.generate_xkcdpassword(mywords, acrostic="face"))
 119
 120
 121
 122 License
 123 =======
 124 This is free software: you may copy, modify, and/or distribute this work under the terms of the BSD 3-Clause license.
 125 See the file ``LICENSE.BSD`` for details.