Weblate 的 Python API¶

安裝¶

Python API 以 Weblate Client 套件另行提供：

pip install wlc

`wlc`¶

wlc 模組會公開 Weblate API 用戶端、用戶端傳回的 API 物件，以及常見 API 失敗時引發的例外狀況。

`Weblate`¶

Weblate 類別是主要的 API 進入點。直接建立此類別不會載入 Weblate Client 設定檔或 WLC_* 環境變數；連線設定取自提供的引數：

from wlc import Weblate

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

若要探索設定檔和環境變數，請明確載入 WeblateConfig，並將它傳給用戶端：

from wlc import Weblate
from wlc.config import WeblateConfig

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

Python 用戶端遵循與命令列用戶端相同的 URL、認證資訊和傳輸政策，請參閱安全性模型。直接使用 API 的人員仍須負責安全地轉譯及儲存傳回的值。

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.

參數:

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]¶: Add a source string to a monolingual base file.

create_component(project: str, *, params: Mapping[str, str | bytes | int | float | Iterable[str | bytes | int | float] | None] | None = None, **kwargs: object) → 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, str | bytes | int | float | Iterable[str | bytes | int | float] | None] | None = None) → str | int | float | bool | list[JSONValue] | dict[str, JSONValue] | None¶: 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, object] | None = None, files: Mapping[str, str | bytes | BinaryIO | TextIO | tuple[str | None, str | bytes | BinaryIO | TextIO] | tuple[str | None, str | bytes | BinaryIO | TextIO, str] | tuple[str | None, str | bytes | BinaryIO | TextIO, str, Mapping[str, str]]] | None = None, params: Mapping[str, str | bytes | int | float | Iterable[str | bytes | int | float] | None] | 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, str | bytes | int | float | Iterable[str | bytes | int | float] | None] | None = None) → Iterator[Unit]¶: List units in the instance.

post(path: str, *, files: Mapping[str, str | bytes | BinaryIO | TextIO | tuple[str | None, str | bytes | BinaryIO | TextIO] | tuple[str | None, str | bytes | BinaryIO | TextIO, str] | tuple[str | None, str | bytes | BinaryIO | TextIO, str, Mapping[str, str]]] | None = None, params: Mapping[str, str | bytes | int | float | Iterable[str | bytes | int | float] | None] | None = None, **kwargs: object) → dict[str, Any]¶: Perform POST request on the API.

raw_request(method: str, path: str, *, data: Mapping[str, object] | None = None, files: Mapping[str, str | bytes | BinaryIO | TextIO | tuple[str | None, str | bytes | BinaryIO | TextIO] | tuple[str | None, str | bytes | BinaryIO | TextIO, str] | tuple[str | None, str | bytes | BinaryIO | TextIO, str, Mapping[str, str]]] | None = None, params: Mapping[str, str | bytes | int | float | Iterable[str | bytes | int | float] | None] | None = None) → bytes¶: Construct request object and returns raw content.

request(method: str, path: str, *, data: Mapping[str, object] | None = None, files: Mapping[str, str | bytes | BinaryIO | TextIO | tuple[str | None, str | bytes | BinaryIO | TextIO] | tuple[str | None, str | bytes | BinaryIO | TextIO, str] | tuple[str | None, str | bytes | BinaryIO | TextIO, str, Mapping[str, str]]] | None = None, params: Mapping[str, str | bytes | int | float | Iterable[str | bytes | int | float] | None] | None = None) → str | int | float | bool | list[JSONValue] | dict[str, JSONValue] | None¶: Construct request object and returns json response.

例外¶

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 物件¶

API 物件支援以屬性或索引鍵存取欄位，也支援 keys() 和 items()。如果存取已知但尚未載入的欄位，系統會從 API 擷取該物件。get_data() 只會傳回目前已載入資料的複本，不會擷取缺少的欄位。

API objects inherit from collections.UserDict. They are mappings, but isinstance(obj, dict) is false. Membership tests, get(), and iteration use the currently loaded fields without fetching missing fields. pop(), setdefault(), popitem(), and clear() also operate only on loaded fields without fetching missing fields. Mapping writes update local object data; they do not send changes to the API. The | operator merges loaded fields into a new plain dictionary, with values from the right operand taking precedence. For consumers that require a plain dictionary, use obj.get_data() for loaded fields or dict(obj.items()) to include all exposed fields, fetching missing fields as needed. Standard json.dumps does not serialize API objects directly; convert them and any nested API objects to dictionaries first.

專案、組件和翻譯共用儲存庫操作：repository()、commit()、push()、pull()、reset() 和 cleanup()。

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

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(*, params: RequestParams | None = None, **kwargs: object) → 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: object)¶

Component object returned by the Weblate API.

add_source_string(*, msgid: str, msgstr: str | builtins.list[str]) → dict[str, Any]¶: Add a source string to a monolingual base file.

add_translation(language: str) → dict[str, Any]¶: Create 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: object) → 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: object)¶

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¶: Load and return this object for API compatibility.

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: QueryValue) → Iterator[Unit]¶: List units in the translation.

upload(file: bytes | str | BinaryIO | TextIO, *, overwrite: bool | None = None, format: str | None = None, **kwargs: object) → dict[str, Any]¶: Upload a translation file to server.

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

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¶: Load and return this object for API compatibility.

patch(**kwargs: object) → bytes¶: Update unit fields using HTTP PATCH.

put(**kwargs: object) → bytes¶: Update unit fields using HTTP PUT.

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

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: object)¶

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: object)¶

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: object)¶

Statistics object returned by the Weblate API.

get_data() → dict[str, Any]¶: Return a copy of the currently loaded object data.

keys() → Iterator[str]¶: 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: object)¶

Language statistics object returned by the Weblate API.

get_data() → dict[str, Any]¶: Return a copy of the currently loaded object data.

keys() → Iterator[str]¶: 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: object)¶

Translation statistics object returned by the Weblate API.

get_data() → dict[str, Any]¶: Return a copy of the currently loaded object data.

keys() → Iterator[str]¶: 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: object)¶

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: object)¶

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.

參數:: 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() → Path | None¶: Return the first user configuration file as a Path, or None.

static find_project_config() → Path | None¶: Return the nearest project configuration file as a Path, or None.

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.

Weblate 的 Python API¶

安裝¶

wlc¶

Weblate¶

例外¶

API 物件¶

wlc.config¶

`wlc`¶

`Weblate`¶

`wlc.config`¶