### Setup Virtual Environment and Install Dependencies

Source: https://opengisch.github.io/qgis-plugin-ci/development/environment.html

Use this script to create a virtual environment, link it to system packages for PyQGIS, and install project dependencies. Ensure you have Python 3 installed.

```bash
# create virtual environment linking to system packages (for pyqgis)
python3 -m venv .venv

# bump dependencies inside venv
python -m pip install -U pip setuptools wheel
python -m pip install -U -r requirements.txt

# install git hooks
pre-commit install

# install project as editable
python -m pip install -e .

```

--------------------------------

### Install Dependencies and Build Documentation

Source: https://opengisch.github.io/qgis-plugin-ci/development/documentation.html

Installs documentation dependencies and builds the HTML documentation website. Open the generated index.html in a browser.

```bash
python -m pip install -U -r requirements/documentation.txt
sphinx-build -b html docs docs/_build/html
```

--------------------------------

### Install qgis-plugin-ci using pip

Source: https://opengisch.github.io/qgis-plugin-ci/index.html

Install the qgis-plugin-ci package using pip. This command is used for initial setup.

```bash
pip install qgis-plugin-ci

```

--------------------------------

### Install System Requirements

Source: https://opengisch.github.io/qgis-plugin-ci/development/testing.html

Installs necessary Qt packages for QGIS plugin development. Run this command on Debian/Ubuntu-based systems.

```bash
sudo apt-get update
sudo apt-get install qt5-default qttools5-dev-tools

```

--------------------------------

### GitHub Workflow for Plugin Deployment

Source: https://opengisch.github.io/qgis-plugin-ci/usage/ci_github.html

This workflow automates the deployment of QGIS plugins. It triggers on new GitHub releases, checks out the code, sets up Python, installs qgis-plugin-ci, and then uses it to release the plugin to GitHub releases and the QGIS plugin repository. Ensure OSGEO_PASSWORD is set in repository secrets.

```yaml
on:
  release:
    types: published

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v2

      - name: Set up Python
        uses: actions/setup-python@v1
        with:
          python-version: 3.12

       # Needed if the plugin is using Transifex, to have the lrelease command
       # - name: Install Qt lrelease
       #   run: |
       #    sudo apt-get update
       #    sudo apt-get install qt5-make qttools5-dev-tools

      - name: Install qgis-plugin-ci
        run: pip3 install qgis-plugin-ci

      - name: Deploy plugin
        run: >-
          qgis-plugin-ci
          release ${GITHUB_REF/refs\/tags\//}
          --github-token ${{ secrets.GITHUB_TOKEN }}
          --osgeo-username ${{ secrets.OSGEO_USER }}
          --osgeo-password ${{ secrets.OSGEO_PASSWORD }}

```

--------------------------------

### Run All Tests

Source: https://opengisch.github.io/qgis-plugin-ci/development/testing.html

Executes all tests using the 'nose2' test runner with verbose output. Ensure 'nose2' is installed.

```bash
nose2 -v

```

--------------------------------

### Write Documentation with Live Render

Source: https://opengisch.github.io/qgis-plugin-ci/development/documentation.html

Builds and serves the documentation website with live updates on file save. Open http://localhost:8000 in a browser.

```bash
sphinx-autobuild -b html docs/ docs/_build/html
```

--------------------------------

### qgispluginci.release.create_plugin_repo

Source: https://opengisch.github.io/qgis-plugin-ci/_apidoc/qgispluginci.release.html

Creates the plugin repository as an XML file.

```APIDOC
## qgispluginci.release.create_plugin_repo

### Description
Creates the plugin repo as an XML file.

### Method
Not specified (likely internal function)

### Endpoint
Not applicable (Python function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **str** - The created plugin repository XML content.

#### Response Example
None
```

--------------------------------

### Changelog Command Help

Source: https://opengisch.github.io/qgis-plugin-ci/usage/cli_changelog.html

Displays the help message for the `changelog` command, outlining its usage, positional arguments, and optional arguments. The `release_version` argument specifies the version to be released.

```bash
usage: qgis-plugin-ci changelog [-h] release_version

positional arguments:
  release_version  The version to be released. If nothing is speficied, the latest
                   version specified into the changelog is used.

optional arguments:
  -h, --help       show this help message and exit

```

--------------------------------

### qgispluginci.cli.cli()

Source: https://opengisch.github.io/qgis-plugin-ci/_apidoc/qgispluginci.cli.html

The main command-line interface function for QGIS Plugin CI.

```APIDOC
## qgispluginci.cli.cli()

### Description
This function serves as the entry point for the command-line interface of the QGIS Plugin CI tool. It is responsible for parsing arguments and executing the appropriate actions.

### Method
N/A (This is a function call, not an HTTP endpoint)

### Endpoint
N/A

### Parameters
This function typically accepts command-line arguments, but specific parameters are not detailed in the provided text.

### Request Example
```bash
# Example of how the cli() function might be invoked from the command line
python -m qgispluginci.cli [arguments]
```

### Response
N/A (The function's output depends on the executed commands and arguments.)
```

--------------------------------

### qgispluginci.cli Module

Source: https://opengisch.github.io/qgis-plugin-ci/_apidoc/qgispluginci.html

Contains the command-line interface function for the package.

```APIDOC
## cli()

### Description
Entry point for the command-line interface of qgis-plugin-ci.

### Function
- **cli()** - Executes the main CLI logic.
```

--------------------------------

### qgispluginci.release Module

Source: https://opengisch.github.io/qgis-plugin-ci/_apidoc/qgispluginci.html

Provides functions for creating releases and uploading assets.

