Updated and simplified new JID class to have more documentation and use PEP8 style.

1 files changed, 119 insertions, 68 deletions

diff --git a/sleekxmpp/xmlstream/jid.py b/sleekxmpp/xmlstream/jid.py
index 2839ba58..292abd92 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)
-
-	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
-
-	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)
-
-
-	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
+    """
+    A representation of a Jabber ID, or JID.
+
+    Each JID may have three components: a user, a domain, and an optional
+    resource. For example: user@domain/resource
+
+    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.
+
+    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