diff --git a/sleekxmpp/xmlstream/__init__.py b/sleekxmpp/xmlstream/__init__.py index 2611896..c82ab34 100644 --- a/sleekxmpp/xmlstream/__init__.py +++ b/sleekxmpp/xmlstream/__init__.py @@ -6,5 +6,6 @@ See the file LICENSE for copying permission. """ +from sleekxmpp.xmlstream.jid import JID from sleekxmpp.xmlstream.stanzabase import StanzaBase, ElementBase from sleekxmpp.xmlstream.xmlstream import XMLStream, RESPONSE_TIMEOUT diff --git a/sleekxmpp/xmlstream/jid.py b/sleekxmpp/xmlstream/jid.py index 2839ba5..292abd9 100644 --- a/sleekxmpp/xmlstream/jid.py +++ b/sleekxmpp/xmlstream/jid.py @@ -1,70 +1,121 @@ +""" + SleekXMPP: The Sleek XMPP Library + Copyright (C) 2010 Nathanael C. Fritz + This file is part of SleekXMPP. + + See the file LICENSE for copying permission. +""" + + class JID(object): - def __init__(self, jid): - """Initialize a new jid""" - self.reset(jid) + """ + A representation of a Jabber ID, or JID. - def reset(self, jid): - """Start fresh from a new jid string""" - self._full = self._jid = str(jid) - self._domain = None - self._resource = None - self._user = None - self._domain = None - self._bare = None - - def __getattr__(self, name): - """Handle getting the jid values, using cache if available""" - if name == 'resource': - if self._resource is not None: return self._resource - self._resource = self._jid.split('/', 1)[-1] - return self._resource - elif name == 'user': - if self._user is not None: return self._user - if '@' in self._jid: - self._user = self._jid.split('@', 1)[0] - else: - self._user = self._user - return self._user - elif name in ('server', 'domain'): - if self._domain is not None: return self._domain - self._domain = self._jid.split('@', 1)[-1].split('/', 1)[0] - return self._domain - elif name == 'full': - return self._jid - elif name == 'bare': - if self._bare is not None: return self._bare - self._bare = self._jid.split('/', 1)[0] - return self._bare + Each JID may have three components: a user, a domain, and an optional + resource. For example: user@domain/resource - def __setattr__(self, name, value): - """Edit a jid by updating it's individual values, resetting by a generated jid in the end""" - if name in ('resource', 'user', 'domain'): - object.__setattr__(self, "_%s" % name, value) - self.regenerate() - elif name == 'server': - self.domain = value - elif name in ('full', 'jid'): - self.reset(value) - elif name == 'bare': - if '@' in value: - u, d = value.split('@', 1) - object.__setattr__(self, "_user", u) - object.__setattr__(self, "_domain", d) - else: - object.__setattr__(self, "_domain", value) - self.regenerate() - else: - object.__setattr__(self, name, value) + When a resource is not used, the JID is called a bare JID. + The JID is a full JID otherwise. + Attributes: + jid -- Alias for 'full'. + full -- The value of the full JID. + bare -- The value of the bare JID. + user -- The username portion of the JID. + domain -- The domain name portion of the JID. + server -- Alias for 'domain'. + resource -- The resource portion of the JID. - def regenerate(self): - """Generate a new jid based on current values, useful after editing""" - jid = "" - if self.user: jid = "%s@" % self.user - jid += self.domain - if self.resource: jid += "/%s" % self.resource - self.reset(jid) - - def __str__(self): - return self.full + Methods: + reset -- Use a new JID value. + regenerate -- Recreate the JID from its components. + """ + def __init__(self, jid): + """Initialize a new JID""" + self.reset(jid) + + def reset(self, jid): + """ + Start fresh from a new JID string. + + Arguments: + jid - The new JID value. + """ + self._full = self._jid = str(jid) + self._domain = None + self._resource = None + self._user = None + self._bare = None + + def __getattr__(self, name): + """ + Handle getting the JID values, using cache if available. + + Arguments: + name -- One of: user, server, domain, resource, + full, or bare. + """ + if name == 'resource': + if self._resource is None: + self._resource = self._jid.split('/', 1)[-1] + return self._resource + elif name == 'user': + if self._user is None: + if '@' in self._jid: + self._user = self._jid.split('@', 1)[0] + else: + self._user = self._user + return self._user + elif name in ('server', 'domain'): + if self._domain is None: + self._domain = self._jid.split('@', 1)[-1].split('/', 1)[0] + return self._domain + elif name == 'full': + return self._jid + elif name == 'bare': + if self._bare is None: + self._bare = self._jid.split('/', 1)[0] + return self._bare + + def __setattr__(self, name, value): + """ + Edit a JID by updating it's individual values, resetting the + generated JID in the end. + + Arguments: + name -- The name of the JID part. One of: user, domain, + server, resource, full, jid, or bare. + value -- The new value for the JID part. + """ + if name in ('resource', 'user', 'domain'): + object.__setattr__(self, "_%s" % name, value) + self.regenerate() + elif name == 'server': + self.domain = value + elif name in ('full', 'jid'): + self.reset(value) + elif name == 'bare': + if '@' in value: + u, d = value.split('@', 1) + object.__setattr__(self, "_user", u) + object.__setattr__(self, "_domain", d) + else: + object.__setattr__(self, "_domain", value) + self.regenerate() + else: + object.__setattr__(self, name, value) + + def regenerate(self): + """Generate a new JID based on current values, useful after editing.""" + jid = "" + if self.user: + jid = "%s@" % self.user + jid += self.domain + if self.resource: + jid += "/%s" % self.resource + self.reset(jid) + + def __str__(self): + """Use the full JID as the string value.""" + return self.full