26: Added AbstractCommand.get_doc() method to return the gettext translated summary of command; added get_doc() method to all example

2 files changed, 72 insertions, 18 deletions

diff --git a/ipalib/base.py b/ipalib/base.py
index a62d58121..522b13b12 100644
--- a/ipalib/base.py
+++ b/ipalib/base.py
@@ -95,7 +95,7 @@ class NameSpace(object):
 		"""
 		Returns True if namespace has an item named `key`.
 		"""
-		return key.replace('-', '_') in self.__kw
+		return bool(key in self.__kw)
 
 	def __iter__(self):
 		"""
@@ -135,17 +135,44 @@ class Named(object):
 	def _get_name(self):
 		return self.__class__.__name__
 
+	def __get_loc(self):
+		cls = self.__class__
+		return '%s.%s' % (cls.__module__, cls.__name__)
+	loc = property(__get_loc)
+
 	def __get_name(self):
 		if self.__name is None:
 			self.__name = self._get_name()
 		return self.__name
 	name = property(__get_name)
 
+	def __get_cli_name(self):
+		return self.name.replace('_', '-')
+	cli_name = property(__get_cli_name)
+
 
 class AbstractCommand(object):
 	def __call__(self):
 		print 'You called %s()' % self.name
 
+	def get_doc(self, _):
+		"""
+		This should return a gettext translated summarary of the command.
+
+		For example, if you were documenting the 'add-user' command, you're
+		method would look something like this.
+
+		>>> def get_doc(self, _):
+		>>>		return _('add new user')
+		"""
+		raise NotImplementedError('%s.%s.%s()' % (
+				self.__class__.__module__,
+				self.__class__.__name__,
+				'get_doc',
+			)
+		)
+
+
 class Attribute(Named):
 	__locked = False
 	__obj = None
diff --git a/ipalib/plugins.py b/ipalib/plugins.py
index 7c1dcf910..85f3a9f46 100644
--- a/ipalib/plugins.py
+++ b/ipalib/plugins.py
@@ -26,21 +26,37 @@ import base
 from run import api
 
 
+# Hypothetical functional commands (not associated with any object):
+class krbtest(base.Command):
+	def get_doc(self, _):
+		return _('test your Kerberos ticket')
+api.register(krbtest)
+
+class discover(base.Command):
+	def get_doc(self, _):
+		return _('discover IPA servers on network')
+api.register(discover)
+
+
 # Register some methods for the 'user' object:
 class user__add(crud.Add):
-	pass
+	def get_doc(self, _):
+		return _('add new user')
 api.register(user__add)
 
 class user__del(crud.Del):
-	pass
+	def get_doc(self, _):
+		return _('delete existing user')
 api.register(user__del)
 
 class user__mod(crud.Mod):
-	pass
+	def get_doc(self, _):
+		return _('edit existing user')
 api.register(user__mod)
 
 class user__find(crud.Find):
-	pass
+	def get_doc(self, _):
+		return _('search for users')
 api.register(user__find)
 
 
@@ -53,57 +69,68 @@ class user__lastname(base.Property):
 	pass
 api.register(user__lastname)
 
-class user__lastname(base.Property):
+class user__login(base.Property):
 	pass
-api.register(user__lastname)
+api.register(user__login)
 
 
 # Register some methods for the 'group' object:
 class group__add(crud.Add):
-	pass
+	def get_doc(self, _):
+		return _('add new group')
 api.register(group__add)
 
 class group__del(crud.Del):
-	pass
+	def get_doc(self, _):
+		return _('delete existing group')
 api.register(group__del)
 
 class group__mod(crud.Mod):
-	pass
+	def get_doc(self, _):
+		return _('exit existing group')
 api.register(group__mod)
 
 class group__find(crud.Find):
-	pass
+	def get_doc(self, _):
+		return _('search for groups')
 api.register(group__find)
 
 
 # Register some methods for the 'service' object
 class service__add(crud.Add):
-	pass
+	def get_doc(self, _):
+		return _('add new service')
 api.register(service__add)
 
 class service__del(crud.Del):
-	pass
+	def get_doc(self, _):
+		return _('delete existing service')
 api.register(service__del)
 
 class service__mod(crud.Mod):
-	pass
+	def get_doc(self, _):
+		return _('edit existing service')
 api.register(service__mod)
 
 class service__find(crud.Find):
-	pass
+	def get_doc(self, _):
+		return _('search for services')
 api.register(service__find)
 
 
 # And to emphasis that the registration order doesn't matter,
 # we'll register the objects last:
 class group(base.Object):
-	pass
+	def get_doc(self, _):
+		return _('')
 api.register(group)
 
 class service(base.Object):
-	pass
+	def get_doc(self, _):
+		return _('')
 api.register(service)
 
 class user(base.Object):
-	pass
+	def get_doc(self, _):
+		return _('')
 api.register(user)