Python - Our key to Efficiency

eGenix.com · Website 2002 · Python · mxUID - An UID datatype

mxUID - An UID datatype

Interface ( Functions : Objects : Constants ) : Examples : Structure : Support : Download : Copyright & License : History : Home

Version 0.1.0

Introduction

XXX Note: The documentation is still far from complete !!!

This package provides a fast mechanism for generating universal 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 session IDs. Other areas where unique IDs play an important role are RPC-implementations, ORBs, etc.

Interface

The mxUID package defines the following interfaces.

Functions

These functions are available.

verify(uid, code='')

Verifies the given uid for validity.

uid may be a string or an ID instance. 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 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.

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.

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 DateTime instance) and defaults to the current time.

Constants

Error: Error class used for package specific errors. It is a subclass of exceptions.StandardError.

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.

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.

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.

What I'd like to hear from you...

Comments, ideas, bug-fixes :-)

Copyright & License

This software is covered by the eGenix.com Public License Agreement. 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 eGenix.com Public License Agreement.

History & Future

Things that still need to be done:

Provide some examples.
Add more documentation.

Changes from 0.1.0 to 0.2.0:

Moved verify() into the C extension.
Added (undocumented, internal) otp() API which allows applying a one-time stamp to a UID string for encryption. The function is idempotent (applying it a second time will reverse the mapping) making it ideal for encryption/decryption.
Added helper APIs mangle() and demangle() which encode the UID strings in a way which should make it very hard to construct valid UIDs without knowledge of the key string provided that only mangled UID strings are made public. The APIs also add noise to the UID strings to cover the internal structure (this doesn't make them more secure to analysis, though).
Changed the UID layout to enhance performance, esp. when using the UIDs as index strings in databases (they no longer start with the timestamp, which caused UIDs to typically differ starting at the 9th string position). The UID length also has gone down to the more computer friendly 32 byte format.
Reduced the maximum code length.
Fixed a portability bug. The mxUID_GetCurrentTime() API (taken from mxDateTime) needs some extra include files on a few platforms. Thanks to Dirk Holtwick for finding this one -- it was a simple copy&paste bug.

Version 0.1.0 was the intial release.

Contact : Impressum : Terms & Conditions : Privacy Policy : Trademarks 2024-11-21