Merge pull request #120 from ghga-de/feature/big_refactor_GSI-1859

Download path refactoring (GSI-1859)

Author: TheByronHimes

.readme_generation/readme_template.md

@@ -13,7 +13,7 @@ $description
 
 We recommend using the provided Docker container.
 
-A pre-built version is available at [docker hub](https://hub.docker.com/repository/docker/ghga/$name):
+A pre-built version is available on [Docker Hub](https://hub.docker.com/repository/docker/ghga/$name):
 ```bash
 docker pull ghga/$name:$version
 ```
@@ -24,11 +24,11 @@ Or you can build the container yourself from the [`./Dockerfile`](./Dockerfile):
 docker build -t ghga/$name:$version .
 ```
 
-For production-ready deployment, we recommend using Kubernetes, however,
-for simple use cases, you could execute the service using docker
+For production-ready deployment, we recommend using Kubernetes.
+However for simple use cases, you could execute the service using docker
 on a single server:
 ```bash
-# The entrypoint is preconfigured:
+# The entrypoint is pre-configured:
 docker run -p 8080:8080 ghga/$name:$version --help
 ```
 
@@ -50,18 +50,18 @@ $config_description
 
 ### Usage:
 
-A template YAML for configuring the service can be found at
+A template YAML file for configuring the service can be found at
 [`./example_config.yaml`](./example_config.yaml).
 Please adapt it, rename it to `.$shortname.yaml`, and place it in one of the following locations:
 - in the current working directory where you execute the service (on Linux: `./.$shortname.yaml`)
 - in your home directory (on Linux: `~/.$shortname.yaml`)
 
-The config yaml will be automatically parsed by the service.
+The config YAML file will be automatically parsed by the service.
 
 **Important: If you are using containers, the locations refer to paths within the container.**
 
 All parameters mentioned in the [`./example_config.yaml`](./example_config.yaml)
-could also be set using environment variables or file secrets.
+can also be set using environment variables or file secrets.
 
 For naming the environment variables, just prefix the parameter name with `${shortname}_`,
 e.g. for the `host` set an environment variable named `${shortname}_host`
@@ -95,12 +95,12 @@ This will give you a full-fledged, pre-configured development environment includ
 - a pre-configured debugger
 - automatic license-header insertion
 
-Moreover, inside the devcontainer, a command `dev_install` is available for convenience.
+Inside the devcontainer, a command `dev_install` is available for convenience.
 It installs the service with all development dependencies, and it installs pre-commit.
 
 The installation is performed automatically when you build the devcontainer. However,
 if you update dependencies in the [`./pyproject.toml`](./pyproject.toml) or the
-[`lock/requirements-dev.txt`](./lock/requirements-dev.txt), please run it again.
+[`lock/requirements-dev.txt`](./lock/requirements-dev.txt), run it again.
 
 ## License
 

README.md

@@ -24,7 +24,7 @@ Additionally, the decrypt command needs the private key to decrypt the downloade
 
 We recommend using the provided Docker container.
 
-A pre-built version is available at [docker hub](https://hub.docker.com/repository/docker/ghga/ghga-connector):
+A pre-built version is available on [Docker Hub](https://hub.docker.com/repository/docker/ghga/ghga-connector):
 ```bash
 docker pull ghga/ghga-connector:1.7.3
 ```
@@ -35,11 +35,11 @@ Or you can build the container yourself from the [`./Dockerfile`](./Dockerfile):
 docker build -t ghga/ghga-connector:1.7.3 .
 ```
 
-For production-ready deployment, we recommend using Kubernetes, however,
-for simple use cases, you could execute the service using docker
+For production-ready deployment, we recommend using Kubernetes.
+However for simple use cases, you could execute the service using docker
 on a single server:
 ```bash
-# The entrypoint is preconfigured:
+# The entrypoint is pre-configured:
 docker run -p 8080:8080 ghga/ghga-connector:1.7.3 --help
 ```
 
@@ -76,18 +76,18 @@ The service requires the following configuration parameters:
 
 ### Usage:
 
-A template YAML for configuring the service can be found at
+A template YAML file for configuring the service can be found at
 [`./example_config.yaml`](./example_config.yaml).
 Please adapt it, rename it to `.ghga_connector.yaml`, and place it in one of the following locations:
 - in the current working directory where you execute the service (on Linux: `./.ghga_connector.yaml`)
 - in your home directory (on Linux: `~/.ghga_connector.yaml`)
 
-The config yaml will be automatically parsed by the service.
+The config YAML file will be automatically parsed by the service.
 
 **Important: If you are using containers, the locations refer to paths within the container.**
 
 All parameters mentioned in the [`./example_config.yaml`](./example_config.yaml)
-could also be set using environment variables or file secrets.
+can also be set using environment variables or file secrets.
 
 For naming the environment variables, just prefix the parameter name with `ghga_connector_`,
 e.g. for the `host` set an environment variable named `ghga_connector_host`
@@ -128,12 +128,12 @@ This will give you a full-fledged, pre-configured development environment includ
 - a pre-configured debugger
 - automatic license-header insertion
 
-Moreover, inside the devcontainer, a command `dev_install` is available for convenience.
+Inside the devcontainer, a command `dev_install` is available for convenience.
 It installs the service with all development dependencies, and it installs pre-commit.
 
 The installation is performed automatically when you build the devcontainer. However,
 if you update dependencies in the [`./pyproject.toml`](./pyproject.toml) or the
-[`lock/requirements-dev.txt`](./lock/requirements-dev.txt), please run it again.
+[`lock/requirements-dev.txt`](./lock/requirements-dev.txt), run it again.
 
 ## License
 

scripts/update_config_docs.py

@@ -15,8 +15,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""Generates a JSON schema from the service's Config class as well as a corresponding
-example config yaml (or check whether these files are up to date).
+"""Generate a JSON Schema from the service's Config class and an example
+config YAML file, or check whether the existing files are up to date.
 """
 
 import importlib
@@ -46,7 +46,7 @@ class ValidationError(RuntimeError):
 def get_config_class():
     """
     Dynamically imports and returns the Config class from the current service.
-    This makes the script service repo agnostic.
+    This makes the script agnostic to the service repository.
     """
     # get the name of the microservice package
     with subprocess.Popen(
@@ -82,28 +82,22 @@ def get_schema() -> str:
 
 def get_example() -> str:
     """Returns an example config YAML."""
-
     config = get_dev_config()
     normalized_config_dict = config.model_dump(mode="json", by_alias=True)
     return yaml.dump(normalized_config_dict, indent=2, sort_keys=True)
 
 
 def update_docs():
-    """Update the example config and config schema files documenting the config
-    options."""
-
-    example = get_example()
-    with open(EXAMPLE_CONFIG_YAML, "w", encoding="utf-8") as example_file:
-        example_file.write(example)
-
-    schema = get_schema()
-    with open(CONFIG_SCHEMA_JSON, "w", encoding="utf-8") as schema_file:
-        schema_file.write(schema)
+    """Update the example config YAML and JSON Schema files documenting the
+    config options.
+    """
+    EXAMPLE_CONFIG_YAML.write_text(get_example(), encoding="utf-8")
+    CONFIG_SCHEMA_JSON.write_text(get_schema(), encoding="utf-8")
 
 
 def print_diff(expected: str, observed: str):
-    """Print differences between expected and observed files."""
-    echo_failure("Differences in Config YAML:")
+    """Print differences between expected and observed example config YAML."""
+    echo_failure("Differences in config YAML file:")
     for line in unified_diff(
         expected.splitlines(keepends=True),
         observed.splitlines(keepends=True),
@@ -114,28 +108,25 @@ def print_diff(expected: str, observed: str):
 
 
 def check_docs():
-    """Check whether the example config and config schema files documenting the config
-    options are up to date.
+    """Check whether the example config YAML and JSON Schema files are up to date.
 
     Raises:
-        ValidationError: if not up to date.
+        ValidationError: If not up to date.
     """
 
     example_expected = get_example()
-    with open(EXAMPLE_CONFIG_YAML, encoding="utf-8") as example_file:
-        example_observed = example_file.read()
+    example_observed = EXAMPLE_CONFIG_YAML.read_text(encoding="utf-8")
     if example_expected != example_observed:
         print_diff(example_expected, example_observed)
         raise ValidationError(
-            f"Example config YAML at '{EXAMPLE_CONFIG_YAML}' is not up to date."
+            f"Example config YAML file at '{EXAMPLE_CONFIG_YAML}' is not up to date."
         )
 
     schema_expected = get_schema()
-    with open(CONFIG_SCHEMA_JSON, encoding="utf-8") as schema_file:
-        schema_observed = schema_file.read()
+    schema_observed = CONFIG_SCHEMA_JSON.read_text(encoding="utf-8")
     if schema_expected != schema_observed:
         raise ValidationError(
-            f"Config schema JSON at '{CONFIG_SCHEMA_JSON}' is not up to date."
+            f"Config schema JSON file at '{CONFIG_SCHEMA_JSON}' is not up to date."
         )