libbe.util.id
¶
Handle ID creation and parsing.
Format¶
BE IDs are formatted:
<bug-directory>[/<bug>[/<comment>]]
where each <..>
is a UUID. For example:
bea86499-824e-4e77-b085-2d581fa9ccab/3438b72c-6244-4f1d-8722-8c8d41484e35
refers to bug 3438b72c-6244-4f1d-8722-8c8d41484e35
which is
located in bug directory bea86499-824e-4e77-b085-2d581fa9ccab
.
This is a bit of a mouthful, so you can truncate each UUID so long as
it remains unique. For example:
bea/343
If there were two bugs 3438...
and 343a...
in bea
, you’d
have to use:
bea/3438
BE will only truncate each UUID down to three characters to slightly future-proof the short user ids. However, if you want to save keystrokes and you know there is only one bug directory, feel free to truncate all the way to zero characters:
/3438
Cross references¶
To refer to other bug-directories/bugs/comments from bug comments, simply
enclose the ID in pound signs (#
). BE will automatically expand the
truncations to the full UUIDs before storing the comment, and the reference
will be appropriately truncated (and hyperlinked, if possible) when the
comment is displayed.
Scope¶
Although bug and comment IDs always appear in compound references,
UUIDs at each level are globally unique. For example, comment
bea/343/ba96f1c0-ba48-4df8-aaf0-4e3a3144fc46
will only appear
under bea/343
. The prefix (bea/343
) allows BE to reduce
caching global comment-lookup tables and enables easy error messages
(“I couldn’t find bea/343/ba9
because I don’t know where the
bea
bug directory is located”).
-
libbe.util.id.
HIERARCHY
= ['bugdir', 'bug', 'comment']¶ Keep track of the object type hierarchy.
-
class
libbe.util.id.
ID
(object, type)¶ Store an object ID and produce various representations.
Parameters: object :
BugDir
orBug
orComment
The object that the ID applies to.
type : ‘bugdir’ or ‘bug’ or ‘comment’
The type of the object.
See also
parse_user
- get uuids back out of the user ids.
short_to_long_user
- convert a single short user id to a long user id.
long_to_short_user
- convert a single long user id to a short user id.
short_to_long_text
- scan text for user ids & convert to long user ids.
long_to_short_text
- scan text for long user ids & convert to short user ids.
Notes
IDs have several formats specialized for different uses.
In storage, all objects are represented by their uuid alone, because that is the simplest globally unique identifier. You can generate ids of this sort with the .storage() method. Because an object’s storage may be distributed across several chunks, and the chunks may not have their own uuid, we generate chunk ids by prepending the objects uuid to the chunk name. The user id types do not support this chunk extension feature.
For users, the full uuids are a bit overwhelming, so we truncate them while retaining local uniqueness (with regards to the other objects currently in storage). We also prepend truncated parent ids for two reasons:
So that a user can locate the repository containing the referenced object. It would be hard to find bug
XYZ
if that’s all you knew. Much easier withABC/XYZ
, whereABC
is the bugdir. Each project can publish a list of bugdir-id-to-location mappings, e.g.:ABC...(full uuid)...DEF https://server.com/projectX/be/
which is easier than publishing all-object-ids-to-location mappings.
Because it’s easier to generate and parse truncated ids if you don’t have to fetch all the ids in the storage repository but can restrict yourself to a specific branch.
You can generate ids of this sort with the
user()
method, although in order to preform the truncation, your object (and its parents must define a sibling_uuids method.While users can use the convenient short user ids in the short term, the truncation will inevitably lead to name collision. To avoid that, we provide a non-truncated form of the short user ids via the
long_user()
method. These long user ids should be converted to short user ids by intelligent user interfaces.Methods
long_user
()storage
(*args)user
()-
long_user
()¶
-
storage
(*args)¶
-
user
()¶
-
class
libbe.util.id.
IDreplacer
(bugdirs, replace_fn, wrap=True, strict=True)¶ Helper class for ID replacement in text.
Reassembles the match elements from
REGEXP
matching into the original ID, for easier replacement.See also
Methods
__call__
(match)
-
exception
libbe.util.id.
InvalidIDStructure
(id, msg=None)¶ A purported ID does not have the appropriate syntax.
Parameters: id : str
The purported ID.
msg : str, optional
A helpful message explaining what went wrong.
-
exception
libbe.util.id.
MultipleIDMatches
(id, common, matches)¶ Multiple IDs match the given user ID.
Parameters: id : str
The not-specific-enough truncated UUID.
common : str
The initial characters common to all matching UUIDs.
matches : list of str
The list of possibly matching UUIDs.
-
exception
libbe.util.id.
NoIDMatches
(id, possible_ids, msg=None)¶ No IDs match the given user ID.
Parameters: id : str
The not-matching, possibly truncated UUID.
possible_ids : list of str
The list of potential UUIDs at that level.
msg : str, optional
A helpful message explaining what went wrong.
-
libbe.util.id.
REGEXP
= '#([-a-f0-9]*)(/[-a-g0-9]*)?(/[-a-g0-9]*)?#'¶ Regular expression for matching IDs (both short and long) in text.
-
libbe.util.id.
child_uuids
(child_storage_ids)¶ Extract uuid children from other children generated by
ID.storage()
.This is useful for separating data belonging to a particular object directly from entries for its child objects. Since the
Storage
backend doesn’t distinguish between the two.Examples
>>> list(child_uuids(['abc123/values', '123abc', '123def'])) ['123abc', '123def']
-
libbe.util.id.
long_to_short_text
(bugdirs, text)¶ Convert long user IDs to short user IDs in text (see
ID
). The list of bugdirs allows uniqueness-maintaining truncation of the bugdir portion of the ID.See also
long_to_short_user
- conversion on a single ID
short_to_long_text
- inverse
-
libbe.util.id.
long_to_short_user
(bugdirs, id)¶ Convert a long user ID to a short user ID (see
ID
). The list of bugdirs allows uniqueness-maintaining truncation of the bugdir portion of the ID.See also
short_to_long_user
- inverse
long_to_short_text
- conversion on a block of text
-
libbe.util.id.
parse_user
(bugdirs, id)¶ Parse a user ID (see
ID
), returning a dict of parsed information.The returned dict will contain a value for “type” (from
HIERARCHY
) and values for the levels that are defined.Notes
This function tries to expand IDs before parsing, so it can handle both short and long IDs successfully.
-
libbe.util.id.
residual
(base, fragment)¶ Split the short ID fragment into a portion corresponding to base, and a portion inside base.
Examples
>>> residual('ABC/DEF/', '//GHI') ('//', 'GHI') >>> residual('ABC/DEF/', '/D/GHI') ('/D/', 'GHI') >>> residual('ABC/DEF', 'A/D/GHI') ('A/D/', 'GHI') >>> residual('ABC/DEF', 'A/D/GHI/JKL') ('A/D/', 'GHI/JKL')
-
libbe.util.id.
short_to_long_text
(bugdirs, text)¶ Convert short user IDs to long user IDs in text (see
ID
). The list of bugdirs allows uniqueness-checking during expansion of the bugdir portion of the ID.See also
short_to_long_user
- conversion on a single ID
long_to_short_text
- inverse
-
libbe.util.id.
short_to_long_user
(bugdirs, id)¶ Convert a short user ID to a long user ID (see
ID
). The list of bugdirs allows uniqueness-checking during expansion of the bugdir portion of the ID.See also
long_to_short_user
- inverse
short_to_long_text
- conversion on a block of text
-
libbe.util.id.
uuid_gen
()¶