2. Common Features¶
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 stringValueError
– given id contains character(s) other than digits 0-9ValueError
– given id contains wrong check digitValueError
– 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 argumentsTypeError
– a given argument is not a Unicode stringValueError
– a given argument contains character(s) other than digits 0-9ValueError
– length of given company_prefix not validValueError
– given company_prefix not validValueError
– length of given location_reference not validValueError
– 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 stringValueError
– given id contains character(s) other than digits 0-9ValueError
– given id contains wrong check digitValueError
– 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 argumentsTypeError
– a given argument is not a Unicode stringValueError
– a given argument contains character(s) other than digits 0-9ValueError
– length of given company_prefix not validValueError
– given company_prefix not validValueError
– length of given item_reference not validValueError
– 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 stringValueError
– given id contains character(s) other than digits 0-9ValueError
– given id contains wrong check digitValueError
– 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 argumentsTypeError
– a given argument is not a Unicode stringValueError
– a given argument contains character(s) other than digits 0-9ValueError
– length of given company_prefix not validValueError
– given company_prefix not validValueError
– length of given item_reference not validValueError
– 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 stringValueError
– given id contains character(s) other than digits 0-9ValueError
– given id contains wrong check digitValueError
– 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 argumentsTypeError
– a given argument is not a Unicode stringValueError
– a given argument contains character(s) other than digits 0-9ValueError
– length of given company_prefix not validValueError
– given company_prefix not validValueError
– length of given item_reference not validValueError
– 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 stringValueError
– given id contains character(s) other than digits 0-9ValueError
– given id contains wrong check digitValueError
– 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 argumentsTypeError
– a given argument is not a Unicode stringValueError
– a given argument contains character(s) other than digits 0-9ValueError
– length of given company_prefix not validValueError
– given company_prefix not validValueError
– length of given shipper_reference not validValueError
– 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 stringValueError
– given id contains character(s) other than digits 0-9ValueError
– given id contains wrong check digitValueError
– 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 argumentsTypeError
– a given argument is not a Unicode stringValueError
– a given argument contains character(s) other than digits 0-9ValueError
– length of given company_prefix not validValueError
– given company_prefix not validValueError
– length of given serial_reference not validValueError
– 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 stringValueError
– given id contains wrong check digitValueError
– 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 argumentsTypeError
– a given argument is not a Unicode stringValueError
– a given argument contains character(s) other than digits 0-9ValueError
– given gs1_prefix not validValueError
– given registration_group not validValueError
– given registrant not validValueError
– combined length of arguments not validValueError
– 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 stringValueError
– given id contains wrong check digitValueError
– 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 argumentsTypeError
– a given argument is not a Unicode stringValueError
– a given argument contains character(s) other than digits 0-9ValueError
– given gs1_prefix not validValueError
– given registration_group not validValueError
– given registrant not validValueError
– combined length of arguments not validValueError
– 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 formatValueError
– 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
instanceRaises: TypeError
– given bic is not a Unicode stringValueError
– given bic (stripped) does not contain 8 or 11 charactersValueError
– given bic contains characters other than A-Z or 0-9ValueError
– 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 stringValueError
– given iban contains an unknown country codeValueError
– given iban contains wrong check digitsValueError
– 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 argumentsTypeError
– given country_code is not a Unicode stringValueError
– given country_code contains an invalid or unknown country codeTypeError
– given bank_identifier is not a Unicode string or not an intValueError
– length of given bank_identifier not valid for the given country codeTypeError
– given bank_account_number is not a Unicode string or not an intValueError
– length of given bank_account_number not valid for the given country codeValueError
– 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.