Field

FieldKey pydantic-model

FieldKey(*args: str | _CoercibleToKey | Self, **kwargs: Any)

Bases: _Key

Field key as a sequence of string parts.

Hashable for use as dict keys in registries. Parts cannot contain forward slashes (/) or double underscores (__).

Examples:

FieldKey("a/b/c")  # String format
# FieldKey(parts=['a', 'b', 'c'])

FieldKey(["a", "b", "c"])  # List format
# FieldKey(parts=['a', 'b', 'c'])

FieldKey(FieldKey(["a", "b", "c"]))  # FieldKey copy
# FieldKey(parts=['a', 'b', 'c'])

FieldKey("a", "b", "c")  # Variadic format
# FieldKey(parts=['a', 'b', 'c'])

Show JSON schema:

{
  "description": "Field key as a sequence of string parts.\n\nHashable for use as dict keys in registries.\nParts cannot contain forward slashes (/) or double underscores (__).\n\nExamples:\n    ```py\n    FieldKey(\"a/b/c\")  # String format\n    # FieldKey(parts=['a', 'b', 'c'])\n\n    FieldKey([\"a\", \"b\", \"c\"])  # List format\n    # FieldKey(parts=['a', 'b', 'c'])\n\n    FieldKey(FieldKey([\"a\", \"b\", \"c\"]))  # FieldKey copy\n    # FieldKey(parts=['a', 'b', 'c'])\n\n    FieldKey(\"a\", \"b\", \"c\")  # Variadic format\n    # FieldKey(parts=['a', 'b', 'c'])\n    ```",
  "properties": {
    "parts": {
      "items": {
        "type": "string"
      },
      "title": "Parts",
      "type": "array"
    }
  },
  "required": [
    "parts"
  ],
  "title": "FieldKey",
  "type": "object"
}

Fields:

• parts (tuple[str, ...])

Validators:

• _validate_input
• _validate_parts_content → parts

Source code in src/metaxy/models/types.py

def __init__(self, *args: str | _CoercibleToKey | Self, **kwargs: Any) -> None:
    """Initialize FieldKey from various input types."""
    super().__init__(*args, **kwargs)

Attributes

table_name property

table_name: str

Get SQL-like table name for this feature key.

Functions

to_string

to_string() -> str

Convert to string representation with "/" separator.

Source code in src/metaxy/models/types.py

def to_string(self) -> str:
    """Convert to string representation with "/" separator."""
    return KEY_SEPARATOR.join(self.parts)

__repr__

__repr__() -> str

Return string representation.

Source code in src/metaxy/models/types.py

def __repr__(self) -> str:
    """Return string representation."""
    return self.to_string()

__str__

__str__() -> str

Return string representation.

Source code in src/metaxy/models/types.py

def __str__(self) -> str:
    """Return string representation."""
    return self.to_string()

__lt__

__lt__(other: Any) -> bool

Less than comparison for sorting.

Source code in src/metaxy/models/types.py

def __lt__(self, other: Any) -> bool:
    """Less than comparison for sorting."""
    if isinstance(other, self.__class__):
        return self.parts < other.parts
    return NotImplemented

__le__

__le__(other: Any) -> bool

Less than or equal comparison for sorting.

Source code in src/metaxy/models/types.py

def __le__(self, other: Any) -> bool:
    """Less than or equal comparison for sorting."""
    if isinstance(other, self.__class__):
        return self.parts <= other.parts
    return NotImplemented

__gt__

__gt__(other: Any) -> bool

Greater than comparison for sorting.

Source code in src/metaxy/models/types.py

def __gt__(self, other: Any) -> bool:
    """Greater than comparison for sorting."""
    if isinstance(other, self.__class__):
        return self.parts > other.parts
    return NotImplemented

__ge__

__ge__(other: Any) -> bool

Greater than or equal comparison for sorting.

Source code in src/metaxy/models/types.py

