Refactor `MetadataField` parameters: fix semantic overloading and ambiguity

[GeigerJ2]

There are a few potential issues with the current fields and their usage throughout the code:

1. exclude_from_cli overload
-> this parameter serves THREE distinct purposes:

• CLI option construction (cmdline/groups/dynamic.py:174):

  aiida-core/src/aiida/cmdline/groups/dynamic.py

  Lines 173 to 175 in 49af7f0

  	for key, field_info in cls.Model.model_fields.items():
  	if get_metadata(field_info, 'exclude_from_cli'):
  	continue

• CLI display output (cmdline/commands/cmd_code.py:242):

  aiida-core/src/aiida/cmdline/commands/cmd_code.py

  Lines 238 to 245 in 49af7f0

  	for field_name, field_info in code.Model.model_fields.items():
  	# Skip fields excluded from CLI
  	if get_metadata(
  	field_info,
  	key='exclude_from_cli',
  	default=False,
  	):
  	continue

• YAML export (orm/nodes/data/code/abstract.py:376):

  aiida-core/src/aiida/orm/nodes/data/code/abstract.py

  Lines 375 to 377 in 49af7f0

  	for key, field in self.Model.model_fields.items():
  	if get_metadata(field, 'exclude_from_cli'):
  	continue

2. is_attribute semantic confusion
-> this parameter has four conflicting interpretations across the codebase:

• orm/nodes/node.py: is_attribute=False = "stored in DB columns (not attributes column)"
  • Used for: uuid, node_type, ctime, mtime, label, description, etc.
    

    aiida-core/src/aiida/orm/nodes/node.py

    Lines 198 to 201 in 49af7f0

    	class Model(Entity.Model):
    	uuid: Optional[str] = MetadataField(
    	None, description='The UUID of the node', is_attribute=False, exclude_to_orm=True, exclude_from_cli=True
    	)

• orm/nodes/data/code/portable.py: is_attribute=False = "not stored at all, only for construction"
  • filepath_files - used to populate repository, then discarded
    

    aiida-core/src/aiida/orm/nodes/data/code/portable.py

    Lines 68 to 76 in 49af7f0

    	filepath_files: str = MetadataField(
    	...,
    	title='Code directory',
    	description='Filepath to directory containing code files.',
    	short_name='-F',
    	is_attribute=False,
    	priority=2,
    	orm_to_model=_export_filpath_files_from_repo, # type: ignore[arg-type]
    	)

• orm/nodes/data/dict.py: is_attribute=False = INCORRECT - content IS stored as attributes
  • The value field contradicts its own metadata
  • Implementation uses self.base.attributes.get/set()
    

    aiida-core/src/aiida/orm/nodes/data/dict.py

    Lines 53 to 58 in 49af7f0

    	class Model(Data.Model):
    	value: t.Dict[str, t.Any] = MetadataField(
    	description='Dictionary content.',
    	is_attribute=False,
    	is_subscriptable=True,
    	)

• .orm/nodes/data/code/installed.py: defaults to is_attribute=True = INCORRECT
  • computer field stored via self.backend_entity.computer, not attributes
    

    aiida-core/src/aiida/orm/nodes/data/code/installed.py

    Lines 44 to 54 in 49af7f0

    	class Model(AbstractCode.Model):
    	"""Model describing required information to create an instance."""
    	computer: str = MetadataField( # type: ignore[assignment]
    	...,
    	title='Computer',
    	description='The remote computer on which the executable resides.',
    	orm_to_model=lambda node, _: cast('InstalledCode', node).computer.label,
    	short_name='-Y',
    	priority=2,
    	)

3. Additional Issues Found

• No way to mark fields as "computed/read-only" (like repository_metadata)
• No distinction between internal implementation details vs user-facing fields
• The TODO comment at cmd_code.py:248-251 explicitly calls out these issues with Dict and InstalledCode
  

  aiida-core/src/aiida/cmdline/commands/cmd_code.py

  Lines 247 to 257 in 49af7f0

  	# Skip fields that are not stored in the attributes column
  	# NOTE: this also catches e.g., filepath_files for PortableCode, which is actually a "misuse"
  	# of the is_attribute metadata flag, as there it is flagging that the field is not stored at all!
  	# TODO (edan-bainglass) consider improving this by introducing a new metadata flag or reworking PortableCode
  	# TODO see also Dict and InstalledCode for other potential misuses of is_attribute
  	if not get_metadata(
  	field_info,
  	key='is_attribute',
  	default=True,
  	):
  	continue

Impact

The current design makes it impossible to correctly:

• Show only attribute-stored fields in CLI output (cmd_code.py logic is broken)
• Distinguish between construction-time vs display-time behavior
• Accurately represent where/how data is persisted

Ping @edan-bainglass

[edan-bainglass]

Thanks @GeigerJ2. A few things:

1. exclude_from_cli - I've dropped this parameter. exclude_to_orm can be used in instances mentioned above. Note that exclude_to_orm is to be understood as "read-only" when it comes to ORM entity creation.
2. is_attribute - it is used correctly in Node, and now also in InstalledCode.Model.computer. It is actually correct in Dict.Model.value, as that is just an alias for attributes (historical decision I guess). Now, in PortableCode.Model.filepath_files, that is indeed still incorrect. Not sure how to handle this yet.
3. repository_metadata is excluded_to_orm, i.e., read-only

As for your impact section, I'm not sure I fully understand. Perhaps first you have a quick look at the current state of #6990. Happy to continue the discussion.