Weblates Python-API

Installation

Die Python-API wird separat als das „Weblate Client“-Paket ausgeliefert:

pip install wlc

wlc

Das wlc -Modul stellt den Weblate-API-Client, die vom Client zurückgegebenen API-Objekte sowie die bei häufigen API-Fehlern ausgelösten Ausnahmen bereit.

Weblate

The Weblate class is the main API entry point. Constructing it directly does not load Weblate Client configuration files or WLC_* environment variables; its connection settings come from the supplied arguments:

from wlc import Weblate

client = Weblate(
    url="https://hosted.weblate.org/api/",
    key="APIKEY",
)
projects = list(client.list_projects())

To use configuration-file and environment discovery, explicitly load WeblateConfig and pass it to the client:

from wlc import Weblate
from wlc.config import WeblateConfig

config = WeblateConfig()
config.load()
client = Weblate(config=config)

The Python client follows the same URL, credential, and transport policy as the command-line client, see Security model. Direct API consumers remain responsible for safely rendering and storing returned values.

class wlc.Weblate(key: str = '', url: str = 'http://127.0.0.1:8000/api/', config: WeblateConfig | None = None, *, retries: int = 0, status_forcelist: Collection[int] | None = None, allowed_methods: Collection[str] | None = None, backoff_factor: float = 0, timeout: int = 300, allow_insecure_http: bool = False, allow_insecure_ssl: bool = False)

Weblate API wrapper object.

Parameter:

• key – API key used for authenticated requests.

• url – API server URL. The URL should point to the Weblate API root.

• config – Configuration object. When supplied, it overrides the other connection and request options.

• retries – Total number of HTTP retries.

• status_forcelist – HTTP status codes that should trigger retries.

• allowed_methods – HTTP methods that may be retried.

• backoff_factor – Retry backoff factor passed to urllib3.

• timeout – HTTP request timeout in seconds.

• allow_insecure_http – Allow API keys over non-local http:// URLs.

• allow_insecure_ssl – Disable TLS certificate verification.

When an API key is configured, non-local http:// URLs are rejected by default. Use HTTPS, loopback HTTP for local development, or set allow_insecure_http only for legacy deployments where HTTPS is not available. Credentials embedded in API URLs are not supported; configure an API key instead.

add_source_string(project: str, component: str, msgid: str, msgstr: str | list[str], source_language: str | None = None) → dict[str, Any]

Adds a source string to a monolingual base file.

create_component(project: str, **kwargs: Any) → dict[str, Any]

Create a new component for project in the instance.

create_language(code: str, name: str, direction: str = 'ltr', plural: dict[str, Any] | None = None) → dict[str, Any]

Create a new language.

create_project(name: str, slug: str, website: str, source_language_name: str | None = None, source_language_code: str | None = None) → dict[str, Any]

Create a new project in the instance.

get(path: str, params: Mapping[str, Any] | None = None) → Any

Perform GET request on the API.

get_component(path: str) → Component

Return component of given path.

get_object(path: str) → Project | Component | Translation | Unit

Return object based on path.

