Create or modernize a python package

Inspired from this article and this tool.

1. Project Structure

Recommended Structure

project/
├── .github/
│ └── workflows/
├── doc/
├── src/
│ └── project/
│ ├── init.py
│ └── main.py
├── test/
│ └── test_main.py
├── .gitignore
├── LICENSE
├── README.md
├── pyproject.toml

You can use this .gitignore

2. Configuration with pyproject.toml

Transitioning from setup.py to pyproject.toml simplifies and modernizes Python package management.

Pros and Cons of Switching from setup.py to pyproject.toml

Pros

1. Standardization: pyproject.toml follows PEP 518, promoting a standardized project configuration.
2. Simplified Configuration: Consolidates build system requirements and project metadata in a single file.
3. Tool Compatibility: Enhanced support for modern Python tools like Poetry and Flit.
4. Future-Proof: Aligns with the future direction of Python packaging.

Cons

1. Learning Curve: Requires learning the TOML format and new configuration syntax.
2. Limited Features: Some advanced build steps may still require setup.py.
3. Tooling Maturity: Some tools may not fully support pyproject.toml yet.
4. Backward Compatibility: Older environments and tools may not recognize pyproject.toml.

Conclusion

Switching to pyproject.toml offers many advantages, but consider your project's specific needs and the current ecosystem support before making the change.

Need for setup.py

In most cases, setup.py is no longer needed when using pyproject.toml. However, it may still be necessary for:

• Complex build steps not yet supported by PEP 517.
• Backward compatibility with older tools or environments.

Sticking with setuptools

setuptools remains a reliable and widely-supported option. It integrates well with pyproject.toml and handles most use cases efficiently.

Why OpenAlea should keep setuptools:

• Language Interoperability: OpenAlea includes many languages such as C, C++, and Fortran. setuptools supports building and distributing extensions written in these languages, ensuring seamless integration.
• Community and Support: setuptools is mature and widely used, providing extensive documentation and community support.
• Custom Build Steps: Allows for custom build steps via setup.py when necessary, providing flexibility.

Exploring Alternatives

• Poetry: Excellent dependency management and packaging.
• Flit: Simplifies publishing of pure Python packages.
• Hatch: Advanced features for managing and packaging projects.

Basic Configuration

[build-system]
requires = ["setuptools", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "your_project"
version = "0.1.0"
description = "A brief description of your project"
readme = "README.md"
authors = [{ name = "Your Name", email = "[email protected]" }]
license = { text = "CeCILL" }
keywords = ["example", "project"]
requires-python = ">=3.8"
dependencies = []

[tool.setuptools.packages.find]
where = ["src"]
namespaces = true

TODO - URGENT: Explain Entrypoint (Wralea) TODO : Improve the Namespaces Wiki Page

3. Documentation

Writing Documentation

Ensure comprehensive and accessible documentation. Use Sphinx and host on ReadTheDocs.

TODO : link (or update) to the doc page for OpenAlea (configuration, logo, configuration file for rtfd with conda, ...). Add examples.

Sphinx Configuration

conf.py for Sphinx

# conf.py

The `conf.py` file is essential for setting up Sphinx to build your project's documentation. It defines the structure, theme, and extensions of your docs, ensuring consistency across builds.

# -- Project information -----------------------------------------------------
project = 'OpenAlea'
author = 'OpenAlea Consortium'
copyright = '2007 - 2024, OpenAlea Consortium'

# The full version, including alpha/beta/rc tags
release = '1.0.0a'

# -- General configuration ---------------------------------------------------

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
import sphinx_rtd_theme


extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon', 'sphinx.ext.viewcode']

# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']

# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = []

# Theme options are theme-specific and customize the look and feel of a theme
# further.  For a list of options available for each theme, see the
# documentation.
#
html_theme = 'sphinx_rtd_theme'
html_theme_options = {'logo_only': False}


# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
html_logo = "_static/openalea_web.svg"

.readthedocs.yml

A .readthedocs.yml file is essential for configuring ReadTheDocs to build and host your Sphinx documentation automatically. This file specifies the environment and build settings for your documentation.

# Read the Docs configuration file for Sphinx projects
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details

# Required
version: 2

# Set the OS, Python version, and other tools you might need
build:
  os: ubuntu-22.04
  tools:
    python: "3.10"

# Build documentation in the "doc/" directory with Sphinx
sphinx:
  configuration: doc/conf.py

conda:
  environment: doc/environment.yml

Publishing doc locally for Testing

Install Sphinx

pip install sphinx

Build Docs

sphinx-build -b html doc/ doc/_build/html

4. Testing

Writing Tests

Use pytest to write and run tests. Place test files in the test/ directory.

Running Tests Locally

To run all tests locally:

pytest

To run a specific test file: pytest test/test_main.py

In the CI/CD file you can setup this part:

    - name: Run tests
      run: |
        pytest

5. Continuous Integration

Set up Continous Integration

6. Checklist

To ensure quality of your package, please use this checklist:

• Project Structure: Organize code, documentation, and tests.
• Configuration: Use pyproject.toml for build and project metadata.
• Dependencies: Clearly define necessary and optional dependencies.
• Documentation: Write and maintain comprehensive documentation.
• Testing: Implement tests using pytest.
• Continuous Integration: Set up CI pipelines (e.g., GitHub Actions).