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 just 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 write a script for testing your new command against the installed one, if we don't already have one available.
- We provide a dedicated tool, b2bt, to ease making sure that the two commands are performing exactly the same, or as close as possible.
Portability testing:
- You should also test execution under Windows for the portability goal.
- The same b2bt tool allows 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 the GitHub flavour of the Markdown language).
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 manual pages). Here's a link to get you started if it's the path you choose.
We provide mdoc man page and GitHub README.md skeletons in our project template to help get you started.

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).
We provide a rather complete generic Makefile in our project template to help get you started (the one in the source code directory, not the one at the package level).

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.
Create a repository and upload your code inside.
Create a release for a version of your code.
Edit the repository details and add the pnu-project topic, which will establish a soft link between your command and the project.

Eventually, consider making a pip package for your entry, so that it can be automatically installed on any Operating System supporting Python.
To publish your package, you'll need to create an account on PyPi and TestPyPi.
We provide a template with all the files required to make your own package. You can download a compressed archive file with everything inside in the assets of the releases section.

Check the issues section of your GitHub repository for bug reports, documentation suggestions, new feature requests. and questions.
If needed, correct things and make new releases.

The PNU project itself doesn't include any code, beyond what we use for tutorials.
Instead we provide an "empty" Python package with dependencies on the best tools identified through the pnu-project GitHub topic or pnu-project PyPi keyword.
If there are multiple implementations to choose from for a peculiar utility, the one that will be referenced will be the first, most complete one. On your marks, get set, go!

Sometimes there are incompatible flavours to choose for implementation, between POSIX, System V, BSD, GNU, and others.
The ideal would be to implement them all and use environment variables or command line options to choose between different commands behaviour.
One such environment variable is the POSIXLY_CORRECT one for strict POSIX compatibility. Though not very pleasant (the GNU project call it POSIX_ME_HARDER 😃), it exists and should be implemented.
Beyond that, there are no standards or conventions that we know about for selecting a peculiar flavour.
We suggest using the FLAVOUR environment variable with a case insensitive value such as posix, unix (for Research Unix), sysv, bsd, gnu, windows, plan9, inferno to indicate the flavour to be used, with possible even more precise indications such as unix:v6, bsd:freebsd, bsd:netbsd, bsd:openbsd, etc.
But that would just be the cherry on the cake!