import requestscore
Generate Markdown Files From A Python Library
get_modules
get_modules (lib:module)
get a list of modules from a python package
For example, we can list all the modules in the requests library:
mods = get_modules(requests)
mods['requests.adapters',
'requests.api',
'requests.auth',
'requests.certs',
'requests.compat',
'requests.cookies',
'requests.exceptions',
'requests.help',
'requests.hooks',
'requests.models',
'requests.packages',
'requests.sessions',
'requests.status_codes',
'requests.structures',
'requests.utils']MarkdownDoc
MarkdownDoc ()
Formatter class for text documentation.
render_quarto_md
render_quarto_md (thing, title=None, forceload=0)
Render text documentation, given an object or a path to an object.
gethelp
gethelp (modname:str, title:str=None)
Get the help string for a module in a markdown format.
This is an example of how the docs are rendered for requests.models:
::: {.cell}
print(gethelp('requests.models'))::: {.cell-output .cell-output-stdout}
---
title: "requests.models"
description: "module requests.models in requests"
---
## Description
requests.models
~~~~~~~~~~~~~~~
This module contains the primary objects that power Requests.
## Classes
builtins.object
RequestEncodingMixin
PreparedRequest(RequestEncodingMixin, RequestHooksMixin)
RequestHooksMixin
Request
Response
### PreparedRequest
```{=html}
<blockquote><strong><code>class PreparedRequest(RequestEncodingMixin, RequestHooksMixin)</code></strong></blockquote> | The fully mutable :class:`PreparedRequest <PreparedRequest>` object,
| containing the exact bytes that will be sent to the server.
|
| Instances are generated from a :class:`Request <Request>` object, and
| should not be instantiated manually; doing so may produce undesirable
| effects.
|
| Usage::
|
| >>> import requests
| >>> req = requests.Request('GET', 'https://httpbin.org/get')
| >>> r = req.prepare()
| >>> r
| <PreparedRequest [GET]>
|
| >>> s = requests.Session()
| >>> s.send(r)
| <Response [200]>
|
| Method resolution order:
| PreparedRequest
| RequestEncodingMixin
| RequestHooksMixin
| builtins.object
|
| Methods defined here:
|
| PreparedRequest.__init__
|
| __init__(self)
| Initialize self. See help(type(self)) for accurate signature.
|
| PreparedRequest.__repr__
|
| __repr__(self)
| Return repr(self).
|
| PreparedRequest.copy
|
| copy(self)
|
| PreparedRequest.prepare
|
| prepare(self, method=None, url=None, headers=None, files=None, data=None, params=None, auth=None, cookies=None, hooks=None, json=None)
| Prepares the entire request with the given parameters.
|
| PreparedRequest.prepare_auth
|
| prepare_auth(self, auth, url='')
| Prepares the given HTTP auth data.
|
| PreparedRequest.prepare_body
|
| prepare_body(self, data, files, json=None)
| Prepares the given HTTP body data.
|
| PreparedRequest.prepare_content_length
|
| prepare_content_length(self, body)
| Prepare Content-Length header based on request method and body
|
| PreparedRequest.prepare_headers
|
| prepare_headers(self, headers)
| Prepares the given HTTP headers.
|
| PreparedRequest.prepare_hooks
|
| prepare_hooks(self, hooks)
| Prepares the given hooks.
|
| PreparedRequest.prepare_method
|
| prepare_method(self, method)
| Prepares the given HTTP method.
|
| PreparedRequest.prepare_url
|
| prepare_url(self, url, params)
| Prepares the given HTTP URL.
|
| ----------------------------------------------------------------------
| Readonly properties inherited from RequestEncodingMixin:
|
| path_url
| Build the path URL to use.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from RequestEncodingMixin:
|
| __dict__
| dictionary for instance variables (if defined)
|
| __weakref__
| list of weak references to the object (if defined)
|
| ----------------------------------------------------------------------
| Methods inherited from RequestHooksMixin:
|
| RequestHooksMixin.deregister_hook
|
| deregister_hook(self, event, hook)
| Deregister a previously registered hook.
| Returns True if the hook existed, False if not.
|
| RequestHooksMixin.register_hook
|
| register_hook(self, event, hook)
| Properly register a hook.Request
class Request(RequestHooksMixin) | Request(method=None, url=None, headers=None, files=None, data=None, params=None, auth=None, cookies=None, hooks=None, json=None)
|
| A user-created :class:`Request <Request>` object.
|
| Used to prepare a :class:`PreparedRequest <PreparedRequest>`, which is sent to the server.
|
| :param method: HTTP method to use.
| :param url: URL to send.
| :param headers: dictionary of headers to send.
| :param files: dictionary of {filename: fileobject} files to multipart upload.
| :param data: the body to attach to the request. If a dictionary or
| list of tuples ``[(key, value)]`` is provided, form-encoding will
| take place.
| :param json: json for the body to attach to the request (if files or data is not specified).
| :param params: URL parameters to append to the URL. If a dictionary or
| list of tuples ``[(key, value)]`` is provided, form-encoding will
| take place.
| :param auth: Auth handler or (user, pass) tuple.
| :param cookies: dictionary or CookieJar of cookies to attach to this request.
| :param hooks: dictionary of callback hooks, for internal usage.
|
| Usage::
|
| >>> import requests
| >>> req = requests.Request('GET', 'https://httpbin.org/get')
| >>> req.prepare()
| <PreparedRequest [GET]>
|
| Method resolution order:
| Request
| RequestHooksMixin
| builtins.object
|
| Methods defined here:
|
| Request.__init__
|
| __init__(self, method=None, url=None, headers=None, files=None, data=None, params=None, auth=None, cookies=None, hooks=None, json=None)
| Initialize self. See help(type(self)) for accurate signature.
|
| Request.__repr__
|
| __repr__(self)
| Return repr(self).
|
| Request.prepare
|
| prepare(self)
| Constructs a :class:`PreparedRequest <PreparedRequest>` for transmission and returns it.
|
| ----------------------------------------------------------------------
| Methods inherited from RequestHooksMixin:
|
| RequestHooksMixin.deregister_hook
|
| deregister_hook(self, event, hook)
| Deregister a previously registered hook.
| Returns True if the hook existed, False if not.
|
| RequestHooksMixin.register_hook
|
| register_hook(self, event, hook)
| Properly register a hook.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from RequestHooksMixin:
|
| __dict__
| dictionary for instance variables (if defined)
|
| __weakref__
| list of weak references to the object (if defined)RequestEncodingMixin
class RequestEncodingMixin(builtins.object) | Readonly properties defined here:
|
| path_url
| Build the path URL to use.
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables (if defined)
|
| __weakref__
| list of weak references to the object (if defined)RequestHooksMixin
class RequestHooksMixin(builtins.object) | Methods defined here:
|
| RequestHooksMixin.deregister_hook
|
| deregister_hook(self, event, hook)
| Deregister a previously registered hook.
| Returns True if the hook existed, False if not.
|
| RequestHooksMixin.register_hook
|
| register_hook(self, event, hook)
| Properly register a hook.
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables (if defined)
|
| __weakref__
| list of weak references to the object (if defined)Response
class Response(builtins.object) | The :class:`Response <Response>` object, which contains a
| server's response to an HTTP request.
|
| Methods defined here:
|
| Response.__bool__
|
| __bool__(self)
| Returns True if :attr:`status_code` is less than 400.
|
| This attribute checks if the status code of the response is between
| 400 and 600 to see if there was a client error or a server error. If
| the status code, is between 200 and 400, this will return True. This
| is **not** a check to see if the response code is ``200 OK``.
|
| Response.__enter__
|
| __enter__(self)
|
| Response.__exit__
|
| __exit__(self, *args)
|
| Response.__getstate__
|
| __getstate__(self)
|
| Response.__init__
|
| __init__(self)
| Initialize self. See help(type(self)) for accurate signature.
|
| Response.__iter__
|
| __iter__(self)
| Allows you to use a response as an iterator.
|
| Response.__nonzero__
|
| __nonzero__(self)
| Returns True if :attr:`status_code` is less than 400.
|
| This attribute checks if the status code of the response is between
| 400 and 600 to see if there was a client error or a server error. If
| the status code, is between 200 and 400, this will return True. This
| is **not** a check to see if the response code is ``200 OK``.
|
| Response.__repr__
|
| __repr__(self)
| Return repr(self).
|
| Response.__setstate__
|
| __setstate__(self, state)
|
| Response.close
|
| close(self)
| Releases the connection back to the pool. Once this method has been
| called the underlying ``raw`` object must not be accessed again.
|
| *Note: Should not normally need to be called explicitly.*
|
| Response.iter_content
|
| iter_content(self, chunk_size=1, decode_unicode=False)
| Iterates over the response data. When stream=True is set on the
| request, this avoids reading the content at once into memory for
| large responses. The chunk size is the number of bytes it should
| read into memory. This is not necessarily the length of each item
| returned as decoding can take place.
|
| chunk_size must be of type int or None. A value of None will
| function differently depending on the value of `stream`.
| stream=True will read data as it arrives in whatever size the
| chunks are received. If stream=False, data is returned as
| a single chunk.
|
| If decode_unicode is True, content will be decoded using the best
| available encoding based on the response.
|
| Response.iter_lines
|
| iter_lines(self, chunk_size=512, decode_unicode=False, delimiter=None)
| Iterates over the response data, one line at a time. When
| stream=True is set on the request, this avoids reading the
| content at once into memory for large responses.
|
| .. note:: This method is not reentrant safe.
|
| Response.json
|
| json(self, **kwargs)
| Returns the json-encoded content of a response, if any.
|
| :param \*\*kwargs: Optional arguments that ``json.loads`` takes.
| :raises requests.exceptions.JSONDecodeError: If the response body does not
| contain valid json.
|
| Response.raise_for_status
|
| raise_for_status(self)
| Raises :class:`HTTPError`, if one occurred.
|
| ----------------------------------------------------------------------
| Readonly properties defined here:
|
| apparent_encoding
| The apparent encoding, provided by the charset_normalizer or chardet libraries.
|
| content
| Content of the response, in bytes.
|
| is_permanent_redirect
| True if this Response one of the permanent versions of redirect.
|
| is_redirect
| True if this Response is a well-formed HTTP redirect that could have
| been processed automatically (by :meth:`Session.resolve_redirects`).
|
| links
| Returns the parsed header links of the response, if any.
|
| next
| Returns a PreparedRequest for the next request in a redirect chain, if there is one.
|
| ok
| Returns True if :attr:`status_code` is less than 400, False if not.
|
| This attribute checks if the status code of the response is between
| 400 and 600 to see if there was a client error or a server error. If
| the status code is between 200 and 400, this will return True. This
| is **not** a check to see if the response code is ``200 OK``.
|
| text
| Content of the response, in unicode.
|
| If Response.encoding is None, encoding will be guessed using
| ``charset_normalizer`` or ``chardet``.
|
| The encoding of the response content is determined based solely on HTTP
| headers, following RFC 2616 to the letter. If you can take advantage of
| non-HTTP knowledge to make a better guess at the encoding, you should
| set ``r.encoding`` appropriately before accessing this property.
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables (if defined)
|
| __weakref__
| list of weak references to the object (if defined)
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| __attrs__ = ['_content', 'status_code', 'headers', 'url', 'history', '...:::
:::
This is another example with `requests.api`:
::: {.cell}
``` {.python .cell-code}
print(gethelp('requests.api'))---
title: "requests.api"
description: "module requests.api in requests"
---
## Description
requests.api
~~~~~~~~~~~~
This module implements the Requests API.
:copyright: (c) 2012 by Kenneth Reitz.
:license: Apache2, see LICENSE for more details.
## Functions
### `delete`
```{=html}
<blockquote><strong><code>delete(url, **kwargs)</code></strong></blockquote> Sends a DELETE request.
:param url: URL for the new :class:`Request` object.
:param \*\*kwargs: Optional arguments that ``request`` takes.
:return: :class:`Response <Response>` object
:rtype: requests.Responseget
get(url, params=None, **kwargs) Sends a GET request.
:param url: URL for the new :class:`Request` object.
:param params: (optional) Dictionary, list of tuples or bytes to send
in the query string for the :class:`Request`.
:param \*\*kwargs: Optional arguments that ``request`` takes.
:return: :class:`Response <Response>` object
:rtype: requests.Responsehead
head(url, **kwargs) Sends a HEAD request.
:param url: URL for the new :class:`Request` object.
:param \*\*kwargs: Optional arguments that ``request`` takes. If
`allow_redirects` is not provided, it will be set to `False` (as
opposed to the default :meth:`request` behavior).
:return: :class:`Response <Response>` object
:rtype: requests.Responseoptions
options(url, **kwargs) Sends an OPTIONS request.
:param url: URL for the new :class:`Request` object.
:param \*\*kwargs: Optional arguments that ``request`` takes.
:return: :class:`Response <Response>` object
:rtype: requests.Responsepatch
patch(url, data=None, **kwargs) Sends a PATCH request.
:param url: URL for the new :class:`Request` object.
:param data: (optional) Dictionary, list of tuples, bytes, or file-like
object to send in the body of the :class:`Request`.
:param json: (optional) json data to send in the body of the :class:`Request`.
:param \*\*kwargs: Optional arguments that ``request`` takes.
:return: :class:`Response <Response>` object
:rtype: requests.Responsepost
post(url, data=None, json=None, **kwargs) Sends a POST request.
:param url: URL for the new :class:`Request` object.
:param data: (optional) Dictionary, list of tuples, bytes, or file-like
object to send in the body of the :class:`Request`.
:param json: (optional) json data to send in the body of the :class:`Request`.
:param \*\*kwargs: Optional arguments that ``request`` takes.
:return: :class:`Response <Response>` object
:rtype: requests.Responseput
put(url, data=None, **kwargs) Sends a PUT request.
:param url: URL for the new :class:`Request` object.
:param data: (optional) Dictionary, list of tuples, bytes, or file-like
object to send in the body of the :class:`Request`.
:param json: (optional) json data to send in the body of the :class:`Request`.
:param \*\*kwargs: Optional arguments that ``request`` takes.
:return: :class:`Response <Response>` object
:rtype: requests.Responserequest
request(method, url, **kwargs) Constructs and sends a :class:`Request <Request>`.
:param method: method for the new :class:`Request` object: ``GET``, ``OPTIONS``, ``HEAD``, ``POST``, ``PUT``, ``PATCH``, or ``DELETE``.
:param url: URL for the new :class:`Request` object.
:param params: (optional) Dictionary, list of tuples or bytes to send
in the query string for the :class:`Request`.
:param data: (optional) Dictionary, list of tuples, bytes, or file-like
object to send in the body of the :class:`Request`.
:param json: (optional) A JSON serializable Python object to send in the body of the :class:`Request`.
:param headers: (optional) Dictionary of HTTP Headers to send with the :class:`Request`.
:param cookies: (optional) Dict or CookieJar object to send with the :class:`Request`.
:param files: (optional) Dictionary of ``'name': file-like-objects`` (or ``{'name': file-tuple}``) for multipart encoding upload.
``file-tuple`` can be a 2-tuple ``('filename', fileobj)``, 3-tuple ``('filename', fileobj, 'content_type')``
or a 4-tuple ``('filename', fileobj, 'content_type', custom_headers)``, where ``'content-type'`` is a string
defining the content type of the given file and ``custom_headers`` a dict-like object containing additional headers
to add for the file.
:param auth: (optional) Auth tuple to enable Basic/Digest/Custom HTTP Auth.
:param timeout: (optional) How many seconds to wait for the server to send data
before giving up, as a float, or a :ref:`(connect timeout, read
timeout) <timeouts>` tuple.
:type timeout: float or tuple
:param allow_redirects: (optional) Boolean. Enable/disable GET/OPTIONS/POST/PUT/PATCH/DELETE/HEAD redirection. Defaults to ``True``.
:type allow_redirects: bool
:param proxies: (optional) Dictionary mapping protocol to the URL of the proxy.
:param verify: (optional) Either a boolean, in which case it controls whether we verify
the server's TLS certificate, or a string, in which case it must be a path
to a CA bundle to use. Defaults to ``True``.
: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.
:return: :class:`Response <Response>` object
:rtype: requests.Response
Usage::
>>> import requests
>>> req = requests.request('GET', 'https://httpbin.org/get')
>>> req
<Response [200]>:::
:::
---
[source](https://github.com/hamelsmu/pydoc_quarto/blob/main/pydoc_quarto/core.py#L123){target="_blank" style="float:right; font-size:smaller"}
### gen_md
> gen_md (lib:str, dest_dir:str)
Generate Quarto Markdown API docs
| | **Type** | **Details** |
| -- | -------- | ----------- |
| lib | str | the name or module of the python library, if module should be in the form `library.module` |
| dest_dir | str | the destination directory the markdown files will be rendered into |
| **Returns** | **None** | |
---
[source](https://github.com/hamelsmu/pydoc_quarto/blob/main/pydoc_quarto/core.py#L116){target="_blank" style="float:right; font-size:smaller"}
### write_md
> write_md (modname, dest_dir)
Write markdown to file
You can generate your docs in the desired directory like so:
::: {.cell}
``` {.python .cell-code}
!rm -rf _test_dir/
gen_md('requests', '_test_dir1/')!ls _test_dir1adapters.qmd compat.qmd hooks.qmd status_codes.qmd
api.qmd cookies.qmd models.qmd structures.qmd
auth.qmd exceptions.qmd packages.qmd utils.qmd
certs.qmd help.qmd sessions.qmdYou can also export docs for a particular model. This might be helpful if pydoc_quarto cannot auto-detect your modules or they are in a deeply nested structure:
!rm -rf _test_dir2/
gen_md('requests.api', '_test_dir2/')!ls _test_dir2/api.qmd