WIP: 📝✅ Is1611/tests and doc

Makefile

@@ -52,9 +52,7 @@ info: info-api info-envs info-tools info-pip ## all infos
 
 
 .venv: .check-uv-installed
-	@uv venv \
-		--python 3.10 \
-		$@
+	@uv venv $@
 	## upgrading tools to latest version in $(shell python3 --version)
 	@uv pip --quiet install --upgrade \
 		pip~=24.0 \
@@ -66,9 +64,10 @@ info: info-api info-envs info-tools info-pip ## all infos
 
 .PHONY: devenv
 devenv: .venv .vscode/settings.json .vscode/launch.json ## create a python virtual environment with dev tools (e.g. linters, etc)
+	# Installing requirements.txt
 	@uv pip --quiet install -r requirements.txt
 	# Installing pre-commit hooks in current .git repo
-	@$</bin/pre-commit install
+	@uvx pre-commit install
 	@echo "To activate the venv, execute 'source .venv/bin/activate'"
 
 

REALEASES.md

@@ -0,0 +1,60 @@
+# Releases
+
+Some notes on how the clients are version and released
+
+## openapi specs (OAS) version != client version
+
+The version found in api/openapi.json for the API is **not used** as the version of the client.
+
+## Versioning Strategy
+
+- We follow **post-release versioning** during development.
+  - Format: `1.2.3.post0.devN` where `N` represents the number of commits since the last release (`1.2.3`).
+  - We opt for post-release versioning rather than pre-release to avoid making early decisions about the next release version.
+
+- Official releases follow the format `1.2.3`.
+
+- **Patch releases** (e.g., `1.2.4`) are used instead of post-releases like `1.2.3.postX`.
+
+- Releases are determined by **git tags**. SEE [Releases](https://github.com/ITISFoundation/osparc-simcore-clients/releases).
+
+- For more details, refer to the following:
+  - GitHub workflow for publishing: `.github/workflows/publish-python-client.yml`
+  - Version computation script: `scripts/compute_version.bash`
+
+
+## `osparc` Package in the https://pypi.org Package Index
+
+- Release history in https://pypi.org/project/osparc/#history
+  - Corresponds to [Releases](https://github.com/ITISFoundation/osparc-simcore-clients/releases).
+- Pre-releases in https://test.pypi.org/project/osparc/#history
+  - all master commits have a pre-released as `X.Y.Z.post0.devN`
+
+### FAQ
+
+#### How to install latest released versions?
+
+```cmd
+pip install osparc
+```
+
+#### How to list all released versions?
+
+```cmd
+pip index versions osparc
+```
+
+#### How to list pre-released versions?
+
+For that we need to include the test index, where we decided to push all the pre-releases. An extra
+index to the standard pypi repo is necessary in order to find the dependencies
+
+```cmd
+pip index versions osparc -i https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ --pre
+```
+
+#### How to install latest pre-release versions?
+
+```cmd
+pip install -i https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ osparc
+```

clients/python/Makefile

@@ -32,7 +32,7 @@ python-client-generator-help: ## help on client-api generator
 
 .PHONY: _postprocess_osparc_client_artifacts
 _postprocess_osparc_client_artifacts:
-	black $(ARTIFACTS_DIR)/client/*.py
+	uvx black $(ARTIFACTS_DIR)/client/*.py
 	@-rm -f $(ARTIFACTS_DIR)/client/README.md
 	@echo "Please visit our [website](https://itisfoundation.github.io/osparc-simcore-clients/#/) for documentation" > $(ARTIFACTS_DIR)/client/README.md
 	@-rm -rf $(CLIENTS_PYTHON_DIR)/src/osparc/data/
@@ -110,14 +110,11 @@ _check_venv_active:
 
 # (0) Environment ---------------------
 
-.PHONY: .install-dev-reqs
-.install-dev-reqs: _check_venv_active
-	uv pip install -r $(CLIENTS_PYTHON_DIR)/requirements/dev.txt
+
 
 .PHONY: install-dev
-install-dev: _check_venv_active .install-dev-reqs python-client  ## installs osparc_client and osparc in edit mode
-	uv pip install -e artifacts/client
-	uv pip install -e .
+install-dev: _check_venv_active python-client  ## installs osparc_client and osparc in edit mode
+	uv pip sync requirements/dev.txt
 	uv pip list
 
 .PHONY: install-unit-test
@@ -129,7 +126,7 @@ install-e2e-test: _check_venv_active ## install packages for e2e testing client
 	uv pip install -r $(CLIENTS_PYTHON_DIR)/requirements/e2e-test.txt
 
 .PHONY: install-doc
-install-doc: _check_venv_active .install-dev-reqs ## install packages for generating documentation
+install-doc: _check_venv_active ## install packages for generating documentation
 	uv pip install -r $(CLIENTS_PYTHON_DIR)/requirements/doc.txt
 
 
@@ -155,7 +152,7 @@ tests: _check_venv_active ## runs tests during development
 		--failed-first \
 		--durations=10 \
 		--pdb \
-		$(CLIENTS_PYTHON_DIR)/test/test_osparc
+		$(CLIENTS_PYTHON_DIR)/test/units
 
 # (3) Packaging -------------------
 

clients/python/requirements/dev.txt

@@ -1,4 +1,6 @@
--r ../../../requirements.txt
+--editable artifacts/client
+--editable .
+
 -r unit-test.txt
 -r e2e-test.txt
 pylint

clients/python/test/e2e/conftest.py

@@ -115,14 +115,15 @@ def api_client() -> Iterable[osparc.ApiClient]:
 def async_client() -> Iterable[AsyncClient]:
     if Version(osparc.__version__) >= Version("8.0.0"):
         configuration = ConfigurationEnvVars()
-        host = configuration.OSPARC_API_HOST.rstrip("/")
+        host = str(configuration.OSPARC_API_HOST).rstrip("/")
         username = configuration.OSPARC_API_KEY
         password = configuration.OSPARC_API_SECRET
     else:
         host = os.environ.get("OSPARC_API_HOST")
         username = os.environ.get("OSPARC_API_KEY")
         password = os.environ.get("OSPARC_API_SECRET")
         assert host and username and password
+
     yield AsyncClient(
         base_url=host,
         auth=BasicAuth(
@@ -178,6 +179,7 @@ def file_with_number(
     file = tmp_path / "file_with_number.txt"
     file.write_text("1")
     server_file = files_api.upload_file(file)
+
     yield server_file
 
     files_api.delete_file(server_file.id)

clients/python/test/e2e/test_files_api.py

@@ -8,6 +8,7 @@
 from pathlib import Path
 
 import osparc
+from osparc._utils import PaginationGenerator
 import pytest
 from _utils import skip_if_no_dev_features
 from conftest import _KB
@@ -50,7 +51,7 @@ def test_search_files(
     tmp_file: Path, api_client: osparc.ApiClient, use_checksum: bool, use_id: bool
 ) -> None:
     checksum: str = _hash_file(tmp_file)
-    results: osparc.PaginationGenerator
+    results: PaginationGenerator
     files_api: osparc.FilesApi = osparc.FilesApi(api_client=api_client)
     try:
         results = files_api._search_files(sha256_checksum=checksum)

clients/python/test/test_osparc/test_osparc_client/test_body_upload_file_v0_files_content_put.py → clients/python/test/units/osparc_client/test_body_upload_file_v0_files_content_put.py

@@ -1,15 +1,14 @@
 # coding: utf-8
 
 """
-    osparc.io web API
+osparc.io web API
 
-    osparc-simcore public web API specifications  # noqa: E501
+osparc-simcore public web API specifications  # noqa: E501
 
-    The version of the OpenAPI document: 0.4.0
-    Generated by: https://openapi-generator.tech
+The version of the OpenAPI document: 0.4.0
+Generated by: https://openapi-generator.tech
 """
 
-
 from __future__ import absolute_import
 
 import unittest

clients/python/test/test_osparc/test_osparc_client/test_file.py → clients/python/test/units/osparc_client/test_file.py

@@ -1,15 +1,14 @@
 # coding: utf-8
 
 """
-    osparc.io web API
+osparc.io web API
 
-    osparc-simcore public web API specifications  # noqa: E501
+osparc-simcore public web API specifications  # noqa: E501
 
-    The version of the OpenAPI document: 0.4.0
-    Generated by: https://openapi-generator.tech
+The version of the OpenAPI document: 0.4.0
+Generated by: https://openapi-generator.tech
 """
 
-
 from __future__ import absolute_import
 
 import unittest

clients/python/test/test_osparc/test_osparc_client/test_files_api.py → clients/python/test/units/osparc_client/test_files_api.py

@@ -1,15 +1,14 @@
 # coding: utf-8
 
 """
-    osparc.io web API
+osparc.io web API
 
-    osparc-simcore public web API specifications  # noqa: E501
+osparc-simcore public web API specifications  # noqa: E501
 
-    The version of the OpenAPI document: 0.4.0
-    Generated by: https://openapi-generator.tech
+The version of the OpenAPI document: 0.4.0
+Generated by: https://openapi-generator.tech
 """
 
-
 from __future__ import absolute_import
 
 import unittest

clients/python/test/test_osparc/test_osparc_client/test_groups.py → clients/python/test/units/osparc_client/test_groups.py

@@ -1,15 +1,14 @@
 # coding: utf-8
 
 """
-    osparc.io web API
+osparc.io web API
 
-    osparc-simcore public web API specifications  # noqa: E501
+osparc-simcore public web API specifications  # noqa: E501
 
-    The version of the OpenAPI document: 0.4.0
-    Generated by: https://openapi-generator.tech
+The version of the OpenAPI document: 0.4.0
+Generated by: https://openapi-generator.tech
 """
 
-
 from __future__ import absolute_import
 
 import unittest

clients/python/test/test_osparc/test_osparc_client/test_http_validation_error.py → clients/python/test/units/osparc_client/test_http_validation_error.py

@@ -1,15 +1,14 @@
 # coding: utf-8
 
 """
-    osparc.io web API
+osparc.io web API
 
-    osparc-simcore public web API specifications  # noqa: E501
+osparc-simcore public web API specifications  # noqa: E501
 
-    The version of the OpenAPI document: 0.4.0
-    Generated by: https://openapi-generator.tech
+The version of the OpenAPI document: 0.4.0
+Generated by: https://openapi-generator.tech
 """
 
-
 from __future__ import absolute_import
 
 import unittest

clients/python/test/test_osparc/test_osparc_client/test_job.py → clients/python/test/units/osparc_client/test_job.py

@@ -1,15 +1,14 @@
 # coding: utf-8
 
 """
-    osparc.io web API
+osparc.io web API
 
-    osparc-simcore public web API specifications  # noqa: E501
+osparc-simcore public web API specifications  # noqa: E501
 
-    The version of the OpenAPI document: 0.4.0
-    Generated by: https://openapi-generator.tech
+The version of the OpenAPI document: 0.4.0
+Generated by: https://openapi-generator.tech
 """
 
-
 from __future__ import absolute_import
 
 import datetime

clients/python/test/test_osparc/test_osparc_client/test_job_inputs.py → clients/python/test/units/osparc_client/test_job_inputs.py

@@ -1,15 +1,14 @@
 # coding: utf-8
 
 """
-    osparc.io web API
+osparc.io web API
 
-    osparc-simcore public web API specifications  # noqa: E501
+osparc-simcore public web API specifications  # noqa: E501
 
-    The version of the OpenAPI document: 0.4.0
-    Generated by: https://openapi-generator.tech
+The version of the OpenAPI document: 0.4.0
+Generated by: https://openapi-generator.tech
 """
 
-
 from __future__ import absolute_import
 
 import unittest

clients/python/test/test_osparc/test_osparc_client/test_job_outputs.py → clients/python/test/units/osparc_client/test_job_outputs.py

@@ -1,15 +1,14 @@
 # coding: utf-8
 
 """
-    osparc.io web API
+osparc.io web API
 
-    osparc-simcore public web API specifications  # noqa: E501
+osparc-simcore public web API specifications  # noqa: E501
 
-    The version of the OpenAPI document: 0.4.0
-    Generated by: https://openapi-generator.tech
+The version of the OpenAPI document: 0.4.0
+Generated by: https://openapi-generator.tech
 """
 
-
 from __future__ import absolute_import
 
 import unittest

clients/python/test/test_osparc/test_osparc_client/test_job_status.py → clients/python/test/units/osparc_client/test_job_status.py

@@ -1,15 +1,14 @@
 # coding: utf-8
 
 """
-    osparc.io web API
+osparc.io web API
 
-    osparc-simcore public web API specifications  # noqa: E501
+osparc-simcore public web API specifications  # noqa: E501
 
-    The version of the OpenAPI document: 0.4.0
-    Generated by: https://openapi-generator.tech
+The version of the OpenAPI document: 0.4.0
+Generated by: https://openapi-generator.tech
 """
 
-
 from __future__ import absolute_import
 
 import datetime

clients/python/test/test_osparc/test_osparc_client/test_meta.py → clients/python/test/units/osparc_client/test_meta.py

@@ -1,15 +1,14 @@
 # coding: utf-8
 
 """
-    osparc.io web API
+osparc.io web API
 
-    osparc-simcore public web API specifications  # noqa: E501
+osparc-simcore public web API specifications  # noqa: E501
 
-    The version of the OpenAPI document: 0.4.0
-    Generated by: https://openapi-generator.tech
+The version of the OpenAPI document: 0.4.0
+Generated by: https://openapi-generator.tech
 """
 
-
 from __future__ import absolute_import
 
 import unittest