```APIDOC
## Release Utilities

### Description
Functions for managing the release process, including archive creation and asset uploading.

### Functions
- **create_archive()** - Creates a release archive for the plugin.
- **create_plugin_repo()** - Creates a new repository for the plugin.
- **release()** - Initiates the plugin release process.
- **release_is_prerelease()** - Checks if a release is a pre-release.
- **upload_asset_to_github_release()** - Uploads an asset to a GitHub release.
- **upload_plugin_to_osgeo_with_token()** - Uploads the plugin to OSGeo using a token.
- **upload_plugin_to_osgeo_xml_rpc()** - Uploads the plugin to OSGeo using XML-RPC.
```

--------------------------------

### qgispluginci.release.create_archive

Source: https://opengisch.github.io/qgis-plugin-ci/_apidoc/qgispluginci.release.html

Creates a plugin archive for release.

```APIDOC
## qgispluginci.release.create_archive

### Description
Creates a plugin archive for release.

### Method
Not specified (likely internal function)

### Endpoint
Not applicable (Python function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
None specified

#### Response Example
None
```

--------------------------------

### qgispluginci.release.upload_plugin_to_osgeo_with_token

Source: https://opengisch.github.io/qgis-plugin-ci/_apidoc/qgispluginci.release.html

Uploads a plugin to the QGIS repository using a token and a POST request.

```APIDOC
## qgispluginci.release.upload_plugin_to_osgeo_with_token

### Description
Upload the plugin to QGIS repository using a token and a POST request.

### Method
POST

### Endpoint
Not specified (internal function, likely interacts with QGIS API)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
None specified

#### Response Example
None

### Parameters
- **archive** (str) - The plugin archive file path to be uploaded.
- **package_name** (str) - The name of the package on the QGIS plugins website.
- **token** (str) - The token created on https://plugins.qgis.org.
```

--------------------------------

### Travis CI Deploy Script for QGIS Plugin CI

Source: https://opengisch.github.io/qgis-plugin-ci/usage/ci_travis.html

Use this script provider to execute the qgis-plugin-ci release command. Ensure a GitHub release already exists for the tag. Requires GH_TOKEN, OSGEO_USERNAME, and OSGEO_PASSWORD environment variables.

```yaml
deploy:
  - provider: script
    script: qgis-plugin-ci release ${TRAVIS_TAG} --github-token ${GH_TOKEN} --osgeo-username ${OSGEO_USERNAME} --osgeo-password {OSGEO_PASSWORD}
    on:
      tags: true

```

--------------------------------

### Release Module

Source: https://opengisch.github.io/qgis-plugin-ci/_apidoc/modules.html

Handles plugin release and deployment processes.

```APIDOC
## Release Module

### Description
Handles plugin release and deployment processes.

### Functions
- `create_archive()`
- `create_plugin_repo()`
- `release()`
- `release_is_prerelease()`
- `upload_asset_to_github_release()`
- `upload_plugin_to_osgeo_with_token()`
- `upload_plugin_to_osgeo_xml_rpc()`
```

--------------------------------

### Set Environment Variables

Source: https://opengisch.github.io/qgis-plugin-ci/development/testing.html

Exports GitHub and Transifex tokens as environment variables. Remember to replace placeholders with actual tokens.

```bash
export github_token={CHANGE_WITH_A_REAL_GITHUB_TOKEN}
export transifex_token={CHANGE_WITH_A_REAL_TRANSIFEX_TOKEN}

```

--------------------------------

### CLI Module

Source: https://opengisch.github.io/qgis-plugin-ci/_apidoc/modules.html

Handles command-line interface operations.

```APIDOC
## CLI Module

### Description
Handles command-line interface operations.

### Functions
- `cli()`
```

--------------------------------

### Package Command Usage

Source: https://opengisch.github.io/qgis-plugin-ci/usage/cli_package.html

This command is used to package QGIS plugins and is not specific to any hosting platform.

```APIDOC
## Package Command

### Description
Packages the QGIS plugin for release.

### Method
CLI Command

### Endpoint
N/A (Command Line Tool)

### Parameters
#### Positional Arguments
- **release_version** (string) - Required - The version to be released.

#### Optional Arguments
- **-h, --help** (boolean) - show this help message and exit
- **--transifex-token TRANSIFEX_TOKEN** (string) - The Transifex API token. If specified translations will be pulled and compiled.
- **-u --plugin-repo-url PLUGIN_REPO_URL** (string) - If specified, a XML repository file will be created in the current directory, the zip URL will use this parameter.
- **-c --allow-uncommitted-changes** (boolean) - If omitted, uncommitted changes are not allowed before packaging. If specified and some changes are detected, a hard reset on a stash create will be used to revert changes made by qgis-plugin-ci.
- **-d --disable-submodule-update** (boolean) - If omitted, a git submodule is updated. If specified, git submodules will not be updated/initialized before packaging.
- **-a ASSET_PATH, --asset-path ASSET_PATH** (string) - An additional asset path to add. Can be specified multiple times.

### Request Example
```bash
qgis-plugin-ci package --transifex-token "YOUR_TRANSIEX_TOKEN" --plugin-repo-url "http://example.com/repo.xml" 1.2.3
```

### Response
N/A (Command Line Tool output)

### Additional Metadata
When packaging the plugin, some extra metadata information can be added if these keys are present in the `metadata.txt`:
  * `commitNumber=` : the commit number in the branch otherwise 1 on a tag
  * `commitSha1=` : the commit ID
  * `dateTime=` : the date time in UTC format when the packaging is done

These extra parameters are specific to QGIS Plugin CI, so it’s strongly recommended storing them below a dedicated section in `metadata.txt`:

```ini
[tool:qgis-plugin-ci]
commitNumber=
commitSha1=
dateTime=
```
```

