2. Common Features

class identifiers.Identifier(*args, **kwds)

Abstract base class for identifiers.

__copy__()

copy(self)

Returns self (identifiers are immutable).

__deepcopy__(memo)

deepcopy(self)

Returns self (identifiers are immutable).

__hash__()

hash(self)

__repr__()

repr(self)

__str__()

str(self)

3. Identifiers standardized by GS1

class identifiers.GLN(*args)

Global Location Number

Used to identify parties and locations, for example companies, warehouses, factories and stores.

An instance of GLN can be created in two ways, by providing a Unicode string representation of a GLN or by providing the GLN’s elements as separate arguments.

1. Form

Parameters:id (Unicode string) – string representation of a GLN (with or without a check digit)

If id does not include a check digit, it is calculated and appended automatically.

Returns:

instance of GLN

Raises:
  • TypeError – given id is not a Unicode string
  • ValueError – given id contains character(s) other than digits 0-9
  • ValueError – given id contains wrong check digit
  • ValueError – length of given id not valid

2. Form

Parameters:
  • company_prefix (Unicode string) – number identifying the company issuing the identifier, starting with a 3-digit GS1 prefix
  • location_reference (Unicode string) – number identifying the location
  • check_digit (Unicode string) – 1-digit number (optional)

If check_digit is omitted, it is calculated and appended automatically.

Returns:

instance of GLN

Raises:
  • TypeError – invalid number of arguments
  • TypeError – a given argument is not a Unicode string
  • ValueError – a given argument contains character(s) other than digits 0-9
  • ValueError – length of given company_prefix not valid
  • ValueError – given company_prefix not valid
  • ValueError – length of given location_reference not valid
  • ValueError – invalid check digit
elements()

Return the identifier’s elements as tuple.

separated(separator='-')

Return a string representation of the identifier with its elements separated by the given separator.

check_digit

Return the identifier’s check digit.

company_prefix

Return the identifier’s company prefix part.

gs1_prefix

Return the identifier’s GS1 prefix part.

location_reference

Return the identifier’s reference part.

class identifiers.GTIN12(*args)

Global Trade Item Number (12 digits)

Used to identify products and services.

An instance of GTIN12 can be created in two ways, by providing a Unicode string representation of a GTIN12 or by providing the GTIN12’s elements as separate arguments.

1. Form

Parameters:id (Unicode string) – string representation of a GTIN12 (with or without a check digit)

If id does not include a check digit, it is calculated and appended automatically.

Returns:

instance of GTIN12

Raises:
  • TypeError – given id is not a Unicode string
  • ValueError – given id contains character(s) other than digits 0-9
  • ValueError – given id contains wrong check digit
  • ValueError – length of given id not valid

2. Form

Parameters:
  • company_prefix (Unicode string) – number identifying the company issuing the identifier, starting with a 3-digit GS1 prefix
  • item_reference (Unicode string) – number identifying the trade item
  • check_digit (Unicode string) – 1-digit number (optional)

If check_digit is omitted, it is calculated and appended automatically.

Returns:

instance of GTIN12

Raises:
  • TypeError – invalid number of arguments
  • TypeError – a given argument is not a Unicode string
  • ValueError – a given argument contains character(s) other than digits 0-9
  • ValueError – length of given company_prefix not valid
  • ValueError – given company_prefix not valid
  • ValueError – length of given item_reference not valid
  • ValueError – invalid check digit
elements()

Return the identifier’s elements as tuple.

separated(separator='-')

Return a string representation of the identifier with its elements separated by the given separator.

check_digit

Return the identifier’s check digit.

company_prefix

Return the identifier’s company prefix part.

gs1_prefix

Return the identifier’s GS1 prefix part.

item_reference

Return the identifier’s reference part.

class identifiers.GTIN13(*args)

Global Trade Item Number (13 digits)

Used to identify products and services.

An instance of GTIN13 can be created in two ways, by providing a Unicode string representation of a GTIN13 or by providing the GTIN13’s elements as separate arguments.

1. Form

Parameters:id (Unicode string) – string representation of a GTIN13 (with or without a check digit)

If id does not include a check digit, it is calculated and appended automatically.

Returns:

instance of GTIN13

Raises:
  • TypeError – given id is not a Unicode string
  • ValueError – given id contains character(s) other than digits 0-9
  • ValueError – given id contains wrong check digit
  • ValueError – length of given id not valid

2. Form

Parameters:
  • company_prefix (Unicode string) – number identifying the company issuing the identifier, starting with a 3-digit GS1 prefix
  • item_reference (Unicode string) – number identifying the trade item
  • check_digit (Unicode string) – 1-digit number (optional)

If check_digit is omitted, it is calculated and appended automatically.

