httpclient Documentation Release 1 Franck Cuny May 07, 2012
CONTENTS 1 Basic usage 3 2 User Guide 5 2.1 Installing httpclient............................................ 5 2.2 Creating your first client......................................... 5 2.3 How to use this library.......................................... 6 2.4 How to test................................................ 7 2.5 HTTPClient............................................... 7 Python Module Index 9 i
ii
httpclient Documentation, Release 1 httpclient is a Python library to build HTTP client CONTENTS 1
httpclient Documentation, Release 1 2 CONTENTS
CHAPTER ONE BASIC USAGE This module is heavily inspired by LWP::UserAgent >>> from httpclient import HTTPClient >>> from http import Request >>> request = Request( GET, http://lumberjaph.net ) >>> cclient = HTTPClient() >>> response = cclient.request(request) >>> print response.status 200 3
httpclient Documentation, Release 1 4 Chapter 1. Basic usage
CHAPTER TWO USER GUIDE 2.1 Installing httpclient 2.1.1 Installing from GitHub At the moment, the only way to get http is from GitHub. I also recommend to use virtualenv and pip to work with this repository. To get the sources and install all the requirements: git clone git://github.com/franckcuny/httpclient.git cd httpclient virtualenv env source virtualenv/bin/activate pip install -r requirements-test.txt pip install -r requirements-test.txt 2.1.2 Testing First you need to install all the requirements for the tests, following the previous instruction. Then, you can easily run the tests with the following command:./run_tests.py 2.2 Creating your first client The client implement a web user agent. It is used to dispatch web requests. In the most common usage, the application creates a Client, and set the default values for the agent string, the timeout, etc. Then a Request object is created. The request is then passed to the client, which dispatch the request and a Response object is returned. >>> from http import Request >>> from httpclient import HTTPClient >>> client = HTTPClient() >>> req = Request( GET, http://lumberjaph.net ) 5
httpclient Documentation, Release 1 The default client will set the timeout to 60 seconds, the useragent string to python-http, and the number of redirection to follow to 7. >>> client = Client(agent= my uber application, timeout=10) 2.3 How to use this library For the purpose of this documentation, let s start with a simple client for the GitHub API. from httpclient import HTTPClient from http import Request, Url import json class GitHubClient(object): def init (self, user_agent=none, base_url= https://api.github.com ): self.base_url = base_url if user_agent is None: self._user_agent = HTTPClient() else: self._user_agent = user_agent @property def user_agent(self): return self._user_agent @user_agent.setter def user_agent(self, user_agent): self._user_agent = user_agent def get_user(self, username): endpoint = Url(self.base_url) endpoint.path.append( users ) endpoint.path.append(username) request = Request( GET, endpoint) response = self.user_agent.request(request) if response.is_success: return json.loads(response.content) else: raise Exception(response.status_line) >>> gh = GitHubClient() >>> res = gh.get_user( franckcuny ) >>> print res[ name ] franck 2.3.1 Setting the useragent You should let the possibility for the developper to set its own user_agent. 6 Chapter 2. User Guide
httpclient Documentation, Release 1 2.4 How to test Now, we will add tests for this client. def _cb(request): response = Response(200, content=json.dumps({ name : batman })) return response class Test(unittest.TestCase): def testname(self): ua = HTTPClient() ua.add_handler( request_send, _cb) client = GitHubClient(user_agent=ua) res = client.get_user( franckcuny ) self.assertequal(res[ name ], batman ) If we execute these test, the callback cb will be called, and since it returns a class:response object, the request is never sent over the wire. 2.5 HTTPClient 2.5.1 Synopsis >>> from http import Request >>> from httpclient import HTTPClient >>> request = Request( GET, http://lumberjaph.net ) >>> client = HTTPClient() >>> client.request(request) >>> response = client.request(request) >>> print response.status 200 2.5.2 Interface HTTPClient instances have the following methods: class httpclient.httpclient HTTPException(fn) add_handler(position, cb) default_header(key) default_headers delete(*args) get(*args) head(*args) mirror(*args) 2.4. How to test 7
httpclient Documentation, Release 1 post(*args) put(*args) remove_handler(position) request(*args) 8 Chapter 2. User Guide
PYTHON MODULE INDEX h httpclient, 7 9