more doc updates

Author: proxymesh

README.md

@@ -1,27 +1,38 @@
-The `python-proxy-headers` package provides support for handling custom proxy headers when making HTTP requests in various python modules.
+# Python Proxy Headers
+
+The `python-proxy-headers` package provides support for handling custom proxy headers when making HTTPS requests in various python modules.
 
 We currently provide extensions to the following packages:
 
 * [urllib3](https://urllib3.readthedocs.io/en/stable/)
 * [requests](https://docs.python-requests.org/en/latest/index.html)
-* [httpx](https://www.python-httpx.org/)
 * [aiohttp](https://docs.aiohttp.org/en/stable/index.html)
+* [httpx](https://www.python-httpx.org/)
 
 None of these modules provide good support for parsing custom response headers from proxy servers. And some of them make it hard to send custom headers to proxy servers. So we at [ProxyMesh](https://proxymesh.com) made these extension modules to support our customers that use Python and want to use custom headers to control our proxy behavior. But these modules can work for handling custom headers with any proxy.
 
-Examples for how to use these extension modules are described below.
+*If you are looking for [Scrapy](https://scrapy.org/) support, please see our [scrapy-proxy-headers](https://github.com/proxymesh/scrapy-proxy-headers) project.*
+
+## Installation
+
+Examples for how to use these extension modules are described below. You must first do the following:
+
+1. `pip install python-proxy-headers`
+2. Install the appropriate package based on the python module you want to use.
+
+This package does not have any dependencies because we don't know which module you want to use.
 
 ## urllib3
 
-If you just want to send custom proxy headers, but don't need to receive proxy response headers, then you can use urllib3 directly, like so:
+If you just want to send custom proxy headers, but don't need to receive proxy response headers, then you can [urllib3.ProxyManager](https://urllib3.readthedocs.io/en/stable/reference/urllib3.poolmanager.html#urllib3.ProxyManager), like so:
 
 ``` python
 import urllib3
 proxy = urllib3.ProxyManager('http://PROXYHOST:PORT', proxy_headers={'X-ProxyMesh-Country': 'US'})
 r = proxy.request('GET', 'https://api.ipify.org?format=json')
 ```
 
-Note that when using this method, if you keep reusing the same `ProxyManager` instance, you may be re-using the proxy connection, which may have different behavior than if you create a new proxy connection for each request. For example, with ProxyMesh, you may keep getting the same IP address if you reuse the proxy connection.
+Note that when using this method, if you keep reusing the same `ProxyManager` instance, you may be re-using the proxy connection, which may have different behavior than if you create a new proxy connection for each request. For example, with ProxyMesh you may keep getting the same IP address if you reuse the proxy connection.
 
 To get proxy response headers, use our extension module like this:
 
@@ -32,11 +43,11 @@ r = proxy.request('GET', 'https://api.ipify.org?format=json')
 r.headers['X-ProxyMesh-IP']
 ```
 
-You can also pass `proxy_headers` into the `ProxyHeaderManager` as well. For example, you pass back the same `X-ProxyMesh-IP` to ensure you get the same IP address on subsequent requests.
+You can also pass `proxy_headers` into our `ProxyHeaderManager` as well. For example, you can pass back the same `X-ProxyMesh-IP` header to ensure you get the same IP address on subsequent requests.
 
 ## requests
 
-The requests adapter builds on the `urllib3_proxy_manager` module to make it easy to pass in proxy headers and receive proxy response headers.
+The requests adapter builds on our `urllib3_proxy_manager` module to make it easy to pass in proxy headers and receive proxy response headers.
 
 ``` python
 from python_proxy_headers import requests_adapter
@@ -57,7 +68,7 @@ async with aiohttp.ClientSession() as session:
 		await r.text()
 ```
 
-However, if you want to get proxy response, you should use our extenion module:
+However, if you want to get proxy response, you should use our extension module:
 
 ``` python
 from python_proxy_headers import aiohttp_proxy
@@ -75,8 +86,8 @@ httpx also supports proxy headers by default, though it's not documented:
 ``` python
 import httpx
 proxy = httpx.Proxy('http://PROXYHOST:PORT', headers={'X-ProxyMesh-Country': 'US'})
-mounts = {'http://': httpx.HTTPTransport(proxy=proxy), 'https://': httpx.HTTPTransport(proxy=proxy)}
-with httpx.Client(mounts=mounts) as client:
+transport = HTTPProxyTransport(proxy=proxy)
+with httpx.Client(mounts={'http://': transort, 'https://': transport}) as client:
 	r = client.get('https://api.ipify.org?format=json')
 ```
 
@@ -117,4 +128,4 @@ r.headers['X-ProxyMesh-IP']
 ```
 
 Our httpx helper module internally provides extension classes for [httpcore](https://www.encode.io/httpcore/), for handling proxy headers over tunnel connections.
-You can use those classes too if you're building on top of httpcore.
+You can use those classes if you're building on top of httpcore.