--------------------------------

### QGIS Plugin CI Package Command Usage

Source: https://opengisch.github.io/qgis-plugin-ci/usage/cli_package.html

This command is used to package a QGIS plugin for release. It accepts a release version and several optional arguments for customization, such as Transifex token, plugin repository URL, and handling of uncommitted changes.

```bash
usage: qgis-plugin-ci package [-h]
                              [--transifex-token TRANSIFEX_TOKEN]
                              [--plugin-repo-url PLUGIN_REPO_URL]
                              [--allow-uncommitted-changes]
                              release_version

positional arguments:
  release_version       The version to be released

optional arguments:
  -h, --help            show this help message and exit
  --transifex-token TRANSIFEX_TOKEN
                        The Transifex API token. If specified translations
                        will be pulled and compiled.
  -u --plugin-repo-url PLUGIN_REPO_URL
                        If specified, a XML repository file will be created in the current directory, the zip URL will use this parameter.
  -c --allow-uncommitted-changes
                        If omitted, uncommitted changes are not allowed before
                        packaging. If specified and some changes are detected,
                        a hard reset on a stash create will be used to revert
                        changes made by qgis-plugin-ci.
  -d --disable-submodule-update
                        If omitted, a git submodule is updated. If specified, git submodules will not be updated/initialized before packaging.
  -a ASSET_PATH, --asset-path ASSET_PATH
                        An additional asset path to add. Can be specified multiple times.
```

--------------------------------

### INI Configuration for QGIS Plugin CI

Source: https://opengisch.github.io/qgis-plugin-ci/configuration/options.html

Configure QGIS Plugin CI using the setup.cfg file with a dedicated [qgis-plugin-ci] section for plugin path, GitHub organization, and project slug.

```ini
[qgis-plugin-ci]
plugin_path = QuickOSM
github_organization_slug = 3liz
project_slug = QuickOSM

```

--------------------------------

### configure_file()

Source: https://opengisch.github.io/qgis-plugin-ci/_apidoc/qgispluginci.utils.html

Configures a file by replacing specified content.

```APIDOC
## configure_file()

### Description
Configures a file by replacing specified content.

### Parameters
#### Path Parameters
- **_source_file** (str) - Description of source file path.
- **_dest_file** (str) - Description of destination file path.
- **_replace** (dict) - Dictionary containing content to replace.
```

--------------------------------

### Push Translations Command

Source: https://opengisch.github.io/qgis-plugin-ci/usage/cli_translation.html

Use this command to push translation files to Transifex. Requires a Transifex API token.

```bash
usage: qgis-plugin-ci push-translation [-h] transifex_token

positional arguments:
  transifex_token  The Transifex API token

optional arguments:
  -h, --help       show this help message and exit

```

--------------------------------

### QGIS Plugin CI Metadata Configuration

Source: https://opengisch.github.io/qgis-plugin-ci/usage/cli_release.html

When packaging a QGIS plugin, additional metadata can be included in the 'metadata.txt' file. These keys provide details about the commit number, SHA1 hash, and packaging date.

```ini
[tool:qgis-plugin-ci]
commitNumber=
commitSha1=
dateTime=
```

--------------------------------

### qgispluginci.parameters Module

Source: https://opengisch.github.io/qgis-plugin-ci/_apidoc/qgispluginci.html

Handles parameter collection and validation for plugin CI processes.

```APIDOC
## Parameters Class

### Description
Manages and validates parameters required for plugin CI operations.

### Methods
- **archive_name()** - Generates the archive name for the plugin.
- **collect_metadata()** - Collects metadata for the plugin release.
- **get_release_version_patterns()** - Retrieves patterns for release version identification.
- **make_from()** - Creates a Parameters object from a given source.
- **validate_args()** - Validates the provided arguments.
```

--------------------------------

### Release Plugin with Transifex and GitHub Tokens

Source: https://opengisch.github.io/qgis-plugin-ci/configuration/translation.html

This job is triggered when a tag is present, indicating a release. It uses qgis-plugin-ci to release the plugin, requiring Transifex, GitHub, OSGeo username, and OSGeo password tokens.

```yaml
jobs:
  include:
    - stage: deploy
      if: tag IS present
      script:
        - >
          qgis-plugin-ci release ${TRAVIS_TAG}
          --transifex-token ${TX_TOKEN}
          --github-token ${GH_TOKEN}
          --osgeo-username ${OSGEO_USERNAME}
          --osgeo-password ${OSGEO_PASSWORD}
```

--------------------------------

### GitLab CI Configuration for Plugin Deployment

Source: https://opengisch.github.io/qgis-plugin-ci/usage/ci_gitlab.html

This configuration deploys a QGIS plugin to the QGIS Plugins Repository when a new Git tag is created. Ensure OSGEO_USER_NAME and OSGEO_USER_PASSWORD are set in your GitLab CI/CD variables. Uncomment translation-related lines if your plugin uses them.

```yaml
stages:
  - 🚀 deploy

deploy:qgis-repository:
  stage: 🚀 deploy
  image: python:3.11
  rules:
    - if: '$CI_COMMIT_TAG'
  before_script:
    - apt update
    - apt install -y git
# Uncomment if plugin use translations
#     - apt install -y qt5-qmake qttools5-dev-tools
#     - python -m pip install -U pyqt5-tools
    - python -m pip install -U qgis-plugin-ci
  script:
    - echo "Deploying the version ${CI_COMMIT_TAG} plugin to QGIS Plugins Repository with the user ${OSGEO_USER_NAME}"
# Uncomment if plugin use translations
#     # Amend gitignore to include translation files with qgis-plugin-ci
#     - sed -i "s|^*.qm.*| |" .gitignore
#     # git tracks new files
#     - git add $PROJECT_FOLDER/resources/i18n/*.qm
    - qgis-plugin-ci release ${CI_COMMIT_TAG}
        --osgeo-username $OSGEO_USER_NAME
        --osgeo-password $OSGEO_USER_PASSWORD
        --allow-uncommitted-changes

```