def __ge__(self, other: Any) -> bool:
    """Greater than or equal comparison for sorting."""
    if isinstance(other, self.__class__):
        return self.parts >= other.parts
    return NotImplemented

__iter__

__iter__() -> Iterator[str]

Return iterator over parts.

Source code in src/metaxy/models/types.py

def __iter__(self) -> Iterator[str]:  # pyright: ignore[reportIncompatibleMethodOverride]
    """Return iterator over parts."""
    return iter(self.parts)

__getitem__

__getitem__(index: int) -> str

Get part by index.

Source code in src/metaxy/models/types.py

def __getitem__(self, index: int) -> str:
    """Get part by index."""
    return self.parts[index]

__len__

__len__() -> int

Get number of parts.

Source code in src/metaxy/models/types.py

def __len__(self) -> int:
    """Get number of parts."""
    return len(self.parts)

__contains__

__contains__(item: str) -> bool

Check if part is in key.

Source code in src/metaxy/models/types.py

def __contains__(self, item: str) -> bool:
    """Check if part is in key."""
    return item in self.parts

__reversed__

__reversed__()

Return reversed iterator over parts.

Source code in src/metaxy/models/types.py

def __reversed__(self):
    """Return reversed iterator over parts."""
    return reversed(self.parts)

__get_validators__ classmethod

__get_validators__()

Pydantic validator for when used as a field type.

Source code in src/metaxy/models/types.py

@classmethod
def __get_validators__(cls):
    """Pydantic validator for when used as a field type."""
    yield cls.validate

validate classmethod

validate(value: Any) -> FieldKey

Convert various inputs to FieldKey.

Source code in src/metaxy/models/types.py

@classmethod
def validate(cls, value: Any) -> FieldKey:
    """Convert various inputs to FieldKey."""
    if isinstance(value, cls):
        return value
    return cls(value)

model_dump

model_dump(**kwargs: Any) -> Any

Serialize to list format for backward compatibility.

Source code in src/metaxy/models/types.py

def model_dump(self, **kwargs: Any) -> Any:
    """Serialize to list format for backward compatibility."""
    # When serializing this key, return it as a list of parts
    # instead of the full Pydantic model structure
    return list(self.parts)

__hash__

__hash__() -> int

Return hash for use as dict keys.

Source code in src/metaxy/models/types.py

def __hash__(self) -> int:
    """Return hash for use as dict keys."""
    return hash(self.parts)

__eq__

__eq__(other: Any) -> bool

Check equality with another instance.

Source code in src/metaxy/models/types.py

def __eq__(self, other: Any) -> bool:
    """Check equality with another instance."""
    if isinstance(other, self.__class__):
        return self.parts == other.parts
    return super().__eq__(other)

FieldSpec pydantic-model

FieldSpec(key: CoercibleToFieldKey, code_version: str = DEFAULT_CODE_VERSION, deps: SpecialFieldDep | list[FieldDep] | None = None, *args, **kwargs: Any)

Bases: BaseModel

Show JSON schema:

