ethspecify 0.2.9__py3-none-any.whl → 0.3.1__py3-none-any.whl

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, generate_specref_files
 
 
 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
 
 
@@ -166,6 +182,28 @@ def list_forks(args):
     return 0
 
 
+def init(args):
+    """Initialize a specrefs directory with basic configuration and empty source mappings."""
+    output_dir = args.path or "specrefs"
+    version = args.version
+
+    # Check if output directory already exists
+    if os.path.exists(output_dir):
+        print(f"Error: directory {repr(output_dir)} already exists.")
+        print("Please specify a different directory or remove the existing one.")
+        return 1
+
+    try:
+        # Generate the specref files
+        print(f"Initializing specrefs directory: {version}")
+        generate_specref_files(output_dir, version, "mainnet")
+        print(f"Successfully created specrefs directory at: {output_dir}")
+        return 0
+    except Exception as e:
+        print(f"Error: {e}")
+        return 1
+
+
 def main():
     parser = argparse.ArgumentParser(
         description="Process files containing <spec> tags."
@@ -240,6 +278,21 @@ def main():
         help="Output format (text or json)",
     )
 
+    # Parser for 'init' command
+    init_parser = subparsers.add_parser("init", help="Initialize a specrefs directory")
+    init_parser.set_defaults(func=init)
+    init_parser.add_argument(
+        "version",
+        type=str,
+        help="Specification version (e.g., 'nightly' or 'v1.6.0-alpha.5')",
+    )
+    init_parser.add_argument(
+        "--path",
+        type=str,
+        help="Output directory for specrefs (default: specrefs)",
+        default="specrefs",
+    )
+
     # Default to 'process' if no args are provided
     if len(sys.argv) == 1:
         sys.argv.insert(1, "process")

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()
@@ -540,7 +773,7 @@ def replace_spec_tags(file_path, config=None):
             prefix = content[:match.start()].splitlines()[-1]
             prefixed_spec = "\n".join(
                 f"{prefix}{line}" if line.rstrip() else prefix.rstrip()
-                for line in spec_content.rstrip().split("\n")
+                for line in spec_content.split("\n")
             )
             updated_tag = f"{new_opening}\n{prefixed_spec}\n{prefix}</spec>"
             return updated_tag
@@ -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
@@ -1274,3 +1518,172 @@ def run_checks(project_dir, config):
                 overall_success = False
 
     return overall_success, results
