This guide shows how to compile and test this project. Anyone who want to contribute to these codes can follow this guide and submit the pull request. Section 2 🔖 and Section 3 🔖 suggests how to work with Docker or Conda, respectively. Please choose either of these tools to deploy the environment and develop this project.
Caution
We strongly suggest users to prepare the environment by Docker (see 2.1. 🔖). Docker is supported by both Linux and Windows. Using Docker can save a lot of steps and mitigate issues caused by the path.
-
Review our code of conduct 📝 before contributing to this project.
-
The metadata of the project is defined in
pyproject.toml. Some metadata are dynamically solved from the other files, like the package version. Therefore, users need to ensure changes are done in the correct places if any part of the metadata needs to be changed. -
The Python codes are in the package
flask_sqlalchemy_compat/folder. These codes are formatted byblack🔨. Note that the automatically generated files (may be introduced in the future) will not be formatted. -
The extra demos are stored in
examples/. These demos show the usages this package in different cases. -
The unit tests are defined in the
tests/folder. -
The
version/folder is only used for helpingpyproject.tomlfetch the current version. -
The tool configurations for
pytest,black, andpyrightare defined inpyproject.toml. However, the configurations forflake8andpylintare still kept in their corresponding configurations files. -
Remember to use
black🔨 to format any modified Python codes. Review your code before sending the pull request.
If you choose to use Docker. The only software you need to install is docker itself. Check the following guide to install Docker on your device:
https://docs.docker.com/get-started/get-docker/
After installing docker, test whether it works or not by
docker run -it --rm hello-worldYou should be able to see the message like this, which shows that docker is working well:
Then, build the docker image by
docker build -t flask-sqlalchemy-compat:latest https://github.com/cainmagi/flask-sqlalchemy-compat.gitThis step may take a little bit long. After successfully building the image, you can start working on this project.
Run the following command to start the tests.
docker run -it --rm flask-sqlalchemy-compat:latestIf the codes have not been modified, you suppose to see the the messages like this:
It shows that all unit tests get passed.
Note
Note that in Python 3.7, the tests will be fewer because flask-sqlalchemy is the
only available backend and some tests are meaningless.
Caution
The demo is not ready now. Check the future version to find the demo.
We have prepared several demos. Run this command to launch the default demo:
docker run -it --rm -p 8080:8080 flask-sqlalchemy-compat:latest --demoThe following command is used for launching a different demo. The available demo names are the .py file names in ./examples
docker run -it --rm -p 8080:8080 flask-sqlalchemy-compat:latest --demo demo=app_fsqla| Demo Name | Description |
|---|---|
default |
Only run some Flask SQLAlchemy (Lite) commits and queries. |
app_fsqla |
A Flask application providing APIs powered by Flask SQLAlchemy. |
app_fsqla_lite |
A Flask application providing APIs powered by Flask SQLAlchemy Lite. |
When the demo is running, you should be able to access the demo by
To modify the scripts, you may want to clone an Git repository by yourself:
git clone https://github.com/cainmagi/flask-sqlalchemy-compatThen, you can run the docker container and mount the newly cloned Git folder to the container:
docker run -it --rm -v <path-to-the-project>:/workdir -p 8080:8080 flask-sqlalchemy-compat:latest --bashWhen the container is running, you should be able to see that your are in the container's console.
Please leave the container open, and follow this guide to attach your vscode to the running container:
https://code.visualstudio.com/docs/devcontainers/attach-container
At the bottom left corner, you should be able to see the name of the current container. When you open a new workspace, you should be able to find the the project in /workdir.
Now you will be able to start the development. You can do the following things to test the codes.
-
Run the
pytest:python -m pytest
-
Format the python codes
black . -
Run an example
python -m examples.app_fsqla
-
Build the python pacakge
python -m build
Before submitting a pull request, please ensure that all unit tests (pytest) get passed and the codes are formatted by black.
Caution
This method is not recommended because conda may take redundant space to install unnecessary pacakges. Users need to maintain the dependencies by themselves.
Before start the installation, you need to ensure the following things are installed:
-
Conda or Mamba
Either MiniConda or MicroMamba is a good option. MicroMamba is even faster than MiniConda. If you choose to use micromamba, you simply need to replace
condabymicromambain any command. -
Git
You need to ensure that Git command is available:
- Get Git: https://git-scm.com/downloads
Use Git to clone the latest source codes:
git clone https://github.com/cainmagi/flask-sqlalchemy-compatThe following steps will help you configure the environment with conda:
-
Create the environment
conda create -c conda-forge -n flaskdev-fsc python=3.12 wheel setuptools
-
Enter the environment
conda activate flaskdev-fsc
-
Install the Python dependencies
pip install -r requirements.txt -r requirements-dev.txt -r tests/requirements.txt
To verify whether you have correctly prepared the environment or not, you can run the following command:
python -m pytestYou can do the following things to test the codes.
-
Run the
pytest:python -m pytest
-
Format the python codes
black . -
Run an example
python -m examples.app_fsqla
-
Build the python pacakge
python -m build
Before submitting a pull request, please ensure that all unit tests (pytest) get passed and the codes are formatted by black.