A python=3.10
-asyncio
-based web backend, using web framework fastapi
.
Please do proper research about python
's asyncio
before committing to this project.
Add --recursive
in your command in order to clone both pd6-be
and its submodule common
(pd6-common
).
git clone --recursive ssh://[email protected]:30001/pdogs/pdogs-6/pd6-be.git
Suggest using PyCharm for development tool; you may also connect your
conda
environment with PyCharm!
Using conda
as example:
conda create --name pd6-be python=3.10
conda activate pd6-be
pip install -r requirements.txt
cp .env.example .env
cp logging.yaml.example logging.yaml
Then
- Fill out the environment variables in
.env
. - Check the
filename
s inlogging.yaml
, and replace if you needed. - Check the
propagate
s inlogging.yaml
, and replace withTrue
if you want to show that genre of log on your console. - Manually create your log folder (default
/log
under your clonedpd6-be
project folder).
pip install uvicorn
uvicorn main:app
On your terminal you should see:
INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO: Started reloader process xxxx using watchgod
INFO: Started server process xxxx
INFO: Waiting for application startup.
INFO: Application startup complete.
Now you can go to http://127.0.0.1:8000
and test it.
You may also turn up the auto-reload option, or change the host & port with --host
and --port
:
uvicorn main:app --reload --host 0.0.0.0 --port 80
python -m run_test
or
python run_test.py
coverage run -m run_test -v
# coverage report
coverage report
pip install ruff
ruff .
These are the very, very, VERY important principles that all developers of this project should take concern of. You should definitely read all of these and take them in your mind.
These principles are so important that you will benefit from those for a very, very long time, until you quit being a developer.
Be a good dev!
- DRY: Don't Repeat Yourself
- KISS: Keep It Simple & Stupid
- YAGNI: You Ain't Gonna Need It
- Color of Bikeshed
- If it ain't broke, don't fix it
- Zen of Python
- Premature optimization is the root of all evil; some discussion
- SRP: Single Responsibility Principle
This project adapts the BREAD concept: Browse, Read, Edit, Add, Delete. It is similar to CRUD (Create, Read, Update, Delete), but with an additional "Browse".
For Browse in this project, it is batch reading with pagination.
Because -- the creator of this project likes BREAD.
If you feel uncomfortable about this, you should go back to the main principles and read Color of Bikeshed.
The recommended (actually forced) IDE for this project is PyCharm >= 2021.3. This is to
- ensure the code style for everyone;
- ensure that you get the correct type hinting. Please try not use VSCode or other IDEs to code in this project.
PyCharm Professional is free for educational users. You may register a pro account for yourself with your @ntu.edu.tw
email. Since the Professional version provides additional useful functionalities such as in-line SQL check, please
apply your pro account and use the Professional version.
Here are some recommended settings to apply to your PyCharm Professional, so your IDE will not raise too many false alarms:
Config location: Editor > Natural Languages > Spelling
You can add .dic
file to the "Custom dictionaries" list, so PyCharm will not raise unwanted typos. You may also update
the .dic
list as you want.
Here are some inspection (Editor > Inspections) configurations that are recommended. You can avoid having to manually scan through the long list by entering the inspection item to the search bar.
Type | Inspection Item | Severity |
---|---|---|
SQL | Redundant ordering direction | Typo |
Also, you can set Profile
in (Editor > Inspection) to Project Default
to ignore some inspections in test files
and highlight test files in sidebar.