{
  "$defs": {
    "FeatureKey": {
      "description": "Feature key as a sequence of string parts.\n\nHashable for use as dict keys in registries.\nParts cannot contain forward slashes (/) or double underscores (__).\n\nExamples:\n    ```py\n    FeatureKey(\"a/b/c\")  # String format\n    # FeatureKey(parts=['a', 'b', 'c'])\n\n    FeatureKey([\"a\", \"b\", \"c\"])  # List format\n    # FeatureKey(parts=['a', 'b', 'c'])\n\n    FeatureKey(FeatureKey([\"a\", \"b\", \"c\"]))  # FeatureKey copy\n    # FeatureKey(parts=['a', 'b', 'c'])\n\n    FeatureKey(\"a\", \"b\", \"c\")  # Variadic format\n    # FeatureKey(parts=['a', 'b', 'c'])\n    ```",
      "properties": {
        "parts": {
          "items": {
            "type": "string"
          },
          "title": "Parts",
          "type": "array"
        }
      },
      "required": [
        "parts"
      ],
      "title": "FeatureKey",
      "type": "object"
    },
    "FieldDep": {
      "properties": {
        "feature": {
          "$ref": "#/$defs/FeatureKey"
        },
        "fields": {
          "anyOf": [
            {
              "items": {
                "$ref": "#/$defs/FieldKey"
              },
              "type": "array"
            },
            {
              "const": "__METAXY_ALL_DEP__",
              "type": "string"
            }
          ],
          "default": "__METAXY_ALL_DEP__",
          "title": "Fields"
        }
      },
      "required": [
        "feature"
      ],
      "title": "FieldDep",
      "type": "object"
    },
    "FieldKey": {
      "description": "Field key as a sequence of string parts.\n\nHashable for use as dict keys in registries.\nParts cannot contain forward slashes (/) or double underscores (__).\n\nExamples:\n    ```py\n    FieldKey(\"a/b/c\")  # String format\n    # FieldKey(parts=['a', 'b', 'c'])\n\n    FieldKey([\"a\", \"b\", \"c\"])  # List format\n    # FieldKey(parts=['a', 'b', 'c'])\n\n    FieldKey(FieldKey([\"a\", \"b\", \"c\"]))  # FieldKey copy\n    # FieldKey(parts=['a', 'b', 'c'])\n\n    FieldKey(\"a\", \"b\", \"c\")  # Variadic format\n    # FieldKey(parts=['a', 'b', 'c'])\n    ```",
      "properties": {
        "parts": {
          "items": {
            "type": "string"
          },
          "title": "Parts",
          "type": "array"
        }
      },
      "required": [
        "parts"
      ],
      "title": "FieldKey",
      "type": "object"
    },
    "SpecialFieldDep": {
      "enum": [
        "__METAXY_ALL_DEP__"
      ],
      "title": "SpecialFieldDep",
      "type": "string"
    }
  },
  "properties": {
    "key": {
      "$ref": "#/$defs/FieldKey"
    },
    "code_version": {
      "default": "__metaxy_initial__",
      "title": "Code Version",
      "type": "string"
    },
    "deps": {
      "anyOf": [
        {
          "$ref": "#/$defs/SpecialFieldDep"
        },
        {
          "items": {
            "$ref": "#/$defs/FieldDep"
          },
          "type": "array"
        }
      ],
      "title": "Deps"
    }
  },
  "title": "FieldSpec",
  "type": "object"
}

Fields:

• key (FieldKey)
• code_version (str)
• deps (SpecialFieldDep | list[FieldDep])

Source code in src/metaxy/models/field.py

def __init__(
    self,
    key: CoercibleToFieldKey,
    code_version: str = DEFAULT_CODE_VERSION,
    deps: SpecialFieldDep | list[FieldDep] | None = None,
    *args,
    **kwargs: Any,
) -> None:
    validated_key = FieldKeyAdapter.validate_python(key)

    # Handle None deps - use empty list as default
    if deps is None:
        deps = []

    super().__init__(
        key=validated_key,
        code_version=code_version,
        deps=deps,
        *args,
        **kwargs,
    )

Functions

__get_pydantic_core_schema__ classmethod

__get_pydantic_core_schema__(source_type, handler)

Add custom validator to coerce strings to FieldSpec.

Source code in src/metaxy/models/field.py

@classmethod
def __get_pydantic_core_schema__(cls, source_type, handler):
    """Add custom validator to coerce strings to FieldSpec."""
    from pydantic_core import core_schema

    # Get the default schema
    python_schema = handler(source_type)

    # Wrap it with a before validator that converts strings
    return core_schema.no_info_before_validator_function(
        _validate_field_spec_from_string,
        python_schema,
    )

FieldDep pydantic-model

FieldDep(feature: CoercibleToFeatureKey | FeatureSpec | type[Feature], fields: list[CoercibleToFieldKey] | Literal[ALL] = ALL, *args, **kwargs)

