Repository: urllib3/urllib3

Issue:
Is HTTPHeaderDict a public API to make requests?
`HTTPHeaderDict` was initially designed to handle response headers, and is not documented for request headers.

 * Should it be documented?
 * How should it be imported? The current options are `from urllib3.response import HTTPHeaderDict` and `from urllib3._collections import HTTPHeaderDict`, and they don't feel right.


Discussion:
The question is "should it be documented for request headers?" and if so, "Why?"
@sigmavirus24 Yes, that's my first bullet point. The context is https://github.com/urllib3/urllib3/pull/2145 where we're catering to the request use case.
I mistyped. I meant should it be used for request headers by users
@sigmavirus24 Sorry, I'm still confused as it still looks like we're both asking the same question!

I don't have a strong opinion on the answer, and am wondering if anyone has an opinion on this minor issue.
My 2¢ is that constructing a HTTPHeaderDict should be the only way to work with headers because basic dictionaries are deceptively simple. 
My vote is that `HTTPHeaderDict` should be supported for request headers, it's already happening in the wild and like @sigmavirus24 said it's actually a good way to work with headers to handle all cases.
I think this has been answered with "Yes". Should we take the next step and make `HTTPHeaderDict` into a top-level object or leave things as-is?
@sethmlarson yeah, I think a good action here would be to allow `from urllib3 import HTTPHeaderDict` and document it for requests in the docs.

(Sounds like a good first issue to me.)
Hi @pquentin  , would adding HTTPHeaderDict as a top level object only involve adding `from .response import HTTPHeaderDict` and appending `HTTPHeaderDict` to the `__all__` list in the file [_init_.py](https://github.com/urllib3/urllib3/blob/main/src/urllib3/__init__.py) _(top level)_  ?
@ubdussamad Yes! But import it from its original location, `_collections`.
@pquentin  For the documentation, would including usage exmaples of  `HTTPHeaderDict` for setting http request headers be enough?
Also, [user-guide](https://github.com/urllib3/urllib3/blob/main/docs/user-guide.rst) is the file I am supposed to edit (for documentation) right?

I am planning to give example like this: 
`
```
import urllib3
from urllib3 import HTTPHeaderDict

print("Urllib Version: "  + urllib3.__version__)

requestHeaders = HTTPHeaderDict()
requestHeaders.add('Set-Cookie', 'foo=bar') # Set custom cookies
requestHeaders.add('set-cookie', 'baz=quxx')
print(requestHeaders['SET-cookie'])

http = urllib3.PoolManager()

url = 'https://httpbin.org/get'

req = http.request('GET', url, headers= requestHeaders) # supply the HTTPHeaderDict object to the headers symbol.

print(req.data.decode('utf-8'))

```
Would this example be fine?
Do I need to write tests for this?

Sorry if I am bothering you too much, I am new to this and can't find much info.
> @pquentin For the documentation, would including usage exmaples of `HTTPHeaderDict` for setting http request headers be enough?

Yes!

> Also, [user-guide](https://github.com/urllib3/urllib3/blob/main/docs/user-guide.rst?rgh-link-date=2021-05-12T12%3A58%3A34Z) is the file I am supposed to edit (for documentation) right?

Right, in the "Header" section, after the dictionary example. (I actually hesitated a bit between the User Guide and Advanced Usage, but the strong wording from @sigmavirus24 suggests that User is fine.)
 
> I am planning to give example like this:
> 
> ```
> [snip]
> ```
> 
> Would this example be fine?

The basic idea is fine, yes! Can you format it in the same way as the current headers example? (Also, `headers` is fine, `requestHeaders` is too verbose and we use snake_case anyway.)

> Do I need to write tests for this?

Nope, not needed. We only run documentation examples by hand.
 
> Sorry if I am bothering you too much, I am new to this and can't find much info.

You're not bothering, that's the whole point of Contributor Friendly issues! And your questions make perfect sense. :+1:


Resolving patch:
diff --git a/src/urllib3/__init__.py b/src/urllib3/__init__.py
--- a/src/urllib3/__init__.py
+++ b/src/urllib3/__init__.py
@@ -8,6 +8,7 @@
 from logging import NullHandler
 
 from . import exceptions
+from ._collections import HTTPHeaderDict
 from ._version import __version__
 from .connectionpool import HTTPConnectionPool, HTTPSConnectionPool, connection_from_url
 from .filepost import encode_multipart_formdata
@@ -23,6 +24,7 @@
 
 __all__ = (
     "HTTPConnectionPool",
+    "HTTPHeaderDict",
     "HTTPSConnectionPool",
     "PoolManager",
     "ProxyManager",


Test patch: