Metadata-Version: 2.4
Name: konnect.curl
Version: 0.3.0
Summary: Pythonic, asynchronous interface to Curl (cURL) using `anyio`
Author-email: Dom Sekotill <dom.sekotill@kodo.org.uk>
Requires-Python: >=3.13
Description-Content-Type: text/markdown
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Mozilla Public License 2.0 (MPL 2.0)
Classifier: Topic :: Internet
License-File: LICENCE.txt
Requires-Dist: anyio ~=4.7
Requires-Dist: kodo.quantities ~=0.1.1
Requires-Dist: pyasn1
Requires-Dist: pyasn1-modules
Requires-Dist: pycurl >=7.48.0, <8
Requires-Dist: typing_extensions ~=4.16
Project-URL: Changelog, https://docs.kodo.org.uk/konnect.curl/changelog.html
Project-URL: Documentation, https://docs.kodo.org.uk/konnect.curl
Project-URL: Issues, https://code.kodo.org.uk/konnect/konnect.curl/-/issues
Project-URL: Source, https://code.kodo.org.uk/konnect/konnect.curl

[![gitlab-ico]][gitlab-link]
[![github-ico]][github-link]
[![docs-ico]][docs-link]

[![licence-mpl20]](/LICENCE.txt)
[![pre-commit-ico]][pre-commit-link]
<!-- [![pipeline-status]][pipeline-report] -->
<!-- [![coverage status]][coverage report] -->


Konnect
=======

Konnect is a project to make the power of the [libcurl multi][] feature available through 
a Pythonic interface.  It consists of this core package (konnect.curl) through which any 
protocol provided by libcurl can be accessed and some additional packages (e.g. 
[konnect.http][]) which provide enhanced interfaces for specific protocols.


Basic Usage
-----------

Users must first create a class that implements the `konnect.curl.abc.Request` 
interface; the methods of this protocol are essentially hooks that are called at certain 
points in a transfer.  The transfer commences when an instance of the request class is 
passed to `konnect.curl.Multi.process()` and the returned awaitable is awaited:

- `configure_handle` is called prior to connection with a single 
  `konnect.curl.abc.ConfigHandle` object as an argument.  This object can be used to 
  configure the request in a manner familiar to users of libcurl, by calling the 
  `konnect.curl.abc.ConfigHandle.setopt()` method of the object.  In particular users should 
  configure libcurl callbacks to handle various additional events specific to the desired 
  protocol.

- The `UpdateHandler` methods `has_update` & `get_update` are called continuously throughout 
  the transfer. The latter, if it returns anything, interrupts the transfer and returns the 
  value from `konnect.curl.Multi.process()`.  The user would normally then continue the 
  transfer by calling `konnect.curl.Multi.process()` again with the same multi and request 
  objects.  It is up to the user to recognise when the return is an interim response or 
  a final response, normally by checking the type of the response. If the implementation has 
  nothing to return during the transfer `has_update` can simply return `False` every time it 
  is called.

- `completed` is called after the transfer is finished, with 
  a `konnect.curl.abc.GetInfoHandle` object that may be used to examine information about 
  the transfer in a way familiar to libcurl users, with it's 
  `konnect.curl.abc.GetInfoHandle.getinfo()` and 
  `konnect.curl.abc.GetInfoHandle.getinfo_raw()` methods.


Instances of `konnect.curl.Multi` are shareable within a thread and although it is possible 
to use multiple instances it is recommended for performance and resource usage reasons to 
use only one.  


Streams
-------

Streams can be created with the `Multi` methods `Multi.get_send_stream()` and 
`Multi.get_receive_stream()`.  The streams implement the interfaces for byte streams in 
*anyio*: `anyio.abc.ByteSendStream` and `anyio.abc.ByteReceiveStream` respectively.  When 
their respective `send()` and `receive()` methods are awaited they run the same procedures 
as `Multi.process()` to progress the transfer.

Streams SHOULD be used as async context managers to ensure they are closed.  They MUST be 
closed for transfers to continue after the main body has been transferred.


[libcurl multi]:
  https://curl.se/libcurl/c/libcurl-multi.html
  "libcurl mutli interface overview"

[konnect.http]:
  https://docs.kodo.org.uk/konnect.http/
  "konnect.http Documentation"

[gitlab-ico]:
  https://img.shields.io/badge/GitLab-code.kodo.org.uk-blue.svg?logo=gitlab
  "GitLab"

[gitlab-link]:
  https://code.kodo.org.uk/konnect/konnect.curl
  "konnect.curl at code.kodo.org.uk"

[github-ico]:
  https://img.shields.io/badge/GitHub-domsekotill/konnect.curl-blue.svg?logo=github
  "GitHub"

[github-link]:
  https://github.com/domsekotill/konnect.curl
  "konnect.curl at github.com"

[docs-ico]:
    https://img.shields.io/badge/Documentation-docs.kodo.org.uk-blue.svg

[docs-link]:
  https://docs.kodo.org.uk/konnect.curl/
  "konnect.curl Documentation"

[pre-commit-ico]:
  https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white
  "Pre-Commit: enabled"

[pre-commit-link]:
  https://github.com/pre-commit/pre-commit
  "Pre-Commit at GitHub.com"

[licence-mpl20]:
  https://img.shields.io/badge/Licence-MPL--2.0-blue.svg
  "Licence: Mozilla Public License 2.0"

[pipeline-status]:
  https://code.kodo.org.uk/konnect/konnect.curl/badges/main/pipeline.svg

[pipeline-report]:
  https://code.kodo.org.uk/konnect/konnect.curl/pipelines/latest
  "Pipelines"

[coverage status]:
  https://code.kodo.org.uk/konnect/konnect.curl/badges/main/coverage.svg

[coverage report]:
  https://code.kodo.org.uk/konnect/konnect.curl/-/jobs/artifacts/main/file/results/coverage.html.d/index.html?job=Unit+Tests

