Summary

    Configurable unique ID generation.


Overview

    Provided is an implementation of a "unique" ID (UID) generator in
    Python.  The implementation does not follow UUID or GUID
    standards, but rather uses available system, host, user, shell
    environment, process, and other ephemeral information fed into a
    hasher (by default MD5) to generate the UID.

    The system is designed to be used both as a standalone application
    and as a module.  The data used to be fed into the hash, as well
    as the hashing mechanism itself, can be overridden both through
    the command line and programmatically by importing the module.


Getting the software

    The current version of uid is 1.0.2.

    The latest version of the software is available in a tarball here:
    "http://www.alcyone.com/software/uid/uid-latest.tar.gz",
    http://www.alcyone.com/software/uid/uid-latest.tar.gz.

    The official URL for this Web site is
    "http://www.alcyone.com/software/uid/",
    http://www.alcyone.com/software/uid/.


Requirements

    uid.py is intended to be used under UNIX and UNIX-like systems in
    Python 2.x.


License

    This code is released under the "GPL",
    http://www.gnu.org/copyleft/gpl.html.


Introduction

    The module works by implementing a 'UIDGenerator' which uses
    available information to generate a hash object, and is invoked
    with its 'generator' method; the generator returns the hash object
    itself.  To create this hash factory, which can either be derived
    from 'HashGenerator' or simply one of the available modules that
    follows the hasher pattern, such as the standard 'md5' or 'sha'
    modules.  By default, the 'md5' module is used.


Sample usage

    To generate and print one UID::

        ./uid.py

    To see the input that goes into the hash, you can run it in
    verbose mode::

        ./uid.py -v

    To specify an alternate hashing mechanism (in this case SHA), you
    can specify another module to use::

        ./uid.py -H sha

    To feed in additional (hopefully uniquifying) information, use the
    '-x' option::

        ./uid.py -x "This is more incidental information"

    Finally, one can generate multiple UIDs in one run with the '-n'
    option::

        ./uid.py -n 10
    
    These options, of course, can be intermixed.


Invocation

    The following command line options alter the behavior of the
    program as follows:

    The '-V/--version' option will print the version of the program
    and exit; '-h/--help' will print some usage and then exit.

    The '-v/--verbose' option will in effect use an identity hashing
    function, and will show the environmental information that goes
    into creating the hash.

    A new hasher can be chosen with the '-H/--hasher' option; this
    must be a module which implements a standard hasher interface.
    Examples are 'md5' (the default), or 'sha'.  The module is
    imported through '__import__' so any available custom module can
    be provided here, provided it behaves the same way that 'md5' or
    'sha' do.

    To generate multiple UIDs in one run, use the '-n/--number'
    option.

    Finally, to provide additional incidental information, use the
    '-x/--extra' option.


Wish list

    A set of options to choose between the different update groups
    would be great; this would allow people to use uid to merely
    generate host IDs, user IDs, etc.


References

    - The hasher API is described in comments, as well as in the
      standard Python library entries for 'md5' or 'sha'.


Release history

    - 1.0.2; 2004 May 19.  Change -p to -x.

    - 1.0.1; 2003 Jan 25.  Swap -v (verbose) and -V (version
      information) options; fix -p option.

    - 1.0; 2002 Aug 14.  Initial release.


Author

    This module was written by "Erik Max Francis",
    http://www.alcyone.com/max/.  If you use this software, have
    suggestions for future releases, or bug reports, "I'd love to hear
    about it", mailto:software@alcyone.com.


Version

    Version 1.0.2 $Date: 2004/05/19 $ $Author: max $
