Skip to content

biip.gs1_prefixes

Support for prefixes allocated by GS1.

GS1 prefixes are used to split the allocation space of various number schemes, e.g. GTIN, GLN, and SSCC.

The allocation space is split twice:

  • First, among the national GS1 organizations, represented by GS1Prefix.
  • Secondly, among the companies that apply to their national GS1 organization for a number allocation, represented by GS1CompanyPrefix.

All prefix data is bundled with Biip. No network access is required.

Examples:

>>> from biip.gs1_prefixes import GS1CompanyPrefix, GS1Prefix
>>> GS1Prefix.extract("7044610873466")
GS1Prefix(value='704', usage='GS1 Norway')
>>> GS1CompanyPrefix.extract("7044610873466")
GS1CompanyPrefix(value='704461')

GS1CompanyPrefix dataclass

Company prefix assigned by GS1.

The prefix assigned to a single company.

Examples:

>>> from biip.gs1_prefixes import GS1CompanyPrefix
>>> GS1CompanyPrefix.extract("7044610873466")
GS1CompanyPrefix(value='704461')
Source code in src/biip/gs1_prefixes/__init__.py 
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
@dataclass(frozen=True)
class GS1CompanyPrefix:
    """Company prefix assigned by GS1.

    The prefix assigned to a single company.

    Examples:
        >>> from biip.gs1_prefixes import GS1CompanyPrefix
        >>> GS1CompanyPrefix.extract("7044610873466")
        GS1CompanyPrefix(value='704461')
    """

    value: str
    """The company prefix itself."""

    @classmethod
    def extract(cls, value: str) -> GS1CompanyPrefix | None:
        """Extract the GS1 Company Prefix from the given value.

        Args:
            value: The string to extract a GS1 Company Prefix from.
                The value is typically a GLN, GTIN, or an SSCC.

        Returns:
            Metadata about the extracted prefix, or `None` if the prefix is unknown.

        Raises:
            ParseError: If the parsing fails.
        """
        if not value.isdecimal():
            msg = f"Failed to get GS1 Company Prefix from {value!r}."
            raise ParseError(msg)

        node = _GS1_COMPANY_PREFIX_TRIE
        digits = list(value)

        while digits:
            digit = digits.pop(0)

            assert isinstance(node, dict)
            if digit not in node:
                # Prefix is undefined.
                return None
            node = node[digit]

            if isinstance(node, int):
                if node == 0:
                    # Prefix is defined, but has zero length.
                    return None
                return cls(value=value[:node])

        return None

value instance-attribute 

value: str

The company prefix itself.

extract classmethod 

extract(value: str) -> GS1CompanyPrefix | None

Extract the GS1 Company Prefix from the given value.

Parameters:

  • value (str) –

    The string to extract a GS1 Company Prefix from. The value is typically a GLN, GTIN, or an SSCC.

Returns:

  • GS1CompanyPrefix | None –

    Metadata about the extracted prefix, or None if the prefix is unknown.

Raises:

Source code in src/biip/gs1_prefixes/__init__.py 
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
@classmethod
def extract(cls, value: str) -> GS1CompanyPrefix | None:
    """Extract the GS1 Company Prefix from the given value.

    Args:
        value: The string to extract a GS1 Company Prefix from.
            The value is typically a GLN, GTIN, or an SSCC.

    Returns:
        Metadata about the extracted prefix, or `None` if the prefix is unknown.

    Raises:
        ParseError: If the parsing fails.
    """
    if not value.isdecimal():
        msg = f"Failed to get GS1 Company Prefix from {value!r}."
        raise ParseError(msg)

    node = _GS1_COMPANY_PREFIX_TRIE
    digits = list(value)

    while digits:
        digit = digits.pop(0)

        assert isinstance(node, dict)
        if digit not in node:
            # Prefix is undefined.
            return None
        node = node[digit]

        if isinstance(node, int):
            if node == 0:
                # Prefix is defined, but has zero length.
                return None
            return cls(value=value[:node])

    return None

GS1Prefix dataclass

Prefix assigned by GS1.

Used to split the allocation space of various number schemes, e.g. GTIN, GLN, and SSCC, among GS1 organizations worldwide.

The GS1 Prefix does not identify the origin of a product, only where the number was assigned to a GS1 member organization.

References

https://www.gs1.org/standards/id-keys/company-prefix

Examples:

>>> from biip.gs1_prefixes import GS1Prefix
>>> GS1Prefix.extract("9781492053743")
GS1Prefix(value='978', usage='Bookland (ISBN)')
Source code in src/biip/gs1_prefixes/__init__.py 
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
@dataclass(frozen=True)
class GS1Prefix:
    """Prefix assigned by GS1.

    Used to split the allocation space of various number schemes, e.g. GTIN,
    GLN, and SSCC, among GS1 organizations worldwide.

    The GS1 Prefix does not identify the origin of a product, only where the
    number was assigned to a GS1 member organization.

    References:
        https://www.gs1.org/standards/id-keys/company-prefix

    Examples:
        >>> from biip.gs1_prefixes import GS1Prefix
        >>> GS1Prefix.extract("9781492053743")
        GS1Prefix(value='978', usage='Bookland (ISBN)')
    """

    value: str
    """The prefix itself."""

    usage: str
    """Description of who is using the prefix."""

    @classmethod
    def extract(cls, value: str) -> GS1Prefix | None:
        """Extract the GS1 Prefix from the given value.

        Args:
            value: The string to extract a GS1 Prefix from.

        Returns:
            Metadata about the extracted prefix, or `None` if the prefix is unknown.

        Raises:
            ParseError: If the parsing fails.
        """
        if not value.isdecimal():
            msg = f"Failed to get GS1 Prefix from {value!r}."
            raise ParseError(msg)

        node = _GS1_PREFIX_TRIE
        digits = list(value)

        while digits:
            digit = digits.pop(0)

            assert isinstance(node, dict)
            if digit not in node:
                # Prefix is undefined.
                return None
            node = node[digit]

            if isinstance(node, list):
                length, usage = node
                return cls(value=value[:length], usage=usage)

        return None

usage instance-attribute 

usage: str

Description of who is using the prefix.

value instance-attribute 

value: str

The prefix itself.

extract classmethod 

extract(value: str) -> GS1Prefix | None

Extract the GS1 Prefix from the given value.

Parameters:

  • value (str) –

    The string to extract a GS1 Prefix from.

Returns:

  • GS1Prefix | None –

    Metadata about the extracted prefix, or None if the prefix is unknown.

Raises:

Source code in src/biip/gs1_prefixes/__init__.py 
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
@classmethod
def extract(cls, value: str) -> GS1Prefix | None:
    """Extract the GS1 Prefix from the given value.

    Args:
        value: The string to extract a GS1 Prefix from.

    Returns:
        Metadata about the extracted prefix, or `None` if the prefix is unknown.

    Raises:
        ParseError: If the parsing fails.
    """
    if not value.isdecimal():
        msg = f"Failed to get GS1 Prefix from {value!r}."
        raise ParseError(msg)

    node = _GS1_PREFIX_TRIE
    digits = list(value)

    while digits:
        digit = digits.pop(0)

        assert isinstance(node, dict)
        if digit not in node:
            # Prefix is undefined.
            return None
        node = node[digit]

        if isinstance(node, list):
            length, usage = node
            return cls(value=value[:length], usage=usage)

    return None