ethspecify 0.2.9__tar.gz → 0.3.0__tar.gz

{ethspecify-0.2.9 → ethspecify-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ethspecify
-Version: 0.2.9
+Version: 0.3.0
 Summary: A utility for processing Ethereum specification tags.
 Home-page: https://github.com/jtraglia/ethspecify
 Author: Justin Traglia
@@ -38,7 +38,7 @@ When that happens, they can update the implementations appropriately.
 ### Installation
 
 ```
-python3 -mpip install ethspecify
+pipx install ethspecify
 ```
 
 ### Adding Spec Tags

{ethspecify-0.2.9 → ethspecify-0.3.0}/README.md

@@ -12,7 +12,7 @@ When that happens, they can update the implementations appropriately.
 ### Installation
 
 ```
-python3 -mpip install ethspecify
+pipx install ethspecify
 ```
 
 ### Adding Spec Tags
@@ -322,4 +322,4 @@ Or, to display just a single line, only specify a single number. For example:
  * has_execution_withdrawal_credential(validator)  # [Modified in Electra:EIP7251]
  * </spec>
  */
- ```
+ ```

{ethspecify-0.2.9 → ethspecify-0.3.0}/ethspecify/cli.py

@@ -3,11 +3,11 @@ import json
 import os
 import sys
 
-from .core import grep, replace_spec_tags, get_pyspec, get_latest_fork, get_spec_item_history, load_config, run_checks
+from .core import grep, replace_spec_tags, get_pyspec, get_latest_fork, get_spec_item_history, load_config, run_checks, sort_specref_yaml
 
 
 def process(args):
-    """Process all spec tags."""
+    """Process all spec tags and sort specref YAML files."""
     project_dir = os.path.abspath(os.path.expanduser(args.path))
     if not os.path.isdir(project_dir):
         print(f"Error: The directory {repr(project_dir)} does not exist.")
@@ -16,10 +16,26 @@ def process(args):
     # Load config once from the project directory
     config = load_config(project_dir)
 
+    # Process spec tags in files
     for f in grep(project_dir, r"<spec\b.*?>", args.exclude):
         print(f"Processing file: {f}")
         replace_spec_tags(f, config)
 
+    # Sort specref YAML files if they exist in config
+    specrefs_config = config.get('specrefs', {})
+    if isinstance(specrefs_config, dict):
+        specrefs_files = specrefs_config.get('files', [])
+    elif isinstance(specrefs_config, list):
+        specrefs_files = specrefs_config
+    else:
+        specrefs_files = []
+
+    for yaml_file in specrefs_files:
+        yaml_path = os.path.join(project_dir, yaml_file)
+        if os.path.exists(yaml_path):
+            if not sort_specref_yaml(yaml_path):
+                print(f"Error sorting: {yaml_file}")
+
     return 0
 
 

{ethspecify-0.2.9 → ethspecify-0.3.0}/ethspecify/core.py

@@ -11,6 +11,90 @@ import tokenize
 import yaml
 
 
+def validate_exception_items(exceptions, version):
+    """
+    Validate that exception items actually exist in the spec.
+    Raises an exception if any item doesn't exist.
+    """
+    if not exceptions:
+        return
+
+    # Get the pyspec data
+    try:
+        pyspec = get_pyspec(version)
+    except Exception as e:
+        print(f"Warning: Could not validate exceptions - failed to load pyspec: {e}")
+        return
+
+    # Map exception keys to pyspec keys
+    exception_to_pyspec_map = {
+        'functions': 'functions',
+        'fn': 'functions',
+        'constants': 'constant_vars',
+        'constant_variables': 'constant_vars',
+        'constant_var': 'constant_vars',
+        'configs': 'config_vars',
+        'config_variables': 'config_vars',
+        'config_var': 'config_vars',
+        'presets': 'preset_vars',
+        'preset_variables': 'preset_vars',
+        'preset_var': 'preset_vars',
+        'ssz_objects': 'ssz_objects',
+        'containers': 'ssz_objects',
+        'container': 'ssz_objects',
+        'dataclasses': 'dataclasses',
+        'dataclass': 'dataclasses',
+        'custom_types': 'custom_types',
+        'custom_type': 'custom_types'
+    }
+
+    errors = []
+
+    for exception_key, exception_items in exceptions.items():
+        # Get the corresponding pyspec key
+        pyspec_key = exception_to_pyspec_map.get(exception_key)
+        if not pyspec_key:
+            errors.append(f"Unknown exception type: '{exception_key}'")
+            continue
+
+        # Ensure exception_items is a list
+        if not isinstance(exception_items, list):
+            exception_items = [exception_items]
+
+        for item in exception_items:
+            # Parse item#fork format
+            if '#' in item:
+                item_name, fork = item.split('#', 1)
+            else:
+                # If no fork specified, we'll check if it exists in any fork
+                item_name = item
+                fork = None
+
+            # Check if the item exists
+            item_found = False
+            if fork:
+                # Check specific fork
+                if ('mainnet' in pyspec and
+                    fork in pyspec['mainnet'] and
+                    pyspec_key in pyspec['mainnet'][fork] and
+                    item_name in pyspec['mainnet'][fork][pyspec_key]):
+                    item_found = True
+            else:
+                # Check if item exists in any fork
+                if 'mainnet' in pyspec:
+                    for check_fork in pyspec['mainnet']:
+                        if (pyspec_key in pyspec['mainnet'][check_fork] and
+                            item_name in pyspec['mainnet'][check_fork][pyspec_key]):
+                            item_found = True
+                            break
+
+            if not item_found:
+                errors.append(f"invalid key: {exception_key}.{item_name}{"#" + fork if fork else ""}")
+
+    if errors:
+        error_msg = "Invalid exception items in configuration:\n" + "\n".join(f"  - {e}" for e in errors)
+        raise Exception(error_msg)
+
 def load_config(directory=None):
     """
     Load configuration from .ethspecify.yml file in the specified directory.
@@ -25,7 +109,22 @@ def load_config(directory=None):
         try:
             with open(config_path, 'r') as f:
                 config = yaml.safe_load(f)
-                return config if config else {}
+                if not config:
+                    return {}
+
+                # Get version from config, default to 'nightly'
+                version = config.get('version', 'nightly')
+
+                # Validate exceptions in root config
+                if 'exceptions' in config:
+                    validate_exception_items(config['exceptions'], version)
+
+                # Also validate exceptions in specrefs section if present
+                if 'specrefs' in config and isinstance(config['specrefs'], dict):
+                    if 'exceptions' in config['specrefs']:
+                        validate_exception_items(config['specrefs']['exceptions'], version)
+
+                return config
         except (yaml.YAMLError, IOError) as e:
             print(f"Warning: Error reading .ethspecify.yml file: {e}")
             return {}
@@ -477,6 +576,140 @@ def extract_attributes(tag):
     return dict(attr_pattern.findall(tag))
 
 
+def sort_specref_yaml(yaml_file):
+    """
+    Sort specref entries in a YAML file by their name field.
+    Preserves formatting and adds single blank lines between entries.
+    """
+    if not os.path.exists(yaml_file):
+        return False
+
+    try:
+        with open(yaml_file, 'r') as f:
+            content_str = f.read()
+
+        # Try to fix common YAML issues with unquoted search strings containing colons
+        # This is the same fix used in check_source_files
+        content_str = re.sub(r'(\s+search:\s+)([^"\n]+:)(\s*$)', r'\1"\2"\3', content_str, flags=re.MULTILINE)
+
+        try:
+            content = yaml.safe_load(content_str)
+        except yaml.YAMLError:
+            # Fall back to FullLoader if safe_load fails
+            content = yaml.load(content_str, Loader=yaml.FullLoader)
+
+        if not content:
+            return False
+
+        # Handle both array of objects and single object formats
+        if isinstance(content, list):
+            # Sort the list by 'name' field if it exists
+            # Special handling for fork ordering within the same item
+            def sort_key(x):
+                name = x.get('name', '') if isinstance(x, dict) else str(x)
+
+                # Known fork names for ordering
+                forks = ['phase0', 'altair', 'bellatrix', 'capella', 'deneb', 'electra']
+
+                # Check if name contains a # separator (like "slash_validator#phase0")
+                if '#' in name:
+                    base_name, fork = name.rsplit('#', 1)
+                    # Define fork order based on known forks list
+                    fork_lower = fork.lower()
+                    if fork_lower in forks:
+                        fork_order = forks.index(fork_lower)
+                    else:
+                        # Unknown forks go after known ones, sorted alphabetically
+                        fork_order = len(forks)
+                    return (base_name, fork_order, fork)
+                else:
+                    # Check if name ends with a fork name (like "BeaconStatePhase0")
+                    name_lower = name.lower()
+                    for i, fork in enumerate(forks):
+                        if name_lower.endswith(fork):
+                            # Extract base name
+                            base_name = name[:-len(fork)]
+                            return (base_name, i, name)
+
+                    # No fork pattern found, just sort by name
+                    return (name, 0, '')
+
+            sorted_content = sorted(content, key=sort_key)
+
+            # Custom YAML writing to preserve formatting
+            output_lines = []
+            for i, item in enumerate(sorted_content):
+                if i > 0:
+                    # Add a single blank line between entries
+                    output_lines.append("")
+
+                # Start each entry with a dash
+                first_line = True
+                for key, value in item.items():
+                    if first_line:
+                        prefix = "- "
+                        first_line = False
+                    else:
+                        prefix = "  "
+
+                    if key == 'spec':
+                        # Preserve spec content as-is, using literal style
+                        output_lines.append(f"{prefix}{key}: |")
+                        # Indent the spec content - preserve it exactly as-is
+                        spec_lines = value.rstrip().split('\n') if isinstance(value, str) else str(value).rstrip().split('\n')
+                        for spec_line in spec_lines:
+                            output_lines.append(f"    {spec_line}")
+                    elif key == 'sources':
+                        if isinstance(value, list) and len(value) == 0:
+                            # Keep empty lists on the same line for clarity
+                            output_lines.append(f"{prefix}{key}: []")
+                        else:
+                            output_lines.append(f"{prefix}{key}:")
+                            if isinstance(value, list):
+                                for source in value:
+                                    if isinstance(source, dict):
+                                        output_lines.append(f"    - file: {source.get('file', '')}")
+                                        if 'search' in source:
+                                            search_val = source['search']
+                                            # Only quote if:
+                                            # 1. Contains a colon followed by space or end of string (YAML mapping issue)
+                                            # 2. Not already quoted
+                                            # 3. Doesn't contain internal quotes (like regex patterns)
+                                            if ((':' in search_val or search_val.endswith(':')) and
+                                                not (search_val.startswith('"') and search_val.endswith('"')) and
+                                                '"' not in search_val):
+                                                # Only quote simple strings with colons, not complex patterns
+                                                if not any(char in search_val for char in ['\\', '*', '|', '[', ']', '(', ')']):
+                                                    search_val = f'"{search_val}"'
+                                            output_lines.append(f"      search: {search_val}")
+                                        if 'regex' in source:
+                                            # Keep boolean values lowercase for consistency
+                                            regex_val = str(source['regex']).lower()
+                                            output_lines.append(f"      regex: {regex_val}")
+                                    else:
+                                        output_lines.append(f"    - {source}")
+                    else:
+                        # Handle other fields - don't escape or modify the value
+                        output_lines.append(f"{prefix}{key}: {value}")
+
+            # Strip trailing whitespace from all lines
+            output_lines = [line.rstrip() for line in output_lines]
+
+            # Write back the sorted content
+            with open(yaml_file, 'w') as f:
+                f.write('\n'.join(output_lines))
+                f.write('\n')  # End file with newline
+
+            return True
+        elif isinstance(content, dict):
+            # If it's a single dict, we can't sort it
+            return False
+    except (yaml.YAMLError, IOError) as e:
+        print(f"Error sorting {yaml_file}: {e}")
+        return False
+
+    return False
+
 def replace_spec_tags(file_path, config=None):
     with open(file_path, 'r') as file:
         content = file.read()
@@ -632,19 +865,23 @@ def check_source_files(yaml_file, project_root, exceptions=None):
         if not spec_ref and 'name' in item:
             spec_ref = item['name']
 
+        # Extract item name and fork for exception checking
+        item_name_for_exception = None
+        fork_for_exception = None
+        if spec_ref and '#' in spec_ref and '.' in spec_ref:
+            # Format: "functions.item_name#fork"
+            _, item_with_fork = spec_ref.split('.', 1)
+            if '#' in item_with_fork:
+                item_name_for_exception, fork_for_exception = item_with_fork.split('#', 1)
+
         # Check if sources list is empty
         if not item['sources']:
             if spec_ref:
-                # Extract item name and fork from spec_ref for exception checking
-                if '#' in spec_ref and '.' in spec_ref:
-                    # Format: "functions.item_name#fork"
-                    _, item_with_fork = spec_ref.split('.', 1)
-                    if '#' in item_with_fork:
-                        item_name, fork = item_with_fork.split('#', 1)
-                        # Check if this item is in exceptions
-                        if is_excepted(item_name, fork, exceptions):
-                            total_count += 1
-                            continue
+                # Check if this item is in exceptions
+                if item_name_for_exception and fork_for_exception:
+                    if is_excepted(item_name_for_exception, fork_for_exception, exceptions):
+                        total_count += 1
+                        continue
 
                 errors.append(f"EMPTY SOURCES: {spec_ref}")
             else:
@@ -654,6 +891,13 @@ def check_source_files(yaml_file, project_root, exceptions=None):
             total_count += 1
             continue
 
+        # Check if item has non-empty sources but is in exceptions
+        if item_name_for_exception and fork_for_exception:
+            if is_excepted(item_name_for_exception, fork_for_exception, exceptions):
+                errors.append(f"EXCEPTION CONFLICT: {spec_ref} has a specref")
+                total_count += 1
+                continue
+
         for source in item['sources']:
             # All sources now use the standardized dict format with file and optional search
             if not isinstance(source, dict) or 'file' not in source:
@@ -964,7 +1208,7 @@ def process_generated_specrefs(specrefs, exceptions, version):
         # Check if singular form exists when we have plural
         elif exception_key.endswith('s') and exception_key[:-1] in exceptions:
             type_exceptions = exceptions[exception_key[:-1]]
-        
+
         # Special handling for ssz_objects/containers
         if spec_type in ['ssz_object', 'container'] and not type_exceptions:
             # Check for 'containers' as an alternative key

{ethspecify-0.2.9 → ethspecify-0.3.0}/ethspecify.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ethspecify
-Version: 0.2.9
+Version: 0.3.0
 Summary: A utility for processing Ethereum specification tags.
 Home-page: https://github.com/jtraglia/ethspecify
 Author: Justin Traglia
@@ -38,7 +38,7 @@ When that happens, they can update the implementations appropriately.
 ### Installation
 
 ```
-python3 -mpip install ethspecify
+pipx install ethspecify
 ```
 
 ### Adding Spec Tags

{ethspecify-0.2.9 → ethspecify-0.3.0}/setup.py

@@ -8,7 +8,7 @@ long_description = (this_directory / "README.md").read_text(encoding="utf-8")
 
 setup(
     name="ethspecify",
-    version="0.2.9",
+    version="0.3.0",
     description="A utility for processing Ethereum specification tags.",
     long_description=long_description,
     long_description_content_type="text/markdown",