입력 검증 및 오류 처리

Aspose.BarCode FOSS for Python는 인코딩하기 전에 모든 입력 데이터를 검증합니다. 각 심볼은 문자 집합, 길이 제한 및 형식 규칙을 확인하는 전용 InputParser 하위 클래스를 가지고 있습니다. 검증이 실패하면 라이브러리는 BarcodeError 계층 구조에서 타입화된 예외를 발생시켜 호출자가 입력 문제, 인코딩 실패 및 렌더링 이슈를 구분할 수 있게 합니다.

The InputParser 계층

각 심볼은 InputParser 구현을 등록합니다. BarcodeService.generate()을 호출하면 파서가 먼저 실행되어 NormalizedPayload를 생성하거나 해당 심볼에 대한 데이터가 유효하지 않을 경우 InvalidInputError을 발생시킵니다.

from aspose_barcode_foss import BarcodeService

service = BarcodeService()

# Valid Code 128 input — passes the Code128InputParser
barcode = service.generate("code128", "VALID-DATA-001")

# Invalid EAN-13 input — too few digits
try:
    barcode = service.generate("ean13", "123")
except Exception as e:
    print(type(e).__name__, e)

각 심볼 파서는 서로 다른 규칙을 검증합니다:

Code128InputParser — 모든 문자가 Code 128 문자 집합이 지원하는 ASCII 범위에 있는지 확인합니다
Code39InputParser — Code39Options.full_ascii에 따라 Code 39 기본 알파벳 또는 전체 ASCII 알파벳에 대해 문자를 검증합니다
Ean13InputParser — 정확히 12자리 또는 13자리 숫자가 필요합니다 (13번째는 체크 디지트)
Ean8InputParser — 정확히 7자리 또는 8자리 숫자가 필요합니다
QrInputParser — 선택된 QrEncodeMode (NUMERIC, ALPHANUMERIC, BYTE, 또는 KANJI)에 대해 데이터를 검증합니다
UpcaInputParser — 정확히 11자리 또는 12자리 숫자가 필요합니다
UpceInputParser — 유효한 UPC-E 패턴을 가진 정확히 6, 7, 혹은 8자리 숫자가 필요합니다

BarcodeError 계층 구조

모든 예외는 BarcodeError을(를) 상속하며, 이는 Python의 내장 Exception을 확장합니다. 이 계층 구조는 다양한 수준의 구체성을 가진 catch 블록을 허용합니다:

Exception	발생 시
`BarcodeError`	모든 라이브러리 예외의 기본 클래스
`InvalidInputError`	입력 데이터가 검증에 실패합니다 (잘못된 문자, 잘못된 길이)
`EncodingError`	검증이 통과된 후 인코딩 로직이 실패합니다
`RenderingError`	렌더러가 SVG 또는 PNG 출력 중 오류를 만나었습니다
`SymbologyNotFoundError`	심볼로지 이름이 `SymbologyRegistry`에 등록되어 있지 않습니다
`UnsupportedCapabilityError`	요청된 기능이 해당 심볼로지에서 사용할 수 없습니다
`UnsupportedFeatureError`	기능이 정의되었지만 구현되지 않았습니다

from aspose_barcode_foss import BarcodeService
from aspose_barcode_foss.errors import (
    BarcodeError,
    InvalidInputError,
    EncodingError,
    SymbologyNotFoundError,
)

service = BarcodeService()

try:
    barcode = service.generate("code128", "TEST-001")
    svg = barcode.to_svg()
except InvalidInputError as e:
    print(f"Input rejected: {e}")
except EncodingError as e:
    print(f"Encoding failed: {e}")
except SymbologyNotFoundError as e:
    print(f"Unknown symbology: {e}")
except BarcodeError as e:
    print(f"Barcode error: {e}")

심볼로지 이름 검증

SymbologyNotFoundError은(는) BarcodeService.generate()이(가) 등록되지 않은 심볼로지 이름을 받을 때 발생합니다. SymbologyRegistry은(는) 정식 이름 또는 별칭으로 이름을 해결하므로 "code128", "Code128", "CODE128" 모두 동일한 정의로 해결됩니다.

from aspose_barcode_foss import BarcodeService
from aspose_barcode_foss.errors import SymbologyNotFoundError

service = BarcodeService()

try:
    barcode = service.generate("invalid_type", "data")
except SymbologyNotFoundError as e:
    print(f"Not found: {e}")

체크 디짓 검증

EAN-13, EAN-8, UPC-A, UPC-E 심볼로지는 체크 디짓을 자동으로 계산합니다. 체크 디짓을 포함한 전체 데이터를 전달하면 파서는 계산된 값과 비교하여 검증합니다. Ean13Options 및 Ean8Options의 allow_check_digit_input 속성이 이 동작을 제어합니다.

from aspose_barcode_foss import BarcodeService
from aspose_barcode_foss import Ean13Options

service = BarcodeService()

# 12 digits — check digit computed automatically
barcode = service.generate("ean13", "590123412345")

