PostgreSQL for novices

📄 Documentation

This README is meant for developers of the project, and not for end users. For end users, please see the documentation linked above.

• PostgreSQL for novices
  • Notes for developers
    • Poetry
      • Versioning
    • Imports
    • Running tests
      • Using docker
    • Building documents
    • Linters and formatters
      • Githooks

Notes for developers

Poetry

This project uses Poetry for packaging. Although one should refer to Poetry docs for a thorough introduction, here's a short summary of the intended workflow with Poetry:

• To install all dependencies and the application, type poetry install. After installation, if the Python scripts folder is in your PATH, you should be able to invoke main.main() with pg4n.
• To make VS Code use Poetry's virtual environment, type poetry env info, copy virtual environment executable path, press F1 and type Python: Select Interpreter > Enter interpreter path... > paste path and press <ENTER>.
• To add/remove a dependency, type poetry add <dep>/poetry remove <dep>.
• To execute a command from within virtual environment shell, type poetry run <cmd>.
• To enter a shell session within the Poetry virtual environment, type poetry shell.

Versioning

You can bump the version number automatically with poetry version patch, poetry version minor, etc. See poetry version -h.

See version history here.

Imports

During development, you must run the program as a module, e.g., poetry run python -m src.pg4n.main, so that the imports work.

Running tests

Having PostgreSQL running on port 5432, do poetry run pytest.

You may need to provide environment variables that match your config:

For example, if PostgreSQL is on port 5433, just do PGPORT=5433 poetry run pytest (Bash syntax).

Using docker

To get a similar PostgreSQL instance as with GitHub Actions workflow:
docker run --rm -P -p 127.0.0.1:5432:5432 --name pg -e POSTGRES_PASSWORD=postgres -d postgres:14.5-alpine

You'll need to tell pytest the password: PGPASSWORD=postgres poetry run pytest.

Building documents

1. If docs/api is not up-to-date or doesn't exist, run:
   poetry run sphinx-apidoc -f -o docs/api src/pg4n '*/test*'
2. To generate the documentation:
   poetry run sphinx-build -b html docs docs/build

Note that the GitHub Pages site is only updated on pushes to main branch.

Linters and formatters

For linting, the following tools are used:

• black for formatting
• pylint for linting
• mypy for static type checking
• isort for sorting imports

To get a grade that the CI/CD pipeline would give you, you can do poetry run scripts/ci-grade.sh to run all the checks. The output is possibly long, so pipe it to a file perusal filter such as less to scroll through it and search for things of concern, e.g., summary to see scores.

Githooks

This project uses poetry-githooks to run automatic formatting on each commit. To set this up, run:

poetry run githooks setup

This needs to be re-run each time the [tool.githooks] section is modified in the pyproject.toml file.

One can skip pre-commit hooks by running git commit with the --no-verify flag.