API Reference

nti.ntiids.interfaces

Interfaces relating to NTIIDs.

interface nti.ntiids.interfaces.INTIID

Extends: zope.interface.common.builtins.ITuple, zope.interface.common.sequence.IMinimalSequence

Represents the parts of an NTIID that has been parsed.

In addition to the named fields, this object acts as a 4-tuple, (provider, type, specific, date).

Note that NTIID components are text (unicode), and ntiid strings are also unicode.

provider

The username of the creating/providing entity.

Implementation:zope.schema.TextLine Read Only:False Required:True Default Value:None Allowed Type:str

nttype

The type of the NTIID.

Implementation:zope.schema.TextLine Read Only:False Required:True Default Value:None Allowed Type:str

specific

The type-specific portion of the NTIID.

Implementation:zope.schema.TextLine Read Only:False Required:True Default Value:None Allowed Type:str

date

The date portion of the NTIID.

Implementation:zope.schema.TextLine Read Only:False Required:True Default Value:None Allowed Type:str

interface nti.ntiids.interfaces.INTIIDResolver

An object that can take an NTIID and produce the object to which it refers.

These should be registered as components named for the ntiid type (e.g, OID).

resolve(ntiid_string)

Returns:The object to which the ntiid_string refers, or None if it cannot be found.

nti.ntiids.ntiids

Constants and types for dealing with our unique IDs.

nti.ntiids.ntiids.ImpossibleToMakeProviderPartSafe

alias of nti.ntiids.ntiids.ImpossibleToMakeSpecificPartSafe

exception nti.ntiids.ntiids.ImpossibleToMakeSpecificPartSafe

Bases: nti.ntiids.ntiids.InvalidNTIIDError

The supplied value cannot be used safely.

exception nti.ntiids.ntiids.InvalidNTIIDError

Bases: zope.schema._bootstrapinterfaces.ValidationError

Raised if the NTIID value (or some part of it) is invalid.

class nti.ntiids.ntiids.NTIID(provider, nttype, specific, date)

Bases: tuple

Create new instance of NTIID(provider, nttype, specific, date)

date

Alias for field number 3

nttype

Alias for field number 1

provider

Alias for field number 0

specific

Alias for field number 2

nti.ntiids.ntiids.escape_provider(provider)

Makes a provider name safe for use in an NTIID by escaping characters not safe for a URL, such as _ and ‘ ‘. When comparing provider names with those that come from an NTIID, you should always call this function.

Returns:The escaped provider.

nti.ntiids.ntiids.find_object_with_ntiid(key, **kwargs)

Attempts to find an object with the given NTIID. No security is implied; traversal is not necessarily used.

Parameters:

• key (string) – The NTIID to find.
• kwargs (dict) – Keyword arguments; this is to assist translation from legacy APIs and they are not currently used. If you send any, warnings will issue a warning.

Returns:

The object found, or None if no object can be found or the ntiid passed is invalid.

nti.ntiids.ntiids.get_parts(ntiid)

Returns:An NTIID named four-tuple (provider, type, type-specific, date) if the ntiid could be parsed, or named four-tuple of None.

nti.ntiids.ntiids.get_provider(ntiid)

Returns:The string of the provider part of the ntiid if it could be parsed, else None.

nti.ntiids.ntiids.get_specific(ntiid)

Returns:The string of the type-specific part of the ntiid if it could be parsed, else None.

nti.ntiids.ntiids.get_type(ntiid)

Returns:The string of the type part of the ntiid if it could be parsed, else None.

nti.ntiids.ntiids.is_ntiid_of_type(ntiid, nttype)

Check if the given ntiid is valid and of the given type (ignoring subtypes).

Returns:A True value if the ntiid is valid and has a type portion equivalent to the given nttype (i.e., ignoring subtypes).

nti.ntiids.ntiids.is_ntiid_of_types(ntiid, nttypes)

Check if the given ntiid is valid and of one of the given types (ignoring subtypes).

Parameters:nttypes – A sequence of types to check; they should not have subtypes. Returns:A True value if the ntiid is valid and has a type portion equivalent to the given nttype (i.e., ignoring subtypes).

nti.ntiids.ntiids.make_ntiid(date='2011-10', provider=None, nttype=None, specific=None, base=None)

Create a new NTIID.

Parameters:

• date (number) – A value from time.time(). If missing (0 or None), today will be used. If a string, then that string should be a portion of an ISO format date, e.g., 2011-10.
• provider (str) – Optional provider name. We will sanitize it for our format.
• nttype (str) – Required NTIID type (if no base is given)
• specific (str) – Optional type-specific part.
• base (str) – If given, an NTIID string from which provider, nttype, specific, and date will be taken if they are not directly specified. If not a valid NTIID, will be ignored.

Returns:

A new NTIID string formatted as of the given date.

nti.ntiids.ntiids.make_provider_safe(provider)

Given a potential provider part, transform it so that it is valid as part of an NTIID string.

Caution

This is not a reversible transformation.

nti.ntiids.ntiids.make_specific_safe(specific, strict=True)

Given a potential specific part, transform it so that it is valid as part of an NTIID string. This includes removing disallowed characters, and limiting the range of characters to printable ASCII compatible characters.

Caution

