Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
262 lines (202 loc) · 6.57 KB

CONTRIBUTING.md

File metadata and controls

262 lines (202 loc) · 6.57 KB

Contributing to Bioinfo Tools

Thank you for your interest in contributing to Bioinfo Tools! This document provides guidelines for adding new features and maintaining the codebase.

Development Setup

  1. Clone the repository:
git clone https://github.com/Mxrcon/Bioinfo-python-scripts.git
cd Bioinfo-python-scripts
  1. Install in development mode:
pip install -e .
  1. Run tests to ensure everything works:
python tests/test_scripts.py

Project Structure

Bioinfo-python-scripts/
├── bioinfo_tools/              # Main package
│   ├── __init__.py            # Package metadata
│   ├── __main__.py            # CLI entry point
│   ├── cli.py                 # Main CLI parser and command routing
│   ├── commands/              # Subcommand modules
│   │   ├── __init__.py
│   │   ├── extract_cds.py
│   │   ├── extract_proteins.py
│   │   ├── extract_genes.py
│   │   └── blast.py
│   └── utils/                 # Shared utilities
│       ├── __init__.py
│       └── common.py
├── tests/                     # Test suite
├── conda_recipe/              # Conda packaging
├── setup.py                   # Package setup
├── pyproject.toml             # Modern Python packaging
└── pixi.toml                  # Pixi configuration

Adding a New Subcommand

Follow these steps to add a new subcommand to the CLI:

1. Create the Command Module

Create a new file in bioinfo_tools/commands/ (e.g., my_command.py):

#!/usr/bin/env python
# -*- coding: utf-8 -*-
"""
My Command subcommand for bioinfo-tools.

Brief description of what this command does.
"""

import logging
from bioinfo_tools.utils import setup_logging

def register_subcommand(subparsers):
    """
    Register the my-command subcommand.
    
    Args:
        subparsers: The subparsers object from argparse
    """
    parser = subparsers.add_parser(
        'my-command',
        help='Short description for help listing',
        description='Longer description of what the command does.',
        formatter_class=__import__('argparse').RawDescriptionHelpFormatter,
        epilog="""
Examples:
    bioinfo-tools my-command -i input.txt -o output.txt
    bioinfo-tools my-command --input input.txt --output output.txt
        """
    )
    
    # Add arguments
    parser.add_argument(
        '--input', '-i',
        required=True,
        metavar='FILE',
        help='Input file path'
    )
    
    parser.add_argument(
        '--output', '-o',
        required=True,
        metavar='FILE',
        help='Output file path'
    )
    
    # Set the function to run when this command is called
    parser.set_defaults(func=run)


def run(args):
    """
    Execute the my-command command.
    
    Args:
        args: Parsed command line arguments
        
    Returns:
        int: Exit code (0 for success, 1 for failure)
    """
    setup_logging()
    
    try:
        logging.info("My Command started")
        logging.info(f"Input: {args.input}")
        logging.info(f"Output: {args.output}")
        
        # Your command logic here
        
        logging.info("My Command finished successfully")
        return 0
        
    except Exception as e:
        logging.error(f"Fatal error: {e}")
        return 1

2. Register the Command

Add your command to bioinfo_tools/commands/__init__.py:

from . import my_command

__all__ = [
    'extract_cds',
    'extract_proteins',
    'extract_genes',
    'blast',
    'my_command'  # Add your command here
]

3. Import in CLI Module

Update bioinfo_tools/cli.py to import and register your command:

def create_parser():
    # ... existing code ...
    
    # Import and register all subcommands
    from bioinfo_tools.commands import (
        extract_cds,
        extract_proteins,
        extract_genes,
        blast,
        my_command  # Add your import here
    )
    
    # Register each subcommand
    extract_cds.register_subcommand(subparsers)
    extract_proteins.register_subcommand(subparsers)
    extract_genes.register_subcommand(subparsers)
    blast.register_subcommand(subparsers)
    my_command.register_subcommand(subparsers)  # Add registration here
    
    return parser

4. Add Tests

Add tests for your new command in tests/test_scripts.py:

def test_my_command():
    """Test my-command."""
    print_header("Testing my-command")
    
    tests_passed = 0
    tests_total = 0
    
    # Test help command
    tests_total += 1
    if run_command(
        ["bioinfo-tools", "my-command", "--help"],
        "bioinfo-tools my-command --help"
    ):
        tests_passed += 1
    
    # Add more tests...
    
    print(f"\n{Colors.BOLD}my-command: {tests_passed}/{tests_total} tests passed{Colors.END}")
    return tests_passed, tests_total

5. Test Your Command

# Test help
bioinfo-tools my-command --help

# Test functionality
bioinfo-tools my-command -i test_input.txt -o test_output.txt

# Run full test suite
python tests/test_scripts.py

Coding Standards

  • Follow PEP 8 style guidelines
  • Use descriptive variable and function names
  • Add docstrings to all functions and classes
  • Use type hints where appropriate
  • Keep functions focused and modular
  • Add logging statements for important operations
  • Handle errors gracefully with try-except blocks
  • Return 0 for success, non-zero for failures

Using Shared Utilities

The bioinfo_tools.utils module provides common functionality:

from bioinfo_tools.utils import (
    setup_logging,           # Configure logging
    load_gene_list,          # Load gene names from file
    validate_input_folder,   # Validate folder exists and has files
    ensure_output_folder     # Create output folder if needed
)

Argument Naming Conventions

For consistency across all commands, use these argument patterns:

  • Input files/folders: --input-folder, -i or --input-file, -i
  • Output files/folders: --output-folder, -o or --output-file, -o
  • Gene lists: --genes-list, -g
  • Database folder: --db-folder, -d
  • E-value: --evalue, -e
  • Type parameters: --db-type, -t or --blast-type, -b

Submitting Changes

  1. Create a new branch for your feature
  2. Make your changes following the coding standards
  3. Add tests for new functionality
  4. Ensure all tests pass
  5. Update documentation (README, help messages, etc.)
  6. Submit a pull request with a clear description

Questions?

If you have questions or need help: