Package: pg4n
PostgreSQL for novices📄 DocumentationThis README is meant for developers of the project, and not for end users. For end users, please see the documentation linked above.PostgreSQL for novicesNotes for developersPoetryVersioningImportsRunning testsUsing dockerBuilding documentsLinters and formattersGithooksNotes for developersPoetryThis project usesPoetryfor packaging. Although one should refer toPoetry docsfor a thorough introduction, here's a short summary of the intended workflow with Poetry:To install all dependencies and the application, typepoetry install. After installation, if the Python scripts folder is in your PATH, you should be able to invokemain.main()withpg4n.To make VS Code use Poetry's virtual environment, typepoetry env info, copy virtual environment executable path, press F1 and typePython: Select Interpreter>Enter interpreter path...> paste path and press<ENTER>.To add/remove a dependency, typepoetry add <dep>/poetry remove <dep>.To execute a command from within virtual environment shell, typepoetry run <cmd>.To enter a shell session within the Poetry virtual environment, typepoetry shell.VersioningYou can bump the version number automatically withpoetry version patch,poetry version minor, etc. Seepoetry version -h.See version historyhere.ImportsDuring development, you must run the program as a module, e.g.,poetry run python -m src.pg4n.main, so that the imports work.Running testsHaving PostgreSQL running on port 5432, dopoetry run pytest.You may need to provide environment variables that match your config:VariableDefault valueDescriptionPGHOST127.0.0.1Hostname of the PostgreSQL server.PGPORT5432Port to an active PostgreSQL instance.PGUSERpostgresThe user that will be used to manage the test database.PGPASSWORDPassword, in case password authentication is used.PGDBNAMEtest_databaseDatabase name.For example, if PostgreSQL is on port 5433, just doPGPORT=5433 poetry run pytest(Bash syntax).Using dockerTo 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-alpineYou'll need to tell pytest the password:PGPASSWORD=postgres poetry run pytest.Building documentsIfdocs/apiis not up-to-date or doesn't exist, run:poetry run sphinx-apidoc -f -o docs/api src/pg4n '*/test*'To generate the documentation:poetry run sphinx-build -b html docs docs/buildNote that the GitHub Pages site is only updated on pushes tomainbranch.Linters and formattersFor linting, the following tools are used:blackfor formattingpylintfor lintingmypyfor static type checkingisortfor sorting importsTo get a grade that the CI/CD pipeline would give you, you can dopoetry run scripts/ci-grade.shto run all the checks. The output is possibly long, so pipe it to a file perusal filter such aslessto scroll through it and search for things of concern, e.g.,summaryto see scores.GithooksThis project usespoetry-githooksto run automatic formatting on each commit. To set this up, run:poetryrungithookssetupThis needs to be re-run each time the[tool.githooks]section is modified in thepyproject.tomlfile.One can skip pre-commit hooks by runninggit commitwith the--no-verifyflag.