Skip to content

Clients

The two entry points. Both are context managers and expose identical surfaces.

Forgejo 

Forgejo(
    instance_url: str,
    *,
    token: str | None = None,
    auth: tuple[str, str] | None = None,
    otp: str | None = None,
    sudo: str | None = None,
    timeout: float | Timeout = _DEFAULT_TIMEOUT,
    follow_redirects: bool = _DEFAULT_FOLLOW_REDIRECTS,
    verify: bool | SSLContext = _DEFAULT_VERIFY,
    client: _ClientT | None = None,
)

The synchronous pyfj client.

sudo 

sudo: str | None

The effective Sudo header value for the current context.

Returns the context-local override when one is set, else the constructor's sudo= default. Assigning a username sets the override for the current context; assigning None clears it and restores the default.

Overrides are context-local, not process-global: sibling asyncio tasks and threads are unaffected, and child tasks created with :func:asyncio.create_task inherit the value at creation time.

request 

request(
    method: str,
    path: str,
    *,
    params: Mapping[str, object] | None = None,
    json: object | None = None,
    data: Mapping[str, object] | None = None,
    files: Mapping[str, object] | None = None,
    headers: Mapping[str, str] | None = None,
) -> Response

Send a raw request to the instance and return the raw response.

Escape hatch for endpoints newer than the vendored Spec: auth and session headers are applied, but no status or transport error mapping happens.

close 

close() -> None

Close the underlying httpx client (also when it was injected).

sudo_as 

sudo_as(username: str) -> _SudoScope

Impersonate username for the duration of a with block.

Returns a context manager that sets the sudo override on entry and restores the previous value on exit, so scopes nest and an exception leaves no residue. Accepts both with and async with and performs no I/O; the override is context-local (see :attr:sudo).

AsyncForgejo 

AsyncForgejo(
    instance_url: str,
    *,
    token: str | None = None,
    auth: tuple[str, str] | None = None,
    otp: str | None = None,
    sudo: str | None = None,
    timeout: float | Timeout = _DEFAULT_TIMEOUT,
    follow_redirects: bool = _DEFAULT_FOLLOW_REDIRECTS,
    verify: bool | SSLContext = _DEFAULT_VERIFY,
    client: _ClientT | None = None,
)

The asynchronous pyfj client.

sudo 

sudo: str | None

The effective Sudo header value for the current context.

Returns the context-local override when one is set, else the constructor's sudo= default. Assigning a username sets the override for the current context; assigning None clears it and restores the default.

Overrides are context-local, not process-global: sibling asyncio tasks and threads are unaffected, and child tasks created with :func:asyncio.create_task inherit the value at creation time.

request 

request(
    method: str,
    path: str,
    *,
    params: Mapping[str, object] | None = None,
    json: object | None = None,
    data: Mapping[str, object] | None = None,
    files: Mapping[str, object] | None = None,
    headers: Mapping[str, str] | None = None,
) -> Response

Send a raw request to the instance and return the raw response.

Escape hatch for endpoints newer than the vendored Spec: auth and session headers are applied, but no status or transport error mapping happens.

aclose 

aclose() -> None

Close the underlying httpx client (also when it was injected).

sudo_as 

sudo_as(username: str) -> _SudoScope

Impersonate username for the duration of a with block.

Returns a context manager that sets the sudo override on entry and restores the previous value on exit, so scopes nest and an exception leaves no residue. Accepts both with and async with and performs no I/O; the override is context-local (see :attr:sudo).

Namespaces

Both clients expose one attribute per resource namespace: