README.txt

   1 ===========================================\r
   2 pyprimes -- generate and test prime numbers\r
   3 ===========================================\r
   4 \r
   5 \r
   6 Introduction\r
   7 ------------\r
   8 \r
   9 Prime numbers are those positive integers which are not divisible exactly\r
  10 by any number other than itself or one. Generating primes and testing for\r
  11 primality has been a favourite mathematical pastime for centuries, as well\r
  12 as of great practical importance for encrypting data. The ``pyprimes``\r
  13 package provides functions for generating prime numbers on the fly and\r
  14 testing whether or not a given number is prime.\r
  15 \r
  16 Features include:\r
  17 \r
  18     - Produce prime numbers lazily, on demand.\r
  19     - Effective, fast algorithms including Sieve of Eratosthenes,\r
  20       Croft Spiral, and Wheel Factorisation.\r
  21     - Test whether numbers are prime efficiently.\r
  22     - Deterministic and probabilistic primality tests.\r
  23     - Examples of what *not* to do provided, including naive trial\r
  24       division, Turner's algorithm (Euler's sieve), and primality\r
  25       testing using a regular expression.\r
  26     - Factorise small numbers into the product of prime factors.\r
  27     - Suitable for Python 2.4 through 3.x from one code base.\r
  28 \r
  29 \r
  30 Installation\r
  31 ------------\r
  32 \r
  33 To install, extract the tarball into the current directory, then cd into the\r
  34 expanded directory. Run:\r
  35 \r
  36     python setup.py install\r
  37 \r
  38 from your system shell (not the python interpreter) to install.\r
  39 \r
  40 \r
  41 Licence\r
  42 -------\r
  43 \r
  44 pyprimes is licenced under the MIT Licence. See the LICENCE.txt file and the\r
  45 header of pyprimes/__init__.py.\r
  46 \r
  47 \r
  48 Test suite\r
  49 ----------\r
  50 \r
  51 pyprimes comes with an extensive test suite containing unit tests, doc tests\r
  52 and regression tests. To run the test suite, run the ``pyprimes/tests.py``\r
  53 module.\r
  54 \r
  55 For Python version 2.5 on up, the most convenient way to do this after\r
  56 installation is from your system shell:\r
  57 \r
  58     python -m pyprimes.test\r
  59 \r
  60 To get even more verbose output, pass the -v switch:\r
  61 \r
  62     python -m pyprimes.test -v\r
  63 \r
  64 The -m switch is not supported by Python 2.4, to run the test suite under\r
  65 that version you will have to give the path to the test module and run it\r
  66 manually. E.g. this may work on some systems:\r
  67 \r
  68     cd /usr/lib/python2.4\r
  69     python2.4 pyprimes/test.py\r
  70 \r
  71 \r
  72 Known Issues and Bugs\r
  73 ---------------------\r
  74 \r
  75 (1) The API of this package is not yet stable. That means that the names of\r
  76     functions, the arguments that they take, values returned, etc. may\r
  77     change without warning in the future.\r
  78 \r
  79 (2) With older versions of Python (2.4 - 2.6), doctests are not run when\r
  80     running the test suite. You can run them manually for each individual\r
  81     module, e.g.:\r
  82 \r
  83         python2.6 -m doctest pyprimes/factors.py -v\r
  84 \r
  85 (3) In general, prime-related functions expect their numeric arguments to\r
  86     be integers, but don't perform any type-checking. If you pass a float,\r
  87     Decimal, Fraction or other non-int (or long) value, behaviour is\r
  88     undefined.\r
  89 \r
  90 (4) The package is currently rather inconsistent in whether it uses\r
  91     floating point sqrt or integer-valued sqrt. This should be considered\r
  92     a known bug.\r
  93 \r