--------------------------------

### qgispluginci.release.upload_asset_to_github_release

Source: https://opengisch.github.io/qgis-plugin-ci/_apidoc/qgispluginci.release.html

Uploads an asset to a GitHub release.

```APIDOC
## qgispluginci.release.upload_asset_to_github_release

### Description
Uploads an asset to a GitHub release.

### Method
Not specified (likely internal function)

### Endpoint
Not applicable (Python function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
None specified

#### Response Example
None
```

--------------------------------

### qgispluginci.translation_clients Module

Source: https://opengisch.github.io/qgis-plugin-ci/_apidoc/qgispluginci.html

Contains clients for interacting with various translation services.

```APIDOC
## Translation Clients

### Description
This package includes modules for connecting to different translation platforms.

#### qgispluginci.translation_clients.baseclient Module
- **BaseClient**: Abstract base class for translation clients.
- **TranslationConfig**: Configuration class for translation settings.

#### qgispluginci.translation_clients.transifex Module
- **TransifexClient**: Client for interacting with the Transifex translation platform.
```

--------------------------------

### qgispluginci.utils Module

Source: https://opengisch.github.io/qgis-plugin-ci/_apidoc/qgispluginci.html

Provides various utility functions for the qgis-plugin-ci package.

```APIDOC
## Utility Functions

### Description
A collection of helper functions used across the qgis-plugin-ci package.

### Functions
- **configure_file()**: Configures a file.
- **convert_octets()**: Converts octets.
- **parse_tag()**: Parses a Git tag.
- **replace_in_file()**: Replaces content within a file.
- **touch_file()**: Updates the modification timestamp of a file.
```

--------------------------------

### Parameters Module

Source: https://opengisch.github.io/qgis-plugin-ci/_apidoc/modules.html

Manages plugin parameters.

```APIDOC
## Parameters Module

### Description
Manages plugin parameters.

### Classes
- `Parameters`
```

--------------------------------

### qgispluginci.version_note Module

Source: https://opengisch.github.io/qgis-plugin-ci/_apidoc/qgispluginci.html

Represents and manages version note information.

```APIDOC
## VersionNote Class

### Description
Represents a version note, including its components and associated metadata.

### Attributes
- **date** (str) - The date associated with the version note.
- **is_prerelease** (bool) - Flag indicating if the version is a pre-release.
- **major** (int) - The major version number.
- **minor** (int) - The minor version number.
- **patch** (int) - The patch version number.
- **prerelease** (str) - The pre-release tag.
- **separator** (str) - The separator used in the version string.
- **text** (str) - The descriptive text of the version note.
- **text_raw** (str) - The raw text of the version note.
- **url** (str) - The URL associated with the version note.
- **version** (str) - The full version string.
```

--------------------------------

### TOML Configuration for QGIS Plugin CI

Source: https://opengisch.github.io/qgis-plugin-ci/configuration/options.html

Configure QGIS Plugin CI using the pyproject.toml file under the [tool.qgis-plugin-ci] section for plugin path, GitHub organization, and project slug.

```toml
[tool.qgis-plugin-ci]
plugin_path = "qgis_plugin_ci_testing"
github_organization_slug = "opengisch"
project_slug = "qgis-plugin-ci"

```

--------------------------------

### qgispluginci.release.upload_plugin_to_osgeo_xml_rpc

Source: https://opengisch.github.io/qgis-plugin-ci/_apidoc/qgispluginci.release.html

Uploads a plugin to the QGIS repository using the XML RPC endpoint.

```APIDOC
## qgispluginci.release.upload_plugin_to_osgeo_xml_rpc

### Description
Upload the plugin to QGIS repository using the XML RPC endpoint.

### Method
Not specified (likely XML RPC)

### Endpoint
Not specified (internal function, likely interacts with QGIS API)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
None specified

#### Response Example
None

### Parameters
- **username** (str) - The username.
- **password** (str) - The password.
- **archive** (str) - The plugin archive file path to be uploaded.
- **server_url** (str) - Optional. The plugin server URL (defaults to plugins.qgis.org).
```

--------------------------------

### Package QGIS Plugin with GitLab CI using Docker

Source: https://opengisch.github.io/qgis-plugin-ci/usage/ci_docker.html

This GitLab CI configuration uses the 3liz/qgis-plugin-ci Docker image to package a QGIS plugin. It runs on tags and specifies a custom plugin repository URL. Ensure the PLUGIN_NAME environment variable is set in your GitLab CI settings.

```yaml
package:
  stage: package
  only:
    - tags
  image: 3liz/qgis-plugin-ci:latest
  script:
    - >
      qgis-plugin-ci
      package ${CI_COMMIT_REF_NAME}
      --plugin-repo-url https://custom.server.url/
  artifacts:
    expose_as: 'QGIS package'
    paths:
      - ${PLUGIN_NAME}.${CI_COMMIT_REF_NAME}.zip
      - plugins.xml

```

--------------------------------

### TransifexClient Class Methods

Source: https://opengisch.github.io/qgis-plugin-ci/_apidoc/qgispluginci.translation_clients.transifex.html

This section outlines the various methods available on the TransifexClient class for managing translation projects and resources.

