{"id":13801719,"url":"https://github.com/SpotlightKid/mrequests","last_synced_at":"2025-05-13T11:31:43.666Z","repository":{"id":45916153,"uuid":"371147395","full_name":"SpotlightKid/mrequests","owner":"SpotlightKid","description":"An HTTP client library (not only) for MicroPython with an API similar to requests","archived":false,"fork":false,"pushed_at":"2024-06-20T00:11:49.000Z","size":95,"stargazers_count":60,"open_issues_count":0,"forks_count":11,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-04-07T13:51:27.755Z","etag":null,"topics":["esp2866","esp32","http","http-client","https","micropython","python","raspberry-pi-pico","requests","rp2","sockets","ssl","stm32","tls"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SpotlightKid.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-05-26T19:27:21.000Z","updated_at":"2025-03-28T14:06:29.000Z","dependencies_parsed_at":"2024-01-29T19:30:20.949Z","dependency_job_id":"978fa489-b171-49ed-8f32-41605d46d8e2","html_url":"https://github.com/SpotlightKid/mrequests","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SpotlightKid%2Fmrequests","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SpotlightKid%2Fmrequests/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SpotlightKid%2Fmrequests/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SpotlightKid%2Fmrequests/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SpotlightKid","download_url":"https://codeload.github.com/SpotlightKid/mrequests/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253932932,"owners_count":21986479,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["esp2866","esp32","http","http-client","https","micropython","python","raspberry-pi-pico","requests","rp2","sockets","ssl","stm32","tls"],"created_at":"2024-08-04T00:01:26.322Z","updated_at":"2025-05-13T11:31:38.830Z","avatar_url":"https://github.com/SpotlightKid.png","language":"Python","readme":"# mrequests\n\nAn HTTP client module for MicroPython with an API *similar* to [requests].\n\nThis is an evolution of the [urequests] module from [micropython-lib] with a few\nextensions and many fixes and convenience features.\n\n\n## Features \u0026 Limitations\n\n\n### Compatibility\n\nSupports many MicroPython ports as well as CPython.\n\n| Port    | Tested on                                     | Notes                                                                                                                        |\n| ------- | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |\n| esp32   | GOOUUU-ESP32 (ESP-WROOM-32)                   |                                                                                                                              |\n| esp32s3 | Waveshare ESP32-S3-Zero                       |                                                                                                                              |\n| esp32c3 | Seeed Xiao-ESP32-C3                           |                                                                                                                              |\n| rp2     | Raspberry Pi Pico W                           |\n| esp8266 | LoLin NodeMcu v3 (ESP8266MOD)                 | Limited SSL/TLS support due to problems with ports `ssl` module                                                              |\n| stm32   | STM32F407VET6 / WIZNET W5500 Ethernet adapter | (Custom) firmware with network/SSL support enabled required. Limited SSL/TLS support due to problems with ports `ssl` module |\n| unix    | Arch Linux                                    | Limited SSL/TLS support due to problems with ports `ssl` module                                                              |\n\n\n### Features\n\n* Supports SSL/TLS with server certificate validation (as far as supported by\n  the `ssl` module of a given MicroPython port).\n* Supports redirection with absolute and relative URLs (see below for details).\n* Supports HTTP basic authentication (requires `binascii` module).\n* Supports socket timeouts.\n* Response headers can optionally be saved in the response object.\n* Respects `Content-length` header in response.\n* Supports responses with chunked transfer encoding.\n* `Response` objects have a `readinto` method to store the response body to a\n  given buffer (or `memoryview`) in chunks of maximum `len(buffer)` size.\n* `Response` objects have `save` and `saveto` methods to save the response\n  body to a file (given by filename resp. file object), reading the response\n  data and writing the file in small chunks.\n* The `Response` class for response objects can be substituted by a custom\n  response class (usually defined by subclassing `Response`).\n\n\n### Limitations\n\n* `mrequests.request` is a synchroneous, blocking function.\n* The code is *not* interrupt save and a fair amount of memory allocation is\n  happening in the process of handling a request.\n* URL parsing does not cover all corner cases (see [test_urlparse] for details).\n* URLs with authentication credentials in the host part (e.g.\n  `http://user:secret@myhost/`) are *not supported*. Pass authentication\n  credentials separately via the `auth` argument instead.\n* SSL/TLS support on the MicroPython `unix`, `stm32` and `esp8266` ports is\n  limited. In particular, their `ssl` module does not support all encryption\n  schemes commonly in use by popular servers, meaning that trying to connect\n  to them via HTTPS will fail with various cryptic error messages.\n\n    On the `esp8266` port no TLS server certificate validation is performed.\n* Request and JSON data may be passed in as `bytes` or strings and the request\n  data will be encoded to `bytes`, if necessary, using the encoding given with\n  the `encoding` parameter. But be aware that encodings other than `utf-8` are\n  *not supported* by most (any?) MicroPython implementations.\n* Custom headers may be passed as a dictionary with `bytes` keys and values\n  and keys and values must contain only ASCII chars. If you need header values\n  to use non-ASCII chars, you need to encode them according to RFC 8187.\n\n    The header dictionary *may* contain also string keys and values, but:\n\n    * Using MicroPython, it causes `Warning: Comparison between bytes and str`\n      to be printed to the standard error output when calling `request`.\n    * It causes additional memory allocations.\n    * The \"Host\" header (if present) must always use `b\"Host\"` as the header\n      dictionary key, i.e. it must be of type `bytes` and use this exact\n      capitalization (unless the headers dictionary uses an implementation with\n      case-insensitive key lookup).\n* The URL and specifically any query string parameters it contains will not be\n  URL-encoded, and it may contain only ASCII chars. Make sure you encode the\n  query string part of the URL with `urlencode.quote` before passing it, if\n  necessary.\n* When encoding `str` instances via `urlencode.urlencode` or `urlencode.quote`,\n  the `encoding` and `errors` arguments are currently ignored by MicroPython and\n  it behaves as if their values were `\"utf-8\"` resp. `\"ignore\"`.\n* In responses using \"chunked\" transfer-encoding, chunk extensions and trailers\n  are ignored.\n\n\n### Redirection Support\n\n* Can follow redirects for response status codes 301, 302, 303, 307 and 308.\n* The HTTP method is changed to `GET` for redirects, unless the original\n  method was `HEAD` or the status code is 307 or 308.\n* For status code 303, if the method of the request resulting in a redirection\n  (which may have been the result of a previous redirection) is `GET`, the\n  redirection is not followed, since the `Location` header is supposed to\n  indicate a non-HTTP resource then.\n* Redirects are allowed to change the protocol from `http` to `https`,\n  but redirects changing from `https` to `http` will not be followed.\n* The `request` function has an additional keyword argument `max_redirects`,\n  defaulting to 1, which controls how many levels of redirections are followed.\n  If this is exceeded, the function raises a `ValueError`.\n* The code does not check for infinite redirection cycles. It is advised to\n  keep `max_redirects` to a low number instead.\n\n\n## Installation\n\nWhile there are multiple ways to install the library from your PC's command\nline, three different installation methods are provided via different scripts:\n\n* `install_mpremote.sh`(Bash script using [mpremote] binary)\n* `install.sh` (Bash script using [rshell] binary, legacy)\n* `install.py` (Python script using `mpremote` as a library)\n\n\n### `install_mpremote.sh`\n\nThe following should be installed and in your shell's `PATH`:\n\n* `mpy-cross`\n* `mpremote`\n\nRun the command:\n\n```con\n./install_mpremote.sh\n```\n\nThis will compile the Python modules with `mpy-cross` and copy the resulting\n`.mpy` files to the board's flash using the `mpremote` command.\n\n\n### `install.sh`\n\nThe following should be installed and in your shell's `PATH`:\n\n* `mpy-cross`\n* `rshell`\n\nFor boards with the `stm32` port run:\n\n```con\nDESTDIR=/flash ./install.sh\n```\n\nFor boards with the `esp8266` or `esp32` port run:\n\n```con\nDESTDIR=/pyboard PORT=/dev/ttyUSB0 BAUD=115200 ./install.sh\n```\n\nThis will compile the Python modules with `mpy-cross` and copy the resulting\n`.mpy` files to the board's flash using the `rshell` comamnd.\n\n\n### `install.py`\n\nThe following should be installed and in your shell's `PATH`:\n\n* `mpy-cross`\n\nAlso, `mpremote` should be available on your `PYTHONPATH`, e.g. installed via\n`pip`:\n\n```con\npython -m pip install mpremote\n```\n\nThen simply run `install.py`:\n\n```con\n./install.py\n```\n\nThis will compile the Python modules with `mpy-cross` and copy the resulting\n`.mpy` files to the board's flash using the `mpremote` library. Run\n`install.py -h` to review installation options.\n\n\n### Manual installation\n\nFor the `unix` port, just copy the `mrequest` directory with all files in it\nto a directory, which is in `sys.path`, e.g. `~/.micropython/lib`, or set the\n`MICROPYPATH` environment variable to a colon-separated list of directories\nincluding the one to which you copied the package directory.\n\nNote: the `mrequests/mrequests.py` module has no dependencies besides modules\nusually already built in to the MicroPython firmware on all ports (as of\nversion \u003e= 1.15) and can be installed and used on its own if flash storage\nspace or available RAM is scarce. The other modules in the `mrequests` package\nprovide support for specific tasks like, for example, sending form-encoded\nrequest parameters or data or parsing url-encoded strings (see the scripts in\nthe `examples` directory for examples of their use).\n\n\n## Examples\n\nBelow are some basic usage examples of the `mrequests` module. More examples\nfor special tasks can be found in the scripts in the [examples](./examples)\ndirectory. Some of these examples require extra modules from [micropython-lib].\nTo install these requirements to a MicroPython board you can use [mpremote]:\n\n```con\nmpremote mip install collections-defaultdict\n```\n\n\n### Simple GET request with JSON response\n\n```py\n\u003e\u003e\u003e import mrequests as requests\n\u003e\u003e\u003e r = requests.get(\"http://httpbin.org/get\",\n                     headers={\"Accept\": \"application/json\"})\n\u003e\u003e\u003e print(r)\n\u003cResponse object at 7f6f91631be0\u003e\n\u003e\u003e\u003e print(r.content)\nb'{\\n  \"args\": {}, \\n  \"headers\": {\\n    \"Accept\": \"application/json\", \\n\n\"Host\": \"httpbin.org\", \\n    \"X-Amzn-Trace-Id\": \"Root=1-[redacted]\"\\n  }, \\n\n\"origin\": \"[redacted]\", \\n  \"url\": \"http://httpbin.org/get\"\\n}\\n'\n\u003e\u003e\u003e print(r.text)\n{\n  \"args\": {},\n  \"headers\": {\n    \"Accept\": \"application/json\",\n    \"Host\": \"httpbin.org\",\n    \"X-Amzn-Trace-Id\": \"Root=1-[redacted]\"\n  },\n  \"origin\": \"[redacted]\",\n  \"url\": \"http://httpbin.org/get\"\n}\n\n\u003e\u003e\u003e print(r.json())\n{'url': 'http://httpbin.org/get', 'headers': {'X-Amzn-Trace-Id':\n'Root=1-[redacted]', 'Host': 'httpbin.org', 'Accept': 'application/json'},\n'args': {}, 'origin': '[redacted]'}\n\u003e\u003e\u003e r.close()\n```\n\nIt is mandatory to close response objects as soon as you finished working with\nthem. On MicroPython platforms without full-fledged OS, not doing so may lead\nto resource leaks and malfunction.\n\n\n### HTTP Basic Auth\n\n```py\n\u003e\u003e\u003e import mrequests as requests\n\u003e\u003e\u003e user = \"joedoe\"\n\u003e\u003e\u003e password = \"simsalabim\"\n\u003e\u003e\u003e url = \"http://httpbin.org/basic-auth/%s/%s\" % (user, password)\n\u003e\u003e\u003e r = requests.get(url, auth=(user, password))\n\u003e\u003e\u003e print(r.text)\n{\n  \"authenticated\": true,\n  \"user\": \"joedoe\"\n}\n\u003e\u003e\u003e r.close()\n```\n\n\n## Reference\n\nThe main function provided by `mrequests` is `request`, which takes an HTTP\nmethod and a URL as positional arguments and several optional keyword arguments\nand returns a `Response` object:\n\n```py\nrequest(method, url, data=None, json=None, headers={}, auth=None,\n        encoding=None, response_class=Response, save_headers=False,\n        max_redirects=1, timeout=None, ssl_context=None)\n```\n\nParameters:\n\n*method (str)* - the HTTP request method as a string in all-caps.\n\n*url (str)* - the URL of the request as a string. This must be an absolute URL,\nincluding the protocol (only `http://` and `https://` are supported) and a host\nname or IP address. The server name may be suffixed with a port number,\nseparated by a colon. The default port is 80 for `http` URLs and 443 for\n`https`.\n\nAuthentication credentials in the host part are not supported (see the *auth*\nparameter below).\n\nThe URL may contain only ASCII chars. The caller is responsible for encoding\nany non-ASCII chars in the path or the query string (for example with\n`urlencode.quote`) or encoding IDN host names if necessary.\n\n*data (bytes, str)* - the request body data as `bytes` or `str` instance. If\ngiven as a string, it will be converted to `bytes` using the encoding given\nwith the `encoding` parameter (requiring additional memory to allocate the new\nbytes object). The caller is responsible for formatting the request data\naccording to the content type specified in the request headers.\n\n*json (obj)* - an object, which will be encoded as JSON and sent as the request\nbody data. Also adds a `Content-Type` header with the value `application/json`.\nThis overwrites data passed with the *data* parameter and allocates memory for\nthe request data. To avoid allocation, pass a JSON-encoded byte string with the\n*data* parameter instead.\n\n*headers (dict)* - a dictionary of additional request headers to sent. Keys and\nvalues should be `bytes` instances and may contain only ASCII chars. They *may*\nbe `str` instances, but see \"Limitations\". `str` keys and values will be\nconverted to `bytes` using ASCII encoding, which causes memory allocation.\n\nA `Content-Length` header will always be added, using the length of the request\ndata as the value. If no `b\"Host\"` key is present in the header dictionary, the\n`Host` header value will be generated based on the host name from the URL.\n\n*auth (tuple)* - HTTP basic authentication credentials given as a\n`(user, password)` tuple of `bytes` objects or a callable, returning such a\ntuple. Some MicroPython versions may also accept `str` instances as the tuple\nelements but may issue a warning message. This will overwrite `Authorization`\nheaders passed in with the *headers* parameter.\n\n*encoding (str)* - the encoding of the request body data, if the the data is\npassed in as a `str` instance with the *data* or *json* parameters. Defauts to\n`utf-8`.\n\n*response_class (obj)* - the class to use for the returned response objects.\nDefaults to `mrequests.Response`. Custom response classes should sub-class\n`mrequests.Response` and must take the same constructor arguments.\n\n*save_headers (bool)* - a boolean, which is passed to the constructor of the\nresponse class instance, which determines whether it keeps a reference to the\nresponse headers in the instance. This is set to `False` by default to save\nmemory. If set to `True`, the default response class will make the reponse\nheader lines available via its `headers` instance attribute as a list of\nunparsed `bytes` objects.\n\n*max_redirects (int)* - the maximum number of valid redirections to follow.\nDefaults to 1. If too many redirections are encountered, a `ValueError` is\nraised.\n\n*timeout (float)* - sets the timeout for the connection socket as a\nnon-negative float in seconds. Defaults to `None`, which blocks indefinitely.\nIf a non-zero value is given, connection attempts or socket read/write\noperations will raise `OSError` if the timeout period value has elapsed before\nthe operation has completed. If zero is given, the socket is put in\nnon-blocking mode.\n\n*ssl_context (ssl.SSLContext)* - pass a custom `ssl.SSLContext` instance to\nconfigure TLS encryption and certificate handling. If performing an HTTPS\nrequest and no SSL context is passed, a default one is created, which allows\nan encrypted connection, but does not require the server to present a valid\ncertificate. If the MicroPython port has proper SSL support, it is strongly\nrecommended to pass your own SSL context instance, which has its `verify_mode`\nattribute set to `ssl.CERT_REQUIRED` and the required certificates loaded.\nSee the documentation of the [ssl module] for details.\n\n---\n\nSeveral convenience wrappers for creating request using common HTTP methods are\navailable:\n\n```py\nhead(url, **kw)\n\nget(url, **kw)\n\npost(url, **kw)\n\nput(url, **kw)\n\npatch(url, **kw)\n\ndelete(url, **kw)\n```\n\nThe url and all keyword arguments are simply passed to `request`.\n\n\n## Authors\n\n**mrequests** is based on [urequests], written by *Paul Sokolovsky* and\npart of [micropython-lib] and licensed under the [MIT license]. It was further\ndeveloped and is maintained by *Christopher Arndt*.\n\n\n## License\n\n**mrequests** is distributed under the terms of the [MIT license] and is free\nand Open Source software.\n\nPlease see the file [LICENSE](./LICENSE) for details.\n\n[micropython-lib]: https://github.com/micropython/micropython-lib\n[mit license]: http://opensource.org/licenses/MIT\n[mpremote]: https://docs.micropython.org/en/latest/reference/mpremote.html\n[requests]: https://github.com/psf/requests\n[rshell]: https://pypi.org/project/rshell/\n[ssl module]: https://docs.micropython.org/en/latest/library/ssl.html#class-sslcontext\n[test_urlparse]: ./tests/test_urlparse.py\n[urequests]: https://github.com/micropython/micropython-lib/blob/master/urequests/urequests.py\n","funding_links":[],"categories":["Libraries"],"sub_categories":["Communications"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FSpotlightKid%2Fmrequests","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FSpotlightKid%2Fmrequests","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FSpotlightKid%2Fmrequests/lists"}