allisbns.isbn

Classes and functions to work with ISBNs.

type allisbns.isbn.ISBN12 = int | integer

A valid ISBN-12 integer number.

type allisbns.isbn.MaybeISBN = str

A string that is expected to be an ISBN.

allisbns.isbn.ISBN_PATTERN: Pattern[str] = re.compile('^(?:978|979)?\\d{9}[\\dXx]$')

A simple pattern to match ISBN-10 and ISBN-13 values.

allisbns.isbn.FIRST_ISBN: Final[ISBN12] = 978000000000

First defined ISBN-12.

allisbns.isbn.LAST_ISBN: Final[ISBN12] = 979999999999

Last defined ISBN-12.

allisbns.isbn.TOTAL_ISBNS: Final = 2000000000

Total number of ISBNs.

allisbns.isbn.ISBN12_LENGTH = 12

The length of ISBN-12 numbers.

class allisbns.isbn.ISBNBounds(start: ISBN12, end: ISBN12)

Bases: NamedTuple

Represents ISBN bounds.

start: ISBN12

Alias for field number 0

end: ISBN12

Alias for field number 1

class allisbns.isbn.CanonicalISBN(value: MaybeISBN)

Bases: object

Represents a canonical (normalized) ISBN-13 string.

Only the ISBN-10 and ISBN-13 pattern check is performed upon creation. So canonical ISBN values are assumed to be valid even if: the registration group or registrant range are undefined, the correct digit is incorrectly calculated. For validation, see validate_isbn().

See also

normalize_isbn()

__init__(value: MaybeISBN)

Creates a canonical ISBN-13 object.

property bookland: Literal['978', '979']

Returns the bookland element.

property check_digit: str

Returns the check digit.

complete() → Self

hyphenate() → str

to_isbn12() → ISBN12

Converts to an ISBN12 number.

class allisbns.isbn.MaskedISBN(bookland: Literal['978', '979'], group: str, registrant: str, publication: str, check_digit: str)

Bases: object

Represents a masked structure of an ISBN-13 string.

Example

It is more practical to create it from a canonical ISBN:

>>> canonical = normalize_isbn("978-000-000-000-X")
>>> MaskedISBN.from_canonical(canonical)
MaskedISBN(
    bookland='978',
    group='0',
    registrant='00',
    publication='000000',
    check_digit='X',
)

bookland: Literal['978', '979']

Bookland, or GS1 element.

group: str

Registration group element.

registrant: str

Registrant element.

publication: str

Publication element.

check_digit: str

Check digit.

classmethod from_canonical(isbn: CanonicalISBN) → Self

Creates a masked structure from a canonical ISBN-13 string.

property elements: dict[str, str | Literal['978', '979']]

hyphenate() → str

Formats an ISBN string with elements delimited by a hyphen.

allisbns.isbn.ensure_isbn12(value: int | integer) → ISBN12

Ensures that a value is an ISBN-12 number.

allisbns.isbn.calculate_check_digit(isbn: CanonicalISBN | ISBN12) → int

Calculates the check digit for an ISBN.

allisbns.isbn.normalize_isbn(value: MaybeISBN | ISBN12, correct: bool = False) → CanonicalISBN

Normalizes an ISBN to a canonical form.

Parameters:

• value – An value to normalize.

• correct – Whether to check and replace the incorrect check digit with the correct one. Defaults to False.

Examples

1. The input ISBN-13 string with the correct check digit:

>>> normalize_isbn("978-000-000-000-2")
CanonicalISBN(9780000000002)

2. The input ISBN-13 string with the incorrect check digit:

>>> # Keep it as it is
>>> normalize_isbn("978-000-000-000-3")
CanonicalISBN(9780000000003)

>>> # Or, correct the check digit
>>> normalize_isbn("978-000-000-000-3", correct=True)
CanonicalISBN(9780000000002)

3. The input ISBN12 integer value:

>>> value: ISBN12 = 978_000_000_000
>>> normalize_isbn(value)
CanonicalISBN(9780000000002)

allisbns.isbn.match_isbn(x: MaybeISBN) → bool

Checks that the input string is an ISBN-10 or ISBN-13.

allisbns.isbn.validate_isbn(value: CanonicalISBN, *, return_reasons: bool = False) → bool | tuple[bool, list[InvalidISBNReason]]

Validates a canonical ISBN.

The validation includes checks for: (1) an undefined registration group, (2) an undefined registrant, and (3) an incorrect check digit. To check if a string is an ISBN or not, see match_isbn() instead.

Parameters:

• value – A canonical ISBN to validate.

• return_reasons – Whether to return reasons for failed checks or not.

Returns:

A boolean value or, if return_reasons is requested, a boolean value and a list of reasons for failed checks.

See also

match_isbn()

Examples

If you need to check a list of unsure ISBNs for validity, you can combine this function with match_isbn():

def check_isbn_for_errors(x: MaybeISBN) -> list[InvalidISBNReason]:
    if not match_isbn(x):
        return [InvalidISBNReason.NOT_ISBN]
    else:
        canonical_isbn = normalize_isbn(x)
        _, errors = validate_isbn(canonical_isbn, return_reasons=True)
        return errors

allisbns.isbn.get_prefix_bounds(prefix: str) → ISBNBounds

Gets bounds for an ISBN prefix.

allisbns.isbn.get_prefix_capacity(prefix: str) → int

Gets the capacity of an ISBN prefix.

allisbns.isbn.extract_group_prefix(isbn: CanonicalISBN) → str

Extracts the group prefix from the ISBN.

Parameters:

isbn – A canonical ISBN-13 string.

Returns:

A found full ISBN group prefix, e.g. ‘978-1’.

Raises:

InvalidISBNError – If the ISBN does not contain valid group prefix.

Note

Group ranges were periodically updated from the RangeMessage.xml file available from the International ISBN Agency and may not be the most recent.

See also

MaskedISBN

allisbns.isbn.generate_isbns(start_isbn: ISBN12 | None = None, limit: int | None = None) → Generator[CanonicalISBN]

Yields canonical ISBN-13 string values.

Parameters:

• start_isbn – A start ISBN-12 number. Defaults to None, meaning yields from the first ISBN-13, ‘978-000-000-000-2’.

• limit – A maximum number of ISBNs to yields. Defaults to None, meaning yields till the last ISBN-13, ‘979-999-999-999-0’.