Returns:

instance of GTIN13

Raises:
  • TypeError – invalid number of arguments
  • TypeError – a given argument is not a Unicode string
  • ValueError – a given argument contains character(s) other than digits 0-9
  • ValueError – length of given company_prefix not valid
  • ValueError – given company_prefix not valid
  • ValueError – length of given item_reference not valid
  • ValueError – invalid check digit
elements()

Return the identifier’s elements as tuple.

separated(separator='-')

Return a string representation of the identifier with its elements separated by the given separator.

check_digit

Return the identifier’s check digit.

company_prefix

Return the identifier’s company prefix part.

gs1_prefix

Return the identifier’s GS1 prefix part.

item_reference

Return the identifier’s reference part.

class identifiers.GTIN14(*args)

Global Trade Item Number (14 digits)

Used to identify products and services.

An instance of GTIN14 can be created in three ways, by providing a GTIN12 or GTIN13, by providing a Unicode string representation of a GTIN14 or by providing the GTIN14’s elements as separate arguments.

1. Form

Parameters:gtin (GTIN12 or GTIN13) – GTIN to be expanded to a GTIN14
Returns:instance of GTIN14

2. Form

Parameters:id (Unicode string) – string representation of a GTIN14 (with or without a check digit)

If id does not include a check digit, it is calculated and appended automatically.

Returns:

instance of GTIN14

Raises:
  • TypeError – given id is not a Unicode string
  • ValueError – given id contains character(s) other than digits 0-9
  • ValueError – given id contains wrong check digit
  • ValueError – length of given id not valid

3. Form

Parameters:
  • level_indicator (Unicode string) – 1-digit number providing additional name space
  • company_prefix (Unicode string) – number identifying the company issuing the identifier, starting with a 3-digit GS1 prefix
  • item_reference (Unicode string) – number identifying the trade item
  • check_digit (Unicode string) – 1-digit number (optional)

If check_digit is omitted, it is calculated and appended automatically.

Returns:

instance of GTIN14

Raises:
  • TypeError – invalid number of arguments
  • TypeError – a given argument is not a Unicode string
  • ValueError – a given argument contains character(s) other than digits 0-9
  • ValueError – length of given company_prefix not valid
  • ValueError – given company_prefix not valid
  • ValueError – length of given item_reference not valid
  • ValueError – invalid check digit
elements()

Return the identifier’s elements as tuple.

separated(separator='-')

Return a string representation of the identifier with its elements separated by the given separator.

check_digit

Return the identifier’s check digit.

company_prefix

Return the identifier’s company prefix part.

gs1_prefix

Return the identifier’s GS1 prefix part.

item_reference

Return the identifier’s reference part.

level_indicator

Return the identifier’s level indicator (i.e. the first digit).

class identifiers.GSIN(*args)

Global Shipment Identification Number

Used to identify shipments, i. e. logistics units delivered to a customer together.

An instance of GSIN can be created in two ways, by providing a Unicode string representation of a GSIN or by providing the GSIN’s elements as separate arguments.

1. Form

Parameters:id (Unicode string) – string representation of a GSIN (with or without a check digit)

If id does not include a check digit, it is calculated and appended automatically.

Returns:

instance of GSIN

Raises:
  • TypeError – given id is not a Unicode string
  • ValueError – given id contains character(s) other than digits 0-9
  • ValueError – given id contains wrong check digit
  • ValueError – length of given id not valid

2. Form

Parameters:
  • company_prefix (Unicode string) – number identifying the company issuing the identifier, starting with a 3-digit GS1 prefix
  • shipper_reference (Unicode string) – number identifying the shipment
  • check_digit (Unicode string) – 1-digit number (optional)

If check_digit is omitted, it is calculated and appended automatically.

Returns:

instance of GSIN

Raises:
  • TypeError – invalid number of arguments
  • TypeError – a given argument is not a Unicode string
  • ValueError – a given argument contains character(s) other than digits 0-9
  • ValueError – length of given company_prefix not valid
  • ValueError – given company_prefix not valid
  • ValueError – length of given shipper_reference not valid
  • ValueError – invalid check digit
elements()

Return the identifier’s elements as tuple.

separated(separator='-')

Return a string representation of the identifier with its elements separated by the given separator.

check_digit

Return the identifier’s check digit.

company_prefix

Return the identifier’s company prefix part.

gs1_prefix

Return the identifier’s GS1 prefix part.

shipper_reference

Return the identifier’s reference part.

class identifiers.SSCC(*args)

Serial Shipping Container Code

Used to identify logistics units, for example loads on pallets, roll cages or parcels.

An instance of SSCC can be created in two ways, by providing a Unicode string representation of a SSCC or by providing the SSCC’s elements as separate arguments.

