How to add a New Problem

[Hugues-DTANKOUO]

How to add a New Problem

Overview

This guide explains the process and requirements for contributing a new programming problem to our Problems application. New problems help expand our collection and provide more learning opportunities for users.

Problem Contribution Requirements

1. Problem Selection

When choosing a problem to add:

• Ensure it doesn't duplicate an existing problem
• Select an appropriate difficulty level (Easy, Medium, Hard)
• Choose problems with educational value that teach specific algorithms or programming concepts
• Consider computational efficiency aspects that could be tested

2. Problem Structure

Each new problem requires the following files:

src/problems/your_problem.py                      # Main function implementation
src/problems/inside_test/your_problem_test.py     # Internal test cases
tests/test_your_problem.py                        # External tests validating the internal tests

Optional (if needed):

src/problems/inside_test/data/your_problem/       # Test data files if required

3. Implementation Requirements

Main Function File (your_problem.py)

"""
.## Level: Easy/Medium/Hard

[Detailed problem description with background information]

.## Example:

[Show usage examples with input/output]

>your_problem input_example
expected_output

"""

# Import necessary libraries here


def your_problem(param1: Type, param2: Type) -> ReturnType:
    """
    Clear description of what the function does.

    :param param1: Description of first parameter
    :param param2: Description of second parameter
    :return: Description of the return value
    """
    # This should be a template for users to implement
    return ...  # type: ignore[return-value]

Internal Tests (inside_test/your_problem_test.py)

from typing import Callable

from problems.inside_test.util import async_timeout


async def your_problem_test_case_1(func: Callable[[Type], ReturnType]) -> None:
    """
    GIVEN [description of test conditions]
    WHEN the function is called
    THEN it should [expected outcome]
    """
    _functional_your_problem = async_timeout(100)(func)
    
    # Test implementation
    result = await _functional_your_problem(test_input)
    assert result == expected_output, "Error message"
    
    # Add more assertions as needed

Create multiple test functions for different test cases.

External Tests (test_your_problem.py)

import pytest

from problems.inside_test import your_problem_test
from problems.your_problem import your_problem


def correct_your_problem(param1: Type, param2: Type) -> ReturnType:
    """
    A correct implementation of the problem for testing.
    """
    # Implement correct solution here
    

async def test_test_case_with_base_function_then_error() -> None:
    """
    GIVEN the test case and base function
    WHEN the test case is run
    THEN an AssertionError should be raised
    """
    with pytest.raises(AssertionError):
        await your_problem_test.your_problem_test_case_1(your_problem)


async def test_test_case_with_correct_function_then_success() -> None:
    """
    GIVEN the test case and correct function
    WHEN the test case is run
    THEN any error should not be raised
    """
    await your_problem_test.your_problem_test_case_1(correct_your_problem)

4. Updates to Existing Files

The following files need to be updated:

1. src/problems/interface.py: Add your problem to PROBLEMS_LIST

   PROBLEMS_LIST = ["anagram", "palindrome", "knapsack", "nqueens", "your_problem"]

2. problems.md: Add your problem to the list with description

   ### <u><a> [5. 🟢/🟡/🔴 **Your Problem** - *Easy/Medium/Hard*](/src/problems/your_problem.py) </a></u>
   <br>
   
   Brief description of your problem and its significance.
   
   **Key Concepts:**
   - Concept 1
   - Concept 2
   - Concept 3
   
   **Example:**
   ```python
   > your_problem(example_input)
   expected_output

3. CHANGELOG.md: Add your problem to the "Next Version" section

   ## Next Version
   
   ### 🚀 New Features:
   
   - Added [Your Problem](/src/problems/your_problem.py) problem (Easy/Medium/Hard)

5. Testing Requirements

• Ensure all tests pass with the correct implementation
• Include timeout tests for performance-critical problems
• Verify base function tests fail correctly
• Cover edge cases and unexpected inputs

Submission Process

1. Fork the repository
2. Create a feature branch (feature/your_problem)
3. Implement the required files
4. Run tests and make sure they pass
5. Submit a pull request with a clear description

Review Criteria

Your problem submission will be reviewed for:

• Code quality and adherence to project standards
• Test coverage and robustness
• Educational value
• Clear problem description
• Appropriate difficulty categorization

Examples

For reference, examine these existing problems:

• anagram.py - Example of an Easy problem
• knapsack.py - Example of a Medium problem
• nqueens.py - Example of a Hard problem

---

Thank you for contributing to our problem collection! Your contribution helps others learn and improve their programming skills.