Skip to content

biip.symbology - Symbology Identifiers

Support for Symbology Identifiers.

Symbology Identifiers is a standardized way to identify what type of barcode symbology was used to encode the following data.

The Symbology Identifiers are a few extra characters that may be prefixed to the scanned data by the barcode scanning hardware. The software interpreting the barcode may use the Symbology Identifier to differentiate how to handle the barcode, but must at the very least be able to strip and ignore the extra characters.

Examples:

>>> from biip.symbology import SymbologyIdentifier
>>> si = SymbologyIdentifier.extract("]E05901234123457")
>>> pprint(si)
SymbologyIdentifier(
    value=']E0',
    iso_symbology=ISOSymbology.EAN_UPC,
    modifiers='0',
    gs1_symbology=GS1Symbology.EAN_13
)
>>> si = SymbologyIdentifier.extract("]I198765432109213")
>>> pprint(si)
SymbologyIdentifier(
    value=']I1',
    iso_symbology=ISOSymbology.ITF,
    modifiers='1',
    gs1_symbology=GS1Symbology.ITF_14
)
References

ISO/IEC 15424:2008.

GS1Symbology

Bases: Enum

Enum of Symbology Identifiers used in the GS1 system.

References
  • GS1 General Specifications, figure 5.1.2-2.
  • ISO/IEC 15424:2008.
Source code in src/biip/symbology.py 
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
class GS1Symbology(Enum):
    """Enum of Symbology Identifiers used in the GS1 system.

    References:
        - GS1 General Specifications, figure 5.1.2-2.
        - ISO/IEC 15424:2008.
    """

    EAN_13 = "E0"
    """EAN-13, UPC-A, or UPC-E."""

    EAN_TWO_DIGIT_ADD_ON = "E1"
    """Two-digit add-on symbol for EAN-13."""

    EAN_FIVE_DIGIT_ADD_ON = "E2"
    """Five-digit add-on symbol for EAN-13."""

    EAN_13_WITH_ADD_ON = "E3"
    """EAN-13, UPC-A, or UPC-E with add-on symbol."""

    EAN_8 = "E4"
    """EAN-8"""

    ITF_14 = "I1"
    """ITF-14"""

    GS1_128 = "C1"
    """GS1-128"""

    GS1_DATABAR = "e0"
    """GS1 DataBar"""

    GS1_COMPOSITE_WITH_SEPARATOR_CHAR = "e1"
    """GS1 Composite. Data packet follows an encoded symbol separator character."""

    GS1_COMPOSITE_WITH_ESCAPE_CHAR = "e2"
    """GS1 Composite. Data packet follows an escape mechanism character."""

    GS1_DATAMATRIX = "d2"
    """GS1 DataMatrix"""

    GS1_QR_CODE = "Q3"
    """GS1 QR Code"""

    GS1_DOTCODE = "J1"
    """GS1 DotCode"""

    @classmethod
    def with_ai_element_strings(cls) -> set[GS1Symbology]:
        """Symbologies that may contain AI Element Strings."""
        return {
            cls.GS1_128,
            cls.GS1_DATABAR,
            cls.GS1_DATAMATRIX,
            cls.GS1_QR_CODE,
            cls.GS1_DOTCODE,
        }

    @classmethod
    def with_gtin(cls) -> set[GS1Symbology]:
        """Symbologies that may contain GTINs."""
        return {cls.EAN_13, cls.EAN_13_WITH_ADD_ON, cls.EAN_8, cls.ITF_14}

    def __repr__(self) -> str:
        """Canonical string representation of format."""
        return f"GS1Symbology.{self.name}"

EAN_13 class-attribute instance-attribute 

EAN_13 = 'E0'

EAN-13, UPC-A, or UPC-E.

EAN_13_WITH_ADD_ON class-attribute instance-attribute 

EAN_13_WITH_ADD_ON = 'E3'

EAN-13, UPC-A, or UPC-E with add-on symbol.

EAN_8 class-attribute instance-attribute 

EAN_8 = 'E4'

EAN-8

EAN_FIVE_DIGIT_ADD_ON class-attribute instance-attribute 

EAN_FIVE_DIGIT_ADD_ON = 'E2'

Five-digit add-on symbol for EAN-13.

EAN_TWO_DIGIT_ADD_ON class-attribute instance-attribute 

