| Name | requests-builder JSON |
| Version |
1.0.0
JSON |
| download |
| home_page | None |
| Summary | A helper package for building HTTP requests with the requests package |
| upload_time | 2024-04-27 12:28:54 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | None |
| keywords |
requests
http
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Request Builder
A utility for building requests with the `requests` library
## Key Features
- dot-notation for path expansions
- call-notation to add different parameters
- slash-notation to send request, using a `requests` function of a method string
- double-slash-notation for post-processing responses
## Examples
### Initialization
```python
from request_builder import RequestBuilder
rb = RequestBuilder('https://example.domain.com')
```
### Expanding the path
```python
# New path will be https://example.domain.com/path/to/endpoint
rb = rb.path.to.endpoint
# Overriding the existing path
rb.path = 'https://example.domain.com/path'
```
### Adding query parameters to request
```python
# Request will now send the two params added
rb = rb(param1='value1', param2='value2')
# Query params are additive, so you can add more and override existing values
rb = rb(param3='value3', param1='value4') # params are now ?param1=value4¶m2=value2¶m3=value3
# You can override all params by setting them directly on the request builder
rb.params = {'param1': 'value2'} # all existing params got overridden
```
### Adding other additive request parameters
**Note:** The same principal applies to the `files` parameter
```python
rb = rb(headers={'X-Custom-Header': 'some_value'})
# Like query params, headers are also additive
rb = rb(header={'X-Another-Custom-Header': 'some_other_value'}) # 2 headers are now present
# And like query params, headers can also be overridden entirely
rb.headers = {'X-Final-Custom-Header': 'another_value'} # all existing headers got overridden
```
### Adding data to request
The type of data and the processing will depend on the type of request builder used.
The regular `RequestBuilder` expects data for the `data` parameter of `requests` functions,
The `JSONRequestsBuilder` expects a JSON-serializable object and will pass it to the `json`
parameter of `requests` functions. The `XMLRequestsBuilder` expects an XML element from the
XML python library (specifically, `xml.etree.ElementTree.Element`), which it will then
dump as bytes and send to the `data` parameter of the `requests` functions.
```python
rb = rb(b'Some data to send to the server')
# Setting the data again will override the existing data, as it is a non-additive parameter
rb = rb(b'Other data to send to the server') # This overrides the previously set data
from request_builder import JSONRequestBuilder
jrb = JSONRequestBuilder('https://example.domain.com')
jrb = jrb({'some': 'json_data'}) # Will be passed to the `json` parameter
```
### Adding other non-additive request parameters
**Note:** The same principal applies to the `auth` and `stream` parameters
```python
rb = rb(timeout=3.0)
# Setting timeout again will override the previous one
rb = rb(timeout=(2.0, 1.0))
```
### Adding cookies
Cookies are a special case because `requests` accepts both dictionaries and `CookieJar` objects,
so handling them is a little more nuanced. Cookies are additive, and both types can be used
when setting them. If a `CookieJar` is set, adding cookies to it will convert the `CookieJar`
to a dictionary and add the new cookies (this will happen whether the added cookies are in the
form of a `CookieJar` or a dictionary), but as long as no cookies are added the `CookieJar` will
not change its type. If a dictionary is set, all added cookies, no matter what form, will be
added to a dictionary.
```python
rb = rb(cookies='<a_cookie_jar>') # As long as cookies aren't added, the CookieJar will remain
# Adding other cookies will break the jar and create a dictionary with the cookies from the jar
# and the added cookies
rb = rb(cookies={'cookie1': 'cookie_value1'})
# A CookieJar can be added to another CookieJar or a dictionary, it will break the jar and add
# the cookies together
rb = rb(cookies='<another_cookie_jar>')
```
### Sending the request
To send the request to the server, slash-notation is used. A function can be used with the
`RequestBuilder` or an HTTP method. The returned data-type if a `requests.Response` object.
#### Using an HTTP method
```python
response = 'GET' / rb
# Also works the other way around!
response = rb / 'POST'
```
#### Using a custom function
```python
import requests
response = requests.get / rb
response = rb / requests.post
```
### Getting a processed response
The request builder can be used raw (with a single slash) or return a processed response, using
double-slash notation. Like the raw form, both HTTP method strings and custom functions can be used.
The return type will depend on the type of `RequestBuilder` used. The raw one will just return the
raw response bytes, the `JSONRequestBuilder` will return the output of calling the `json()` method
on the response, and `XMLRequestBuilder` will try to parse the response bytes as an XML element and
then return it (the return type will be `xml.etree.ElementTree.Element`).
```python
from request_builder import JSONRequestBuilder
rb = JSONRequestBuilder('https://example.domain.com')
response_json = 'GET' // rb
response_json = rb // 'GET' # Also works!
```
#### Error suppression
Additionally, there is an option when initializing the builder to supress errors. By default, request
builders will raise an error for non-OK HTTP response codes and parsing issues, but if the suppression
option if turned on all errors will be suppressed and the following behaviour will be occurring:
- If the response code is not ok (so if `response.ok` is `False`), no error will be raised and the
response data will be passed to processing.
- If the parsing fails, the raw response bytes will be returned instead.
```python
from request_builder import RequestBuilder
rb = RequestBuilder('https://example.domain.com', suppress_errors=True) # All errors will be suppressed
```
## Parameter Reference
All parameters can be set through the initialization of the builder and setting attributes afterward,
but only some can be set through the `__call__` function. The breakdown is as follows:
### Additive parameters
- `params` (through kwargs in `__call__`)
- `headers`
- `files`
- `cookies`
### Non-additive-parameters
- `data` (1st positional argument in `__call__`)
- `auth`
- `timeout`
- `stream`
### Init-only parameters (not available to set through `__call__`)
- `cert`
- `allow_redirects`
- `verify`
- `proxies`
### RequestBuilder custom parameters
- `suppress_errors` (cannot be changed after initialization)
Raw data
{
"_id": null,
"home_page": null,
"name": "requests-builder",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "Requests, HTTP",
"author": null,
"author_email": "Dor Genosar <dor.genosar@outlook.com>",
"download_url": "https://files.pythonhosted.org/packages/c2/ac/2ec55c5f76bdfe26d4876162a7792a6ab64b77534f3b21f48bcd3f08b9c9/requests_builder-1.0.0.tar.gz",
"platform": null,
"description": "# Request Builder\r\nA utility for building requests with the `requests` library\r\n\r\n## Key Features\r\n\r\n- dot-notation for path expansions\r\n- call-notation to add different parameters\r\n- slash-notation to send request, using a `requests` function of a method string\r\n- double-slash-notation for post-processing responses\r\n\r\n## Examples\r\n\r\n### Initialization\r\n\r\n```python\r\nfrom request_builder import RequestBuilder\r\n\r\nrb = RequestBuilder('https://example.domain.com')\r\n```\r\n\r\n### Expanding the path\r\n\r\n```python\r\n# New path will be https://example.domain.com/path/to/endpoint\r\nrb = rb.path.to.endpoint\r\n\r\n# Overriding the existing path\r\nrb.path = 'https://example.domain.com/path'\r\n```\r\n\r\n### Adding query parameters to request\r\n\r\n```python\r\n# Request will now send the two params added\r\nrb = rb(param1='value1', param2='value2')\r\n\r\n# Query params are additive, so you can add more and override existing values\r\nrb = rb(param3='value3', param1='value4') # params are now ?param1=value4¶m2=value2¶m3=value3\r\n\r\n# You can override all params by setting them directly on the request builder\r\nrb.params = {'param1': 'value2'} # all existing params got overridden\r\n```\r\n\r\n### Adding other additive request parameters\r\n\r\n**Note:** The same principal applies to the `files` parameter\r\n\r\n```python\r\nrb = rb(headers={'X-Custom-Header': 'some_value'})\r\n\r\n# Like query params, headers are also additive\r\nrb = rb(header={'X-Another-Custom-Header': 'some_other_value'}) # 2 headers are now present\r\n\r\n# And like query params, headers can also be overridden entirely\r\nrb.headers = {'X-Final-Custom-Header': 'another_value'} # all existing headers got overridden\r\n```\r\n\r\n### Adding data to request\r\n\r\nThe type of data and the processing will depend on the type of request builder used.\r\nThe regular `RequestBuilder` expects data for the `data` parameter of `requests` functions,\r\nThe `JSONRequestsBuilder` expects a JSON-serializable object and will pass it to the `json`\r\nparameter of `requests` functions. The `XMLRequestsBuilder` expects an XML element from the\r\nXML python library (specifically, `xml.etree.ElementTree.Element`), which it will then\r\ndump as bytes and send to the `data` parameter of the `requests` functions.\r\n\r\n```python\r\nrb = rb(b'Some data to send to the server')\r\n\r\n# Setting the data again will override the existing data, as it is a non-additive parameter\r\nrb = rb(b'Other data to send to the server') # This overrides the previously set data\r\n\r\nfrom request_builder import JSONRequestBuilder\r\n\r\njrb = JSONRequestBuilder('https://example.domain.com')\r\njrb = jrb({'some': 'json_data'}) # Will be passed to the `json` parameter\r\n```\r\n\r\n### Adding other non-additive request parameters\r\n\r\n**Note:** The same principal applies to the `auth` and `stream` parameters\r\n\r\n```python\r\nrb = rb(timeout=3.0)\r\n\r\n# Setting timeout again will override the previous one\r\nrb = rb(timeout=(2.0, 1.0))\r\n```\r\n\r\n### Adding cookies\r\n\r\nCookies are a special case because `requests` accepts both dictionaries and `CookieJar` objects,\r\nso handling them is a little more nuanced. Cookies are additive, and both types can be used\r\nwhen setting them. If a `CookieJar` is set, adding cookies to it will convert the `CookieJar`\r\nto a dictionary and add the new cookies (this will happen whether the added cookies are in the\r\nform of a `CookieJar` or a dictionary), but as long as no cookies are added the `CookieJar` will\r\nnot change its type. If a dictionary is set, all added cookies, no matter what form, will be\r\nadded to a dictionary.\r\n\r\n```python\r\nrb = rb(cookies='<a_cookie_jar>') # As long as cookies aren't added, the CookieJar will remain\r\n\r\n# Adding other cookies will break the jar and create a dictionary with the cookies from the jar\r\n# and the added cookies\r\nrb = rb(cookies={'cookie1': 'cookie_value1'})\r\n\r\n# A CookieJar can be added to another CookieJar or a dictionary, it will break the jar and add\r\n# the cookies together\r\nrb = rb(cookies='<another_cookie_jar>')\r\n```\r\n\r\n### Sending the request\r\n\r\nTo send the request to the server, slash-notation is used. A function can be used with the\r\n`RequestBuilder` or an HTTP method. The returned data-type if a `requests.Response` object.\r\n\r\n#### Using an HTTP method\r\n\r\n```python\r\nresponse = 'GET' / rb\r\n\r\n# Also works the other way around!\r\nresponse = rb / 'POST'\r\n```\r\n\r\n#### Using a custom function\r\n\r\n```python\r\nimport requests\r\n\r\nresponse = requests.get / rb\r\n\r\nresponse = rb / requests.post\r\n```\r\n\r\n### Getting a processed response\r\n\r\nThe request builder can be used raw (with a single slash) or return a processed response, using\r\ndouble-slash notation. Like the raw form, both HTTP method strings and custom functions can be used.\r\nThe return type will depend on the type of `RequestBuilder` used. The raw one will just return the\r\nraw response bytes, the `JSONRequestBuilder` will return the output of calling the `json()` method\r\non the response, and `XMLRequestBuilder` will try to parse the response bytes as an XML element and\r\nthen return it (the return type will be `xml.etree.ElementTree.Element`).\r\n\r\n```python\r\nfrom request_builder import JSONRequestBuilder\r\n\r\nrb = JSONRequestBuilder('https://example.domain.com')\r\nresponse_json = 'GET' // rb\r\n\r\nresponse_json = rb // 'GET' # Also works!\r\n```\r\n\r\n#### Error suppression\r\n\r\nAdditionally, there is an option when initializing the builder to supress errors. By default, request\r\nbuilders will raise an error for non-OK HTTP response codes and parsing issues, but if the suppression\r\noption if turned on all errors will be suppressed and the following behaviour will be occurring:\r\n\r\n- If the response code is not ok (so if `response.ok` is `False`), no error will be raised and the\r\n response data will be passed to processing.\r\n- If the parsing fails, the raw response bytes will be returned instead.\r\n\r\n```python\r\nfrom request_builder import RequestBuilder\r\n\r\nrb = RequestBuilder('https://example.domain.com', suppress_errors=True) # All errors will be suppressed\r\n```\r\n\r\n## Parameter Reference\r\n\r\nAll parameters can be set through the initialization of the builder and setting attributes afterward,\r\nbut only some can be set through the `__call__` function. The breakdown is as follows:\r\n\r\n### Additive parameters\r\n\r\n- `params` (through kwargs in `__call__`)\r\n- `headers`\r\n- `files`\r\n- `cookies`\r\n\r\n### Non-additive-parameters\r\n\r\n- `data` (1st positional argument in `__call__`)\r\n- `auth`\r\n- `timeout`\r\n- `stream`\r\n\r\n### Init-only parameters (not available to set through `__call__`)\r\n\r\n- `cert`\r\n- `allow_redirects`\r\n- `verify`\r\n- `proxies`\r\n\r\n### RequestBuilder custom parameters\r\n\r\n- `suppress_errors` (cannot be changed after initialization)\r\n",
"bugtrack_url": null,
"license": null,
"summary": "A helper package for building HTTP requests with the requests package",
"version": "1.0.0",
"project_urls": {
"Homepage": "https://github.com/labrador-team/request-builder",
"Issues": "https://github.com/labrador-team/request-builder/issues"
},
"split_keywords": [
"requests",
" http"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "01fcdf076b058096b64fccbea052d46dc549e817164c1d814de34063c37ec0f2",
"md5": "8271b0d1bf9b12fb324ac2a6fe85dba3",
"sha256": "8e191b9a2eb7e7e08121056d30d3481b5757cf793a70b915735526d43883291e"
},
"downloads": -1,
"filename": "requests_builder-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8271b0d1bf9b12fb324ac2a6fe85dba3",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 11451,
"upload_time": "2024-04-27T12:28:50",
"upload_time_iso_8601": "2024-04-27T12:28:50.485976Z",
"url": "https://files.pythonhosted.org/packages/01/fc/df076b058096b64fccbea052d46dc549e817164c1d814de34063c37ec0f2/requests_builder-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c2ac2ec55c5f76bdfe26d4876162a7792a6ab64b77534f3b21f48bcd3f08b9c9",
"md5": "8dff44235e380f8c22ce463929e61df8",
"sha256": "dd19b7c4aec0771cfcd657d58c330654da8b2c106264256d0ad02be7fd87807a"
},
"downloads": -1,
"filename": "requests_builder-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "8dff44235e380f8c22ce463929e61df8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 14259,
"upload_time": "2024-04-27T12:28:54",
"upload_time_iso_8601": "2024-04-27T12:28:54.088790Z",
"url": "https://files.pythonhosted.org/packages/c2/ac/2ec55c5f76bdfe26d4876162a7792a6ab64b77534f3b21f48bcd3f08b9c9/requests_builder-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-27 12:28:54",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "labrador-team",
"github_project": "request-builder",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "requests-builder"
}
