Merge pull request #7 from vesellov/master

added README.md and bumped version

Author: vesellov

README.md

@@ -0,0 +1,88 @@
+# epp-python-client
+
+[EPP](https://en.wikipedia.org/wiki/Extensible_Provisioning_Protocol) is Extensible Provisioning Protocol used for registrar-registry communication to register and manage domains.
+
+The library provides an interface to the Extensible Provisioning Protocol:
+
+- Python client library for sending/receiving/parsing XML-formatted EPP requests and responses
+- RPC server running as intermediate gateway between consumer application and EPP registry
+- RPC client library written for Python applications to be able to interract with the RPC server
+
+
+
+## Install
+
+	pip install --upgrade https://github.com/datahaven-net/epp-python-client/archive/master.zip
+
+
+
+## Usage
+
+### Python client
+
+	from epp import epp_client
+	conn = epp_client.EPPConnection(
+		host='localhost',
+		port=700,
+		user='epp_user_01',
+		password='some_secret',
+		verbose=True,
+	)
+	conn.open()
+	print(conn.domain_check(domain_name='domain-may-not-exist.com'))
+	conn.close()
+
+
+The client is using `beautifulsoup4` to parse XML responses into Python objects. It is possible to access each element of the EPP response directly:
+
+	from epp import epp_client
+	conn = epp_client.EPPConnection(
+		host='localhost',
+		port=700,
+		user='epp_user_01',
+		password='some_secret',
+		verbose=True,
+		return_soup=True,
+	)
+	conn.open()
+	print(conn.domain_check(domain_name='domain-possibly-exist.com').find('response').resdata.find('domain:name').get('avail') == '0')
+	conn.close()
+
+
+
+### RPC server & client
+
+It is also possible to use the library in another way using intermediate RabbitMQ queue server.
+If your application requires stable and reliable connection to the EPP registry system and be able to run many EPP requests per minute it is not possible to establish new EPP connection for each request using the only Python client.
+
+There is an RPC server included in that library:
+
+1. when RPC-server starts it first connects to the EPP back-end system via Python client library and holds the connection open after "greeting" and "login" command are processed
+2. then it connects to the RabbitMQ server to be able to receive and process RPC calls from external applications
+3. it also automatically reconnects to the EPP system when connection is closed on server side
+
+To be able to run the server first you must create two text files holding credentials to your EPP registry system and RabbitMQ server:
+
+###### epp_params.txt
+	
+	epp.your-registry.com 700 epp_login epp_password
+
+
+###### rabbitmq_params.txt
+
+	localhost 5672 rabbitmq_rpc_server_login rabbitmq_rpc_server_password
+
+
+To start RPC server use the command above:
+
+	epp-gate -v --reconnect --epp=epp_params.txt --rabbitmq=rabbitmq_params.txt --queue=epp_messages
+
+
+Connection to the RPC server is carried out through RabbitMQ RPC-client also included in that library:
+
+	from epp import rpc_client
+	rpc_client.make_client(
+		rabbitmq_credentials=('localhost', 5672, 'rabbitmq_rpc_client_login', 'rabbitmq_rpc_client_password', ),
+		rabbitmq_queue_name='epp_messages',
+	)
+	print(rpc_client.cmd_domain_check(domains=["domain-possibly-exist.com", "another-domain.com", ]))

setup.py

@@ -2,7 +2,7 @@
 
 setup_params = dict(
     name='epp-python-client',
-    version='0.0.1',
+    version='0.0.2',
     author='Veselin Penev',
     author_email='[email protected]',
     packages=find_packages(where='src'),
@@ -18,6 +18,7 @@
     install_requires=[
         "beautifulsoup4",
         "lxml",
+        "pika",
     ],
 )
 

src/epp/epp_client.py

@@ -61,7 +61,7 @@ class EPPResponseEmptyError(Exception):
 
 class EPPConnection:
 
-    def __init__(self, host, port, user, password, verbose=False, raise_errors=False):
+    def __init__(self, host, port, user, password, verbose=False, raise_errors=False, return_soup=None):
         self.host = host
         self.port = int(port)
         self.user = user
@@ -72,6 +72,7 @@ def __init__(self, host, port, user, password, verbose=False, raise_errors=False
         self.format_32 = get_format_32()
         self.verbose = verbose
         self.raise_errors = raise_errors
+        self.return_soup = return_soup
 
     def open(self, timeout=10):
         self.socket = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
@@ -175,15 +176,15 @@ def write(self, xml):
             return None
         return ret
 
-    def call(self, cmd, soup=False):
+    def call(self, cmd, soup=None):
         if self.write(cmd):
             if self.verbose:
                 logger.debug('sent %d bytes:\n%s\n', len(cmd), cmd)
         raw = self.read()
         if raw:
             if self.verbose:
                 logger.debug('received %d bytes:\n%s', len(raw), raw.decode())
-        if soup:
+        if soup is True or (self.return_soup is True and soup is not False):
             try:
                 soup = BeautifulSoup(raw, "lxml")
                 result = soup.find('result')
@@ -218,79 +219,81 @@ def greeting(self):
             logger.debug('connected to %s (v%s)', svid, self.version)
         return greeting_response
 
-    def login(self):
+    def login(self, **kwargs):
         if self.verbose:
             logger.debug('attempt to login with: %r', self.user)
+        kwargs['soup'] = False
         login_response = self.call(cmd=commands.login % dict(
             user=self.user,
             password=self.password,
-        ))
+        ), **kwargs)
         soup = BeautifulSoup(login_response, "lxml")
         result = soup.find('result')
         code = int(result.get('code'))
         if code != 1000:
             raise Exception('login response code: %r' % code)
         return True
 
-    def logout(self):
-        logout_response = self.call(cmd=commands.logout)
+    def logout(self, **kwargs):
+        kwargs['soup'] = False
+        logout_response = self.call(cmd=commands.logout, **kwargs)
         soup = BeautifulSoup(logout_response, "lxml")
         result = soup.find('result')
         code = int(result.get('code'))
         if code not in [1000, 1300, 1500, ]:
             raise Exception('logout response code: %r' % code)
         return True
 
-    def poll_req(self):
+    def poll_req(self, **kwargs):
         return self.call(cmd=commands.poll % dict(
             cltrid=make_cltrid(),
-        ))
+        ), **kwargs)
 
-    def poll_ack(self, msg_id):
+    def poll_ack(self, msg_id, **kwargs):
         return self.call(cmd=commands.poll_ack % dict(
             cltrid=make_cltrid(),
             msgid=msg_id,
-        ))
+        ), **kwargs)
 
-    def host_check(self, nameservers_list):
+    def host_check(self, nameservers_list, **kwargs):
         return self.call(cmd=commands.nameserver.check % dict(
             cltrid=make_cltrid(),
             nameservers='\n'.join([commands.nameserver.single % ns for ns in nameservers_list]),
-        ))
+        ), **kwargs)
 
-    def host_info(self, nameserver):
+    def host_info(self, nameserver, **kwargs):
         return self.call(cmd=commands.nameserver.info % dict(
             cltrid=make_cltrid(),
             nameserver=nameserver,
-        ))
+        ), **kwargs)
 
-    def host_create(self, nameserver, ip_addresses_list):
+    def host_create(self, nameserver, ip_addresses_list, **kwargs):
         return self.call(cmd=commands.nameserver.create % dict(
             cltrid=make_cltrid(),
             nameserver=nameserver,
             ip_addresses='\n'.join([commands.nameserver.ip_address % ipaddr for ipaddr in ip_addresses_list])
-        ))
+        ), **kwargs)
 
-    def contact_check(self, contact):
+    def contact_check(self, contact, **kwargs):
         return self.call(cmd=commands.contact.check % dict(
             cltrid=make_cltrid(),
             contacts=commands.contact.single % contact,
-        ))
+        ), **kwargs)
 
-    def contact_check_multiple(self, contacts_list):
+    def contact_check_multiple(self, contacts_list, **kwargs):
         return self.call(cmd=commands.contact.check % dict(
             cltrid=make_cltrid(),
             contacts='\n'.join([commands.contact.single % c for c in contacts_list]),
-        ))
+        ), **kwargs)
 
-    def contact_info(self, contact_id, auth_info=None):
+    def contact_info(self, contact_id, auth_info=None, **kwargs):
         return self.call(cmd=commands.contact.info % dict(
             cltrid=make_cltrid(),
             contact_id=contact_id,
             auth_info='' if not auth_info else commands.contact.auth_info % auth_info,
-        ))
+        ), **kwargs)
 
-    def contact_create(self, contact_id, voice=None, fax=None, email=None, contacts=[], auth_info=None):
+    def contact_create(self, contact_id, voice=None, fax=None, email=None, contacts=[], auth_info=None, **kwargs):
         return self.call(cmd=commands.contact.create % dict(
             cltrid=make_cltrid(),
             contact_id=contact_id,
@@ -317,9 +320,9 @@ def contact_create(self, contact_id, voice=None, fax=None, email=None, contacts=
                 ) for cont in contacts
             ]),
             auth_info='' if not auth_info else commands.contact.auth_info % auth_info,