1. Form

Parameters:id (Unicode string) – string representation of a SSCC (with or without a check digit)

If id does not include a check digit, it is calculated and appended automatically.

Returns:

instance of SSCC

Raises:
  • TypeError – given id is not a Unicode string
  • ValueError – given id contains character(s) other than digits 0-9
  • ValueError – given id contains wrong check digit
  • ValueError – length of given id not valid

2. Form

Parameters:
  • company_prefix (Unicode string) – number identifying the company issuing the identifier, starting with a 3-digit GS1 prefix
  • serial_reference (Unicode string) – number identifying the shipping container
  • check_digit (Unicode string) – 1-digit number (optional)

If check_digit is omitted, it is calculated and appended automatically.

Returns:

instance of SSCC

Raises:
  • TypeError – invalid number of arguments
  • TypeError – a given argument is not a Unicode string
  • ValueError – a given argument contains character(s) other than digits 0-9
  • ValueError – length of given company_prefix not valid
  • ValueError – given company_prefix not valid
  • ValueError – length of given serial_reference not valid
  • ValueError – invalid check digit
elements()

Return the identifier’s elements as tuple.

separated(separator='-')

Return a string representation of the identifier with its elements separated by the given separator.

check_digit

Return the identifier’s check digit.

company_prefix

Return the identifier’s company prefix part.

extension_digit

Return the identifier’s extension digit (i.e. the first digit).

gs1_prefix

Return the identifier’s GS1 prefix part.

serial_reference

Return the identifier’s reference part.

4. Identifiers for publications

class identifiers.ISBN(*args)

International Standard Book Number

The ISBN is a unique international identifier for monographic publications.

Each ISBN consists of 13 digits. It contains a 3-digits GS1 prefix (‘978’ or ‘979’), a Registration Group, denoting the local registration authority, a number denoting the Registrant, i. e. the company which registered the ISBN, a number denoting the Publication and a check digit.

An instance of ISBN can be created in two ways, by providing a Unicode string representation of an ISBN or by providing a GS1 prefix, a registration group, a registrant, a publication number and, optionally, a check digit.

1. Form

Parameters:

id (Unicode string) – string representation of an ISBN

Returns:

instance of ISBN

Raises:
  • TypeError – given id is not a Unicode string
  • ValueError – given id contains wrong check digit
  • ValueError – given id does not follow the format required for an ISBN

2. Form

Parameters:
  • gs1_prefix (Unicode string) – 3-digit GS1 prefix
  • registration_group (Unicode string) – number identifying the local registration authority
  • registrant (Unicode string) – number identifying the publishing company
  • publication (Unicode string) – number identifying the publication
  • check_digit (Unicode string) – 1-digit number (optional)
Returns:

instance of ISBN

Raises:
  • TypeError – invalid number of arguments
  • TypeError – a given argument is not a Unicode string
  • ValueError – a given argument contains character(s) other than digits 0-9
  • ValueError – given gs1_prefix not valid
  • ValueError – given registration_group not valid
  • ValueError – given registrant not valid
  • ValueError – combined length of arguments not valid
  • ValueError – wrong check digit
elements()

Return the identifier’s elements (gs1_prefix, registration_group, registrant, publication, check_digit) as tuple.

separated(separator='-')

Return a string representation of the identifier with its elements separated by the given separator.

check_digit

Return the identifier’s check digit.

gs1_prefix

Return the identifier’s GS1 prefix part.

publication

Return the identifier’s reference part.

registrant

Return the Registrant of the identifier.

registration_group

Return the Registration Group of the identifier.

class identifiers.ISMN(*args)

International Standard Music Number

The ISMN is a unique international identifier of all notated music publications, whether available for sale, hire or gratis, whether a part, a score, or an element in a multi-media kit.

Each ISMN consists of 13 digits. It contains a 3-digits GS1 prefix (‘979’), a Registration Group (‘0’), a number denoting the Registrant, i. e. the company which registered the ISMN, a number denoting the Publication and a check digit.

An instance of ISMN can be created in two ways, by providing a Unicode string representation of an ISMN or by providing a GS1 prefix, a registration group, a registrant, a publication number and, optionally, a check digit.

1. Form

Parameters:

id (Unicode string) – string representation of an ISMN

Returns:

instance of ISMN

Raises:
  • TypeError – given id is not a Unicode string
  • ValueError – given id contains wrong check digit
  • ValueError – given id does not follow the format required for an ISMN

2. Form

Parameters:
  • gs1_prefix (Unicode string) – 3-digit GS1 prefix
  • registration_group (Unicode string) – number identifying the local registration authority
  • registrant (Unicode string) – number identifying the publishing company
  • publication (Unicode string) – number identifying the publication
  • check_digit (Unicode string) – 1-digit number (optional)
