Follow through on euring_type (#107)

Author: dyve

README.md

@@ -98,7 +98,7 @@ Decoded JSON structure (single record):
 ### Python Library
 
 ```python
-from euring import EuringRecord, is_valid_type, TYPE_ALPHABETIC
+from euring import EuringRecord, is_valid_euring_type, TYPE_ALPHABETIC
 
 # Decode a record
 record = EuringRecord.decode(
@@ -118,28 +118,48 @@ record_json = record.serialize(output_format="json")
 record_2020 = record.export("euring2020")
 
 # Validate a value
-is_valid = is_valid_type("ABC", TYPE_ALPHABETIC)
+is_valid = is_valid_euring_type("ABC", TYPE_ALPHABETIC)
 ```
 
 Decoded records expose a single `fields` mapping keyed by the stable ASCII
 snake_case field `key`. Each field entry includes the official `name`, the raw
 `value`, and an `order` index for stable sorting.
 
+### Field keys
+
+For programmatic use, each field also has a stable ASCII [snake_case](https://en.wikipedia.org/wiki/Snake_case) `key`.
+
+The EURING manuals use field names that may include spaces, hyphens, and mixed case. In many programming environments these are awkward to work with (for example when used as object attributes, column names, or identifiers in code). To make decoded output easier to use in Python, JSON, R, and similar tools, the library exposes a normalized ASCII snake_case `key` for every field.
+
+These keys are provided as a practical convenience for developers. They are not part of the formal EURING specification, and consuming systems are free to map them to their own conventions where needed.
+
+## EURING Reference Data
+
+This package ships with EURING reference data in `src/euring/data`.
+
+- All EURING Code tables follow the EURING Manual.
+- EURING-published updates for Species, Ringing Schemes, Place Codes, and Circumstances are curated and checked into the package.
+- End users do not need to refresh data separately.
+
 ## Data definition
 
 EURING vocabulary (as per the manuals):
 
 - Record: one encounter record.
 - Field: a single data element within a record.
 - Field name: the official EURING name for a field.
-- Type: the data type assigned to a field (Alphabetic, Alphanumeric, Integer, Numeric, Text).
+- EURING encoding type (`euring_type`): the wire-level constraint assigned to a field
+  (Alphabetic, Alphanumeric, Integer, Numeric, Text).
+- Value type (`value_type`): the intended data type used by this library for a field.
 - Code: the coded value stored in a field.
 - Code table: the reference table that maps codes to descriptions.
 - Column: fixed-width position in EURING2000 records.
 
 EURING uses a record-based format: each record contains a fixed sequence of fields.
 The manuals define official field names (with spaces/hyphens), which we preserve for display.
 
+
+
 ### Encoding vs data from an IT perspective
 
 A EURING record is UTF-8 text that follows an ASCII-era encoding structure
@@ -188,22 +208,6 @@ the EURING format.
 
 This package introduces a signed numeric type (`NumericSigned`) for the EURING2020 fields Latitude and Longitude. `NumericSigned` behaves like `Numeric`, but allows a leading minus sign and explicitly disallows -0. `NumericSigned` is a small, intentional clarification of the generic numeric types. The manuals clearly permit negative Latitude and Longitude in EURING2020, but the generic `Numeric` definition does not describe signed numbers. Making this explicit in the code helps prevent invalid values while staying faithful to the manuals and real-world usage. If a future revision of the specification formally defines signed numeric fields, this implementation can align with it without breaking compatibility.
 
-### Field keys
-
-For programmatic use, each field also has a stable ASCII [snake_case](https://en.wikipedia.org/wiki/Snake_case) `key`.
-
-The EURING manuals use field names that may include spaces, hyphens, and mixed case. In many programming environments these are awkward to work with (for example when used as object attributes, column names, or identifiers in code). To make decoded output easier to use in Python, JSON, R, and similar tools, the library exposes a normalized ASCII snake_case `key` for every field.
-
-These keys are provided as a practical convenience for developers. They are not part of the formal EURING specification, and consuming systems are free to map them to their own conventions where needed.
-
-## EURING Reference Data
-
-This package ships with EURING reference data in `src/euring/data`.
-
-- All EURING Code tables follow the EURING Manual.
-- EURING-published updates for Species, Ringing Schemes, Place Codes, and Circumstances are curated and checked into the package.
-- End users do not need to refresh data separately.
-
 ### Data sources
 
 - Species: <https://www.euring.org/files/documents/EURING_SpeciesCodes_IOC15_1.csv>

example.py

@@ -8,7 +8,7 @@
     EuringRecord,
     euring_dms_to_float,
     euring_lat_to_dms,
-    is_valid_type,
+    is_valid_euring_type,
 )
 
 
@@ -18,10 +18,10 @@ def main():
 
     # Test type validation
     print("\n1. Type Validation:")
-    print(f"is_alphabetic('ABC'): {is_valid_type('ABC', TYPE_ALPHABETIC)}")
-    print(f"is_alphabetic('abc'): {is_valid_type('abc', TYPE_ALPHABETIC)}")
-    print(f"is_integer('123'): {is_valid_type('123', TYPE_INTEGER)}")
-    print(f"is_integer('12.3'): {is_valid_type('12.3', TYPE_INTEGER)}")
+    print(f"is_alphabetic('ABC'): {is_valid_euring_type('ABC', TYPE_ALPHABETIC)}")
+    print(f"is_alphabetic('abc'): {is_valid_euring_type('abc', TYPE_ALPHABETIC)}")
+    print(f"is_integer('123'): {is_valid_euring_type('123', TYPE_INTEGER)}")
+    print(f"is_integer('12.3'): {is_valid_euring_type('12.3', TYPE_INTEGER)}")
 
     # Test coordinate conversion
     print("\n2. Coordinate Conversion:")

src/euring/__init__.py

@@ -39,7 +39,7 @@
     is_numeric,
     is_numeric_signed,
     is_text,
-    is_valid_type,
+    is_valid_euring_type,
 )
 from .utils import (
     euring_dms_to_float,
@@ -68,7 +68,7 @@
     "is_numeric",
     "is_numeric_signed",
     "is_text",
-    "is_valid_type",
+    "is_valid_euring_type",
     "EuringException",
     "EuringConstraintException",
     "EuringTypeException",

src/euring/field_schema.py

@@ -17,7 +17,7 @@
     TYPE_NUMERIC,
     TYPE_NUMERIC_SIGNED,
     TYPE_TEXT,
-    is_valid_type,
+    is_valid_euring_type,
 )
 
 __all__ = [
@@ -87,7 +87,7 @@ def _validate_raw(self, raw: str) -> str | None:
                 return None
             raise EuringConstraintException('Required field, empty value "" is not permitted.')
         self._validate_length(raw)
-        if self.euring_type and not is_valid_type(raw, self.euring_type):
+        if self.euring_type and not is_valid_euring_type(raw, self.euring_type):
             raise EuringTypeException(f'Value "{raw}" is not valid for type {self.euring_type}.')
         return raw
 
@@ -160,7 +160,7 @@ def encode(self, value: Any | None) -> str:
         ):
             str_value = str_value.zfill(self.length)
         self._validate_length(str_value)
-        if self.euring_type and not is_valid_type(str_value, self.euring_type):
+        if self.euring_type and not is_valid_euring_type(str_value, self.euring_type):
             raise EuringTypeException(f'Value "{str_value}" is not valid for type {self.euring_type}.')
         return str_value
 
@@ -183,7 +183,7 @@ def encode_for_format(self, value: Any | None, *, format: str) -> str:
         if self.key == "date" and isinstance(value, dt_date):
             str_value = value.strftime("%d%m%Y")
             self._validate_length(str_value)
-            if self.euring_type and not is_valid_type(str_value, self.euring_type):
+            if self.euring_type and not is_valid_euring_type(str_value, self.euring_type):
                 raise EuringTypeException(f'Value "{str_value}" is not valid for type {self.euring_type}.')
             return str_value
 
@@ -203,7 +203,7 @@ def encode_for_format(self, value: Any | None, *, format: str) -> str:
             str_value = str_value.lstrip("0") or "0"
 
         self._validate_length(str_value, ignore_variable_length=ignore_variable_length)
-        if self.euring_type and not is_valid_type(str_value, self.euring_type):
+        if self.euring_type and not is_valid_euring_type(str_value, self.euring_type):
             raise EuringTypeException(f'Value "{str_value}" is not valid for type {self.euring_type}.')
         return str_value
 

src/euring/types.py

@@ -110,18 +110,18 @@ def is_text(value: str) -> bool:
     return _matches(value, RE_TEXT)
 
 
-def is_valid_type(value: str, type: str) -> bool:
-    """Return True if a value matches the specified EURING field type."""
-    if type == TYPE_ALPHABETIC:
+def is_valid_euring_type(value: str, euring_type: str) -> bool:
+    """Return True if a value matches the specified EURING encoding type."""
+    if euring_type == TYPE_ALPHABETIC:
         return is_alphabetic(value)
-    if type == TYPE_ALPHANUMERIC:
+    if euring_type == TYPE_ALPHANUMERIC:
         return is_alphanumeric(value)
-    if type == TYPE_INTEGER:
+    if euring_type == TYPE_INTEGER:
         return is_integer(value)
-    if type == TYPE_NUMERIC:
+    if euring_type == TYPE_NUMERIC:
         return is_numeric(value)
-    if type == TYPE_NUMERIC_SIGNED:
+    if euring_type == TYPE_NUMERIC_SIGNED:
         return is_numeric_signed(value)
-    if type == TYPE_TEXT:
+    if euring_type == TYPE_TEXT:
         return is_text(value)
     return False

tests/test_types.py

@@ -10,7 +10,7 @@
     is_numeric,
     is_numeric_signed,
     is_text,
-    is_valid_type,
+    is_valid_euring_type,
 )
 
 
@@ -59,10 +59,10 @@ def test_text(self):
         assert not is_text("Hello\x00World")
         assert not is_text("Hello|World")
 
-    def test_is_valid_type(self):
-        assert is_valid_type("ABC", TYPE_ALPHABETIC)
-        assert is_valid_type("123", TYPE_INTEGER)
-        assert is_valid_type("-12.3", TYPE_NUMERIC_SIGNED)
-        assert not is_valid_type("-0", TYPE_NUMERIC_SIGNED)
-        assert not is_valid_type("abc", TYPE_ALPHABETIC)
-        assert is_valid_type("ABC", "Unknown") is False
+    def test_is_valid_euring_type(self):
+        assert is_valid_euring_type("ABC", TYPE_ALPHABETIC)
+        assert is_valid_euring_type("123", TYPE_INTEGER)
+        assert is_valid_euring_type("-12.3", TYPE_NUMERIC_SIGNED)
+        assert not is_valid_euring_type("-0", TYPE_NUMERIC_SIGNED)
+        assert not is_valid_euring_type("abc", TYPE_ALPHABETIC)
+        assert is_valid_euring_type("ABC", "Unknown") is False