# 13 digits — parser verifies the 13th digit matches the computed value
barcode = service.generate(
    "ean13", "5901234123457",
    encode=Ean13Options(allow_check_digit_input=True),
)

팁 및 모범 사례

데이터가 심볼로지 요구 사항을 충족하지 않을 수 있는 사용자 입력 폼에서 InvalidInputError을 잡아내세요.
BarcodeError을(를) 오류 유형을 구분할 필요가 없을 때만 포괄적인 처리용으로 사용합니다.
generate()을 호출하기 전에 심볼로지 이름을 지원되는 7가지 심볼로지(code128, code39, ean13, ean8, qrcode, upca, upce) 중 하나와 비교하여 SymbologyNotFoundError을 방지합니다.
데이터에 비-ASCII 문자가 포함된 경우 QR 코드에 대해 QrOptions을 통해 encoding_mode을 명시적으로 설정합니다.
체크 디지털을 수동으로 제공하는 대신 라이브러리에게 계산하도록 하세요 — 이렇게 하면 불일치를 방지할 수 있습니다

일반적인 문제

문제	원인	해결
`InvalidInputError` 에 EAN-13	데이터가 12자리보다 적거나 숫자가 아닌 문자를 포함하고 있습니다.	정확히 12자리 또는 13자리의 숫자를 제공하십시오.
`SymbologyNotFoundError`	심볼로지 이름에 오타가 있습니다 (예: `"code_128"` 대신 `"code128"`).	밑줄 없이 정규 이름을 사용하십시오.
`EncodingError`에 대한 Code 39	데이터에는 `full_ascii=True` 없이 소문자가 포함되어 있습니다	설정 `Code39Options(full_ascii=True)`
`UnsupportedFeatureError`	정의는 되었지만 아직 구현되지 않은 기능을 호출하고 있습니다	심볼로지 프로파일에서 `known_limitations`를 확인하십시오
`InvalidInputError`에 대한 UPC-A	데이터에 12자리 초과 숫자가 포함되어 있습니다	정확히 11자리 또는 12자리 숫자를 제공하십시오

FAQ

생성하기 전에 심볼로지 이름이 유효한지 어떻게 확인할 수 있나요?

BarcodeService.registry을(를) 사용하여 SymbologyRegistry에 접근합니다. 이름이 등록되지 않았을 경우 get_definition()를 호출하고 SymbologyNotFoundError를 잡습니다.

EAN 바코드에 대한 체크 디지털 검증을 비활성화할 수 있나요?

파서는 전체 길이 입력을 제공할 때 항상 체크 디지털을 검증합니다(EAN-13는 13자리, EAN-8는 8자리). 검증을 피하려면 데이터 자리만 제공하고(EAN-13는 12자리, EAN-8는 7자리) 라이브러리에게 체크 디지털을 계산하게 하세요.

바이너리 데이터를 1D 바코드 심볼로지에 전달하면 어떻게 되나요?

InvalidInputError이(가) 발생합니다. Code 128, Code 39, EAN 및 UPC 심볼로지는 텍스트 데이터만 허용합니다. 바이너리 데이터의 경우 QR Code를 QrEncodeMode.BYTE와 함께 사용하십시오.

라이브러리는 QR 코드의 데이터 길이를 검증합니까?

QrInputParser은(는) 데이터가 요청된 QR 버전의 용량 내에 들어가는지 검증합니다. 버전이 지정되지 않은 경우, 라이브러리는 데이터를 수용할 수 있는 가장 작은 버전을 선택합니다.

API Reference 요약

클래스 / 메서드	설명
`InputParser.parse(data, options)`	추상 메서드 — 입력을 `NormalizedPayload` 로 검증하고 정규화합니다
`Code128InputParser.parse(data, options)`	Code 128 입력 문자를 검증합니다
`Code39InputParser.parse(data, options)`	Code 39 기본 또는 전체 ASCII 입력을 검증합니다
`Ean13InputParser.parse(data, options)`	EAN-13 자릿수 및 체크 디지트를 검증합니다
`Ean8InputParser.parse(data, options)`	EAN-8 자릿수 및 체크 디지트를 검증합니다
`QrInputParser.parse(data, options)`	선택된 인코드 모드에 따라 QR 데이터를 검증합니다
`UpcaInputParser.parse(data, options)`	UPC-A 자릿수를 검증합니다
`UpceInputParser.parse(data, options)`	UPC-E 자리 수와 패턴을 검증합니다
`BarcodeError`	바코드 라이브러리의 기본 예외
`InvalidInputError`	잘못된 입력 데이터에 대해 발생함
`EncodingError`	인코딩에 실패했을 때 발생함
`RenderingError`	렌더링에 실패했을 때 발생함
`SymbologyNotFoundError`	등록되지 않은 심볼 이름에 대해 발생함
`UnsupportedCapabilityError`	사용 불가능한 기능에 대해 발생함
`UnsupportedFeatureError`	구현되지 않은 기능에 대해 발생함

참조

Aspose.BarCode for Python — Enterprise Documentation