ci: Add basic check that all dependencies are declared

Author: JanEbbing

.gitlab-ci.yml

@@ -237,6 +237,31 @@ mustache_example_manual:
   rules:
     - if: $CI_PIPELINE_SOURCE != "schedule"
 
+.basic_usage_example_base:
+  stage: test
+  extends: .test
+  script:
+    - poetry build --verbose --no-interaction
+    - cd examples/basic_usage
+    - python3 -m venv .examplevenv
+    - source .examplevenv/bin/activate
+    - pip install ../../dist/deepl-*.tar.gz
+    - set -o pipefail
+    - python . 2>&1 | tee basic_usage_result.txt
+    - grep -q "Success" basic_usage_result.txt
+
+basic_usage_example_scheduled:
+  extends: .basic_usage_example_base
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "schedule"
+  retry: 2
+
+basic_usage_example_manual:
+  stage: test
+  extends: .basic_usage_example_base
+  rules:
+    - if: $CI_PIPELINE_SOURCE != "schedule"
+
 # stage: publish -------------------------
 
 pypi upload:

CHANGELOG.md

@@ -5,6 +5,11 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 
+## [Unreleased]
+### Added
+* Added basic usage example of the library
+
+
 ## [1.16.1] - 2023-11-07
 ### Fixed
 * Fixed typo in error message when no auth key is provided.
@@ -273,6 +278,7 @@ Version increased to avoid conflicts with old packages on PyPI.
 Initial version.
 
 
+[Unreleased]: https://github.com/DeepLcom/deepl-python/compare/v1.16.1...HEAD
 [1.16.1]: https://github.com/DeepLcom/deepl-python/compare/v1.16.0...v1.16.1
 [1.16.0]: https://github.com/DeepLcom/deepl-python/compare/v1.15.0...v1.16.0
 [1.15.0]: https://github.com/DeepLcom/deepl-python/compare/v1.14.0...v1.15.0

examples/basic_usage/README.md

@@ -0,0 +1,4 @@
+# Example: Basic usage
+
+An example showing how to translate with the `deepl` python package, showcasing various features.
+It is also used to test the package, preventing regressions.

examples/basic_usage/__main__.py

@@ -0,0 +1,54 @@
+# Copyright 2023 DeepL SE (https://www.deepl.com)
+# Use of this source code is governed by an MIT
+# license that can be found in the LICENSE file.
+
+import io
+import deepl
+import os
+
+env_auth_key = "DEEPL_AUTH_KEY"
+env_server_url = "DEEPL_SERVER_URL"
+
+
+def main():
+    auth_key = os.getenv(env_auth_key)
+    server_url = os.getenv(env_server_url)
+    if auth_key is None:
+        raise Exception(
+            f"Please provide authentication key via the {env_auth_key} "
+            "environment variable or --auth_key argument"
+        )
+
+    # Create a Translator object, and call get_usage() to validate connection
+    translator = deepl.Translator(auth_key, server_url=server_url)
+    translator.get_usage()
+
+    # Use most translation features of the library
+    translator.translate_text(
+        ["I am an example sentence", "I am another sentence"],
+        source_lang="EN",
+        target_lang="FR",
+        formality=deepl.Formality.DEFAULT,
+        tag_handling=None,
+    )
+    ginfo = translator.create_glossary(
+        "Test Glossary", "DE", "FR", {"Hallo": "Bonjour"}
+    )
+    with io.BytesIO() as output_file:
+        translator.translate_document(
+            "My example document",
+            output_file,
+            source_lang="DE",
+            target_lang="FR",
+            filename="example.txt",
+            glossary=ginfo,
+        )
+    translator.translate_text_with_glossary(
+        ["Ich bin ein Beispielsatz.", "Ich bin noch ein Satz."], glossary=ginfo
+    )
+
+    print("Success")
+
+
+if __name__ == "__main__":
+    main()