-        ))
+        ), **kwargs)
 
-    def contact_update(self, contact_id, voice=None, fax=None, email=None, contacts=[], auth_info=None):
+    def contact_update(self, contact_id, voice=None, fax=None, email=None, contacts=[], auth_info=None, **kwargs):
         return self.call(cmd=commands.contact.update % dict(
             cltrid=make_cltrid(),
             contact_id=contact_id,
@@ -346,37 +349,37 @@ def contact_update(self, contact_id, voice=None, fax=None, email=None, contacts=
                 ) for cont in contacts
             ]),
             auth_info='' if not auth_info else commands.contact.auth_info % auth_info,
-        ))
+        ), **kwargs)
 
-    def contact_delete(self, contact_id):
+    def contact_delete(self, contact_id, **kwargs):
         return self.call(cmd=commands.contact.delete % dict(
             cltrid=make_cltrid(),
             contact_id=contact_id,
-        ))
+        ), **kwargs)
 
-    def domain_check(self, domain_name):
+    def domain_check(self, domain_name, **kwargs):
         return self.call(cmd=commands.domain.check % dict(
             cltrid=make_cltrid(),
             domain_names=commands.domain.single % domain_name,
-        ))
+        ), **kwargs)
 
-    def domain_check_multiple(self, domains_list):
+    def domain_check_multiple(self, domains_list, **kwargs):
         return self.call(cmd=commands.domain.check % dict(
             cltrid=make_cltrid(),
             domain_names='\n'.join([
                 commands.domain.single % d for d in domains_list
             ]),
-        ))
+        ), **kwargs)
 
-    def domain_info(self, domain_name, auth_info=None):
+    def domain_info(self, domain_name, auth_info=None, **kwargs):
         return self.call(cmd=commands.domain.info % dict(
             cltrid=make_cltrid(),
             domain_name=domain_name,
             auth_info='' if not auth_info else commands.domain.auth_info % auth_info,
-        ))
+        ), **kwargs)
 
     def domain_create(self, domain_name, registrant, nameservers=[], period=1, period_units='y',
-                      contact_admin=None, contact_billing=None, contact_tech=None, auth_info=None):
+                      contact_admin=None, contact_billing=None, contact_tech=None, auth_info=None, **kwargs):
         return self.call(cmd=commands.domain.create % dict(
             cltrid=make_cltrid(),
             domain_name=domain_name,
@@ -389,20 +392,20 @@ def domain_create(self, domain_name, registrant, nameservers=[], period=1, perio
             contact_billing='' if not contact_billing else commands.domain.single_contact1 % dict(type='billing', id=contact_billing),
             contact_tech='' if not contact_tech else commands.domain.single_contact1 % dict(type='tech', id=contact_tech),
             auth_info='' if not auth_info else commands.domain.auth_info % auth_info,
-        ))
+        ), **kwargs)
 
-    def domain_renew(self, domain_name, cur_exp_date, period=1, period_units='y'):
+    def domain_renew(self, domain_name, cur_exp_date, period=1, period_units='y', **kwargs):
         return self.call(cmd=commands.domain.renew % dict(
             cltrid=make_cltrid(),
             domain_name=domain_name,
             cur_exp_date=cur_exp_date,
             period='' if period is None else commands.domain.period % dict(value=period, units=period_units or 'y'),
-        ))
+        ), **kwargs)
 
     def domain_update(self, domain_name, auth_info=None,
                       add_nameservers=[], remove_nameservers=[],
                       add_contacts=[], remove_contacts=[], change_registrant=None,
-                      rgp_restore=None, rgp_restore_report=None):
+                      rgp_restore=None, rgp_restore_report=None, **kwargs):
         restore_extension = ''
         if rgp_restore:
             restore_extension = commands.domain.restore_request_extension
@@ -428,12 +431,12 @@ def domain_update(self, domain_name, auth_info=None,
                 commands.domain.single_registrant % change_registrant
             ),
             restore_extension=restore_extension,
-        ))
+        ), **kwargs)
 
-    def domain_transfer(self, domain_name, auth_info=None, period=None, period_units=None):
+    def domain_transfer(self, domain_name, auth_info=None, period=None, period_units=None, **kwargs):
         return self.call(cmd=commands.domain.transfer % dict(
             cltrid=make_cltrid(),
             domain_name=domain_name,
             auth_info='' if not auth_info else commands.domain.auth_info % auth_info,
             period='' if period is None else commands.domain.period % dict(value=period, units=period_units or 'y'),
-        ))
+        ), **kwargs)