+
+
+def generate_specref_files(output_dir, version="nightly", preset="mainnet"):
+    """
+    Generate specref YAML files without sources for manual mapping.
+    Creates a basic directory structure with empty sources.
+    """
+    # Create output directory if it doesn't exist
+    os.makedirs(output_dir, exist_ok=True)
+
+    # Get all spec items
+    pyspec = get_pyspec(version)
+    if preset not in pyspec:
+        raise ValueError(f"Preset '{preset}' not found")
+
+    # Get all forks in chronological order, excluding EIP forks
+    all_forks = sorted(
+        [fork for fork in pyspec[preset].keys() if not fork.startswith("eip")],
+        key=lambda x: (x != "phase0", x)
+    )
+
+    # Map history keys to file names and spec attribute names
+    category_map = {
+        'constant_vars': ('constants.yml', 'constant_var'),
+        'config_vars': ('configs.yml', 'config_var'),
+        'preset_vars': ('presets.yml', 'preset_var'),
+        'functions': ('functions.yml', 'fn'),
+        'ssz_objects': ('containers.yml', 'container'),
+        'dataclasses': ('dataclasses.yml', 'dataclass'),
+        'custom_types': ('types.yml', 'custom_type'),
+    }
+
+    # Collect all items organized by category
+    items_by_category = {cat: {} for cat in category_map.keys()}
+
+    for fork in all_forks:
+        if fork not in pyspec[preset]:
+            continue
+        fork_data = pyspec[preset][fork]
+
+        for category in items_by_category.keys():
+            if category not in fork_data:
+                continue
+
+            for item_name, item_data in fork_data[category].items():
+                # Track which forks have this item
+                if item_name not in items_by_category[category]:
+                    items_by_category[category][item_name] = []
+                items_by_category[category][item_name].append((fork, item_data))
+
+    # Generate YAML files for each category
+    for category, (filename, spec_attr) in category_map.items():
+        if not items_by_category[category]:
+            continue
+
+        output_path = os.path.join(output_dir, filename)
+        entries = []
+
+        # Sort items alphabetically
+        for item_name in sorted(items_by_category[category].keys()):
+            forks_data = items_by_category[category][item_name]
+
+            # Find all unique versions of this item (where content differs)
+            versions = []  # List of (fork, item_data, spec_content)
+            prev_content = None
+
+            for fork, item_data in forks_data:
+                # Build the spec content based on category
+                if category == 'functions':
+                    spec_content = item_data
+                elif category in ['constant_vars', 'config_vars', 'preset_vars']:
+                    # item_data is a list: [type, value, ...]
+                    if isinstance(item_data, (list, tuple)) and len(item_data) >= 2:
+                        type_info = item_data[0]
+                        value = item_data[1]
+                        if type_info:
+                            spec_content = f"{item_name}: {type_info} = {value}"
+                        else:
+                            spec_content = f"{item_name} = {value}"
+                    else:
+                        spec_content = str(item_data)
+                elif category == 'ssz_objects':
+                    spec_content = item_data
+                elif category == 'dataclasses':
+                    spec_content = item_data.replace("@dataclass\n", "")
+                elif category == 'custom_types':
+                    # custom_types are simple type aliases: TypeName = SomeType
+                    spec_content = f"{item_name} = {item_data}"
+                else:
+                    spec_content = str(item_data)
+
+                # Only add this version if it's different from the previous one
+                if prev_content is None or spec_content != prev_content:
+                    versions.append((fork, item_data, spec_content))
+                    prev_content = spec_content
+
+            # Create entries based on number of unique versions
+            use_fork_suffix = len(versions) > 1
+
+            for idx, (fork, item_data, spec_content) in enumerate(versions):
+                # Calculate hash of current version
+                hash_value = hashlib.sha256(spec_content.encode('utf-8')).hexdigest()[:8]
+
+                # For multiple versions after the first, use diff style
+                if use_fork_suffix and idx > 0:
+                    # Get previous version for diff
+                    prev_fork, _, prev_spec_content = versions[idx - 1]
+
+                    # Generate diff
+                    diff_content = diff(prev_fork, strip_comments(prev_spec_content), fork, strip_comments(spec_content))
+
+                    # Build spec tag with style="diff"
+                    spec_tag = f'<spec {spec_attr}="{item_name}" fork="{fork}" style="diff" hash="{hash_value}">'
+                    content = diff_content
+                else:
+                    # Build spec tag without style="diff"
+                    spec_tag = f'<spec {spec_attr}="{item_name}" fork="{fork}" hash="{hash_value}">'
+                    content = spec_content
+
+                # Create entry
+                entry_name = f'{item_name}#{fork}' if use_fork_suffix else item_name
+                entry = {
+                    'name': entry_name,
+                    'sources': [],
+                    'spec': f'{spec_tag}\n{content}\n</spec>'
+                }
+                entries.append(entry)
+
+        # Write YAML file
+        if entries:
+            with open(output_path, 'w') as f:
+                for i, entry in enumerate(entries):
+                    if i > 0:
+                        f.write('\n')
+                    f.write(f'- name: {entry["name"]}\n')
+                    f.write('  sources: []\n')
+                    f.write('  spec: |\n')
+                    for line in entry['spec'].split('\n'):
+                        f.write(f'    {line}\n')
+
+    # Create .ethspecify.yml config file
+    config_path = os.path.join(output_dir, '.ethspecify.yml')
+    with open(config_path, 'w') as f:
+        f.write(f'version: {version}\n')
+        f.write('style: full\n')
+        f.write('\n')
+        f.write('specrefs:\n')
+        f.write('  files:\n')
+        for category, (filename, _) in category_map.items():
+            if items_by_category[category]:
+                f.write(f'    - {filename}\n')
+        f.write('\n')
+        f.write('  exceptions:\n')
+        f.write('    # Add any exceptions here\n')
+
+    # Strip trailing whitespace from all generated files
+    all_files = [config_path]
+    for category, (filename, _) in category_map.items():
+        if items_by_category[category]:
+            all_files.append(os.path.join(output_dir, filename))
+
+    for file_path in all_files:
+        with open(file_path, 'r') as f:
+            lines = f.readlines()
+        with open(file_path, 'w') as f:
+            for line in lines:
+                f.write(line.rstrip() + '\n')
+
+    return list(category_map.values())

