Make exceptions have a base class; add type hints to functions

Py3CX/__init__.py

@@ -1,11 +1,14 @@
+import typing
 # Environment var definitions
 ENV_URI='TCX_SITE_URI'
 ENV_AUTH_USER='TCX_API_AUTH_USERNAME'
 ENV_AUTH_PASS='TCX_API_AUTH_PASSWORD'
 
-class APIError(Exception):
+class Py3CXException(Exception):
 	pass
-class ValidationError(Exception):
+class APIError(Py3CXException):
+	pass
+class ValidationError(Py3CXException):
 	pass
 
 class Request:
@@ -74,7 +77,7 @@ class TransactionalObject(APIObject):
 			'Id':self._session})
 
 class Py3CX:
-	class __Call(ReadOnlyObject):
+	class _Call(ReadOnlyObject):
 		def __init__(self, tcx, callid):
 			super().__init__(tcx, 'activeCalls')
 			self.params=callid
@@ -95,7 +98,7 @@ class Py3CX:
 			self.tcx.rq.post('activeCalls/drop', params={
 				'Id': self.params})
 			self.params=None
-	class __User(TransactionalObject):
+	class _User(TransactionalObject):
 		def __init__(self, parent, params):
 			super().__init__(parent, 'ExtensionList/set')
 			self.params=params
@@ -115,9 +118,9 @@ class Py3CX:
 			self.sip_authpw=parms['AuthPassword']['_value']
 			self.provision_uri=parms['MyPhoneProvLink']['_value']
 			self.webpw=parms['AccessPassword']['_value']
-			self.extension=Py3CX.__Extension(self.tcx, self.params)
+			self.extension=Py3CX._Extension(self.tcx, self.params)
 			self.cancel()
-	class __Extension(ReadOnlyObject):
+	class _Extension(ReadOnlyObject):
 		def __init__(self, parent, params, populate=True):
 			super().__init__(parent, api='ExtensionList')
 			self.params=params
@@ -141,7 +144,7 @@ class Py3CX:
 			self.cli=res['OutboundCallerId']
 			self.mobile=res['MobileNumber']
 			self.online=res['IsRegistered']
-	class __PhoneSystem:
+	class _PhoneSystem:
 		class System(object):
 			class License(object):
 				pass
@@ -205,7 +208,7 @@ class Py3CX:
 			self.refresh_inroute()
 			self.refresh_sysstat()
 		@property
-		def extensionlist(self):
+		def list_extensions(self) -> typing.List[Py3CX._Extension]:
 			if self.extlist is None:
 				self.extlist=ReadOnlyObject(self.tcx, api='ExtensionList')
 			self.extlist.refresh()
@@ -213,7 +216,7 @@ class Py3CX:
 			assert (len(res)>0), "No extensions found"
 			ret=[]
 			for extension in res:
-				this=Py3CX.__Extension(self.tcx, params=extension['Number'], populate=False)
+				this=Py3CX._Extension(self.tcx, params=extension['Number'], populate=False)
 				this.firstname=extension['FirstName']
 				this.surname=extension['LastName']
 				this.name="%s %s" % (this.firstname, this.surname)
@@ -226,7 +229,7 @@ class Py3CX:
 				ret.append(this)
 			return ret
 		@property
-		def callslist(self):
+		def list_calls(self) -> typing.List[Py3CX._Call]:
 			if self.calllist is None:
 				self.calllist=ReadOnlyObject(self.tcx, api='activeCalls')
 			self.calllist.refresh()
@@ -234,7 +237,7 @@ class Py3CX:
 			if len(res)==0: return []
 			ret=[]
 			for call in res:
-				this=Py3CX.__Call(self.tcx, call['Id'])
+				this=Py3CX._Call(self.tcx, call['Id'])
 				this.caller=call['Caller']
 				this.callee=call['Callee']
 				this.state=call['Status']
@@ -260,16 +263,16 @@ class Py3CX:
 			'Password': self.passw})
 		self.rq.sess.headers.update({'x-xsrf-token':rs.cookies['XSRF-TOKEN']})
 	@property
-	def authenticated(self):
+	def authenticated(self) -> bool:
 		try:
 			self.rq.get('CurrentUser')
 		except APIError:
 			return False
 		return True
 	@property
-	def System(self):
+	def system(self) -> Py3CX._PhoneSystem:
 		assert self.authenticated, "Py3CX not authenticated yet!"
 		if self.__tcxsystem is None:
-			self.__tcxsystem=__PhoneSystem(self)
+			self.__tcxsystem=Py3CX._PhoneSystem(self)
 		return self.__tcxsystem