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.
6. Identifiers for exchanges and exchange traded financial assets¶
-
class
identifiers.
MIC
(mic)¶ Market Identifier Code
A unique identification code used to identify securities trading exchanges, regulated and non-regulated trading markets.
Each MIC is a four alpha character code, defined in ISO 10383.
Parameters: mic (Unicode string) – string representation of the MIC
Returns: MIC
instanceRaises: TypeError
– given mic is not a Unicode stringValueError
– given mic is not registered
-
class
identifiers.
ISIN
(*args)¶ International Securities Identification Number
An International Securities Identification Number uniquely identifies a tradable financial asset, a.k.a security.
As defined in ISO 6166, each ISIN consists of a two-letter ISO 3166-1 Country Code for the issuing country, followed by nine alpha-numeric characters (the National Securities Identifying Number, or NSIN, which identifies the security), and one numerical check digit, calculated by the Luhn algorithm.
Instances of
ISIN
can be created in two ways, by providing a Unicode string representation of an ISIN or by providing a country code and a national securities identifying number.1. Form
Parameters: isin (Unicode string) – string representation of an ISIN
Returns: instance of
ISIN
Raises: TypeError
– given isin is not a Unicode stringValueError
– given isin contains an unknown country codeValueError
– given isin contains a wrong check digitValueError
– given isin must be 12 characters longValueError
– given isin contains invalid character(s)
2. Form
Parameters: - country_code (Unicode string) – 2-character country code according to ISO 3166
- nsin (Unicode string) – national securities identifying number
Returns: instance of
ISIN
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 nsin is not a Unicode stringValueError
– length of given nsin not validValueError
– given nsin contains invalid character(s)
-
elements
()¶ Return the ISIN’s Country Code, National Securities Identifying Number and check digit as tuple.
-
check_digit
¶ Return the ISIN’s check digits.
-
country_code
¶ Return the ISIN’s Country Code.
-
nsin
¶ Return the ISIN’s National Securities Identifying Number.