ethspecify-0.3.1.dist-info/METADATA

@@ -0,0 +1,237 @@
+Metadata-Version: 2.4
+Name: ethspecify
+Version: 0.3.1
+Summary: A utility for processing Ethereum specification tags.
+Home-page: https://github.com/jtraglia/ethspecify
+Author: Justin Traglia
+Author-email: jtraglia@pm.me
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.6
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests==2.32.3
+Requires-Dist: PyYAML>=6.0
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# ethspecify
+
+A tool for referencing the Ethereum specifications in clients.
+
+The idea is that ethspecify will help developers keep track of when the specification changes. It
+will also help auditors verify that the client implementations match the specifications. Ideally,
+this is configured as a CI check which notifies client developers when the specification changes.
+When that happens, they can update the implementations appropriately.
+
+## Getting started
+
+### Installation
+
+```
+pipx install ethspecify
+```
+
+### Initialize specrefs
+
+From the root of the client source directory, initialize a directory for specrefs:
+
+```
+$ ethspecify init v1.6.0-beta.0
+Initializing specrefs directory: v1.6.0-beta.0
+Successfully created specrefs directory at: specrefs
+```
+
+This creates a `specrefs` directory with `.ethspecify.yml` and YAML files for each spec category
+(constants, configs, presets, functions, containers, dataclasses, types).
+
+### Map sources
+
+Edit the YAML files to add sources for where each spec item is implemented.
+
+If it's the entire file:
+
+```yaml
+- name: BlobParameters
+  sources:
+    - file: ethereum/spec/src/main/java/tech/pegasys/teku/spec/logic/versions/fulu/helpers/BlobParameters.java
+  spec: |
+    <spec dataclass="BlobParameters" fork="fulu" hash="a4575aa8">
+    class BlobParameters:
+        epoch: Epoch
+        max_blobs_per_block: uint64
+    </spec>
+```
+
+If it's multiple entire files:
+
+```yaml
+- name: BlobsBundleDeneb
+  sources:
+    - file: ethereum/spec/src/main/java/tech/pegasys/teku/spec/datastructures/execution/BlobsBundle.java
+    - file: ethereum/spec/src/main/java/tech/pegasys/teku/spec/datastructures/builder/BlobsBundleSchema.java
+    - file: ethereum/spec/src/main/java/tech/pegasys/teku/spec/datastructures/builder/versions/deneb/BlobsBundleDeneb.java
+    - file: ethereum/spec/src/main/java/tech/pegasys/teku/spec/datastructures/builder/versions/deneb/BlobsBundleSchemaDeneb.java
+  spec: |
+    <spec dataclass="BlobsBundle" fork="deneb" hash="8d6e7be6">
+    class BlobsBundle(object):
+        commitments: List[KZGCommitment, MAX_BLOB_COMMITMENTS_PER_BLOCK]
+        proofs: List[KZGProof, MAX_BLOB_COMMITMENTS_PER_BLOCK]
+        blobs: List[Blob, MAX_BLOB_COMMITMENTS_PER_BLOCK]
+    </spec>
+```
+
+If it's a specific part of a file:
+
+```yaml
+- name: EFFECTIVE_BALANCE_INCREMENT
+  sources:
+    - file: ethereum/spec/src/main/resources/tech/pegasys/teku/spec/config/presets/mainnet/phase0.yaml
+      search: "EFFECTIVE_BALANCE_INCREMENT:"
+  spec: |
+    <spec preset_var="EFFECTIVE_BALANCE_INCREMENT" fork="phase0" hash="23dfe52c">
+    EFFECTIVE_BALANCE_INCREMENT: Gwei = 1000000000
+    </spec>
+```
+
+You can also use regex in the searches if that is necessary:
+
+```yaml
+- name: ATTESTATION_DUE_BPS
+  sources:
+    - file: ethereum/spec/src/main/resources/tech/pegasys/teku/spec/config/configs/mainnet.yaml
+      search: "^ATTESTATION_DUE_BPS:"
+      regex: true
+  spec: |
+    <spec config_var="ATTESTATION_DUE_BPS" fork="phase0" hash="929dd1c9">
+    ATTESTATION_DUE_BPS: uint64 = 3333
+    </spec>
+```
+
+### Check specrefs
+
+Run the check command in CI to verify all spec items are properly mapped:
+
+```
+$ ethspecify check --path=specrefs
+MISSING: constants.BLS_MODULUS#deneb
+```
+
+### Add exceptions
+
+Some spec items may not be implemented in your client. Add them to the exceptions list in
+`specrefs/.ethspecify.yml`:
+
+```yaml
+specrefs:
+  files:
+    - containers.yml
+    - functions.yml
+    # ...
+
+exceptions:
+  containers:
+    # Not defined, unnecessary
+    - Eth1Block
+
+  functions:
+    # No light client support
+    - is_valid_light_client_header
+    - process_light_client_update
+```
+
+## Style Options
+
+This attribute can be used to change how the specification content is shown.
+
+### `hash` (default)
+
+This style adds a hash of the specification content to the spec tag, without showing the content.
+
+```
+<spec fn="apply_deposit" fork="electra" hash="c723ce7b" />
+```
+
+> [!NOTE]
+> The hash is the first 8 characters of the specification content's SHA256 digest.
+
+### `full`
+
+This style displays the whole content of this specification item, including comments.
+
+```
+<spec fn="is_fully_withdrawable_validator" fork="deneb" style="full">
+def is_fully_withdrawable_validator(validator: Validator, balance: Gwei, epoch: Epoch) -> bool:
+    """
+    Check if ``validator`` is fully withdrawable.
+    """
+    return (
+        has_eth1_withdrawal_credential(validator)
+        and validator.withdrawable_epoch <= epoch
+        and balance > 0
+    )
+</spec>
+```
+
+### `link`
+
+This style displays a GitHub link to the specification item.
+
+```
+<spec fn="apply_pending_deposit" fork="electra" style="link" hash="83ee9126">
+https://github.com/ethereum/consensus-specs/blob/dev/specs/electra/beacon-chain.md#new-apply_pending_deposit
+</spec>
+```
+
+### `diff`
+
+This style displays a diff with the previous fork's version of the specification.
+
+```
+<spec ssz_object="BeaconState" fork="electra" style="diff">
+--- deneb
++++ electra
+@@ -27,3 +27,12 @@
+     next_withdrawal_index: WithdrawalIndex
+     next_withdrawal_validator_index: ValidatorIndex
+     historical_summaries: List[HistoricalSummary, HISTORICAL_ROOTS_LIMIT]
++    deposit_requests_start_index: uint64
++    deposit_balance_to_consume: Gwei
++    exit_balance_to_consume: Gwei
++    earliest_exit_epoch: Epoch
++    consolidation_balance_to_consume: Gwei
++    earliest_consolidation_epoch: Epoch
++    pending_deposits: List[PendingDeposit, PENDING_DEPOSITS_LIMIT]
++    pending_partial_withdrawals: List[PendingPartialWithdrawal, PENDING_PARTIAL_WITHDRAWALS_LIMIT]
++    pending_consolidations: List[PendingConsolidation, PENDING_CONSOLIDATIONS_LIMIT]
+</spec>
+```
+
+> [!NOTE]
+> Comments are stripped from the specifications when the `diff` style is used. We do this because
+> these complicate the diff; the "[Modified in Fork]" comments aren't valuable here.
+
+This can be used with any specification item, like functions too:
+
+```
+<spec fn="is_eligible_for_activation_queue" fork="electra" style="diff">
+--- phase0
++++ electra
+@@ -4,5 +4,5 @@
+     """
+     return (
+         validator.activation_eligibility_epoch == FAR_FUTURE_EPOCH
+-        and validator.effective_balance == MAX_EFFECTIVE_BALANCE
++        and validator.effective_balance >= MIN_ACTIVATION_BALANCE
+     )
+</spec>
+```

