Permalink
Browse files

Added some roughed out doc changes

  • Loading branch information...
1 parent 3bf1b4f commit 0ae1a05dc404bebecc3fc69cc6a6e2a9c7061b7a @infracanophile committed Apr 3, 2013
Showing with 18 additions and 72 deletions.
  1. +1 −0 AUTHORS.rst
  2. +16 −72 README.rst
  3. +1 −0 requests/api.py
View
@@ -123,3 +123,4 @@ Patches and Suggestions
- Denis Ryzhkov <denisr@denisr.com>
- Wilfred Hughes <me@wilfred.me.uk> @dontYetKnow
- Dmitry Medvinsky <me@dmedvinsky.name>
+- Jesse Sherlock <jesse@jessesherlock.com>
View
@@ -1,82 +1,26 @@
-Requests: HTTP for Humans
+Requests: HTTP for Humans (now with source_address support)
=========================
+Fork of Kenneth Reitz's fantastic Requests library with source_address support (and a forked version of the included urllib3 that's included with requests).
-.. image:: https://travis-ci.org/kennethreitz/requests.png?branch=master
- :target: https://travis-ci.org/kennethreitz/requests
+Find the real documentation here: https://github.com/kennethreitz/requests
-Requests is an Apache2 Licensed HTTP library, written in Python, for human
-beings.
+I've removed the docs from this fork because I haven't had time to update all of them and no docs is better than docs that are wrong.
-Most existing Python modules for sending HTTP requests are extremely
-verbose and cumbersome. Python's builtin urllib2 module provides most of
-the HTTP capabilities you should need, but the api is thoroughly broken.
-It requires an enormous amount of work (even method overrides) to
-perform the simplest of tasks.
+source_address is a kwarg on request building methods (get/post/put/etc)
-Things shouldn't be this way. Not in Python.
+session objects have a source_address attribute that can be set on the session (and overridden on an individual request like all the other session object attributes).
-.. code-block:: pycon
-
- >>> r = requests.get('https://api.github.com', auth=('user', 'pass'))
- >>> r.status_code
- 204
- >>> r.headers['content-type']
- 'application/json'
- >>> r.text
- ...
-
-See `the same code, without Requests <https://gist.github.com/973705>`_.
-
-Requests allow you to send HTTP/1.1 requests. You can add headers, form data,
-multipart files, and parameters with simple Python dictionaries, and access the
-response data in the same way. It's powered by httplib and `urllib3
-<https://github.com/shazow/urllib3>`_, but it does all the hard work and crazy
-hacks for you.
-
-
-Features
---------
-
-- International Domains and URLs
-- Keep-Alive & Connection Pooling
-- Sessions with Cookie Persistence
-- Browser-style SSL Verification
-- Basic/Digest Authentication
-- Elegant Key/Value Cookies
-- Automatic Decompression
-- Unicode Response Bodies
-- Multipart File Uploads
-- Connection Timeouts
-- Thread-safety
-
-
-Installation
-------------
-
-To install requests, simply:
+If you pass in 0 for the port then the underlying HTTPConnection object falls back to "default behaviour" which, as far as I can tell, is the normal "any available port" behaviour.
-.. code-block:: bash
-
- $ pip install requests
-
-Or, if you absolutely must:
-
-.. code-block:: bash
-
- $ easy_install requests
-
-But, you really shouldn't do that.
-
-
-
-Contribute
-----------
+.. code-block:: pycon
+ >>> r = requests.get('https://api.github.com', auth=('user', 'pass'), source_address=('127.0.0.1', 54444))
+ >>> r = requests.get('https://api.github.com', auth=('user', 'pass'), source_address=('127.0.0.1', 0))
+ >>> sess = requests.session()
+ >>> sess.source_address = ('127.0.0.1', 54444)
+ >>> sess.auth = ('user', 'pass')
+ >>> r = sess.get('https://api.github.com')
-#. Check for open issues or open a fresh issue to start a discussion around a feature idea or a bug. There is a Contributor Friendly tag for issues that should be ideal for people who are not very familiar with the codebase yet.
-#. Fork `the repository`_ on Github to start making your changes to the **master** branch (or branch off of it).
-#. Write a test which shows that the bug was fixed or that the feature works as expected.
-#. Send a pull request and bug the maintainer until it gets merged and published. :) Make sure to add yourself to AUTHORS_.
+I don't have good test coverage yet (and none at all checked in at the moment because I was using netcat to set up a fake server). I will work out a reasonable way to test this and then hopefully get this merged into requests.
-.. _`the repository`: http://github.com/kennethreitz/requests
-.. _AUTHORS: https://github.com/kennethreitz/requests/blob/master/AUTHORS.rst
+I'm definitely open to suggestions of more elegant ways to thread the source_address parameter through the session, adapter, connectionpool and connection objects that are in between the requests api and the underlying HTTPConnection. It's not bad right now but I have a feeling that someone with a better mental model of how Requests works might see a nicer way to thread this argument through the class hierarchy.
View
@@ -32,6 +32,7 @@ def request(method, url, **kwargs):
:param verify: (optional) if ``True``, the SSL cert will be verified. A CA_BUNDLE path can also be provided.
:param stream: (optional) if ``False``, the response content will be immediately downloaded.
:param cert: (optional) if String, path to ssl client cert file (.pem). If Tuple, ('cert', 'key') pair.
+ :param source_address: (optional) ('source_IP', source_port) pair.
Usage::

0 comments on commit 0ae1a05

Please sign in to comment.