EAN_TWO_DIGIT_ADD_ON = 'E1'

Two-digit add-on symbol for EAN-13.

GS1_128 class-attribute instance-attribute 

GS1_128 = 'C1'

GS1-128

GS1_COMPOSITE_WITH_ESCAPE_CHAR class-attribute instance-attribute 

GS1_COMPOSITE_WITH_ESCAPE_CHAR = 'e2'

GS1 Composite. Data packet follows an escape mechanism character.

GS1_COMPOSITE_WITH_SEPARATOR_CHAR class-attribute instance-attribute 

GS1_COMPOSITE_WITH_SEPARATOR_CHAR = 'e1'

GS1 Composite. Data packet follows an encoded symbol separator character.

GS1_DATABAR class-attribute instance-attribute 

GS1_DATABAR = 'e0'

GS1 DataBar

GS1_DATAMATRIX class-attribute instance-attribute 

GS1_DATAMATRIX = 'd2'

GS1 DataMatrix

GS1_DOTCODE class-attribute instance-attribute 

GS1_DOTCODE = 'J1'

GS1 DotCode

GS1_QR_CODE class-attribute instance-attribute 

GS1_QR_CODE = 'Q3'

GS1 QR Code

ITF_14 class-attribute instance-attribute 

ITF_14 = 'I1'

ITF-14

with_ai_element_strings classmethod 

with_ai_element_strings() -> set[GS1Symbology]

Symbologies that may contain AI Element Strings.

Source code in src/biip/symbology.py 
198
199
200
201
202
203
204
205
206
207
@classmethod
def with_ai_element_strings(cls) -> set[GS1Symbology]:
    """Symbologies that may contain AI Element Strings."""
    return {
        cls.GS1_128,
        cls.GS1_DATABAR,
        cls.GS1_DATAMATRIX,
        cls.GS1_QR_CODE,
        cls.GS1_DOTCODE,
    }

with_gtin classmethod 

with_gtin() -> set[GS1Symbology]

Symbologies that may contain GTINs.

Source code in src/biip/symbology.py 
209
210
211
212
@classmethod
def with_gtin(cls) -> set[GS1Symbology]:
    """Symbologies that may contain GTINs."""
    return {cls.EAN_13, cls.EAN_13_WITH_ADD_ON, cls.EAN_8, cls.ITF_14}

ISOSymbology

Bases: Enum

Enum of barcode symbologies that are supported by Symbology Identifers.

References

ISO/IEC 15424:2008, table 1.

Source code in src/biip/symbology.py 
 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
102
103
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
class ISOSymbology(Enum):
    """Enum of barcode symbologies that are supported by Symbology Identifers.

    References:
        ISO/IEC 15424:2008, table 1.
    """

    CODE_39 = "A"
    """Code 39"""

    TELEPEN = "B"
    """Telepen"""

    CODE_128 = "C"
    """Code 128"""

    CODE_ONE = "D"
    """Code One"""

    EAN_UPC = "E"
    """EAN/UPC"""

    CODABAR = "F"
    """Codabar"""

    CODE_93 = "G"
    """Code 93"""

    CODE_11 = "H"
    """Code 11"""

    ITF = "I"
    """ITF (Interleaved 2 of 5)"""

    CODE_16K = "K"
    """Code 16K"""

    PDF417 = "L"
    """PDF417 and MicroPDF417"""

    MSI = "M"
    """MSI"""

    ANKER = "N"
    """Anker"""

    CODABLOCK = "O"
    """Codablock"""

    PLESSEY_CODE = "P"
    """Plessey Code"""

    QR_CODE = "Q"
    """QR Code and QR Code 2005"""

    STRAIGHT_2_OF_5_WITH_2_BAR_START_STOP_CODE = "R"
    """Straigt 2 of 5 (with two bar start/stop codes)"""

    STRAIGHT_2_OF_5_WITH_3_BAR_START_STOP_CODE = "S"
    """Straigt 2 of 5 (with three bar start/stop codes)"""

    CODE_49 = "T"
    """Code 49"""

    MAXICODE = "U"
    """MaxiCode"""

    OTHER_BARCODE = "X"
    """Other barcode"""

    SYSTEM_EXPANSION = "Y"
    """System expansion"""

    NON_BARCODE = "Z"
    """Non-barcode"""

    CHANNEL_CODE = "c"
    """Channel Code"""

    DATA_MATRIX = "d"
    """Data Matrix"""

    RSS_EAN_UCC_COMPOSITE = "e"
    """RSS and EAN.UCC Composite"""

    OCR = "o"
    """OCR (Optical Character Recognition)"""

    POSICODE = "p"
    """PosiCode"""

    SUPERCODE = "s"
    """SuperCode"""

    AZTEC_CODE = "z"
    """Aztec Code"""

    def __repr__(self) -> str:
        """Canonical string representation of format."""
        return f"ISOSymbology.{self.name}"