```APIDOC
## TransifexClient Class

### Description
Provides methods to interact with the Transifex API for managing translations.

### Methods

#### `create_language(_language_code : str_, _coordinators_)`
Creates a new language in Transifex.

#### `create_project()`
Creates a new project in Transifex.

#### `create_resource()`
Creates a new resource in Transifex.

#### `delete_project()`
Deletes a project from Transifex.

#### `get_organization()`
Retrieves organization details from Transifex.

#### `get_project()`
Retrieves project details from Transifex.

#### `get_resource()`
Retrieves resource details from Transifex.

#### `get_translation(_language_code : str_, _path_to_output_file : str_) → str`
Fetches the translation resource for a given language code and saves it to the specified output file path.

#### `list_languages()`
Lists all available languages in Transifex.

#### `list_resources()`
Lists all available resources in Transifex.

#### `login()`
Logs into the Transifex service.

#### `project_exists(_project_slug : str_) → bool`
Checks if a project with the given slug exists in Transifex.

#### `update_source_translation()`
Updates the source translation for a resource in Transifex.
```

--------------------------------

### Exceptions Module

Source: https://opengisch.github.io/qgis-plugin-ci/_apidoc/modules.html

Defines custom exceptions for the QGIS Plugin CI tool.

```APIDOC
## Exceptions Module

### Description
Defines custom exceptions for the QGIS Plugin CI tool.

### Exceptions
- `BuiltResourceInSources`
- `ConfigurationNotFound`
- `GithubReleaseCouldNotUploadAsset`
- `GithubReleaseNotFound`
- `MissingChangelog`
- `TransifexManyResources`
- `TransifexNoResource`
- `TranslationFailed`
- `UncommitedChanges`
```

--------------------------------

### YAML Configuration for QGIS Plugin CI

Source: https://opengisch.github.io/qgis-plugin-ci/configuration/options.html

Use this YAML format for the .qgis-plugin-ci file to configure plugin path, GitHub organization, and project slug.

```yaml
plugin_path: qgis_plugin_ci_testing
github_organization_slug: opengisch
project_slug: qgis-plugin-ci

```

--------------------------------

### qgispluginci.exceptions Module

Source: https://opengisch.github.io/qgis-plugin-ci/_apidoc/qgispluginci.exceptions.html

This section lists and describes the custom exceptions available in the qgispluginci.exceptions module.

```APIDOC
## qgispluginci.exceptions Module

### Description
This module defines custom exceptions used by the QGIS Plugin CI tool to signal specific error conditions.

### Exceptions

- **BuiltResourceInSources** (Exception) - Raised when a resource is built within the sources directory.
- **ConfigurationNotFound** (Exception) - Raised when a required configuration file is not found.
- **GithubReleaseCouldNotUploadAsset** (Exception) - Raised when an asset fails to upload to a GitHub release.
- **GithubReleaseNotFound** (Exception) - Raised when a specified GitHub release cannot be found.
- **MissingChangelog** (Exception) - Raised when a changelog file is missing.
- **TransifexManyResources** (Warning) - Indicates that too many resources were found on Transifex.
- **TransifexNoResource** (Exception) - Raised when no resources are found on Transifex.
- **TranslationFailed** (Exception) - Raised when the translation process fails.
- **UncommitedChanges** (Exception) - Raised when there are uncommitted changes in the repository.
```

--------------------------------

### qgispluginci.changelog Module

Source: https://opengisch.github.io/qgis-plugin-ci/_apidoc/qgispluginci.html

Provides functionality for parsing changelog files.

```APIDOC
## ChangelogParser

### Description
Parses changelog files to extract version information and content.

### Class Attributes
- **CHANGELOG_FILEPATH** (str) - The default file path for the changelog.

### Methods
- **content()** - Returns the full content of the changelog.
- **has_changelog()** - Checks if a changelog file exists.
- **last_items()** - Retrieves the last few items from the changelog.
- **latest_version()** - Returns the latest version found in the changelog.
```

--------------------------------

### Version Note Module

Source: https://opengisch.github.io/qgis-plugin-ci/_apidoc/modules.html

Handles version notes for plugins.

```APIDOC
## Version Note Module

### Description
Handles version notes for plugins.

### Classes
- `VersionNote`
```

--------------------------------

### qgispluginci.exceptions Module

Source: https://opengisch.github.io/qgis-plugin-ci/_apidoc/qgispluginci.html

Defines custom exceptions used within the qgis-plugin-ci package.

```APIDOC
## Custom Exceptions

### Description
This module defines specific exceptions to handle various error conditions within the qgis-plugin-ci package.

### Exception List
- **BuiltResourceInSources**: Indicates a built resource found in source files.
- **ConfigurationNotFound**: Raised when a required configuration file is missing.
- **GithubReleaseCouldNotUploadAsset**: Error during GitHub asset upload.
- **GithubReleaseNotFound**: Specified GitHub release not found.
- **MissingChangelog**: Indicates that a changelog file is missing.
- **TransifexManyResources**: Error related to too many resources in Transifex.
- **TransifexNoResource**: Error indicating no resource found in Transifex.
- **TranslationFailed**: General exception for translation process failures.
- **UncommitedChanges**: Raised when there are uncommitted changes in the repository.
```

--------------------------------

### qgispluginci.release.release_is_prerelease

Source: https://opengisch.github.io/qgis-plugin-ci/_apidoc/qgispluginci.release.html

Checks if a release is a prerelease based on tag name or GitHub release.

```APIDOC
## qgispluginci.release.release_is_prerelease

### Description
Check the tag name or the GitHub release if the version must be experimental or not.

### Method
Not specified (likely internal function)

### Endpoint
Not applicable (Python function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **bool** - True if the release is a prerelease, False otherwise.

#### Response Example
None
```

--------------------------------

### qgispluginci.translation Module

Source: https://opengisch.github.io/qgis-plugin-ci/_apidoc/qgispluginci.html

Handles translation file management and synchronization.

```APIDOC
## Translation Class

### Description
Manages translation files, including pulling, pushing, and updating strings.

### Methods
- **compile_strings()** - Compiles translation strings.
- **pull()** - Pulls translation updates.
- **push()** - Pushes translation changes.
- **update_strings()** - Updates the translation strings.
```

--------------------------------

### touch_file()

Source: https://opengisch.github.io/qgis-plugin-ci/_apidoc/qgispluginci.utils.html

Updates the modification time of a file or creates it if it doesn't exist.

```APIDOC
## touch_file(_path_ , _update_time : bool = False_, _create_dir : bool = True_)

### Description
Updates the modification time of a file or creates it if it doesn't exist.

### Parameters
#### Path Parameters
- **_path_** (any) - The path to the file.
- **_update_time** (bool) - Whether to update the modification time. Defaults to False.
- **_create_dir** (bool) - Whether to create directories if they don't exist. Defaults to True.
```

--------------------------------

### Push Translations with Transifex

Source: https://opengisch.github.io/qgis-plugin-ci/configuration/translation.html

Use this job to push translations to Transifex when changes are merged to the master branch. Requires the TX_TOKEN environment variable.

```yaml
jobs:
  include:
    - stage: push-translation
      if: branch = master
      script: qgis-plugin-ci push-translation ${TX_TOKEN}
```

--------------------------------

### Utils Module

Source: https://opengisch.github.io/qgis-plugin-ci/_apidoc/modules.html

Provides various utility functions.

```APIDOC
## Utils Module

### Description
Provides various utility functions.

### Functions
- `configure_file()`
- `convert_octets()`
- `parse_tag()`
- `replace_in_file()`
- `touch_file()`
```

--------------------------------

### QGIS Plugin CI Release Command Usage

Source: https://opengisch.github.io/qgis-plugin-ci/usage/cli_release.html

This command is used for releasing QGIS plugins hosted on GitHub. It requires a release version and supports various options for authentication, repository creation, and handling uncommitted changes.

```bash
usage: qgis-plugin-ci release [-h] [--release-tag RELEASE_TAG]
                              [--transifex-token TRANSIFEX_TOKEN]
                              [--github-token GITHUB_TOKEN] [-r] [-c] [-d]
                              [--alternative-repo-url ALTERNATIVE_REPO_URL]
                              [--qgis-token QGIS_TOKEN]
                              [--osgeo-username OSGEO_USERNAME]
                              [--osgeo-password OSGEO_PASSWORD]
                              release_version

positional arguments:
  release_version       The version to be released (x.y.z).

options:
  -h, --help            show this help message and exit
  --release-tag RELEASE_TAG
                        The release tag, if different from the version (e.g. vx.y.z).
  --transifex-token TRANSIFEX_TOKEN
                        The Transifex API token. If specified translations will be pulled and
                        compiled.
  --github-token GITHUB_TOKEN
                        The GitHub API token. If specified, the archive will be pushed to an
                        already existing release.
  -r, --create-plugin-repo
                        Will create a XML repo as a Github release asset. Github token is
                        required.
  -c, --allow-uncommitted-changes
                        If omitted, uncommitted changes are not allowed before releasing. If
                        specified and some changes are detected, a hard reset on a stash
                        create will be used to revert changes made by qgis-plugin-ci.
  -d, --disable-submodule-update
                        If omitted, a git submodule is updated. If specified, git submodules
                        will not be updated/initialized before packaging.
  --alternative-repo-url ALTERNATIVE_REPO_URL
                        The URL of the endpoint to publish the plugin (defaults to
                        plugins.qgis.org)
  -a ASSET_PATH, --asset-path ASSET_PATH
                        An additional asset path to add. Can be specified multiple times.
  --qgis-token QGIS_TOKEN
                        The token from https://plugins.qgis.org to publish the plugin. Incompatible with the OSGeo user name.
  --osgeo-username OSGEO_USERNAME
                        The OSGeo user name to publish the plugin. Incompatible with QGIS token.
  --osgeo-password OSGEO_PASSWORD
                        The OSGeo password to publish the plugin. Incompatible with QGIS token.
```

--------------------------------

### Changelog Module

Source: https://opengisch.github.io/qgis-plugin-ci/_apidoc/modules.html

Provides functionality for parsing changelogs.

```APIDOC
## Changelog Module

### Description
Provides functionality for parsing changelogs.

### Functions
- `ChangelogParser`
```

--------------------------------

### Run Specific Test

Source: https://opengisch.github.io/qgis-plugin-ci/development/testing.html

Runs a specific test module using Python's unittest framework. Replace 'test.test_changelog' with the desired test file.

```python
python -m unittest test.test_changelog

```

--------------------------------

### BaseClient Class

Source: https://opengisch.github.io/qgis-plugin-ci/_apidoc/qgispluginci.translation_clients.baseclient.html

The BaseClient class provides an interface for interacting with translation platforms. It includes methods for managing projects, resources, and translations.

```APIDOC
## BaseClient Class

### Description
Provides an interface for interacting with translation platforms. It includes methods for managing projects, resources, and translations.

### Methods

- **create_language**(_language_code : str_)
  Creates a new language entry.

- **create_project**()
  Creates a new project.

- **create_resource**()
  Creates a new resource.

- **delete_project**()
  Deletes an existing project.

- **get_project**()
  Retrieves project information.

- **get_resource**()
  Retrieves resource information.

- **get_translation**(_language_code : str_, _path_to_output_file : str_) → str
  Retrieves translations for a given language and saves them to a file.

- **list_languages**()
  Lists all available languages.

- **list_resources**()
  Lists all available resources.

- **login**()
  Logs in to the translation service.

- **project_exists**()
  Checks if a project exists.

- **update_source_translation**()
  Updates the source translation.
```