Bases: BaseModel

Show JSON schema:

{
  "$defs": {
    "FeatureKey": {
      "description": "Feature key as a sequence of string parts.\n\nHashable for use as dict keys in registries.\nParts cannot contain forward slashes (/) or double underscores (__).\n\nExamples:\n    ```py\n    FeatureKey(\"a/b/c\")  # String format\n    # FeatureKey(parts=['a', 'b', 'c'])\n\n    FeatureKey([\"a\", \"b\", \"c\"])  # List format\n    # FeatureKey(parts=['a', 'b', 'c'])\n\n    FeatureKey(FeatureKey([\"a\", \"b\", \"c\"]))  # FeatureKey copy\n    # FeatureKey(parts=['a', 'b', 'c'])\n\n    FeatureKey(\"a\", \"b\", \"c\")  # Variadic format\n    # FeatureKey(parts=['a', 'b', 'c'])\n    ```",
      "properties": {
        "parts": {
          "items": {
            "type": "string"
          },
          "title": "Parts",
          "type": "array"
        }
      },
      "required": [
        "parts"
      ],
      "title": "FeatureKey",
      "type": "object"
    },
    "FieldKey": {
      "description": "Field key as a sequence of string parts.\n\nHashable for use as dict keys in registries.\nParts cannot contain forward slashes (/) or double underscores (__).\n\nExamples:\n    ```py\n    FieldKey(\"a/b/c\")  # String format\n    # FieldKey(parts=['a', 'b', 'c'])\n\n    FieldKey([\"a\", \"b\", \"c\"])  # List format\n    # FieldKey(parts=['a', 'b', 'c'])\n\n    FieldKey(FieldKey([\"a\", \"b\", \"c\"]))  # FieldKey copy\n    # FieldKey(parts=['a', 'b', 'c'])\n\n    FieldKey(\"a\", \"b\", \"c\")  # Variadic format\n    # FieldKey(parts=['a', 'b', 'c'])\n    ```",
      "properties": {
        "parts": {
          "items": {
            "type": "string"
          },
          "title": "Parts",
          "type": "array"
        }
      },
      "required": [
        "parts"
      ],
      "title": "FieldKey",
      "type": "object"
    }
  },
  "properties": {
    "feature": {
      "$ref": "#/$defs/FeatureKey"
    },
    "fields": {
      "anyOf": [
        {
          "items": {
            "$ref": "#/$defs/FieldKey"
          },
          "type": "array"
        },
        {
          "const": "__METAXY_ALL_DEP__",
          "type": "string"
        }
      ],
      "default": "__METAXY_ALL_DEP__",
      "title": "Fields"
    }
  },
  "required": [
    "feature"
  ],
  "title": "FieldDep",
  "type": "object"
}

Fields:

• feature (FeatureKey)
• fields (list[FieldKey] | Literal[ALL])

Source code in src/metaxy/models/field.py

def __init__(
    self,
    feature: "CoercibleToFeatureKey | FeatureSpec | type[Feature]",
    fields: list[CoercibleToFieldKey]
    | Literal[SpecialFieldDep.ALL] = SpecialFieldDep.ALL,
    *args,
    **kwargs,
):
    from metaxy.models.feature import Feature
    from metaxy.models.feature_spec import FeatureSpec

    if isinstance(feature, FeatureSpec):
        feature_key = feature.key
    elif isinstance(feature, type) and issubclass(feature, Feature):
        feature_key = feature.spec().key
    else:
        feature_key = FeatureKeyAdapter.validate_python(feature)

    assert isinstance(feature_key, FeatureKey)

    if isinstance(fields, list):
        validated_fields: Any = TypeAdapter(list[FieldKey]).validate_python(fields)
    else:
        validated_fields = fields  # Keep the enum value as-is

    super().__init__(feature=feature_key, fields=validated_fields, *args, **kwargs)