ANKER class-attribute instance-attribute 

ANKER = 'N'

Anker

AZTEC_CODE class-attribute instance-attribute 

AZTEC_CODE = 'z'

Aztec Code

CHANNEL_CODE class-attribute instance-attribute 

CHANNEL_CODE = 'c'

Channel Code

CODABAR class-attribute instance-attribute 

CODABAR = 'F'

Codabar

CODABLOCK class-attribute instance-attribute 

CODABLOCK = 'O'

Codablock

CODE_11 class-attribute instance-attribute 

CODE_11 = 'H'

Code 11

CODE_128 class-attribute instance-attribute 

CODE_128 = 'C'

Code 128

CODE_16K class-attribute instance-attribute 

CODE_16K = 'K'

Code 16K

CODE_39 class-attribute instance-attribute 

CODE_39 = 'A'

Code 39

CODE_49 class-attribute instance-attribute 

CODE_49 = 'T'

Code 49

CODE_93 class-attribute instance-attribute 

CODE_93 = 'G'

Code 93

CODE_ONE class-attribute instance-attribute 

CODE_ONE = 'D'

Code One

DATA_MATRIX class-attribute instance-attribute 

DATA_MATRIX = 'd'

Data Matrix

EAN_UPC class-attribute instance-attribute 

EAN_UPC = 'E'

EAN/UPC

ITF class-attribute instance-attribute 

ITF = 'I'

ITF (Interleaved 2 of 5)

MAXICODE class-attribute instance-attribute 

MAXICODE = 'U'

MaxiCode

MSI class-attribute instance-attribute 

MSI = 'M'

MSI

NON_BARCODE class-attribute instance-attribute 

NON_BARCODE = 'Z'

Non-barcode

OCR class-attribute instance-attribute 

OCR = 'o'

OCR (Optical Character Recognition)

OTHER_BARCODE class-attribute instance-attribute 

OTHER_BARCODE = 'X'

Other barcode

PDF417 class-attribute instance-attribute 

PDF417 = 'L'

PDF417 and MicroPDF417

PLESSEY_CODE class-attribute instance-attribute 

PLESSEY_CODE = 'P'

Plessey Code

POSICODE class-attribute instance-attribute 

POSICODE = 'p'

PosiCode

QR_CODE class-attribute instance-attribute 

QR_CODE = 'Q'

QR Code and QR Code 2005

RSS_EAN_UCC_COMPOSITE class-attribute instance-attribute 

RSS_EAN_UCC_COMPOSITE = 'e'

RSS and EAN.UCC Composite

STRAIGHT_2_OF_5_WITH_2_BAR_START_STOP_CODE class-attribute instance-attribute 

STRAIGHT_2_OF_5_WITH_2_BAR_START_STOP_CODE = 'R'

Straigt 2 of 5 (with two bar start/stop codes)

STRAIGHT_2_OF_5_WITH_3_BAR_START_STOP_CODE class-attribute instance-attribute 

STRAIGHT_2_OF_5_WITH_3_BAR_START_STOP_CODE = 'S'

Straigt 2 of 5 (with three bar start/stop codes)

SUPERCODE class-attribute instance-attribute 

SUPERCODE = 's'

SuperCode

SYSTEM_EXPANSION class-attribute instance-attribute 

SYSTEM_EXPANSION = 'Y'

System expansion

TELEPEN class-attribute instance-attribute 

TELEPEN = 'B'

Telepen

SymbologyIdentifier dataclass

Data class containing a Symbology Identifier.