--------------------------------

### Pull Translations Command

Source: https://opengisch.github.io/qgis-plugin-ci/usage/cli_translation.html

Use this command to pull translation files from Transifex. Requires a Transifex API token. Optionally, it can compile TS files into QM files.

```bash
usage: qgis-plugin-ci pull-translation [-h] [--compile] transifex_token

positional arguments:
  transifex_token  The Transifex API token

optional arguments:
  -h, --help       show this help message and exit
  --compile        Will compile TS files into QM files

```

--------------------------------

### qgispluginci.release.release

Source: https://opengisch.github.io/qgis-plugin-ci/_apidoc/qgispluginci.release.html

Manages the overall release process for a QGIS plugin.

```APIDOC
## qgispluginci.release.release

### Description
Manages the overall release process for a QGIS plugin, including packaging, repository creation, and uploading.

### Method
Not specified (likely internal function)

### Endpoint
Not applicable (Python function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
None specified

#### Response Example
None

### Parameters
- **parameters** (Parameters_) - The configuration parameters.
- **release_version** (str) - The release version (x.y.z).
- **release_tag** (str) - Optional. The release tag (vx.y.z). If not given, the release version will be used.
- **github_token** (str) - The GitHub token.
- **upload_plugin_repo_github** (bool) - If true, a custom repo will be created as a release asset on Github and could later be used in QGIS as a custom plugin repository.
- **tx_api_token** (str) - The Transifex token.
- **alternative_repo_url** (str) - URL of the endpoint to upload the plugin to.
- **qgis_token** (str) - Token from https://plugins.qgis.org to upload the plugin.
- **osgeo_username** (str) - osgeo username to upload the plugin to official QGIS repository.
- **osgeo_password** (str) - osgeo password to upload the plugin to official QGIS repository.
- **allow_uncommitted_changes** (bool) - If False, uncommitted changes are not allowed before packaging/releasing. If True and some changes are detected, a hard reset on a stash create will be used to revert changes made by qgis-plugin-ci.
- **plugin_repo_url** (str) - If set, this URL will be used to create the ZIP URL in the XML file.
- **disable_submodule_update** (bool) - If omitted, a git submodule is updated. If specified, git submodules will not be updated/initialized before packaging.
- **asset_paths** (tuple[str]) - Additional asset to be packaged/released.
```

--------------------------------

### TransifexClient API

Source: https://opengisch.github.io/qgis-plugin-ci/_apidoc/qgispluginci.translation_clients.html

The TransifexClient class extends the BaseClient to specifically interact with the Transifex translation platform. It includes all BaseClient functionalities plus Transifex-specific methods.

```APIDOC
## TransifexClient Methods

### Description
Client for interacting with the Transifex translation platform.

### Methods
- `create_language()`
- `create_project()`
- `create_resource()`
- `delete_project()`
- `get_organization()`
- `get_project()`
- `get_resource()`
- `get_translation()`
- `list_languages()`
- `list_resources()`
- `login()`
- `project_exists()`
- `update_source_translation()`
```

--------------------------------

### Specify Custom Changelog Path

Source: https://opengisch.github.io/qgis-plugin-ci/usage/cli_changelog.html

Configure the path to a specific CHANGELOG.md file using the `changelog_path` option in the configuration file. This is useful if your changelog is not located in the root directory.

```ini
changelog_path=CHANGELOG-3.4.md
```

```ini
changelog_path=subfolder/CHANGELOG.md
```

--------------------------------

### Travis CI Releases Provider for QGIS Plugin CI

Source: https://opengisch.github.io/qgis-plugin-ci/usage/ci_travis.html

Configure Travis CI to automatically create a GitHub release using the releases provider. This requires the GH_TOKEN environment variable. The release title can be customized using the tag.

```yaml
- provider: releases
  name: Title of the release ${TRAVIS_TAG}
  api_key: ${GH_TOKEN}
  on:
    tags: true

```

--------------------------------

### qgis-plugin-ci release Command

Source: https://opengisch.github.io/qgis-plugin-ci/usage/cli_release.html

The 'release' command is used to manage the release process of QGIS plugins on GitHub. It handles versioning, tagging, and uploading plugin archives.