Operates on (project, component or translation objects.

get_project(path: str) → Project

Return project of given path.

get_translation(path: str) → Translation

Return translation of given path.

get_unit(path: str) → Unit

Return unit of given path.

invoke_request(method: str, path: str, data: Mapping[str, Any] | None = None, files: Mapping[str, Any] | None = None, params: Mapping[str, Any] | None = None) → Response

Construct request object.

list_categories(path: str = 'categories/') → Iterator[Category]

List categories in the instance.

list_changes(path: str = 'changes/') → Iterator[Change]

List changes in the instance.

list_components(path: str = 'components/') → Iterator[Component]

List components in the instance.

list_languages() → Iterator[Language]

List languages in the instance.

list_projects(path: str = 'projects/') → Iterator[Project]

List projects in the instance.

list_translations(path: str = 'translations/') → Iterator[Translation]

List translations in the instance.

list_units(path: str, params: Mapping[str, Any] | None = None) → Iterator[Unit]

List units in the instance.

post(path: str, files: Mapping[str, Any] | None = None, params: Mapping[str, Any] | None = None, **kwargs: Any) → dict[str, Any]

Perform POST request on the API.

raw_request(method: str, path: str, data: Mapping[str, Any] | None = None, files: Mapping[str, Any] | None = None, params: Mapping[str, Any] | None = None) → bytes

Construct request object and returns raw content.

request(method: str, path: str, data: Mapping[str, Any] | None = None, files: Mapping[str, Any] | None = None, params: Mapping[str, Any] | None = None) → Any

Construct request object and returns json response.

Ausnahmen

exception wlc.WeblateException(message: str | None = None)

Generic error.

exception wlc.WeblatePermissionError(message: str | None = None)

You don’t have permission to access this object.

exception wlc.WeblateDeniedError(message: str | None = None)

Access denied, API key is wrong or missing.

exception wlc.WeblateThrottlingError(limit: str, retry_after: str)

Throttling on the server.

API-Objekte

API objects support attribute and keyed access to their fields, together with keys() and items(). Accessing a known field that is not loaded yet fetches the object from the API. get_data() returns a copy of only the data currently loaded without fetching missing fields.

Projects, components, and translations share repository operations: repository(), commit(), push(), pull(), reset(), and cleanup().

class wlc.Project(weblate: Weblate, url: str, **kwargs: Any)

Project object returned by the Weblate API.

categories() → Iterator[Category]

List categories in the project.

changes() → Iterator[Change]

List changes in the project.

cleanup() → dict[str, Any]

Cleanup Weblate repository from untracked files.

commit() → dict[str, Any]

Commit Weblate changes.

create_component(**kwargs: Any) → dict[str, Any]

Create a new component in the project.

delete() → None

Delete the project.

full_slug() → str

Return the project slug.

get_data() → dict[str, Any]

Return a copy of the currently loaded object data.

languages() → builtins.list[LanguageStats]

Return language statistics for the project.

list() → Iterator[Component]

List components in the project.

pull() → dict[str, Any]

Pull upstream changes into Weblate.

push() → dict[str, Any]

Push Weblate changes upstream.

repository() → LazyObject

Return repository object.

reset() → dict[str, Any]

Reset Weblate repository to upstream.

statistics() → Statistics

Return statistics for the project.

class wlc.Component(weblate: Weblate, url: str, **kwargs: Any)

Component object returned by the Weblate API.

add_source_string(msgid: str, msgstr: str | builtins.list[str]) → dict[str, Any]

Adds a source string to a monolingual base file.

add_translation(language: str) → dict[str, Any]

Creates a new translation in the component.

changes() → Iterator[Change]

List changes in the component.

cleanup() → dict[str, Any]

Cleanup Weblate repository from untracked files.

commit() → dict[str, Any]

Commit Weblate changes.

delete() → None

Delete the component.

download(convert: str | None = None) → bytes

Download translation file from server.

full_slug() → str

Return the component slug including project and category path.

get_data() → dict[str, Any]

Return a copy of the currently loaded object data.

list() → Iterator[Translation]

List translations in the component.

lock() → dict[str, Any]

Lock component from translations.

lock_status() → dict[str, Any]

Return component lock status.

patch(**kwargs: Any) → bytes

Update component fields.

pull() → dict[str, Any]

Pull upstream changes into Weblate.

push() → dict[str, Any]

Push Weblate changes upstream.

repository() → LazyObject

Return repository object.

reset() → dict[str, Any]

Reset Weblate repository to upstream.

statistics() → Iterator[TranslationStatistics]

Return statistics for component.

unlock() → dict[str, Any]

Unlock component from translations.

class wlc.Translation(weblate: Weblate, url: str, **kwargs: Any)

Translation object returned by the Weblate API.

changes() → Iterator[Change]

List changes in the translation.

cleanup() → dict[str, Any]

Cleanup Weblate repository from untracked files.

commit() → dict[str, Any]

Commit Weblate changes.

delete() → None

Delete the translation.

download(convert: str | None = None) → bytes

Download translation file from server.

get_data() → dict[str, Any]

Return a copy of the currently loaded object data.

list() → Translation

API compatibility method, returns self.

pull() → dict[str, Any]

Pull upstream changes into Weblate.

push() → dict[str, Any]

Push Weblate changes upstream.

repository() → LazyObject

Return repository object.

reset() → dict[str, Any]

Reset Weblate repository to upstream.

statistics() → TranslationStatistics

Return statistics for translation.

units(**kwargs: Any) → Iterator[Unit]

List units in the translation.

upload(file: Any, overwrite: bool | None = None, format: str | None = None, **kwargs: Any) → dict[str, Any]

Upload a translation file to server.

class wlc.Unit(weblate: Weblate, url: str, **kwargs: Any)

Translation unit object returned by the Weblate API.

delete() → bytes

Delete the unit.

get_data() → dict[str, Any]

Return a copy of the currently loaded object data.

list() → Unit

API compatibility method, returns self.

patch(**kwargs: Any) → bytes

Update unit fields using HTTP PATCH.

put(**kwargs: Any) → bytes

Update unit fields using HTTP PUT.

class wlc.Category(weblate: Weblate, url: str, **kwargs: Any)

Category object returned by the Weblate API.

full_slug() → str

Return the category slug including the project and parent categories.

get_data() → dict[str, Any]

Return a copy of the currently loaded object data.

class wlc.Language(weblate: Weblate, url: str, **kwargs: Any)

Language object returned by the Weblate API.

get_data() → dict[str, Any]

Return a copy of the currently loaded object data.

class wlc.Change(weblate: Weblate, url: str, **kwargs: Any)

Change object returned by the Weblate API.

get_data() → dict[str, Any]

Return a copy of the currently loaded object data.

class wlc.Statistics(weblate: Weblate, url: str = '', **kwargs: Any)

Statistics object returned by the Weblate API.

get_data() → dict[str, Any]

Return a copy of the currently loaded object data.

keys() → Any

Return present statistics fields without fetching URL-less objects.

refresh() → None

Refresh statistics when a backing API URL is available.

class wlc.LanguageStats(weblate: Weblate, url: str = '', **kwargs: Any)

Language statistics object returned by the Weblate API.

get_data() → dict[str, Any]

Return a copy of the currently loaded object data.

keys() → Any

Return present statistics fields without fetching URL-less objects.

refresh() → None

Refresh statistics when a backing API URL is available.

class wlc.TranslationStatistics(weblate: Weblate, url: str = '', **kwargs: Any)

Translation statistics object returned by the Weblate API.

get_data() → dict[str, Any]

Return a copy of the currently loaded object data.

keys() → Any

Return present statistics fields without fetching URL-less objects.

refresh() → None

Refresh statistics when a backing API URL is available.

class wlc.ProjectRepository(weblate: Weblate, url: str, **kwargs: Any)

Project repository status object.

cleanup() → dict[str, Any]

Cleanup Weblate repository from untracked files.

commit() → dict[str, Any]

Commit Weblate changes.

get_data() → dict[str, Any]

Return a copy of the currently loaded object data.

pull() → dict[str, Any]

Pull upstream changes into Weblate.

push() → dict[str, Any]

Push Weblate changes upstream.

reset() → dict[str, Any]

Reset Weblate repository to upstream.

class wlc.Repository(weblate: Weblate, url: str, **kwargs: Any)

Component or translation repository status object.

cleanup() → dict[str, Any]

Cleanup Weblate repository from untracked files.

commit() → dict[str, Any]

Commit Weblate changes.

get_data() → dict[str, Any]

Return a copy of the currently loaded object data.

pull() → dict[str, Any]

Pull upstream changes into Weblate.

push() → dict[str, Any]

Push Weblate changes upstream.

reset() → dict[str, Any]

Reset Weblate repository to upstream.

wlc.config

exception wlc.config.WLCConfigurationError

Configuration could not be loaded or combines unsafe option sources.

class wlc.config.WeblateConfig(section: str = 'weblate')

Configuration parser wrapper with defaults.

Parameter:

section – Configuration section to use.

The parser loads user configuration, optional project configuration, and command-line or environment overrides. API keys in project configuration are constrained so unscoped secrets can not be paired with a project-provided API URL.

static find_config() → str | None

Find the first user configuration file.

static find_project_config() → str | None

Find the nearest project configuration file.

get_allow_insecure_http() → bool

Return whether authenticated non-local HTTP URLs are allowed.

The insecure HTTP opt-in is enable-only. Persistent configuration is scoped to the selected network origin.

get_allow_insecure_ssl() → bool

Return whether TLS verification is disabled for the selected origin.

get_request_options() → tuple[int, list[int] | None, list[str], float, int]

Get request retry and timeout options.

get_url_key() → tuple[str, str]

Get the resolved API URL and API key.

load(path: Path | str | None = None) → None

Load configuration from an explicit path or discovered locations.

When path is specified, only that file is loaded. Otherwise the user configuration is loaded first, followed by the nearest project configuration file from the current directory or its parents.

validate_url_key() → None

Validate URL and key source combination.

When the API URL comes from automatically discovered project configuration, unscoped keys must pin the destination explicitly: WLC_KEY requires WLC_URL, and a command-line key requires a command-line URL.