# Weblate 的 Python API ## 安装 Python API 作为 [Weblate 客户端](https://pypi.org/project/wlc/) 包单独发布： ```sh pip install wlc ``` ## [`wlc`](#module-wlc) The [`wlc`](#module-wlc) module exposes the Weblate API client, API objects returned by the client, and exceptions raised for common API failures. ### [`Weblate`](#wlc.Weblate) The [`Weblate`](#wlc.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: ```python 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`](#wlc.config.WeblateConfig) and pass it to the client: ```python 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 [安全模型](https://docs.weblate.org/zh-cn/latest/wlc.md#wlc-security). 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](#wlc.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] 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](#wlc.Component) Return component of given path. #### get_object(path: str) → [Project](#wlc.Project) | [Component](#wlc.Component) | [Translation](#wlc.Translation) | [Unit](#wlc.Unit) Return object based on path. Operates on (project, component or translation objects. #### get_project(path: str) → [Project](#wlc.Project) Return project of given path. #### get_translation(path: str) → [Translation](#wlc.Translation) Return translation of given path. #### get_unit(path: str) → [Unit](#wlc.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](#wlc.Category)] List categories in the instance. #### list_changes(path: str = 'changes/') → Iterator[[Change](#wlc.Change)] List changes in the instance. #### list_components(path: str = 'components/') → Iterator[[Component](#wlc.Component)] List components in the instance. #### list_languages() → Iterator[[Language](#wlc.Language)] List languages in the instance. #### list_projects(path: str = 'projects/') → Iterator[[Project](#wlc.Project)] List projects in the instance. #### list_translations(path: str = 'translations/') → Iterator[[Translation](#wlc.Translation)] List translations in the instance. #### list_units(path: str, params: Mapping[str, Any] | None = None) → Iterator[[Unit](#wlc.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. ### 异常 ### *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 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](#wlc.Weblate), url: str, \*\*kwargs: Any) Project object returned by the Weblate API. #### categories() → Iterator[[Category](#wlc.Category)] List categories in the project. #### changes() → Iterator[[Change](#wlc.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](#wlc.LanguageStats)] Return language statistics for the project. #### list() → Iterator[[Component](#wlc.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](#wlc.Statistics) Return statistics for the project. ### *class* wlc.Component(weblate: [Weblate](#wlc.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](#wlc.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](#wlc.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](#wlc.TranslationStatistics)] Return statistics for component. #### unlock() → dict[str, Any] Unlock component from translations. ### *class* wlc.Translation(weblate: [Weblate](#wlc.Weblate), url: str, \*\*kwargs: Any) Translation object returned by the Weblate API. #### changes() → Iterator[[Change](#wlc.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](#wlc.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](#wlc.TranslationStatistics) Return statistics for translation. #### units(\*\*kwargs: Any) → Iterator[[Unit](#wlc.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](#wlc.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](#wlc.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](#wlc.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](#wlc.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](#wlc.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](#wlc.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](#wlc.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](#wlc.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](#wlc.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](#wlc.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`](#module-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() → 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.