```APIDOC
## qgis-plugin-ci release

### Description
This command is specific for plugins hosted on GitHub. It automates the release process, including versioning, tagging, and uploading.

### Method
CLI Command

### Endpoint
N/A (This is a command-line tool)

### Parameters
#### Positional Arguments
- **release_version** (string) - Required - The version to be released (e.g., x.y.z).

#### Options
- **-h, --help** (boolean) - Optional - Show this help message and exit.
- **--release-tag RELEASE_TAG** (string) - Optional - The release tag, if different from the version (e.g., vx.y.z).
- **--transifex-token TRANSIFEX_TOKEN** (string) - Optional - The Transifex API token. If specified, translations will be pulled and compiled.
- **--github-token GITHUB_TOKEN** (string) - Optional - The GitHub API token. If specified, the archive will be pushed to an already existing release.
- **-r, --create-plugin-repo** (boolean) - Optional - Will create a XML repo as a Github release asset. GitHub token is required.
- **-c, --allow-uncommitted-changes** (boolean) - Optional - If omitted, uncommitted changes are not allowed before releasing. If specified and some changes are detected, a hard reset on a stash create will be used to revert changes made by qgis-plugin-ci.
- **-d, --disable-submodule-update** (boolean) - Optional - If omitted, a git submodule is updated. If specified, git submodules will not be updated/initialized before packaging.
- **--alternative-repo-url ALTERNATIVE_REPO_URL** (string) - Optional - The URL of the endpoint to publish the plugin (defaults to plugins.qgis.org).
- **-a ASSET_PATH, --asset-path ASSET_PATH** (string) - Optional - An additional asset path to add. Can be specified multiple times.
- **--qgis-token QGIS_TOKEN** (string) - Optional - The token from https://plugins.qgis.org to publish the plugin. Incompatible with the OSGeo user name.
- **--osgeo-username OSGEO_USERNAME** (string) - Optional - The OSGeo user name to publish the plugin. Incompatible with QGIS token.
- **--osgeo-password OSGEO_PASSWORD** (string) - Optional - The OSGeo password to publish the plugin. Incompatible with QGIS token.

### Error Handling
- If the exit code is `2`, it means the upload to the QGIS plugin server has failed.

### Additional Metadata
When packaging the plugin, some extra metadata information can be added if these keys are present in the `metadata.txt`:
  * `commitNumber=` : the commit number in the branch otherwise 1 on a tag
  * `commitSha1=` : the commit ID
  * `dateTime=` : the date time in UTC format when the packaging is done

These extra parameters are specific to QGIS Plugin CI, so it’s strongly recommended storing them below a dedicated section:

```
[tool:qgis-plugin-ci]
commitNumber=
commitSha1=
dateTime=
```
```

--------------------------------

### Parameters Class Methods

Source: https://opengisch.github.io/qgis-plugin-ci/_apidoc/qgispluginci.parameters.html

Static and class methods available on the Parameters class for various utility functions.

```APIDOC
## Parameters Class Methods

### Description
Static and class methods available on the `Parameters` class for various utility functions.

### Methods
#### static archive_name(_plugin_name_ , _release_version : str_) → str
Returns the archive file name.

#### collect_metadata() → Callable[[str, Any | None], Any]
Returns a closure capturing a Dict of metadata, allowing to retrieve one value after the other while also iterating over the file once.

#### static get_release_version_patterns() → dict[str, Pattern]

#### classmethod make_from(_*_ , _args : Any | None = None_, _path_to_config_file : Path | None = None_, _optional_configuration : bool = False_) → Parameters
Instantiate from a config file or by exploring the filesystem Accepts an argparse Namespace for backward compatibility.

#### static validate_args(_args : Namespace_)
Raise an exception just in case: - the user didn’t opt-out of validation using the –no-validation flag; and - the value of release_version matches no supported pattern.
```

--------------------------------

### parse_tag()

Source: https://opengisch.github.io/qgis-plugin-ci/_apidoc/qgispluginci.utils.html

Parses a version tag to determine the semantic version.

```APIDOC
## parse_tag(_version_tag : str_) → VersionNote | None

### Description
Parse a tag and determine the semantic version.

### Parameters
#### Path Parameters
- **_version_tag** (str) - The version tag string to parse.
```

--------------------------------

### Handle Unknown Error During Plugin Upload

Source: https://opengisch.github.io/qgis-plugin-ci/misc/faq.html

If you encounter an 'Unknown error' during plugin upload, try uploading manually via the web UI. This error can occur for various reasons, such as a mismatch in plugin names between versions.

```text
A fault occurred
Fault code: 1
Fault string: Unknown error, ['  File "/usr/local/lib/python3.7/site-packages/rpc4django/xmlrpcdispatcher.py", line 84, in dispatch\n    response = self._dispatch(method, params, **kwargs)\n', '  File "/usr/local/lib/python3.7/site-packages/rpc4django/xmlrpcdispatcher.py", line 121, in _dispatch\n    return func(*params, **kwargs)\n', '  File "./plugins/api.py", line 121, in plugin_upload\n    raise Fault(1, e.message)\n']


```

--------------------------------

### convert_octets()

Source: https://opengisch.github.io/qgis-plugin-ci/_apidoc/qgispluginci.utils.html

Converts a mount of octets into a human-readable size format.

```APIDOC
## convert_octets(_octets : int_) → str

### Description
Convert a mount of octets in readable size.

### Parameters
#### Path Parameters
- **octets** (int) - mount of octets to convert

### Request Example
```python
>>> convert_octets(1024)
"1ko"
```

### Response
#### Success Response (200)
- **str** (str) - Readable size string.
```

--------------------------------

### BaseClient API

Source: https://opengisch.github.io/qgis-plugin-ci/_apidoc/qgispluginci.translation_clients.html

The BaseClient class provides a foundational set of methods for interacting with translation services. It defines common operations such as project and resource management, language listing, and translation retrieval.

```APIDOC
## BaseClient Methods

### Description
Provides core functionalities for translation management.

### Methods
- `create_language()`
- `create_project()`
- `create_resource()`
- `delete_project()`
- `get_project()`
- `get_resource()`
- `get_translation()`
- `list_languages()`
- `list_resources()`
- `login()`
- `project_exists()`
- `update_source_translation()`

### TranslationConfig Fields

#### Fields
- **api_token** (string) - API token for authentication.
- **i18n_type** (string) - Type of internationalization.
- **organization_name** (string) - Name of the organization.
- **private** (boolean) - Whether the project is private.
- **project_name** (string) - Name of the project.
- **project_slug** (string) - Slug for the project.
- **repository_url** (string) - URL of the repository.
- **resource_file_path** (string) - Path to the resource file.
- **resource_slug** (string) - Slug for the resource.
- **source_language_code** (string) - Code of the source language.
```