Python Reference

Public API

EURING data processing library.

This package provides functionality to decode and validate EURING (European Union for Bird Ringing) data records. EURING is the standard format for bird ringing data exchange in Europe.

Main features: - Decode EURING 2000 and 2000+ format records - Validate field types and formats - Parse geographical coordinates - Look up code meanings

exception euring.EuringConstraintException

Bases: EuringException

Raised when a value violates field constraints beyond type.

exception euring.EuringException

Bases: Exception

Base exception for EURING errors.

exception euring.EuringLookupException

Bases: EuringException

Raised when a lookup value cannot be resolved.

class euring.EuringRecord(format: str, *, strict: bool = True)

Bases: object

Build or decode EURING records.

classmethod decode(value: str, format: str | None = None) → EuringRecord

Decode a EURING record string into an EuringRecord.

property display_format: str

Return the formal EURING format name.

export(output_format: str, *, force: bool = False, warn_on_loss: bool = True) → str

Export the record to another EURING string format.

property fields: dict[str, dict[str, object]]

Return the decoded field data.

has_errors(errors: object) → bool

Return True when a structured errors payload contains entries.

serialize(output_format: str | None = None) → str

Serialize and validate a EURING record string or JSON payload.

set(key: str, value: object) → EuringRecord

Set a field value by key.

to_dict() → dict[str, object]

Return a JSON-serializable representation of the record.

update(values: dict[str, object]) → EuringRecord

Update multiple field values.

validate(record: str | None = None) → dict[str, list]

Validate all fields, then apply multi-field and record-level checks.

exception euring.EuringTypeException

Bases: EuringException

Raised when a value does not satisfy its declared EURING type.

euring.convert_euring_record(value: str, source_format: str | None = None, target_format: str = 'euring2020', force: bool = False) → str

Convert EURING records between euring2000, euring2000plus, and euring2020.

euring.euring_coordinates_to_lat_lng(value: str) → dict[str, float]

Parse EURING geographical coordinates into latitude/longitude decimals.

euring.euring_identification_display_format(euring_number: Any) → str

Return EURING number in upper case, with anything that is not a letter or digit removed.

Parameters:

euring_number

Returns:

euring.euring_identification_export_format(euring_number: Any) → str

Return EURING code formatted for display and with added internal padding (dots) up to length 10.

Parameters:

• euring_number

• length

Returns:

euring.euring_scheme_export_format(scheme_code: Any) → str

Proper export format for a scheme code.

Parameters:

scheme_code – Scheme code (string)

Returns:

Formatted scheme code

euring.euring_species_export_format(species_code: str | int | None) → str

Proper export format for EURING species code.

Parameters:

species_code

Returns:

euring.is_alphabetic(value: str) → bool

Alphabetic.

Upper case letters drawn from the 26-letter Roman alphabet, some punctuation marks (but never commas) may be included. :param value: Value to test :return: Result

euring.is_alphanumeric(value: str) → bool

Alphanumeric.

Combinations of upper case letters, digits 0 to 9 and arithmetic signs. :param value: Value to test :return: Result

euring.is_integer(value: str) → bool

Integer.

Whole numbers, one or more digits. Note that some fields require leading zeroes. :param value: Value to test :return: Result

euring.is_numeric(value: str) → bool

Numeric.

Any numbers, with decimal points allowed. :param value: Value to test :return: Result

euring.is_numeric_signed(value: str) → bool

Numeric signed.

Like Numeric, but allows a leading minus sign. The value -0 is not permitted. :param value: Value to test :return: Result

euring.is_text(value: str) → bool

Text.

Any combination of letters, numbers and punctuation marks. :param value: Value to test :return: Result

euring.is_valid_euring_type(value: str, euring_type: str) → bool

Return True if a value matches the specified EURING encoding type.

euring.lat_lng_to_euring_coordinates(lat: float, lng: float) → str

Format latitude and longitude as EURING geographical coordinates.

Usage examples

Build a EURING record:

from euring import EuringRecord

record = EuringRecord("euring2000plus")
record.set("ringing_scheme", "GBB")
record.set("primary_identification_method", "A0")
record.set("identification_number", "1234567890")
record.set("place_code", "AB00")
record.set("geographical_coordinates", "+0000000+0000000")
record.set("accuracy_of_coordinates", "1")
record_str = record.serialize()
record_json = record.serialize(output_format="json")
record_2020 = record.export("euring2020")

serialize() raises ValueError if required fields are missing or a value fails validation. Use EuringRecord("euring2000plus", strict=False) to allow missing optional values and keep placeholders in the output. Use export() to convert to other EURING string formats.

Serialization always re-encodes from the current values. For EURING2000, fixed-width output uses hyphens for empty values and zero-pads integers to the declared length. For EURING2000+/EURING2020, empty values remain empty strings except for fields that explicitly use hyphen placeholders (for example Elapsed Time, Distance, and Direction); these placeholders are defined per-field via the empty_value schema attribute.