Guiguts - an application to support creation of ebooks for PG
poetry install
If additional dependencies are added to GG2, or you use pyenv to switch to a new version of python, you will need to re-run this command.
poetry run guiguts
. Alternatively,
you can start a virtual environment shell with poetry shell
, then run
GG2 with guiguts
.C:\Users\<username>\AppData\Local\Programs\Python\Python311
pyenv lets you easily switch between multiple versions of Python, if that would be useful for development/testing.
git clone https://github.com/pyenv-win/pyenv-win.git "$HOME\.pyenv"
[System.Environment]::SetEnvironmentVariable('PYENV',$env:USERPROFILE + "\.pyenv\pyenv-win\","User")
[System.Environment]::SetEnvironmentVariable('PYENV_ROOT',$env:USERPROFILE + "\.pyenv\pyenv-win\","User")
[System.Environment]::SetEnvironmentVariable('PYENV_HOME',$env:USERPROFILE + "\.pyenv\pyenv-win\","User")
pyenv install 3.11.7
,
pyenv install 3.12.0
, etc.pyenv global 3.11.7
, for example.(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | py -
C:\Users\<username>\AppData\Roaming
C:\Users\<username>\AppData\Roaming\Python\Scripts
Either clone the GG2 Github repo or a fork thereof.
In the cloned GG2 directory, create a virtual environment using a version of python you installed above.
poetry env use ~/AppData/Local/Programs/Python/Python311/python.exe
poetry config virtualenvs.prefer-active-python true
Developing Guiguts on macOS requires installing Homebrew first.
Install python and python-tk using Homebrew. Note that we install and use a specific version in the commands below for consistency with other developers.
brew install python@3.11 python-tk@3.11
We also install poetry using Homebrew.
brew install poetry
Either clone the GG2 Github repo or a fork thereof.
In the cloned GG2 directory, create a virtual environment using a version of python you installed above.
poetry env use $(brew --prefix)/bin/python3.11
sudo apt install python3.11 python3-pip python3-tk idle-python3.11 git
sudo python3.11 -m pip install poetry
## Test that Tk will work
python3.11 -m tkinter
Click me!
button to test mouse clicks, and
QUIT
to close the window, ending the test. poetry env use $(which python3.11)
Guiguts 2 uses flake8 and
pylint for static code analysis, and
black for consistent styling. All use default
settings, with the exception of maximum line length checking which is adjusted
in the recommended manner (using the .flake8
file and the tool.pylint
section of pyproject.toml
) to avoid conflicts with black.
All of the above tools will be installed via poetry
as described above.
poetry run flake8 .
will check all src
& tests
python files.
poetry run pylint --recursive y .
will check all src
& tests
python files.
poetry run black .
will reformat all src
& tests
python files where necessary.
This project uses Github Actions to ensure none of the above tools report any error.
Naming conventions from PEP8 are used. To summarize, class names use CapWords; constants are ALL_UPPERCASE; most other variables, functions and methods are all_lowercase.
Google-style docstrings are used to document modules, classes, functions, etc.
Sphinx will be installed by poetry (above) and can be used to create HTML documentation by running the following command:
poetry run python -m sphinx -b html docs docs/build`
HTML docs will appear in the docs/build
directory.
Sphinx can also be used to check coverage, i.e. that docstrings have been used everywhere appropriate:
poetry run python -m sphinx -M coverage docs docs/build`
This project uses Github Actions to ensure running sphinx does not report an error, and that the coverage check does not report any undocumented items.
Mypy will be installed by poetry (above) and is used for static type checking. Where developers have added type hints, mypy will issue warnings when those types are used incorrectly.
It is not intended that every variable should have its type annotated, but developers are encouraged to add type hints to function definitions, e.g.
def myfunc(num: int) -> str:
...
Note that functions without type annotation will not be type checked. The type hints cheat sheet has a summary of how to use type annotations for various common situations.
To type check the Guiguts package and the test routines:
poetry run mypy -p guiguts
poetry run mypy tests
Pytest will be installed by poetry (above) and is used for testing.
All tests can be run using the following command:
poetry run pytest
Developers are encouraged to add tests (as appropriate) when new code is added to the project.
This project uses Github Actions to ensure running pytest
does not report an error.
Three debugger configs are provided.
Requirement: Python Debugger extension
Use the "Python: Select Interpreter" command to choose the appropriate Python environment. Your Poetry config should be detected and available to choose. If the Poetry config is not auto-detected, use poetry env info -e
in the shell to find the Poetry-configured python interpreter. Then in the "Python: Select Interpreter" command, choose "Enter interpreter path..." and paste the full path to the python
executable.
Copyright Contributors to the Guiguts-py project
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.