The Player's Handbook

So you decided to play with us, that's insanely great!

If you are in just for fun, the first 3 steps below will be enough for the time being and you can safely skip all the other steps.

However, if you intend to take the full learning curve and eventually publish your work or submit it to the project, please keep on reading.

Selection

The first step is to decide on a Unix command to reimplement in Python 3.x.
You can use our suggested list in the front page, pick one from our Monster Manual, or just go for any other one (even from other operating systems!) that fits your whims and fancies.
If you have selected a POSIX command, you can start implementing the POSIX.1 version instead of the latest version available in your favourite Operating System. POSIX versions are simpler and more testing oriented.

If you are starting with Python & Unix, check our tutorials first.
Aim to be compliant with the PEP 8 Style Guide for Python Code.
- Though it's a good read, you can also check your code compliance with the pylint utility, and learn as you go.
Do your unit tests:
- There you can use our very simple debugging and logging tutorial, which we suggest.
- Or the more complex Python unit testing library or the third party pytest framework (check this article for advocacy on this later one).
Last but not least, try to follow the Pythonic way, that is to say using Python specific code constructs (loops, list comprehension and so on...).

As Mando says:

This is the way!

There are 3 kind of tests that you should do:

Security checks:
- IT security is the concern of everyone. And it starts with the conception and the coding of your software (well even before with hardware or your compiler and interpreters, but that's another story).
- You can check your code security with the bandit package utility.
Back to back testing:
- You can provide a script for testing your new command against the installed one.
- We'll soon provide a dedicated tool to ease making sure that the two commands are performing exactly the same.
Portability testing:
- You should also test execution under Windows for the portability goal.
- The same tool will allow you to compare Windows results with those of your Unix machine.

The traditional Unix way for documenting things is to write a manual page (in the newer mdoc or classical man languages).
If you intend to publish your code on GitHub, also write a README.md file (in Markdown language or the GitHub flavour).
Though probably unneeded when it comes to documenting small Unix commands, if you feel like you could write a novel, consider using the Read the Docs platform and the Sphinx generation tool (which can even generate manu pages). Here's a link to get you started if it's the path you choose.

Write an installation script or Makefile (check this excellent tutorial for Makefiles) to install your commands and man pages.
However, if you need something portable across multiple Operating Systems, you'll have to go for a Python package (more on this later).

Select an OSI-approved Open Source License and put it in a License file.
Eventually use Black, "The Uncompromising Code Formatter" utility, to reformat your code in a conventional way, hopefully improving readability by others.
Create a GitHub account.

Either:

Clone this repository, make your changes and submit them for inclusion here if you prefer this over the pnu-project GitHub topic linking.