RFC: Make pyyaml an Optional Dependency

[lundybernard]

This RFC proposes making pyyaml an optional dependency in the project. This change will allow users who do not require YAML support to avoid installing the pyyaml library, reducing installation overhead and potential security vulnerabilities associated with unused packages.

Introduction

Currently, the project includes pyyaml as a mandatory dependency. However, not all users need pyyaml for their workflows. By making it an optional dependency, we can provide a more lightweight and versatile solution.

Problem Statement

The mandatory inclusion of pyyaml forces all users to install it, regardless of whether they need its functionality. This increases the installation size and may introduce unnecessary security risks.

Ideally, batconf will only depend on stdlib by default.

Proposed Solution

Make pyyaml an optional dependency. Users who need YAML support can install the pyyaml library separately. We will also update the documentation to guide users on how to install optional dependencies. Prior to making the change, a deprecation warning will be published to inform users of the upcoming change.

Detailed Design

Components

• Dependency Management: Update the pyproject.toml to list pyyaml as an optional dependency.
• Codebase: Modify the parts of the code that depend on pyyaml to check for its availability and provide a meaningful error message if it is not installed.

API Changes

No changes to the public API. Internal code that uses pyyaml may need to include conditional imports.

Dependencies

pyyaml will be moved to an optional dependency section in the pyproject.toml file.

Alternatives

• Do Nothing: Keep pyyaml as a mandatory dependency. Not chosen due to reasons outlined in the problem statement.
• Remove pyyaml Entirely: Not chosen because YAML support is useful for many users.

Impact

• Compatibility: Minimal impact as existing users can install pyyaml explicitly if needed.
• Performance: No significant impact on performance.
• Security: Reduced risk by minimizing unnecessary dependencies.
• Usability: Users needing pyyaml will need to install it manually.

Implementation Plan

1. Deprecation Warning: Release a new version with a deprecation warning indicating that pyyaml will become an optional dependency in future releases.
   • Add warnings in the codebase wherever pyyaml is imported or used.
   • Update the documentation to include notes on the upcoming change.
2. Optional Dependency Implementation:
   • Update pyproject.toml to mark pyyaml as an optional dependency.
   • Modify code to handle optional importing of pyyaml and provide fallback error messages.
3. Documentation: Update the documentation to inform users about the optional dependency and how to install it.
4. Final Release: Release a new version with the proposed changes.

Drawbacks

• Users who need YAML support will have to perform an extra step to install pyyaml using pip install batconf[yaml] or modify their pyproject.toml to specify the optional dependency.
• This change will break some existing installations, requiring users to modify their installation process.

Testing

• Unit Tests: Ensure that all functionality works both with and without the pyyaml library installed.
• Integration Tests: Verify that the project installs and functions correctly in environments both with and without the pyyaml dependency.
• User Acceptance Tests: Confirm with a sample user group that the documentation is clear and the installation process is smooth.

[lundybernard]

Before making this change, I want to add one or more additional configuration file options, which utilize only stdlib.

I'm considering TOML as the first new addition, and recommended default.