Contributing

Any change, big or small, that you think can help improve this project is more than welcome 🎉.

As well as this, feel free to open an issue with any new suggestions or bug reports. Every contribution is appreciated.

Contributors ✨

Thanks goes to these wonderful people (emoji key):


Timothy Langer
⚠️ 📖
Charlie Wilson
💻 ⚠️
Max Bowman
💻 ⚠️		 Mohsen BANAN
Mohsen BANAN
🐛

This project follows the all-contributors specification. Contributions of any kind are welcome!

🏗 Setup

First, fork the GitHub project to your account. Then, run the following with your GitHub handle in place of INSERT_GITHUB_NAME:

git clone https://github.com/INSERT_GITHUB_NAME/checkdigit
cd checkdigit
poetry install && poetry shell
pre-commit install

Before submitting any new changes, please run make beforehand. This formats the code and runs the tests. Thank you :)

🏛 Project structure

checkdigit
├── scripts
│   ├── format.sh
│   └── tests.sh
├── checkdigit
│   ├── gs1.py
│   ├── isbn.py
│   ├── luhn.py
│   └── etc.
└── tests

Each new format should go into a separate file which is named accordingly.

📚 Building the Docs

The documentation can be found in docs/source.

We can use sphinx-autobuild to continuously rebuild the docs when changes are made.

make docs

🎪 File structure

Similar data formats should use the same function (e.g. ISBN-10 and ISBN-13 functions determine the length before calculations).

Each of the Python files follow the same general format:

# License + File docstring

from checkdigit._data import cleanse, convert, missing_template


def calculate(data: str) -> str:
    """Determines check digit.

    Args:
        data: A string of data missing a check digit

    Returns:
        str: The single missing check digit (not the whole block of data)

    Examples:
        >>> # These should show some different applications of the function.
        >>> from checkdigit import ...
        >>> calculate(...)
        "output"
    """
    # This helps to deal with user formatting inconsistencies
    # e.g. spaces, hyphens, etc.
    data = cleanse(data)

    # Insert logic here

    # convert() deals with 10 or 11 being the possible check digit
    # N.B. This might not always be necessary if 10/11 aren't options (e.g. binary parity)
    return convert(...)


def validate(data: str) -> bool:
    """Validates a block of data from the check digit.

    Args:
        data: A string representing a full block of data

    Returns:
        bool: A boolean representing whether the data is valid or not

    Examples:
        >>> # These should show some different applications of the function.
        >>> from checkdigit import ...
        >>> validate(...)
        "output"
    """

    # Remove the check digit and see if it matches
    # calculate() cleanses the data for us
    return calculate(data[:-1]) == data[-1]


def missing(data: str) -> str:
    """Returns the missing digit from a block of data.

    Args:
        data: A string with a question mark in the place of a missing digit.

    Returns:
        A string representing the missing digit (not the whole block of data)

    Examples:
        >>> # These should show some different applications of the function.
        >>> from checkdigit import ...
        >>> missing(...)
        "output"
    """

    # For the majority of formats, there's a default template that should work well
    # This just brute forces the digits from 0-9 and runs validate() on it.
    return missing_template(data, "module-name")