ethspecify-0.3.1.dist-info/RECORD

@@ -0,0 +1,9 @@
+ethspecify/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ethspecify/cli.py,sha256=fbHtny1-VS6IZZlDzPSvkyLr4NDYDYcBXzOiGUGOlyU,10093
+ethspecify/core.py,sha256=gfDBeYzrhNM6wHGtoyy_7SnKUQF_w5iFGljQcdUmaJQ,66694
+ethspecify-0.3.1.dist-info/licenses/LICENSE,sha256=Awxsr73mm9YMBVhBYnzeI7bNdRd-bH6RDtO5ItG0DaM,1071
+ethspecify-0.3.1.dist-info/METADATA,sha256=mI1j8bbLAKBH_dvLHKuP1kgNsdjXnUMcGnS2l2SPh_s,6996
+ethspecify-0.3.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+ethspecify-0.3.1.dist-info/entry_points.txt,sha256=09viGkCg9J3h0c9BFRN-BKaJUEaIc4JyULNgBP5EL_g,51
+ethspecify-0.3.1.dist-info/top_level.txt,sha256=0klaMvlVyOkXW09fwZTijJpdybITEp2c9zQKV5v30VM,11
+ethspecify-0.3.1.dist-info/RECORD,,

ethspecify-0.2.9.dist-info/METADATA

@@ -1,351 +0,0 @@
-Metadata-Version: 2.4
-Name: ethspecify
-Version: 0.2.9
-Summary: A utility for processing Ethereum specification tags.
-Home-page: https://github.com/jtraglia/ethspecify
-Author: Justin Traglia
-Author-email: jtraglia@pm.me
-Classifier: Programming Language :: Python :: 3
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Operating System :: OS Independent
-Requires-Python: >=3.6
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: requests==2.32.3
-Requires-Dist: PyYAML>=6.0
-Dynamic: author
-Dynamic: author-email
-Dynamic: classifier
-Dynamic: description
-Dynamic: description-content-type
-Dynamic: home-page
-Dynamic: license-file
-Dynamic: requires-dist
-Dynamic: requires-python
-Dynamic: summary
-
-# ethspecify
-
-A tool for referencing the Ethereum specifications in clients.
-
-The idea is that ethspecify will help developers keep track of when the specification changes. It
-will also help auditors verify that the client implementations match the specifications. Ideally,
-this is configured as a CI check which notifies client developers when the specification changes.
-When that happens, they can update the implementations appropriately.
-
-## Getting Started
-
-### Installation
-
-```
-python3 -mpip install ethspecify
-```
-
-### Adding Spec Tags
-
-In your client, add HTML tags like this:
-
-```
-/*
- * <spec fn="is_fully_withdrawable_validator" fork="deneb" />
- */
-```
-
-```
-/*
- * <spec ssz_object="BeaconState" fork="electra" style="diff" />
- */
-```
-
-### Populating Spec Tags
-
-Then, navigate to your codebase and run `ethspecify`:
-
-```
-ethspecify
-```
-
-## Specification Options
-
-### Version
-
-This attribute specifies which version of the consensus specifications to use. Default is `nightly`.
-
-- `nightly` (default) - Uses the latest nightly build from the master branch
-- `v1.6.0-alpha.2`, `v1.6.0-alpha.3`, etc. - Uses a specific tagged release version
-
-Example:
-```
-/*
- * <spec fn="apply_deposit" fork="electra" version="v1.6.0-alpha.3" />
- */
-```
-
-### Fork
-
-This attribute can be any of the [executable
-specifications](https://github.com/ethereum/consensus-specs/blob/e6bddd966214a19d2b97199bbe3c02577a22a8b4/Makefile#L3-L15)
-in the consensus-specs. At the time of writing, these are: phase0, altair, bellatrix, capella,
-deneb, electra, fulu, whisk, eip6800, and eip7732.
-
-### Style
-
-This attribute can be used to change how the specification content is shown.
-
-#### `hash` (default)
-
-This style adds a hash of the specification content to the spec tag, without showing the content.
-
-```
-/*
- * <spec fn="apply_deposit" fork="electra" hash="c723ce7b" />
- */
-```
-
-> [!NOTE]
-> The hash is the first 8 characters of the specification content's SHA256 digest.
-
-#### `full`
-
-This style displays the whole content of this specification item, including comments.
-
-```
-/*
- * <spec fn="is_fully_withdrawable_validator" fork="deneb" style="full">
- * def is_fully_withdrawable_validator(validator: Validator, balance: Gwei, epoch: Epoch) -> bool:
- *     """
- *     Check if ``validator`` is fully withdrawable.
- *     """
- *     return (
- *         has_eth1_withdrawal_credential(validator)
- *         and validator.withdrawable_epoch <= epoch
- *         and balance > 0
- *     )
- * </spec>
- */
-```
-
-#### `link`
-
-This style displays a GitHub link to the specification item.
-
-```
-/*
- * <spec fn="apply_pending_deposit" fork="electra" style="link" hash="83ee9126">
- * https://github.com/ethereum/consensus-specs/blob/dev/specs/electra/beacon-chain.md#new-apply_pending_deposit
- * </spec>
- */
-```
-
-#### `diff`
-
-This style displays a diff with the previous fork's version of the specification.
-
-```
-/*
- * <spec ssz_object="BeaconState" fork="electra" style="diff">
- * --- deneb
- * +++ electra
- * @@ -27,3 +27,12 @@
- *      next_withdrawal_index: WithdrawalIndex
- *      next_withdrawal_validator_index: ValidatorIndex
- *      historical_summaries: List[HistoricalSummary, HISTORICAL_ROOTS_LIMIT]
- * +    deposit_requests_start_index: uint64
- * +    deposit_balance_to_consume: Gwei
- * +    exit_balance_to_consume: Gwei
- * +    earliest_exit_epoch: Epoch
- * +    consolidation_balance_to_consume: Gwei
- * +    earliest_consolidation_epoch: Epoch
- * +    pending_deposits: List[PendingDeposit, PENDING_DEPOSITS_LIMIT]
- * +    pending_partial_withdrawals: List[PendingPartialWithdrawal, PENDING_PARTIAL_WITHDRAWALS_LIMIT]
- * +    pending_consolidations: List[PendingConsolidation, PENDING_CONSOLIDATIONS_LIMIT]
- * </spec>
- */
-```
-
-> [!NOTE]
-> Comments are stripped from the specifications when the `diff` style is used. We do this because
-> these complicate the diff; the "[Modified in Fork]" comments aren't valuable here.
-
-This can be used with any specification item, like functions too:
-
-```
-/*
- * <spec fn="is_eligible_for_activation_queue" fork="electra" style="diff">
- * --- phase0
- * +++ electra
- * @@ -4,5 +4,5 @@
- *      """
- *      return (
- *          validator.activation_eligibility_epoch == FAR_FUTURE_EPOCH
- * -        and validator.effective_balance == MAX_EFFECTIVE_BALANCE
- * +        and validator.effective_balance >= MIN_ACTIVATION_BALANCE
- *      )
- * </spec>
- */
-```
-
-## Supported Specification Items
-
-### Constants
-
-These are items found in the `Constants` section of the specifications.
-
-```
-/*
- * <spec constant_var="COMPOUNDING_WITHDRAWAL_PREFIX" fork="electra" style="full">
- * COMPOUNDING_WITHDRAWAL_PREFIX: Bytes1 = '0x02'
- * </spec>
- */
-```
-
-### Custom Types
-
-These are items found in the `Custom types` section of the specifications.
-
-```
-/*
- * <spec custom_type="Blob" fork="electra" style="full">
- * Blob = ByteVector[BYTES_PER_FIELD_ELEMENT * FIELD_ELEMENTS_PER_BLOB]
- * </spec>
- */
-```
-
-### Preset Variables
-
-These are items found in the
-[`presets`](https://github.com/ethereum/consensus-specs/tree/dev/presets) directory.
-
-For preset variables, in addition to the `preset_var` attribute, you can specify a `preset`
-attribute: minimal or mainnet.
-
-```
-/*
- * <spec preset="minimal" preset_var="PENDING_CONSOLIDATIONS_LIMIT" fork="electra" style="full">
- * PENDING_CONSOLIDATIONS_LIMIT: uint64 = 64
- * </spec>
- *
- * <spec preset="mainnet" preset_var="PENDING_CONSOLIDATIONS_LIMIT" fork="electra" style="full">
- * PENDING_CONSOLIDATIONS_LIMIT: uint64 = 262144
- * </spec>
- */
-```
-
-It's not strictly necessary to specify the preset attribute. The default preset is mainnet.
-
-```
-/*
- * <spec preset_var="FIELD_ELEMENTS_PER_BLOB" fork="electra" style="full">
- * FIELD_ELEMENTS_PER_BLOB: uint64 = 4096
- * </spec>
- */
-```
-
-### Config Variables
-
-These are items found in the
-[`configs`](https://github.com/ethereum/consensus-specs/tree/dev/presets) directory.
-
-```
-/*
- * <spec config_var="MAX_REQUEST_BLOB_SIDECARS" fork="electra" style="full">
- * MAX_REQUEST_BLOB_SIDECARS = 768
- * </spec>
- */
-```
-
-### SSZ Objects
-
-These are items found in the `Containers` section of the specifications.
-
-```
-/*
- * <spec ssz_object="ConsolidationRequest" fork="electra" style="full">
- * class ConsolidationRequest(Container):
- *     source_address: ExecutionAddress
- *     source_pubkey: BLSPubkey
- *     target_pubkey: BLSPubkey
- * </spec>
- */
-```
-
-### Dataclasses
-
-These are classes with the `@dataclass` decorator.
-
-```
-/*
- * <spec dataclass="PayloadAttributes" fork="electra" style="full">
- * class PayloadAttributes(object):
- *     timestamp: uint64
- *     prev_randao: Bytes32
- *     suggested_fee_recipient: ExecutionAddress
- *     withdrawals: Sequence[Withdrawal]
- *     parent_beacon_block_root: Root  # [New in Deneb:EIP4788]
- * </spec>
- */
-```
-
-### Functions
-
-These are all the functions found in the specifications.
-
-For example, two versions of the same function:
-
-```
-/*
- * <spec fn="is_fully_withdrawable_validator" fork="deneb" style="full">
- * def is_fully_withdrawable_validator(validator: Validator, balance: Gwei, epoch: Epoch) -> bool:
- *     """
- *     Check if ``validator`` is fully withdrawable.
- *     """
- *     return (
- *         has_eth1_withdrawal_credential(validator)
- *         and validator.withdrawable_epoch <= epoch
- *         and balance > 0
- *     )
- * </spec>
- */
-```
-
-```
-/*
- * <spec fn="is_fully_withdrawable_validator" fork="electra" style="full">
- * def is_fully_withdrawable_validator(validator: Validator, balance: Gwei, epoch: Epoch) -> bool:
- *     """
- *     Check if ``validator`` is fully withdrawable.
- *     """
- *     return (
- *         has_execution_withdrawal_credential(validator)  # [Modified in Electra:EIP7251]
- *         and validator.withdrawable_epoch <= epoch
- *         and balance > 0
- *     )
- * </spec>
- */
-```
-
-With functions, it's possible to specify which line/lines should be displayed. For example:
-
-```
-/*
- * <spec fn="is_fully_withdrawable_validator" fork="electra" style="full" lines="5-9">
- * return (
- *     has_execution_withdrawal_credential(validator)  # [Modified in Electra:EIP7251]
- *     and validator.withdrawable_epoch <= epoch
- *     and balance > 0
- * )
- * </spec>
- */
-```
-
-Note that the content is automatically dedented.
-
-Or, to display just a single line, only specify a single number. For example:
-
-```
-/*
- * <spec fn="is_fully_withdrawable_validator" fork="electra" style="full" lines="6">
- * has_execution_withdrawal_credential(validator)  # [Modified in Electra:EIP7251]
- * </spec>
- */
- ```

ethspecify-0.2.9.dist-info/RECORD

@@ -1,9 +0,0 @@
-ethspecify/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-ethspecify/cli.py,sha256=Ida4n7BSjZrkvwINyzh3M61JzFqdLPc93i62JIQ_64g,8183
-ethspecify/core.py,sha256=GwXLoCWKJ-BTyjkVP58eR1Gay2bGegdH6RvAaqLUwas,48832
-ethspecify-0.2.9.dist-info/licenses/LICENSE,sha256=Awxsr73mm9YMBVhBYnzeI7bNdRd-bH6RDtO5ItG0DaM,1071
-ethspecify-0.2.9.dist-info/METADATA,sha256=AhTvvhzxBaGj3gjs1dvsubn0YFTIznMIUWP5cF9-anA,9212
-ethspecify-0.2.9.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-ethspecify-0.2.9.dist-info/entry_points.txt,sha256=09viGkCg9J3h0c9BFRN-BKaJUEaIc4JyULNgBP5EL_g,51
-ethspecify-0.2.9.dist-info/top_level.txt,sha256=0klaMvlVyOkXW09fwZTijJpdybITEp2c9zQKV5v30VM,11
-ethspecify-0.2.9.dist-info/RECORD,,