harens/checkdigit

🔒 An easy-to-use check digit library for data validation

---

checkdigit is a pure Python library built for identification numbers. You want to validate a credit card number, or maybe even calculate a missing digit on an ISBN code? We've got you covered 😎.

Want to know more? Check out the API Reference and documentation!

Installation

MacPorts 🍎

sudo port install py-checkdigit

PyPi 🐍

pip install checkdigit

✨ Features

• 📦 Works out of the box with all supported Python versions (3.7-3.11).
• ⌨️ PEP 561 compatible, with built in support for type checking.
• 🏃 Zero runtime dependencies. What you see is what you get.
• 🧮 Capable of calculating missing digits or validating a block of data.
• 📝 Extensive in-code comments and docstrings to explain how it works behind the scenes.

✅ Supported Formats

• Even/Odd binary parity
• CRC

• GS1 Standards

  • EAN-8/13
  • GDTI
  • GLN
  • SSCC
  • UPC-A/E
  • etc. (all fixed length numeric GS1 data structures with a check digit)

• ISBN-10/13
• Luhn
• Verhoeff

For each of these formats, we provide functions to validate them and calculate missing digits.

Do you have any formats that you'd like to see supported? 🤔 Feel free to raise an issue, or even to send a pull request!

✨ Contributors

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

Want to help out? Check out the contributing page.

Thanks goes to these wonderful people (emoji key):

Timothy Langer ⚠️ 📖

Charlie Wilson 💻 ⚠️

Max Bowman 💻 ⚠️

Mohsen BANAN 🐛

📙 License

This project is licensed under GPL-3.0-or-later.

checkdigit's Issues

CLI Tool

There are many examples of python libraries that also feature CLI Tools (such as uvicorn)

There are various tools to accomplish this. However, the flags will have to be considered since there are lots of functions (validate10, missing, etc.)

Correct old wiki ISBN/EAN description

EAN is calculated with the oppostie weightings to ISBN.

Maybe note that the info in the old wiki should no longer be viewed as correct?

Fix Travis Deployment

Travis Deployment is currently failing due to HTTPError: 403 Client Error: Invalid or non-existent authentication information

An example of this is Build #16

It is hoped that bdcb7dd will fix this

Additional Tests

Having more tests can never be a bad thing!

Tests can be found in the tests.py file. An example would be the following:

checkdigit/tests.py

Line 64 in 59c3ee3

test(isbn.missing("?131103628"), "0")

The first parameter of test is the function to be tested, and the second is the expected value.

EDIT: This issue will be an ongoing issue, since when new features are added, more tests will be required.

Document Makefile methods

Following from c6f2e58, the shell scripts were replaced with a Makefile.

It might be useful to somehow document the various attributes that it provides.

Add mypy + pylint to tests

The code is currently fully type-checked, so it shouldn't be that hard to get mypy tests passing. Some of the code might need to be reformatted for pylint to work properly.

Fix "method_complexity" issue in checkdigit/luhn.py

Function calculate has a Cognitive Complexity of 12 (exceeds 5 allowed). Consider refactoring.

https://codeclimate.com/github/harens/checkdigit/checkdigit/luhn.py#issue_5fc23e4529cddf0001000020

PyPi README Images

Currently, the images on PyPi aren't formatting correctly

This should be fixed in the next release, due to 8a2c72d

Fix PyPi Formatting

See here.

Currently, a separate README has to be used, since PyPi understandably doesn't like HTML in the rst file.

This means that the gif is currently broken, and a different file to the main README has to be maintained

Refactor ISBN Functions

The ISBN Functions can also be used for various other codes, including Bookland, EAN-13 and EAN-8.

It might be useful to refactor it such that there aren't different functions for different lengths (i.e. only one validation functions).

Also, find a generic name for these types of codes, and collect it all under one heading.

Implement Credit Card Validator

Use a Luhn Algorithm to check Credit Card and IMEI numbers
This is a planned feature

Show Example Code

Showing example code in the README will help to show features

It will also help to improve understanding

Separate build tests from linting tests

Similar to seaport's tests.

This can hopefully not only speed up the tests, but also make it easier to see where they've failed.

Separate ISBNs from GTIN/GS1

See here.

All the GTIN-based codes should be a subset of GS1. The documentation should also be updated to reflect this.

Fix "method_complexity" issue in checkdigit/isbn.py

Function missing has a Cognitive Complexity of 6 (exceeds 5 allowed). Consider refactoring.

https://codeclimate.com/github/harens/checkdigit/checkdigit/isbn.py#issue_5fc23e4529cddf000100001f

For ISBN13 calculate and validate, when the checksum is 0 returned value is X instead

bookUtils.cs -i isbnCalculate13 978-1-960957-03
Returns X --- instead of 0

bookUtils.cs -i isbnValidate13 978-1-960957-03-X --- Returns True
bookUtils.cs -i isbnValidate13 978-1-960957-03-0 --- Returns False

978-1-960957-03-0 is a valid ISBN13.

Returning X instead of 0 seems to be by design, but why?

If it is not by design, then it is a bug.

P.S. bookUtils.cs is just a python command service that uses checkdigit.isbn

Support EAN-8 and UPC-E

EAN-13 and UPC-A, the two more common variants of each standard, are currently supported. It would be useful if EAN-8 and UPC-E, which are generally of a smaller size, are also supported.

See here for details about EAN/UPC barcodes.

Update API Short Descriptions

See here

Currently, the short descriptions aren't very descriptive, e.g. ISBN Validation Functions.

Maybe it can be improved by saying what it actually is, similar to the wiki first line on the code.

Determine additional Credit Card info

See here

e.g. Company that issued the credit card.

Script for setting up environment/linting

The commands required are currently documented in the README. It would be useful to have it all in one script to make it easier to setup.

This would also help when more commands are added in the future. It could also be this file that is run by GitHub Actions.

v0.0.3 is a tag, not a release

A very pedantic and minor issue from me; v0.0.3 does not show as a release but merely as a tag.

All the best

Move from GitHub Wiki to RTD

This was done with seaport, and so should be a similar process here.

This can allow us to automatically build the docs rather than updating it manually by hand with each new feature. This would however mean converting the markdown into rst.

Error handling

At the moment, there is very little error handling and defensive programming.

Small things such as detecting if there are invalid characters or whether the size is wrong (and then throwing an error) can help to improve the user experience.

This should be quite straight forward to do, and so this should be a good task for any new contributors!

GTIN: False results if length not 10 or 12

If the length of a GTIN code isn't 10, currently, checkdigit treats it as if it were 12 digits. This can lead to false results for other lengths.

This is the line in question:

checkdigit/checkdigit/gtin.py

Line 72 in a85a0a8

weights = (1, 3) * 6 if isbn else (3, 1) * 6

We always multiply by 6, which assumes the length is 12.

Remove Image Shadows

This will improve the visual aspect of the README

Add EAN-specific tests