Returns:

instance of ISMN

Raises:
  • TypeError – invalid number of arguments
  • TypeError – a given argument is not a Unicode string
  • ValueError – a given argument contains character(s) other than digits 0-9
  • ValueError – given gs1_prefix not valid
  • ValueError – given registration_group not valid
  • ValueError – given registrant not valid
  • ValueError – combined length of arguments not valid
  • ValueError – wrong check digit
elements()

Return the identifier’s elements (gs1_prefix, registration_group, registrant, publication, check_digit) as tuple.

separated(separator='-')

Return a string representation of the identifier with its elements separated by the given separator.

check_digit

Return the identifier’s check digit.

gs1_prefix

Return the identifier’s GS1 prefix part.

publication

Return the identifier’s reference part.

registrant

Return the Registrant of the identifier.

registration_group

Return the Registration Group of the identifier.

class identifiers.ISSN(digits)

International Standard Serial Number

The ISSN is used to identify newspapers, journals, magazines and periodicals of all kinds and on all media - print and electronic.

Parameters:digits (unicode string) – string representation of the ISSN

The argument must be a string with 8 digits, with 7 digits or with 7 digits followed by an ‘X’, optionally separated by a blank or a hyphen after the fourth digit.

Returns:

instance of ISSN

Raises:
  • ValueError – given arg has invalid format
  • ValueError – given arg contains wrong check digit
as_gtin(addon=None)

Return GTIN13 created from self + addon.

check_digit

Return the ISSN’s check digit.

raw_number

Return the ISSN without check digit.

5. Identifiers for banks and bank accounts

class identifiers.BIC(bic)

Business Identifier Code

Used to identify financial and non-financial institutions.

Each BIC consists of the Party Prefix (4 alpha-numeric), the Country Code (2 alpha) and the Party Suffix (2 alpha-numeric), optionally followed by the Branch Code (3 alpha-numeric).

Parameters:

bic (Unicode string) – string representation of the BIC

Returns:

BIC instance

Raises:
  • TypeError – given bic is not a Unicode string
  • ValueError – given bic (stripped) does not contain 8 or 11 characters
  • ValueError – given bic contains characters other than A-Z or 0-9
  • ValueError – given bic contains an unknown country code
elements()

Return the BIC’s Party Prefix, Country Code, Party Suffix and Branch Code as a tuple.

branch_code

Return the BIC’s Branch Code (maybe empty).

country_code

Return the BIC’s Country Code.

party_prefix

Return the BIC’s Party Prefix.

party_suffix

Return the BIC’s Party Suffix.

class identifiers.IBAN(*args)

International Bank Account Number

An internationally agreed system of identifying bank accounts across national borders.

Each IBAN consists of a two-letter ISO 3166-1 Country Code, followed by two check digits and up to thirty alphanumeric characters for a BBAN (Basic Bank Account Number) which has a fixed length per country and, included within it, a bank identifier with a fixed position and a fixed length per country. The check digits are calculated based on the scheme defined in ISO/IEC 7064 (MOD97-10).

Instances of IBAN can be created in two ways, by providing a Unicode string representation of an IBAN or by providing a country code, a bank identifier and a bank account number.

1. Form

Parameters:

iban (Unicode string) – string representation of an IBAN

Returns:

instance of IBAN

Raises:
  • TypeError – given iban is not a Unicode string
  • ValueError – given iban contains an unknown country code
  • ValueError – given iban contains wrong check digits
  • ValueError – given iban does not follow the format required for the given country code

2. Form

Parameters:
  • country_code (Unicode string) – 2-character country code according to ISO 3166
  • bank_identifier (Unicode string or int) – code identifying the bank maintaining the account
  • bank_account_number (Unicode string or int) – code identifying the account (within the namespace of the bank)
Returns:

instance of IBAN

Raises:
  • TypeError – invalid number of arguments
  • TypeError – given country_code is not a Unicode string
  • ValueError – given country_code contains an invalid or unknown country code
  • TypeError – given bank_identifier is not a Unicode string or not an int
  • ValueError – length of given bank_identifier not valid for the given country code
  • TypeError – given bank_account_number is not a Unicode string or not an int
  • ValueError – length of given bank_account_number not valid for the given country code
  • ValueError – given bank_identifier and bank_account_number do not follow the BBAN format required for the given country code
elements()

Return the IBAN’s Country Code, check digits, Bank Identifier and Bank Account Number as tuple.

bank_account_number

Return the IBAN’s Bank Account Number.

bank_identifier

Return the IBAN’s Bank Identifier.

check_digits

Return the IBAN’s check digits.

country_code

Return the IBAN’s Country Code.