ava-shared-resources 0.0.40

Pydantic classes

ava-shared-resources is a shared library for AVA Platform.

Features

TODO

Development

For this project Poetry is used. Poetry can be installed:

• As system-wide package as described in docs.
• As python package inside virtual environment (should be used when cannot be installed system-wide).

Poetry is responsible only for python packaging and dependency management.

In order to create virtual environment with specific version of python (that required by the project and might not be installed on your system) you'll have to use either:

• Conda (preferrable option)
• Pyenv (windows version) (works perfectly on UNIX-based OS, not on Windows!)

Configure poetry

1. [Optional] First let's tell poetry to not create virtual env by default (only needed if poetry is installed as system package, not as pip package):

   poetry config virtualenvs.create false
   

2. Setup credentials for WK's private PyPi repository

   2.1) You need to have a PyPi Artifactory account. Make sure that you have read permissions to https://artifactory.wolterskluwer.io/ui/repos/tree/General/dxg-ava-pypi/. If you don't have it you can reach [e-mail].

   2.2) Set the account with the following command:

   pip config set global.extra-index-url https://${username}:${API_Key}@artifactory.wolterskluwer.io/artifactory/api/pypi/dxg-ava-pypi/simple
   

   You can get the API Key from https://artifactory.wolterskluwer.io (from user profile)

   2.3) As the code is managed by poetry, Artifactory account has to be also specified for it (WK username should work):

   poetry config repositories.artifactory https://artifactory.wolterskluwer.io/artifactory/api/pypi/dxg-ava-pypi/
   poetry config http-basic.artifactory ${username} ${API_Key}
   

   You can get the API Key from https://artifactory.wolterskluwer.io (from user profile)

Create virtual environment

a) Create virtual env with Conda

1. In order to create virtual environment with conda run this command:

   conda create --name [env name] python=[version] --no-default-packages
   

   For example:

   conda create --name ava-configurations python=3.10.13 --no-default-packages
   

2. And activate this environment:

   conda activate ava-configurations
   

3. [Optional] Installing poetry as python package (if not installed system-wide):

   pip install poetry-core==1.4.0 poetry==1.3.0
   

b) Create virtual env with Pyenv (for UNIX-like OS)

CAUTION: windows version of pyenv doesn't not compile python from source code unlike version for UNIX-like OS. That means that it relies on prebuilt python version which is available on official python website. If there is no such version - you are out of luck.

In order to create virtual environment with Pyenv do these steps:

1. Install pyenv as it's explained in pyenv's github README file.

2. Install python with:

   pyenv install [python version]
   

   For example:

   pyenv install 3.7.11
   

3. Make just installed python used system-wide by default

   pyenv global 3.7.11
   

4. Create virtual environment with python's default venv module:

   python -m venv [venv_name]
   

5. Activate virtual environment:

   source [venv_name]/bin/activate
   

   or

   . [venv_name]/bin/activate
   

6. [Optional] Installing poetry as python package (if not installed system-wide):

   pip install poetry-core==1.4.0 poetry==1.3.0
   

All next steps should be done with activated virtual environment.

Install packages

Inside project you can find two files:

• pyproject.toml: describes dependencies and version restrictions

• poetry.lock: specifies exact version of packages ("frozen" version)

For installing packages poetry provides two commands:

• poetry install: will install packages with "frozen" versions if poetry.lock is provided. If not will find best suitable package version (with no conflicts with all other packages) and write down it into poetry.lock file.

• poetry update: will find best suitable package versions and update poetry.lock file.

IMPORTANT: for reproducibility use only poetry install command.

poetry install

Updating poetry.lock

poetry.lock file can be updated with command:

poetry update

and executed in two cases:

1. When we want to update packages and write their versions into poetry.lock file

2. If any changes are made to pyproject.toml file. Other way poetry will raise warning that poetry.lock file is outdated as it is not synced with pyproject.toml

Configure pre-commit hook

After setting up the environment, to install the pre-commit hook in the system, run the following command:

pre-commit install

This will install the hook and set it up to run automatically before each commit.

Committing with pre-commit hook

After making code changes, follow the standard process for commit and push:

1. Add the files:

   git add .
   

2. Commit the changes (the pre-commit hook will run automatically from .pre-commit-config.yaml):

   git commit -m "commit message"
   

   To commit while skipping one of the hooks, set the SKIP environment variable to the ID of the hook you want to skip. For example:

   SKIP=flake8 git commit -m "commit message"
   

3. Push the changes:

   git push
   

Release to PyPi Artifactory

After making changes to the code it has to be pushed as a package to PyPi Artifactory.

For pushing to repository next steps has to be done:

1. If needed update package version in pyproject.toml file (in tool.poetry.version section).

2. You need to have a PyPi Artifactory account. Make sure that you have not only read but also write permissions to https://artifactory.wolterskluwer.io/ui/repos/tree/General/dxg-ava-pypi/. If you don't have it you can reach [e-mail].

3. Set the account with the following command:

   pip config set global.extra-index-url https://${username}:${API_Key}@artifactory.wolterskluwer.io/artifactory/api/pypi/dxg-ava-pypi/simple
   

   You can get the API Key from https://artifactory.wolterskluwer.io (from user profile)

4. As the code is managed by poetry, Artifactory account has to be also specified for it (WK username should work):

   poetry config repositories.at https://artifactory.wolterskluwer.io/artifactory/api/pypi/dxg-ava-pypi/
   poetry config http-basic.at ${username} ${API_Key}
   

   You can get the API Key from https://artifactory.wolterskluwer.io (from user profile)

5. Build and publish package:

   Build and publish the repo using script ava-shared-resources/utils/build_publish_repo.py.

   It will build the package and place it in /dist folder with .whl extension. Before building make sure the package version is not already present in the artifactory, else function will give an error. Same package will be uploaded in the Artifactory repository. Try to install it and check if it works as expected.