Skip to content

Contributing

Thank you for being interested in contributing to HTTPXYZ. There are many ways you can contribute to the project:

Reporting Bugs or Other Issues

Stumbled upon some unexpected behaviour?

Possible bugs may be raised as a "Potential Issue" discussion, feature requests may be raised as an "Ideas" discussion. We can then determine if the discussion needs to be escalated into an "Issue" or not, or if we'd consider a pull request.

Try to be more descriptive as you can and in case of a bug report, provide as much information as possible like:

  • OS platform
  • Python version
  • Installed dependencies and versions (python -m pip freeze)
  • Code snippet
  • Error traceback

You should always try to reduce any examples to the simplest possible case that demonstrates the issue.

Some possibly useful tips for narrowing down potential issues...

  • Does the issue exist on HTTP/1.1, or HTTP/2, or both?
  • Does the issue exist with Client, AsyncClient, or both?
  • When using AsyncClient does the issue exist when using asyncio or trio, or both?

Development

To start developing HTTPXYZ create a fork of the HTTPXYZ repository on Codeberg.

Then clone your fork with the following command replacing YOUR-USERNAME with your username:

$ git clone https://codeberg.org/YOUR-USERNAME/httpxyz

You can now install the project and its dependencies using:

$ cd httpxyz
$ scripts/install

Testing and Linting

We use custom shell scripts to automate testing, linting, and documentation building workflow.

To run the tests, use:

$ scripts/test

Warning

The test suite spawns testing servers on ports 8000 and 8001. Make sure these are not in use, so the tests can run properly.

Any additional arguments will be passed to pytest. See the pytest documentation for more information.

For example, to run a single test script:

$ scripts/test tests/test_multipart.py

To run the code auto-formatting:

$ scripts/lint

Lastly, to run code checks separately (they are also run as part of scripts/test), run:

$ scripts/check

Documenting

Documentation pages are located under the docs/ folder.

To run the documentation site locally (useful for previewing changes), use:

$ scripts/docs

Resolving Build / CI Failures

It may be worth it to run $ scripts/lint to attempt auto-formatting the code and if that job succeeds commit the changes.

Docs Job Failed

This job failing means the documentation failed to build. This can happen for a variety of reasons like invalid markdown or missing configuration within mkdocs.yml.

Releasing

This section is targeted at HTTPXYZ maintainers.

Before releasing a new version, create a pull request that includes:

  • An update to the changelog:
    • We follow the format from keepachangelog.
    • Compare master with the tag of the latest release, and list all entries that are of interest to our users:
      • Things that must go in the changelog: added, changed, deprecated or removed features, and bug fixes.
      • Things that should not go in the changelog: changes to documentation, tests or tooling.
      • Try sorting entries in descending order of impact / importance.
      • Keep it concise and to-the-point. 🎯
  • A version bump: see __version__.py.

For an example, see #1006.

Once the release PR is merged, create a new release including:

  • Tag version like 0.13.3.
  • Release title Version 0.13.3
  • Description copied from the changelog.

Once created this release will not be automatically uploaded to PyPI, because we are on codeberg.

Development proxy setup

To test and debug requests via a proxy it's best to run a proxy server locally. Any server should do but HTTPCore's test suite uses mitmproxy which is written in Python, it's fully featured and has excellent UI and tools for introspection of requests.

You can install mitmproxy using pip install mitmproxy or several other ways.

mitmproxy does require setting up local TLS certificates for HTTPS requests, as its main purpose is to allow developers to inspect requests that pass through it. We can set them up follows:

  1. pip install trustme-cli.
  2. trustme-cli -i example.org www.example.org, assuming you want to test connecting to that domain, this will create three files: server.pem, server.key and client.pem.
  3. mitmproxy requires a PEM file that includes the private key and the certificate so we need to concatenate them: cat server.key server.pem > server.withkey.pem.
  4. Start the proxy server mitmproxy --certs server.withkey.pem, or use the other mitmproxy commands with different UI options.

At this point the server is ready to start serving requests, you'll need to configure HTTPXYZ as described in the proxy section and the SSL certificates section, this is where our previously generated client.pem comes in:

ctx = ssl.create_default_context(cafile="/path/to/client.pem")
client = httpxyz.Client(proxy="http://127.0.0.1:8080/", verify=ctx)

Note, however, that HTTPS requests will only succeed to the host specified in the SSL/TLS certificate we generated, HTTPS requests to other hosts will raise an error like:

ssl.SSLCertVerificationError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate
verify failed: Hostname mismatch, certificate is not valid for
'duckduckgo.com'. (_ssl.c:1108)

If you want to make requests to more hosts you'll need to regenerate the certificates and include all the hosts you intend to connect to in the seconds step, i.e.

trustme-cli -i example.org www.example.org duckduckgo.com www.duckduckgo.com