-
Ciarán Ainsworth authoredCiarán Ainsworth authored
funkwhale-api-client
A client library for accessing the Funkwhale API.
Note: This client is under active development and is not considered production-ready.
Usage
Endpoint structure
The Funkwhale API client follows the same structure for each available endpoint.
- Each API path/method combination is representsd by a Python module with four methods:
-
sync
: A blocking request that returns parsed data (if successful) orNone
-
sync_detailed
: A blocking request that always returns aRequest
, optionally withparsed
set if the request was successful. -
asyncio
: An async request that returns parsed data (if successful) orNone
-
asyncio_detailed
: An async request that always returns aRequest
, optionally withparsed
set if the request was successful.
-
- All path/query parameters and bodies are represented by method arguments.
- If the endpoint contains tags, the first tag is used as a module name for the function
- Any endpoint which doesn't contain a tag is located in
funkwhale_api_client.api.default
Use the library in your project
To get started, create a Client
in your project.
from funkwhale_api_client import Client
client = Client(base_url="https://api.example.com")
If you're interacting with endpoints that require authentication, create an AuthenticatedClient
.
from funkwhale_api_client import AuthenticatedClient
client = AuthenticatedClient(base_url="https://api.example.com", token="SuperSecretToken")
Next, call the endpoint using the data model and endpoint method.
from funkwhale_api_client.models import MyDataModel
from funkwhale_api_client.api.my_tag import get_my_data_model
from funkwhale_api_client.types import Response
my_data: MyDataModel = get_my_data_model.sync(client=client)
# return more information with the sync_detailed method
response: Response[MyDataModel] = get_my_data_model.sync_detailed(client=client)
Call endpoints asynchronously by using the async methods.
from funkwhale_api_client.models import MyDataModel
from funkwhale_api_client.api.my_tag import get_my_data_model
from funkwhale_api_client.types import Response
my_data: MyDataModel = await get_my_data_model.asyncio(client=client)
response: Response[MyDataModel] = await get_my_data_model.asyncio_detailed(client=client)
Certificate validation
The library attempts to validate TLS on HTTPS endpoints by default. Using certificate verification is highly recommended most of the time, but sometimes you may need to authenticate to a server (especially an internal server) using a custom certificate bundle.
client = AuthenticatedClient(
base_url="https://internal_api.example.com",
token="SuperSecretToken",
verify_ssl="/path/to/certificate_bundle.pem",
)
You can also disable certificate validation altogether. This is a security risk and is not recommended.
client = AuthenticatedClient(
base_url="https://internal_api.example.com",
token="SuperSecretToken",
verify_ssl=False
)
Contribute to development
The Funkwhale API client is generated from the Funkwhale OpenAPI schema. If you notice an issue with the API itself, consider contributing to Funkwhale.
Build / publish the client
This project uses Poetry to manage dependencies and packaging. Make sure you have it installed before you start.
To publish a new version of the client:
-
Update the metadata in
pyproject.toml
(e.g. authors, version) -
If you're using a private repository, configure it with Poetry
poetry config repositories.<your-repository-name> <url-to-your-repository> # Set up your repository poetry config http-basic.<your-repository-name> <username> <password> # Configure your credentials
-
Publish the client:
- Publish to PyPI with
poetry publish --build
- Publish to a private repository with
poetry publish --build -r <your-repository-name>
.
- Publish to PyPI with
If you want to install this client into another project without publishing it (e.g. for development) then:
- If the project uses Poetry, add the client using
poetry add <path-to-this-client>
. - If the project doesn't use Poetry:
- Build a wheel with
poetry build -f wheel
- Install that wheel from the target project
pip install <path-to-wheel>
- Build a wheel with
Create tests
Tests are split into two types: integration tests and model tests.
Integration tests
You can test methods by calling them with a Client
or AuthenticatedClient
and expecting a specific result. Check tests/integration/test_albums.py
for an example.
Model tests
You can test models by asserting equality with a response from a Funkwhale server. For example, to test the /api/v1/albums
endpoint:
- Find the API call in
api/albums/albums_list.py
- Check which model is used in the
_parse_response()
method. In this casePaginatedAlbumList
- Fetch data from the
/api/v1/albums
endpoint using cURL and save the output totests/data/paginated_album_list.json
- Create a test to assert equality between the resulting JSON and the
PaginatedAlbumList
model using the model'sfrom_dict()
method
An example test can be found in tests/unit/test_model_paginated_album_list.py
.
Run tests
You can run the whole suite of tests with the following command:
poetry run pytest