mxUID - Unique Identifiers for Python
1. Introduction
This package provides a fast mechanism for generating unique identification strings (UIDs). The intent is to make these UIDs unique with high probability in order to serve as object or data set identifiers.
A typical use lies in generating object and session IDs. Other areas where unique IDs play an important role are RPC-implementations, ORBs, etc.
In order to improve interoperability with typical applications already using string to manage such ids, the UID extension does not introduce a new type, but instead uses standard Python strings to store the UIDs.
2. mx.UID.UID String
To simplify and speed up handling UIDs the package provides a fast constructor for building universal ID strings (UIDs). These strings are normal Python strings using a special predefined format.
The information encoded in the UID includes a timestamp, the process ID, a host ID, an optional ID code (up to 100 characters) and a CRC value to assure the integrity of the UID. This makes the UIDs unique with a high probability.
UID strings have a length of (32 + len(code)) bytes. If no code is used, their length will always be 32 bytes.
Since UID strings are really only Python strings, they behave in the same way, i.e. offer the same methods.
2.1 mx.UID.UID String Constructors
These constructors are available in the package:
UID(object=None, code='', timestamp=None)
Create a new UID string for object.
code is optionally included in the UID. In order to hide it using the mangle()helper, the code string should only contain lowercase HEX characters (0-9, a-f). Non-HEX parts will not be mangled.
timestamp must be a ticks float (or an mx.DateTime.DateTime instance) and defaults to the current time.
3. mx.UID Functions
These functions are available.
verify(uid, code='')
Verifies the validity of the given uid.
uid may be a string or object that has a .__str__()method. If code is given, the id must have been created using that code.
timestamp(uid)
Returns the timestamp encoded in the UID string uid as mx.DateTime.DateTime instance.
mangle(uid, key)
Mangle the UID string uid using the given key string.
The output has the same length as the input UID string and should make it hard to forge valid UIDs without knowledge of the key string.
Note that the output string is not a valid UID string in itself, i.e. it most likely won't verify().
demangle(euid, key)
Demangle a mangle()d UID string euid using the given key string.
4. mx.UID Constants
Error
Error class used for package specific errors. It is a subclass of StandardError.
5. Examples of Use
Here is a very simple one:
from mx.UID import *
>>> uid = UID()
>>> print uid
003bb9f7e7080c6d0c0001400601693a4c
>>> verify(uid)
1
>>> verify(uid + '123')
0
>>> timestamp(uid)
<DateTime object for '2001-10-02 19:22:47.00' at 81cc330>
More examples will eventually appear in the Examples subdirectory of the package.
6. Package Structure
[UID]
Doc/
[mxUID]
UID.py
Entries enclosed in brackets are packages (i.e. they are directories that include a __init__.py file). Ones without brackets are just simple subdirectories that are not accessible via import.
The package imports all symbols from the extension module, so you only need to 'from mx import UID' to start working.
7. Support
eGenix.com is providing commercial support for this package. If you are interested in receiving information about this service please see the eGenix.com Support Conditions.
8. Copyright & License
© 2001-2011, Copyright by eGenix.com Software GmbH, Langenfeld, Germany; All Rights Reserved. mailto: info@egenix.com
This software is covered by the eGenix.com Public License Agreement, which is included in the following section. The text of the license is also included as file "LICENSE" in the package's main directory.
By downloading, copying, installing or otherwise using the software, you agree to be bound by the terms and conditions of the following eGenix.com Public License Agreement.
EGENIX.COM PUBLIC LICENSE AGREEMENT
Version 1.1.0
This license agreement is based on the Python CNRI License Agreement, a widely accepted open-source license.
1. Introduction
This "License Agreement" is between eGenix.com Software, Skills and Services GmbH ("eGenix.com"), having an office at Pastor-Loeh-Str. 48, D-40764 Langenfeld, Germany, and the Individual or Organization ("Licensee") accessing and otherwise using this software in source or binary form and its associated documentation ("the Software").
2. License
Subject to the terms and conditions of this eGenix.com Public License Agreement, eGenix.com hereby grants Licensee a non-exclusive, royalty-free, world-wide license to reproduce, analyze, test, perform and/or display publicly, prepare derivative works, distribute, and otherwise use the Software alone or in any derivative version, provided, however, that the eGenix.com Public License Agreement is retained in the Software, or in any derivative version of the Software prepared by Licensee.
3. NO WARRANTY
eGenix.com is making the Software available to Licensee on an "AS IS" basis. SUBJECT TO ANY STATUTORY WARRANTIES WHICH CAN NOT BE EXCLUDED, EGENIX.COM MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED. BY WAY OF EXAMPLE, BUT NOT LIMITATION, EGENIX.COM MAKES NO AND DISCLAIMS ANY REPRESENTATION OR WARRANTY OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF THE SOFTWARE WILL NOT INFRINGE ANY THIRD PARTY RIGHTS.
4. LIMITATION OF LIABILITY
EGENIX.COM SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF THE SOFTWARE FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS (INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF BUSINESS INFORMATION, OR OTHER PECUNIARY LOSS) AS A RESULT OF USING, MODIFYING OR DISTRIBUTING THE SOFTWARE, OR ANY DERIVATIVE THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF.
SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION OR LIMITATION OF INCIDENTAL OR CONSEQUENTIAL DAMAGES, SO THE ABOVE EXCLUSION OR LIMITATION MAY NOT APPLY TO LICENSEE.
5. Termination
This License Agreement will automatically terminate upon a material breach of its terms and conditions.
6. Third Party Rights
Any software or documentation in source or binary form provided along with the Software that is associated with a separate license agreement is licensed to Licensee under the terms of that license agreement. This License Agreement does not apply to those portions of the Software. Copies of the third party licenses are included in the Software Distribution.
7. General
Nothing in this License Agreement affects any statutory rights of consumers that cannot be waived or limited by contract.
Nothing in this License Agreement shall be deemed to create any relationship of agency, partnership, or joint venture between eGenix.com and Licensee.
If any provision of this License Agreement shall be unlawful, void, or for any reason unenforceable, such provision shall be modified to the extent necessary to render it enforceable without losing its intent, or, if no such modification is possible, be severed from this License Agreement and shall not affect the validity and enforceability of the remaining provisions of this License Agreement.
This License Agreement shall be governed by and interpreted in all respects by the law of Germany, excluding conflict of law provisions. It shall not be governed by the United Nations Convention on Contracts for International Sale of Goods.
This License Agreement does not grant permission to use eGenix.com trademarks or trade names in a trademark sense to endorse or promote products or services of Licensee, or any third party.
The controlling language of this License Agreement is English. If Licensee has received a translation into another language, it has been provided for Licensee's convenience only.
8. Agreement
By downloading, copying, installing or otherwise using the Software, Licensee agrees to be bound by the terms and conditions of this License Agreement.
For question regarding this License Agreement, please write to:
eGenix.com Software, Skills and Services GmbH
Pastor-Loeh-Str. 48
D-40764 Langenfeld
Germany