Source code in src/biip/symbology.py 
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
@dataclass
class SymbologyIdentifier:
    """Data class containing a Symbology Identifier."""

    value: str
    """Raw unprocessed value."""

    iso_symbology: ISOSymbology
    """The recognized ISO symbology."""

    modifiers: str
    """Symbology modifiers.

    Refer to [`gs1_symbology`][biip.symbology.SymbologyIdentifier.gs1_symbology]
    or ISO/IEC 15424 for interpretation.
    """

    gs1_symbology: GS1Symbology | None = None
    """If the Symbology Identifier is used in the GS1 system,
    this field is set to indicate how to interpret the following data.
    """

    @classmethod
    def extract(cls, value: str) -> SymbologyIdentifier:
        """Extract the Symbology Identifier from the given value.

        Args:
            value: The string to extract a Symbology Identifier from.

        Returns:
            Metadata about the extracted Symbology Identifier.

        Raises:
            ParseError: If the parsing fails.
        """
        if not value.startswith("]"):
            msg = (
                f"Failed to get Symbology Identifier from {value!r}. "
                "No initial ']' flag character found."
            )
            raise ParseError(msg)

        try:
            iso_symbology = ISOSymbology(value[1])
        except ValueError as exc:
            msg = (
                f"Failed to get Symbology Identifier from {value!r}. "
                f"{value[1]!r} is not a recognized code character."
            )
            raise ParseError(msg) from exc

        if iso_symbology == ISOSymbology.SYSTEM_EXPANSION:
            modifiers_length = int(value[2]) + 1
        else:
            modifiers_length = 1

        modifiers = value[2 : 2 + modifiers_length]

        value = f"]{iso_symbology.value}{modifiers}"

        gs1_symbology: GS1Symbology | None
        try:
            gs1_symbology = GS1Symbology(f"{iso_symbology.value}{modifiers}")
        except ValueError:
            gs1_symbology = None

        return cls(
            value=value,
            iso_symbology=iso_symbology,
            modifiers=modifiers,
            gs1_symbology=gs1_symbology,
        )

    def __len__(self) -> int:
        """Get the length of the Symbology Identfier."""
        return len(self.value)

    def __str__(self) -> str:
        """Get the string representation of the Symbology Identifier."""
        return self.value

gs1_symbology class-attribute instance-attribute 

gs1_symbology: GS1Symbology | None = None

If the Symbology Identifier is used in the GS1 system, this field is set to indicate how to interpret the following data.

iso_symbology instance-attribute 

iso_symbology: ISOSymbology

The recognized ISO symbology.

modifiers instance-attribute 

modifiers: str

Symbology modifiers.

Refer to gs1_symbology or ISO/IEC 15424 for interpretation.

value instance-attribute 

value: str

Raw unprocessed value.

extract classmethod 

extract(value: str) -> SymbologyIdentifier

Extract the Symbology Identifier from the given value.

Parameters:

  • value (str) –

    The string to extract a Symbology Identifier from.

Returns:

Raises:

Source code in src/biip/symbology.py 
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
@classmethod
def extract(cls, value: str) -> SymbologyIdentifier:
    """Extract the Symbology Identifier from the given value.

    Args:
        value: The string to extract a Symbology Identifier from.

    Returns:
        Metadata about the extracted Symbology Identifier.

    Raises:
        ParseError: If the parsing fails.
    """
    if not value.startswith("]"):
        msg = (
            f"Failed to get Symbology Identifier from {value!r}. "
            "No initial ']' flag character found."
        )
        raise ParseError(msg)

    try:
        iso_symbology = ISOSymbology(value[1])
    except ValueError as exc:
        msg = (
            f"Failed to get Symbology Identifier from {value!r}. "
            f"{value[1]!r} is not a recognized code character."
        )
        raise ParseError(msg) from exc

    if iso_symbology == ISOSymbology.SYSTEM_EXPANSION:
        modifiers_length = int(value[2]) + 1
    else:
        modifiers_length = 1

    modifiers = value[2 : 2 + modifiers_length]

    value = f"]{iso_symbology.value}{modifiers}"

    gs1_symbology: GS1Symbology | None
    try:
        gs1_symbology = GS1Symbology(f"{iso_symbology.value}{modifiers}")
    except ValueError:
        gs1_symbology = None

    return cls(
        value=value,
        iso_symbology=iso_symbology,
        modifiers=modifiers,
        gs1_symbology=gs1_symbology,
    )