crossbill 0.1.0

A library for building Finagle-style asynchronous clients and servers

Crossbill

Description

Crossbill is a Python library focused on building Finagle-style Service-based asynchronous clients and servers. It is very much a work in progress, and as such, does not follow semantic versioning, nor should the APIs be considered stable.

Getting Started

No version of Crossbill has been published to PyPI as of yet, so it needs to be included as a dependency via git. Here's a walkthrough of doing so using uv.

Create a New Project

$ uv init crossbill-demo
$ cd crossbill-demo

Add Crossbill as a Dependency

$ uv add git+https://github.com/ryanoneill/crossbillpy

Code the Example

By default, uv will generate a hello.py file. Replace its contents with the following code:

import asyncio
from crossbill.core import Service
from crossbill.string import (
    StringClient,
    StringRequest,
    StringResponse,
    StringServer,
)
from crossbill.transport import Address


class EchoService(Service[StringRequest, StringResponse]):
    async def __call__(self, request: StringRequest) -> StringResponse:
        return StringResponse(request.value)


async def main() -> None:
    address = Address("localhost", 12345)
    server = StringServer()
    await server.serve(address, EchoService())

    message = "Hello from crossbill-demo!"
    client = StringClient()
    await client.connect(address)
    response = await client(StringRequest(message))
    print(response.value)

    await client.close()
    await server.close()


if __name__ == "__main__":
    asyncio.run(main())

Run the Example

$ uv run hello.py
Hello from crossbill-demo!

Development

The crossbill project uses uv, "[a]n extremely fast Python package and project manager, written in Rust." If you don't have it installed, follow the installation guide in order to do so.

Dependency Installation

With uv installed, run the following from the command line to ensure that all dependencies are properly installed.

$ uv sync

Testing

This project uses pytest along with asyncio in order to run asynchronous tests. A predominant number of tests within this library will fit that criteria due to the nature of the domain space.

To run the existing unit tests, run the following from the command line.

$ uv run pytest

Coverage

This project uses coverage and pytest-cov for measuring code coverage. To generate the report when running tests, run the following from the command line.

$ uv run pytest --cov

If there are lines with missing coverage, to see which lines in particular, run the following from the command line.

$ uv run pytest --cov --cov-report term-missing