From e7337211fb73006d4f1d2990a90c9c29b9d2dbbf Mon Sep 17 00:00:00 2001
From: Stephan Erb <steve-e@h3c.de>
Date: Tue, 1 Dec 2009 23:31:17 +0100
Subject: [PATCH] Rename the Contacts class and document it, beeing a temporary
 refactoring artifact.

---
 src/common/contacts.py | 29 ++++++++++++++++++++---------
 src/common/gajim.py    |  4 ++--
 2 files changed, 22 insertions(+), 11 deletions(-)

diff --git a/src/common/contacts.py b/src/common/contacts.py
index 8f8397047..591e839a3 100644
--- a/src/common/contacts.py
+++ b/src/common/contacts.py
@@ -94,9 +94,8 @@ class CommonContact(XMPPEntity):
 
 class Contact(CommonContact):
 	"""
-	Information concerning each contact
+	Information concerning a contact
 	"""
-
 	def __init__(self, jid, account, name='', groups=[], show='', status='',
 			sub='', ask='', resource='', priority=0, keyID='', client_caps=None,
 			our_chatstate=None, chatstate=None, last_status_time=None, msg_id=
@@ -209,11 +208,20 @@ class GC_Contact(CommonContact):
 			status=self.status, sub='none', client_caps=self.client_caps)
 
 
-class Contacts:
+class LegacyContactsAPI:
 	"""
-	Information concerning all contacts and groupchat contacts
+	This is a GOD class for accessing contact and groupchat information.
+	The API has several flaws:
+		
+		* it mixes concerns because it deals with contacts, groupchats,
+		  groupchat contacts and metacontacts
+		* some methods like get_contact() may return None. This leads to 
+		  a lot of duplication all over Gajim because it is not sure
+		  if we receive a proper contact or just None.
+		  
+	It is a long way to cleanup this API. Therefore just stick with it
+	and use it as before. We will try to figure out a migration path.
 	"""
-
 	def __init__(self):
 		self._metacontact_manager = MetacontactManager(self)
 		self._accounts = {}
@@ -226,8 +234,8 @@ class Contacts:
 		self._metacontact_manager.change_account_name(old_name, new_name)
 
 	def add_account(self, account_name):
-		self._accounts[account_name] = Account(account_name,
-				Contacts_New(), GC_Contacts())
+		self._accounts[account_name] = Account(account_name, Contacts(),
+			GC_Contacts())
 		self._metacontact_manager.add_account(account_name)
 
 	def get_accounts(self):
@@ -406,8 +414,11 @@ class Contacts:
 		return self._accounts[account].gc_contacts.get_nb_role_total_gc_contacts(room_jid, role)
 
 
-class Contacts_New():
-
+class Contacts():
+	"""
+	This is a breakout of the contact related behavior of the old 
+	Contacts class (which is not called LegacyContactsAPI)
+	"""
 	def __init__(self):
 		# list of contacts  {jid1: [C1, C2]}, } one Contact per resource
 		self._contacts = {}
diff --git a/src/common/gajim.py b/src/common/gajim.py
index 509ef0591..7c3753a6e 100644
--- a/src/common/gajim.py
+++ b/src/common/gajim.py
@@ -100,7 +100,7 @@ else:
 
 os_info = None # used to cache os information
 
-from contacts import Contacts
+from contacts import LegacyContactsAPI
 from events import Events
 
 gmail_domains = ['gmail.com', 'googlemail.com']
@@ -111,7 +111,7 @@ last_message_time = {} # list of time of the latest incomming message
 							# {acct1: {jid1: time1, jid2: time2}, }
 encrypted_chats = {} # list of encrypted chats {acct1: [jid1, jid2], ..}
 
-contacts = Contacts()
+contacts = LegacyContactsAPI()
 gc_connected = {} # tell if we are connected to the room or not {acct: {room_jid: True}}
 gc_passwords = {} # list of the pass required to enter a room {room_jid: password}
 automatic_rooms = {} # list of rooms that must be automaticaly configured and for which we have a list of invities {account: {room_jid: {'invities': []}}}