diff options
| -rw-r--r-- | sleekxmpp/jid.py | 162 |
1 files changed, 138 insertions, 24 deletions
diff --git a/sleekxmpp/jid.py b/sleekxmpp/jid.py index dc6eb6b9..2adc4372 100644 --- a/sleekxmpp/jid.py +++ b/sleekxmpp/jid.py @@ -3,8 +3,7 @@ sleekxmpp.jid ~~~~~~~~~~~~~~~~~~~~~~~ - This module allows for working with Jabber IDs (JIDs) by - providing accessors for the various components of a JID. + This module allows for working with Jabber IDs (JIDs). Part of SleekXMPP: The Sleek XMPP Library @@ -21,17 +20,24 @@ import encodings.idna from sleekxmpp.util import stringprep_profiles - +#: These characters are not allowed to appear in a JID. ILLEGAL_CHARS = '\x00\x01\x02\x03\x04\x05\x06\x07\x08\t\n\x0b\x0c\r' + \ '\x0e\x0f\x10\x11\x12\x13\x14\x15\x16\x17\x18\x19' + \ '\x1a\x1b\x1c\x1d\x1e\x1f' + \ ' !"#$%&\'()*+,./:;<=>?@[\\]^_`{|}~\x7f' +#: The basic regex pattern that a JID must match in order to determine +#: the local, domain, and resource parts. This regex does NOT do any +#: validation, which requires application of nodeprep, resourceprep, etc. JID_PATTERN = "^(?:([^\"&'/:<>@]{1,1023})@)?([^/@]{1,1023})(?:/(.{1,1023}))?$" +#: The set of escape sequences for the characters not allowed by nodeprep. JID_ESCAPE_SEQUENCES = set(['\\20', '\\22', '\\26', '\\27', '\\2f', '\\3a', '\\3c', '\\3e', '\\40', '\\5c']) +#: A mapping of unallowed characters to their escape sequences. An escape +#: sequence for '\' is also included since it must also be escaped in +#: certain situations. JID_ESCAPE_TRANSFORMATIONS = {' ': '\\20', '"': '\\22', '&': '\\26', @@ -40,8 +46,10 @@ JID_ESCAPE_TRANSFORMATIONS = {' ': '\\20', ':': '\\3a', '<': '\\3c', '>': '\\3e', - '@': '\\40'} + '@': '\\40', + '\\': '\\5c'} +#: The reverse mapping of escape sequences to their original forms. JID_UNESCAPE_TRANSFORMATIONS = {'\\20': ' ', '\\22': '"', '\\26': '&', @@ -54,6 +62,9 @@ JID_UNESCAPE_TRANSFORMATIONS = {'\\20': ' ', '\\5c': '\\'} +# pylint: disable=c0103 +#: The nodeprep profile of stringprep used to validate the local, +#: or username, portion of a JID. nodeprep = stringprep_profiles.create( nfkc=True, bidi=True, @@ -75,7 +86,9 @@ nodeprep = stringprep_profiles.create( lambda c: c in ' \'"&/:<>@'], unassigned=[stringprep.in_table_a1]) - +# pylint: disable=c0103 +#: The resourceprep profile of stringprep, which is used to validate +#: the resource portion of a JID. resourceprep = stringprep_profiles.create( nfkc=True, bidi=True, @@ -97,7 +110,13 @@ resourceprep = stringprep_profiles.create( def _parse_jid(data): """ Parse string data into the node, domain, and resource - components of a JID. + components of a JID, if possible. + + :param string data: A string that is potentially a JID. + + :raises InvalidJID: + + :returns: tuple of the validated local, domain, and resource strings """ match = re.match(JID_PATTERN, data) if not match: @@ -105,30 +124,52 @@ def _parse_jid(data): (node, domain, resource) = match.groups() - _validate_node(node) - _validate_domain(domain) - _validate_resource(resource) + node = _validate_node(node) + domain = _validate_domain(domain) + resource = _validate_resource(resource) return node, domain, resource def _validate_node(node): + """Validate the local, or username, portion of a JID. + + :raises InvalidJID: + + :returns: The local portion of a JID, as validated by nodeprep. + """ try: if node is not None: node = nodeprep(node) + return node except stringprep_profiles.StringPrepError: raise InvalidJID('Invalid local part') def _validate_domain(domain): + """Validate the domain portion of a JID. + + IP literal addresses are left as-is, if valid. Domain names + are stripped of any trailing label separators (`.`), and are + checked with the nameprep profile of stringprep. If the given + domain is actually a punyencoded version of a domain name, it + is converted back into its original Unicode form. Domains must + also not start or end with a dash (`-`). + + :raises InvalidJID: + + :returns: The validated domain name + """ ip_addr = False + # First, check if this is an IPv4 address try: socket.inet_aton(domain) ip_addr = True except socket.error: pass + # Check if this is an IPv6 address if not ip_addr and hasattr(socket, 'inet_pton'): try: socket.inet_pton(socket.AF_INET6, domain.strip('[]')) @@ -137,6 +178,8 @@ def _validate_domain(domain): pass if not ip_addr: + # This is a domain name, which must be checked further + domain_parts = [] for label in domain.split('.'): try: @@ -145,6 +188,9 @@ def _validate_domain(domain): except UnicodeError: raise InvalidJID('Could not encode domain as ASCII') + if label.startswith('xn--'): + label = encodings.idna.ToUnicode(label) + for char in label: if char in ILLEGAL_CHARS: raise InvalidJID('Domain contains illegar characters') @@ -158,27 +204,38 @@ def _validate_domain(domain): if not domain: raise InvalidJID('Missing domain') + return domain + def _validate_resource(resource): + """Validate the resource portion of a JID. + + :raises InvalidJID: + + :returns: The local portion of a JID, as validated by resourceprep. + """ try: if resource is not None: resource = resourceprep(resource) + return resource except stringprep_profiles.StringPrepError: raise InvalidJID('Invalid resource') def _escape_node(node): + """Escape the local portion of a JID.""" result = [] for i, char in enumerate(node): if char == '\\': - if ''.join((data[i:i+3])) in JID_ESCAPE_SEQUENCES: + if ''.join((node[i:i+3])) in JID_ESCAPE_SEQUENCES: result.append('\\5c') continue result.append(char) for i, char in enumerate(result): - result[i] = JID_ESCAPE_TRANSFORMATIONS.get(char, char) + if char != '\\': + result[i] = JID_ESCAPE_TRANSFORMATIONS.get(char, char) escaped = ''.join(result) @@ -191,6 +248,12 @@ def _escape_node(node): def _unescape_node(node): + """Unescape a local portion of a JID. + + .. note:: + The unescaped local portion is meant ONLY for presentation, + and should not be used for other purposes. + """ unescaped = [] seq = '' for i, char in enumerate(node): @@ -212,6 +275,14 @@ def _unescape_node(node): def _format_jid(local=None, domain=None, resource=None): + """Format the given JID components into a full or bare JID. + + :param string local: Optional. The local portion of the JID. + :param string domain: Required. The domain name portion of the JID. + :param strin resource: Optional. The resource portion of the JID. + + :return: A full or bare JID string. + """ result = [] if local: result.append(local) @@ -228,13 +299,20 @@ class InvalidJID(ValueError): pass +# pylint: disable=R0903 class UnescapedJID(object): + """ + .. versionadded:: 1.1.10 + """ + def __init__(self, local, domain, resource): self._jid = (local, domain, resource) + # pylint: disable=R0911 def __getattr__(self, name): - """ + """Retrieve the given JID component. + :param name: one of: user, server, domain, resource, full, or bare. """ @@ -258,6 +336,7 @@ class UnescapedJID(object): return _format_jid(*self._jid) def __repr__(self): + """Use the full JID as the representation.""" return self.__str__() @@ -285,11 +364,27 @@ class JID(object): :host: Alias for ``domain``. :resource: The resource portion of the JID. - :param string jid: A string of the form ``'[user@]domain[/resource]'``. + :param string jid: + A string of the form ``'[user@]domain[/resource]'``. + :param string local: + Optional. Specify the local, or username, portion + of the JID. If provided, it will override the local + value provided by the `jid` parameter. The given + local value will also be escaped if necessary. + :param string domain: + Optional. Specify the domain of the JID. If + provided, it will override the domain given by + the `jid` parameter. + :param string resource: + Optional. Specify the resource value of the JID. + If provided, it will override the domain given + by the `jid` parameter. + + :raises InvalidJID: """ + # pylint: disable=W0212 def __init__(self, jid=None, **kwargs): - """Initialize a new JID""" self._jid = (None, None, None) if jid is None or jid == '': @@ -300,7 +395,6 @@ class JID(object): jid = jid._jid local, domain, resource = jid - validated = True local = kwargs.get('local', local) domain = kwargs.get('domain', domain) @@ -309,30 +403,47 @@ class JID(object): if 'local' in kwargs: local = _escape_node(local) if 'domain' in kwargs: - _validate_domain(domain) + domain = _validate_domain(domain) if 'resource' in kwargs: - _validate_resource(resource) + resource = _validate_resource(resource) self._jid = (local, domain, resource) def unescape(self): + """Return an unescaped JID object. + + Using an unescaped JID is preferred for displaying JIDs + to humans, and they should NOT be used for any other + purposes than for presentation. + + :return: :class:`UnescapedJID` + + .. versionadded:: 1.1.10 + """ return UnescapedJID(_unescape_node(self._jid[0]), self._jid[1], self._jid[2]) def regenerate(self): - """Deprecated""" + """No-op + + .. deprecated:: 1.1.10 + """ pass def reset(self, data): """Start fresh from a new JID string. :param string data: A string of the form ``'[user@]domain[/resource]'``. + + .. deprecated:: 1.1.10 """ self._jid = JID(data)._jid + # pylint: disable=R0911 def __getattr__(self, name): - """ + """Retrieve the given JID component. + :param name: one of: user, server, domain, resource, full, or bare. """ @@ -351,8 +462,10 @@ class JID(object): else: return None + # pylint: disable=W0212 def __setattr__(self, name, value): - """ + """Update the given JID component. + :param name: one of: ``user``, ``username``, ``local``, ``node``, ``server``, ``domain``, ``host``, ``resource``, ``full``, ``jid``, or ``bare``. @@ -377,21 +490,22 @@ class JID(object): return _format_jid(*self._jid) def __repr__(self): + """Use the full JID as the representation.""" return self.__str__() + # pylint: disable=W0212 def __eq__(self, other): - """ - Two JIDs are considered equal if they have the same full JID value. - """ + """Two JIDs are equal if they have the same full JID value.""" if isinstance(other, UnescapedJID): return False other = JID(other) return self._jid == other._jid + # pylint: disable=W0212 def __ne__(self, other): """Two JIDs are considered unequal if they are not equal.""" - return not self._jid == other._jid + return not self == other def __hash__(self): """Hash a JID based on the string version of its full JID.""" |