PyPI Package

[joanferrecid098]

As this tool is made to be used as a module, I had the idea of making it a package and using GitHub actions to publish it automatically it to PyPI. You can review all of the changed code and decide if implementing it is worth it or not.

Btw, excuse me for my English, it's not my native language.

Here I have written a documentation for the changes and (if you choose to) how to implement it to your repository.

Changes

Firstly, the directory tree has changed to accomodate for the Python package publication.

├── chessencryption/
│   ├── __init__.py
│   ├── decode.py
│   ├── encode.py
│   └── util.py
├── readme.md
├── requirements.txt
├── setup.py
├── test/
└── tests.py

setup.py

This file containes the module's information, such as its name, the description, and the version (note about it here).

It uses setuptools for setting up the build information and open to include readme.md as the description in PyPI.

tests.py

To test the code's functionality, this file can be useful as it encrypts a set string to PGN and later decrypts it. This checks if the two strings match, and if it fails it will raise an exception.

Note: don't write files to the /temp directory, as this script may overwrite the contents.

requirements.txt

Three new dependencies were added to it, and the three are required to build the Python module. These are setuptools, wheel and twine.

.gitignore

Three build-related directories were added to the file to not accidentaly push the repository with the built package.

__init__.py

This is a standard file for Python modules that includes the available methods. The ones currently added are:

• encode from encode.py
• decode from decode.py
• to_binary_string from util.py
• get_pgn_games from util.py

decode.py/encode.py

Few changes were made to the files, only updated the util.py imports as follows:

# Old import
from util import get_pgn_games

# New import
from .util import get_pgn_games

This is due to the files being in a different directory instead of the same as the user's (take the tests.py file, for example).

python-publish.yml

Lastly, this is the GitHub actions file that will automatically run tests and publish the package to PyPI. It is currently set to run every time the repository is pushed, but you can change it to your liking using the on: parameter. I recommend seeing the official page for triggers.

It consists of two jobs consecutively, a testing phase and a publishing phase. The publishing will only run if the tests have deemed successful.

The testing will run the tests.py file and will only succeed if no exceptions are thrown (if the strings don't match, for example).

The publishing will build the package and use this action to publish it to your PyPI account using a set token.

Implementation

Now, if you do wish to implement this there are a few steps you'll have to do so you can use it at its fullest.

1. Check the files to make sure they fit your use-case.
2. Make any necessary changes to them (optional)
3. Log in (or create) to your PyPI account.
4. Create an API token in the account information page.
5. Head to Settings > Secrets and Variables > Actions > Repository Secrets in GitHub.
6. Create a new secret called PYPI_API_TOKEN and insert the one created previously.

Steps 3-6 are only required if you want to publish the package automatically using GH Actions.

Manual Build

If you prefer to manually build the package, that is an option too. Just install the new requirements and run the following command:

python setup.py sdist bdist_wheel

This will create the required directories and files. The final build file is the one called chessencryption-*.whl.

Version Note

One of the only minor downsides using this configuration is that if you commit changes to the repository and want to publish the new version of the package, you are required to update the version: parameter in setup.py to able to publish it without errors.

But this can be sometimes useful if the only thing you did was update something like a README file and don't need to publish the package. If you don't change the version the tests will still be run but the publishing will fail (which is the intended outcome in this scenario).

Usage

Here is an example of the syntax for the package.

import chessencryption

# Returns encoded PGN string
encoded_pgn = chessencryption.encode(file_path="input.txt")

# Takes encoded PGN and outputs into file
chessencryption.decode(pgn_string=encoded_pgn, output_file_path="decoded.txt")

Final Notes

I understand if you don't think its worth it to implement this, I mostly did it for the fun of it. If you do decide to implement this, tell me and I'll unoccupate the package name chessencryption in PyPI. For any doubts, don't hesitate to reach out.

Good luck in your development/editing career!