goodpractices.rst

Overview

This file, [goodpractices.rst](/projects/286/67223), serves as a comprehensive guide outlining best practices and recommendations for integrating and testing Python projects using `pytest`. It provides detailed instructions on:

• Setting up your Python environment for development and testing.

• Recommended project layouts and test discovery conventions.

• Choosing import modes for test modules.

• Advisories on deprecated practices such as running tests via setuptools.

• Using tools like tox and flake8-pytest-style for automation and code quality.

Its primary purpose is to help developers structure their Python projects and tests effectively, ensuring smooth integration, reliable test execution, and maintainable codebases.

Detailed Content Breakdown

1. Installation and Environment Setup

• Virtual Environments: Recommends using Python's built-in venv module to isolate dependencies from the system Python.

• Package Installation: Advises creating a pyproject.toml file with a minimal build system setup using hatchling.

• Editable Installs: Shows how to install packages in editable mode (pip install -e .) to allow live code changes without reinstalling.

**Example `pyproject.toml` snippet:**

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "PACKAGENAME"
version = "PACKAGEVERSION"

2. Python Test Discovery Conventions

`pytest` uses a standard discovery mechanism that:

• Starts collecting tests either from configured testpaths or the current directory.

• Recurses into subdirectories except those listed in norecursedirs.

• Searches for files matching test_*.py or *_test.py.

• Collects test items that are:

  • Test functions/methods prefixed with test.

  • Test classes prefixed with Test (without __init__), including staticmethod and classmethod methods.

• Supports unittest.TestCase subclasses as well.

3. Test Layout Recommendations

Two common layouts are discussed:

a) Tests Outside Application Code (Recommended)

Structure:

pyproject.toml
src/
    mypkg/
        __init__.py
        app.py
        view.py
tests/
    test_app.py
    test_view.py

Benefits:

• Tests can run against installed or editable versions.

• Recommended to use importlib import mode to avoid import issues.

• Suggests usage of the src directory layout to avoid common pitfalls.

• Advises setting PYTHONPATH=src or configuring pythonpath in pyproject.toml for test runs without editable install.

**Example config addition:**

[tool.pytest.ini_options]
addopts = [
    "--import-mode=importlib",
]
pythonpath = "src"

b) Tests Inside Application Code

Structure:

pyproject.toml
[src/]mypkg/
    __init__.py
    app.py
    view.py
    tests/
        __init__.py
        test_app.py
        test_view.py

• Tests can be run using pytest --pyargs mypkg.

• Supports src layout as well.

• Recommends absolute imports when using namespace packages without __init__.py.

4. Import Modes

Details on `pytest` import modes:

• prepend (default):

  • Adds directories to sys.path before importing.

  • Imports test files as top-level modules, requiring unique test file names.

  • Introduces potential conflicts when using editable installs or tox.

• importlib (recommended for new projects):

  • Uses importlib to import test modules without altering sys.path.

  • Avoids name conflicts and is more predictable.

Workarounds when using `prepend` import mode include adding `__init__.py` files to test directories to make them packages, allowing duplicate test module names with qualified imports.

5. Using tox

• tox automates creating isolated environments and running tests against installed packages.

• Helps detect packaging issues by testing installed versions rather than source checkouts.

6. Deprecated Practices

• Advises against using python setup.py test and pytest-runner.

• Explains that setuptools test commands are deprecated and pose security risks.

• References official deprecation notices and issues.

7. Code Style Checking with flake8-pytest-style

• Recommends using the third-party plugin flake8-pytest-style to enforce pytest-specific style rules.

• Helps catch common mistakes in fixture usage, naming, and markers.

• Plugin is configurable and not officially maintained by pytest.

Implementation Details and Algorithms

This file is a **documentation guide** rather than executable code. Therefore, it contains no classes or functions, nor any algorithms. Instead, it focuses on textual guidelines, configuration snippets, and command-line examples.

Its content is structured in reStructuredText (reST) format, suitable for Sphinx or similar documentation generators, with cross-references (`:doc:`, `:ref:`, `:confval:`) to other documentation topics.

Interaction with Other Parts of the System

• Project Packaging: Links to pyproject.toml and packaging tutorial documentation for proper project setup.

• pytest Core: Describes how pytest discovers tests, imports modules, and runs them.

• Build Tools: Mentions hatchling as the build backend.

• Test Automation: Integrates with tox for automated virtualenv creation and testing.

• Static Analysis: Suggests flake8-pytest-style plugin for linting pytest code.

• External References: Provides URLs and references to blog posts, GitHub issues, and official docs to deepen understanding.

Overall, this file acts as an integration point consolidating best practices for Python project testing and distribution workflows, ensuring consistency and maintainability across the development lifecycle.

Visual Diagram

Since this file is a **utility documentation guide** without classes or functions, the most appropriate diagram is a **flowchart** illustrating the main concepts and their relationships, focusing on test discovery, layout choices, and tooling.

flowchart TD
    A[Start: Setup Python Package]
    A --> B[Create pyproject.toml]
    B --> C{Choose Test Layout}
    C -->|Tests Outside App Code| D[Use src/ and tests/ folders]
    C -->|Tests Inside App Code| E[Inline tests in package folder]
    D --> F[Install package editable: pip install -e .]
    E --> F
    F --> G{Select Import Mode}
    G -->|prepend (default)| H[Require unique test filenames]
    G -->|importlib (recommended)| I[No sys.path changes, fewer conflicts]
    H --> J[May add __init__.py to tests/ for packages]
    I --> K[Run pytest normally]
    J --> K
    K --> L[Use tox for automated testing]
    L --> M[Use flake8-pytest-style for linting]
    M --> N[Run tests and maintain code quality]
    N --> O[End]

This flowchart shows the typical workflow a developer follows when setting up testing with pytest according to the recommendations in this file.

**Summary** The [goodpractices.rst](/projects/286/67223) file is a detailed guide that helps Python developers set up their project environments, structure tests effectively, and avoid common pitfalls during test discovery and execution. It promotes modern tooling and practices such as editable installs, `src` layouts, importlib import mode, and use of `tox` and linting tools to achieve robust and maintainable test suites.