This is not a reversible transformation.

Parameters:strict (bool) – If true (the default) then a maximally compatible set of characters will be substituted to make the safest part most likely to be parsed even by borderline parsers (such as those that are regex based). If set to false, however, only the minimal set of characters prohibited by the conforming parser implementation of this module will be replaced; typically only do this for backwards compatibility reasons. Raises:InvalidNTIIDError – If this cannot be done. In particular, we refuse to create a safe part that consists entirely of the replacement characters; at least one character originally supplied must be valid. We also refuse to create a zero-length safe part.

nti.ntiids.ntiids.maketrans()

Return a translation table usable for str.translate().

If there is only one argument, it must be a dictionary mapping Unicode ordinals (integers) or characters to Unicode ordinals, strings or None. Character keys will be then converted to ordinals. If there are two arguments, they must be strings of equal length, and in the resulting dictionary, each character in x will be mapped to the character at the same position in y. If there is a third argument, it must be a string, whose characters will be mapped to None in the result.

nti.ntiids.ntiids.validate_ntiid_string(ntiid, encoding='utf-8')

Ensures the string is a valid NTIID, else raises InvalidNTIIDError.

Returns:The ntiid, after validation and ensuring that it is text.

nti.ntiids.ntiids.ROOT = 'tag:nextthought.com,2011-10:Root'

When NTIIDs (usually of a particular type) are arranged into a tree, or a forest of trees, this NTIID specifies the conceptual root of the entire tree or forest.

nti.ntiids.ntiids.TAG_NTC = 'tag:nextthought.com'

prefix of NTIIDs

nti.ntiids.ntiids.TYPE_INTID = 'INTID'

The intid type is not currently used. Instead, intid is included as a part of the OID, preventing access using a stale URL after an object is deleted

nti.ntiids.ntiids.TYPE_MISSING = 'Missing'

Used as an opaque identifier to refer to an object that was once (weakly) referenced, but can no longer be found. Only the system will ever generate these, and these are never valid to send as input to the system; they can never be resolved. In general, references to the same missing object will produce the same missing NTIID; however, in some cases, it may be possible for references to different missing objects to produce the same missing NTIID. Context will usually make it clear if this has happened.

nti.ntiids.ntiids.TYPE_NAMED_ENTITY = 'NamedEntity'

Named entities are globally accessible knowing nothing more than a simple string name. There should be a defined subtype for each namespace and/or specific kind of named entity

nti.ntiids.ntiids.TYPE_NAMED_ENTITY_COMMUNITY = 'NamedEntity:Community'

Subtype of named entities identifying a particular community

nti.ntiids.ntiids.TYPE_NAMED_ENTITY_USER = 'NamedEntity:User'

Subtype of named entities identifying a particular user account

nti.ntiids.ntiids.TYPE_OID = 'OID'

Used as an opaque identifier to a specific object. This will not incorporate the object’s name or path (when those concepts make sense). Instead, it points to an object by identity.

nti.ntiids.ntiids.TYPE_ROOM = 'MeetingRoom'

AKA an extant “chat” session

nti.ntiids.ntiids.TYPE_TRANSCRIPT = 'Transcript'

Transcripts and TranscriptSummaries. Note that they are not subtypes of a common type because they contain quite different information and are used in different ways.

nti.ntiids.ntiids.TYPE_UUID = 'UUID'

Meant to specify some sort of unique but otherwise meaningless local portion. (Not necessarily an actual GUID).

nti.ntiids.oids

Functions for externalizing OIDs.

nti.ntiids.oids.to_external_ntiid_oid(contained, default_oid=None, add_to_connection=False, add_to_intids=False, mask_creator=False, use_cache=True)

Returns:

An NTIID string utilizing the object’s creator and persistent id.

Parameters:

• default_oid (str) – The default value for the externalization of the OID. If this is None (the default), and no external OID can be found (using toExternalOID()), then this function will return None.
• add_to_connection – If the object is persistent but not yet added to a connection, setting this to true will attempt to add it to the nearest connection in its containment tree, thus letting it have an OID.
• mask_creator (bool) – If true (not the default), then the actual creator of the object will not be present in the NTIID string.

nti.ntiids.schema

Support for using NTIIDs in a zope schema.

class nti.ntiids.schema.ValidNTIID(*args, **kw)

Bases: nti.schema.field.ValidURI

A schema field that checks that the value is a correctly formed NTIID. (This does not perform any validation that the value is actually reachable or accessibly in a library or catalog.)

fromUnicode(value)

>>> from zope.schema import Text
>>> t = Text(constraint=lambda v: 'x' in v)
>>> t.fromUnicode(b"foo x spam") # doctest: +IGNORE_EXCEPTION_DETAIL
Traceback (most recent call last):
...
zope.schema._bootstrapinterfaces.WrongType:
    ('foo x spam', <type 'unicode'>, '')
>>> result = t.fromUnicode(u"foo x spam")
>>> isinstance(result, bytes)
False
>>> str(result)
'foo x spam'
>>> t.fromUnicode(u"foo spam") # doctest: +IGNORE_EXCEPTION_DETAIL
Traceback (most recent call last):
...
zope.schema._bootstrapinterfaces.ConstraintNotSatisfied:
    (u'foo spam', '')