Weblate’s Python API¶

Installation¶

The Python API is shipped separately as the Weblate Client package:

pip install wlc

`wlc`¶

The wlc module exposes the Weblate API client, API objects returned by the client, and exceptions raised for common API failures.

`Weblate`¶

The Weblate class is the main API entry point.

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

Weblate API wrapper object.

Parameters:

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.

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.

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.

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.

Exceptions¶

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 objects¶

API objects behave as mappings and support deferred loading. Attribute access loads missing data from the API when needed.

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.

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.

languages() → builtins.list[LanguageStats]¶: Return language statistics for the project.

list() → Iterator[Component]¶: List components in the project.

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.

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.

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.

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.

delete() → None¶: Delete the translation.

download(convert: str | None = None) → bytes¶: Download translation file from server.

list() → Translation¶: API compatibility method, returns self.

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.

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.

class wlc.Language(weblate: Weblate, url: str, **kwargs: Any)¶: Language object returned by the Weblate API.

class wlc.Change(weblate: Weblate, url: str, **kwargs: Any)¶: Change object returned by the Weblate API.

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

Statistics object returned by the Weblate API.

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.

class wlc.TranslationStatistics(weblate: Weblate, url: str = '', **kwargs: Any)¶: Translation statistics object returned by the Weblate API.

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

class wlc.Repository(weblate: Weblate, url: str, **kwargs: Any)¶: Component or translation repository status object.

`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.

Parameters:: 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: a command-line flag, a true WLC_ALLOW_INSECURE_HTTP value, or trusted configuration can enable it. False or unset command-line and environment sources do not disable a configuration opt-in. Automatically discovered project configuration can not enable it.

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.