A client library for accessing the Forgejo API
Project description
pyforgejo
A client library for accessing the Forgejo API.
Usage
Create a client:
from pyforgejo import AuthenticatedClient
client = AuthenticatedClient(base_url='https://codeberg.org/api/v1', token='API_TOKEN')
Call an endpoint:
from pyforgejo.api.user import user_get_current
response = user_get_current.sync_detailed(client=client)
# async version
response_async = user_get_current.asyncio_detailed(client=client)
response = await response_async
print(response)
Installation
pip install pyforgejo
Forgejo API
Resources:
- API Usage | Forgejo – Beyond coding. We forge.: user guide for the Forgejo API
- Forgejo API | Codeberg: API reference for Codeberg
- Forgejo API Swagger spec | Codeberg: Codeberg's Forgejo API Swagger spec
- openapi-generators/openapi-python-client: repo for the generator library that was used to generate
pyforgejo
- About Swagger Specification | Documentation | Swagger: docs for Swagger spec
- The OpenAPI Specification Explained | OpenAPI Documentation: docs for OpenAPI spec
The structure of the import statement for interacting with a specific endpoint follows this pattern:
from pyforgejo.api.<root_path> import <operation_id>
Here, <tag>
is the root path or tag for the endpoint in the Swagger spec, and <operation_id>
is the operationId
for the specific function you want to call, converted to snake case.
For example, for the endpoint /repos/search
, the Swagger spec is:
"/repos/search": {
"tags": ["repository"],
"operationId": "repoSearch",
...
}
So to hit that endpoint, the import statement will be:
from pyforgejo.api.repository import repo_search
Every path/operation combo becomes a Python module with four functions:
sync
: Blocking request that returns parsed data (if successful) orNone
sync_detailed
: Blocking request that always returns aRequest
, optionally withparsed
set if the request was successfulasyncio
: Likesync
but async instead of blockingasyncio_detailed
: Likesync_detailed
but async instead of blocking
All path/query parameters and bodies become method arguments.
Development
openapi-python-client
pyforgejo
is generated with openapi-python-client, with as of now very little modification.
If you run into any issues, please create an issue in this repo.
If you want to work on a PR, please consider making a PR to openapi-python-client
rather than to this repo.
openapi-python-client
was chosen to generate this client over openapi-generator and fern because of the following reasons:
openapi-python-client
is Python-specific, which allows it to leverage specific language features, have a clearer code, and offer a better developer experience, compared toopenapi-generator
's one-size-fits-all approachopenapi-python-client
is written in Python, so users ofpyforgejo
will be more likely to be able to make contributions and fix bugs in the generator's code itself, whileopenapi-generator
is written in Java, which represents a higher barrier to contributionsopenapi-python-client
supports more authentication options, including access tokens, thanfern
- the documentation is limited, but clearer than for
openapi-generator
Generating the client with openapi-python-client
- Convert Forgejo's Swagger spec to OpenAPI with swagger-converter, as Swagger is not supported by
openapi-python-client
. - Install openapi-python-client:
pip install openapi-python-client
- Create a
config.yaml
file with the following content:project_name_override: "pyforgejo"
- Generate the client (this will create a
pyforgejo/
dir):openapi-python-client generate --path /path/to/forgejo_openapi.json --config /path/to/config.yaml
- Alternatively, update the client:
git clone https://codeberg.org/harabat/pyforgejo openapi-python-client update --path /path/to/forgejo_openapi.json --config ./pyforgejo/config.yaml
- Navigate to the
pyforgejo/
dir and call the API:from pyforgejo.client import AuthenticatedClient from pyforgejo.api.user import user_get_current client = AuthenticatedClient(base_url='FORGEJO_URL' + '/api/v1', token='ACCESS_TOKEN') response = user_get_current.sync_detailed(client=client) print(response) # Response(status_code=<HTTPStatus.OK: 200>, ...)
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for pyforgejo-1.0.1-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 84e34e640d1e15ddb96c2d58a8df8e84c3bd5e94372803f7f4a65698cdd7c9b6 |
|
MD5 | 18edb0a32e896f0c61f83309dea42829 |
|
BLAKE2b-256 | d0451294bb589748daa263a4902382445ba54976a8beae595b7574bd206f42b1 |