README

   1 ion README
   2 ------
   3
   4 WHAT IS IT:
   5   a collection of generally useful routines
   6   (and experimental algorithms :)
   7
   8 INCLUDING:
   9   * general maths (most functions support both scalars and list/array-likes)
  10   ** factorials
  11   ** fast sum of series 1,2,3,4,5 ... N
  12   ** number of sequences of N size taken from a set of K size
  13   ** number of places a sequence of length N can be subdivided
  14   ** round N to nearest power of B
  15   ** convert a power of B, N, to an exponent of B, such that B**E == N
  16   ** find common denominator
  17   ** find all integers that divide evenly into N
  18   ** linear/spline interpolation of a 1d series of values
  19   ** binary representation of a number
  20   * spatial maths
  21   ** subclassable Grid type
  22   ** grid snapping and 'is-in-cell'
  23   ** polar/cartesian transform
  24   ** polar distance
  25   ** calculate triple of weights based on position in triangle
  26   * randomization
  27   ** return true P% of the time
  28   ** weighted sampling from a set of items
  29   ** fill weighted boxes in a roughly even way
  30   ** randomly dispense contents of a box
  31   ** convert nested percentage weights to flat 0..1 weights
  32   ** dice roll (single, and iterative/infinite)
  33   ** chain iterator, which yields values while percentage chance of success
  34      rolls succeed, and stops as soon as they fail.
  35      Like OHRRPGCE 'chain attack/ chain %' option
  36   * misc
  37   ** find numeric limits of data types (builtin types or simple numpy types)
  38   ** sort sequence according to template
  39   ** reverse of zip (flat sequence a,b,c,a,b,c,a,b,c -> a,b,c tuples)
  40   ** easily read every line or every byte of a file
  41   ** calculate minimum number of bits required to store a given integer.
  42   ** quickly set multiple attributes on an object
  43   ** Metadata class for easy management of metadata,
  44      with yaml serialization support.
  45
  46 REQUIREMENTS:
  47
  48 just Python 2.5, as far as I know.
  49
  50 pyYAML is required if you want to de/serialize metadata from/to YAML.
  51
  52 having NumPy installed will make certain parts of the API more
  53 flexible and much faster, though. (eg. sum of series 1,2,3,4,5...N can be
  54 calculated using a single polynomial evaluation)
  55
  56 Matplotlib might be eventually required for generating function plots
  57 in docs.
  58 it will not be required for just using ion.
  59
  60
  61
  62 CONTRIBUTIONS:
  63
  64 are welcomed, of course. These are some areas that particularly need work:
  65  * more comprehensive unit testing
  66  * better docstrings
  67    (use http://www.scipy.org/scipy/numpy/wiki/CodingStyleGuidelines as a guide)
  68  * better sphinx docs (currently I mostly use autodoc directive, and the docs need
  69    better organization too)
  70  * better PEP 8 conformance (partial) -- what I'm aiming for is
  71    similar, just requires a space between function names and
  72    (parameter, lists). see ion/__init__.py for a good example.
  73  * running 'cheesecake_index --with-pep8 -p <sdist-output-package-file>' helps to
  74    get a metric of most of the above.
  75    currently (0.02, first release) it gives 71% kwalitee.
  76    when the above points are well addressed, I anticipate the
  77    kwalitee index rising to ~93%
  78  * better PKG-INFO. Does 'provides' field need to be specified?
  79    of course, a downloadable package is good too.
  80
  81
  82 CONTACT:
  83
  84 please send patches, bug reports, feedback + co. to
  85 David Gowers <00ai99 AT gmail DOT com>
  86 (replacing ' AT ' with '@' and ' DOT ' with '.' )
  87
  88
  89
  90
  91
  92 NOTE:
  93 there are no capitals missing in this document.
  94 not capitalizing the first word in each sentence is a
  95 deliberate choice inspired by Lojban (www.lojban.org).