Best practices for Open Source Python Software

[bebatut]

Best practices for Python codes

https://stackoverflow.com/questions/5341006/where-should-i-put-tests-when-packaging-python-modules
https://pythonchb.github.io/PythonTopics/where_to_put_tests.html
https://stackoverflow.com/questions/44977227/how-to-configure-main-py-init-py-and-setup-py-for-a-basic-package-setu
https://setuptools.pypa.io/en/latest/userguide/entry_point.html
https://stackoverflow.com/questions/19170054/entry-point-in-setup-py
https://stackoverflow.com/questions/31327762/what-is-the-difference-between-init-py-and-main-py
https://setuptools.pypa.io/en/stable/setuptools.html#automatic-script-creation
https://click.palletsprojects.com/en/5.x/setuptools/
https://stackoverflow.com/questions/4042905/what-is-main-py

https://python-packaging.readthedocs.io/en/latest/testing.html

• requirements.txt file with list of dependencies
• Project structure (guide)
• Code style (guide)
  • Follow PEP8 standard
  • Run flake8 or black
• Testing (guide)
  • Unit test
  • Automated tests verifying the functionality of the software
• Continuous integration with GitHub Action
  • Automated tests
  • Code style
• Packaging (guide)
  • Pypi
  • Conda

General best practices

• Use Git and GitHub
• LICENSE file: A plain-text file with the contents of an OSI approved software license
• CONTRIBUTING.md file: Clear guidelines for third parties wishing to contribute to the software
• .gitignore file
• Versioning & DOI
  • Connect repository to archiving tool like Zenodo
  • Generate releases often
• Documentation (guide)
  • README.md
    • Add a description of the project
    • Add installation details
  • Documentation together with the code: GitHub page, ReadTheDoc
  • A statement of need: Section titled 'Statement of Need' that clearly states what problems the software is designed to solve and who the target audience is
  • Installation instructions: Clearly-stated list of dependencies, installation guideline
  • Example usage: Examples of how to use the software (ideally to solve real-world analysis problems).
  • Functionality documentation: Documentation of the core functionality of the software documented to a satisfactory level (e.g., API method documentation)
  • API documentation inside the functions

[YedilSerzhan]

Thanks, it's very comprehensive.

I think for the code style it's worth mentioning PEP 8, the standard style guide for python development. The tools flake8 and black are based on it.

In my opinion, the file gitignore is also very important. There are usually some untracked files you want git to ignore.

[bebatut]

Thanks! I updated with your suggestions

[teresa-m]

Thanks a lot @bebatut! It is a very comprehensive collection. I think it could be shared with every student starting a project as a guideline for best practice. What do you think?
Maybe then we could add a small section on how to work with git to the general good practices?

• Use git and GitHub
• add a description of your project to the readme or a different file
• document intermediate results like plots or screenshots in the readme or a different file (e.g. overleave )