ethspecify 0.2.0__py3-none-any.whl → 0.2.2__py3-none-any.whl

ethspecify/cli.py

@@ -3,7 +3,7 @@ import json
 import os
 import sys
 
-from .core import grep, replace_spec_tags, get_pyspec, get_latest_fork
+from .core import grep, replace_spec_tags, get_pyspec, get_latest_fork, get_spec_item_history
 
 
 def process(args):
@@ -21,78 +21,53 @@ def process(args):
 
 
 def list_tags(args):
-    """List all available tags for a specific fork and preset."""
-    # Get the specification data
-    pyspec = get_pyspec()
-    fork = args.fork
-    preset = args.preset
+    """List all available tags with their fork history."""
+    preset = getattr(args, 'preset', 'mainnet')
+    return _list_tags_with_history(args, preset)
 
-    # Validate that the fork exists
-    if fork not in pyspec[preset]:
-        print(f"Error: Fork '{fork}' not found in {preset} preset")
-        available_forks = list(pyspec[preset].keys())
-        print(f"Available forks: {', '.join(available_forks)}")
+
+def _list_tags_with_history(args, preset):
+    """List all tags with their fork history."""
+    try:
+        history = get_spec_item_history(preset)
+    except ValueError as e:
+        print(f"Error: {e}")
         return 1
 
-    # Format output based on requested format
     if args.format == "json":
         result = {
-            "fork": fork,
             "preset": preset,
-            "tags": {
-                "functions": list(pyspec[preset][fork]['functions'].keys()),
-                "constant_vars": list(pyspec[preset][fork]['constant_vars'].keys()),
-                "custom_types": list(pyspec[preset][fork]['custom_types'].keys()),
-                "ssz_objects": list(pyspec[preset][fork]['ssz_objects'].keys()),
-                "dataclasses": list(pyspec[preset][fork]['dataclasses'].keys()),
-                "preset_vars": list(pyspec[preset][fork]['preset_vars'].keys()),
-                "config_vars": list(pyspec[preset][fork]['config_vars'].keys()),
-            }
+            "mode": "history",
+            "history": history
         }
         print(json.dumps(result, indent=2))
     else:
-        # Plain text output
-        print(f"Available tags for {fork} fork ({preset} preset):")
-        maybe_fork = f' fork="{fork}"' if fork != get_latest_fork() else ""
-
-        print("\nFunctions:")
-        for fn_name in sorted(pyspec[preset][fork]['functions'].keys()):
-            if args.search is None or args.search.lower() in fn_name.lower():
-                print(f"  <spec fn=\"{fn_name}\"{maybe_fork} />")
-
-        print("\nConstants:")
-        for const_name in sorted(pyspec[preset][fork]['constant_vars'].keys()):
-            if args.search is None or args.search.lower() in const_name.lower():
-                print(f"  <spec constant_var=\"{const_name}\"{maybe_fork} />")
-
-        print("\nCustom Types:")
-        for type_name in sorted(pyspec[preset][fork]['custom_types'].keys()):
-            if args.search is None or args.search.lower() in type_name.lower():
-                print(f"  <spec custom_type=\"{type_name}\"{maybe_fork} />")
-
-        print("\nSSZ Objects:")
-        for obj_name in sorted(pyspec[preset][fork]['ssz_objects'].keys()):
-            if args.search is None or args.search.lower() in obj_name.lower():
-                print(f"  <spec ssz_object=\"{obj_name}\"{maybe_fork} />")
-
-        print("\nDataclasses:")
-        for class_name in sorted(pyspec[preset][fork]['dataclasses'].keys()):
-            if args.search is None or args.search.lower() in class_name.lower():
-                print(f"  <spec dataclass=\"{class_name}\"{maybe_fork} />")
-
-        print("\nPreset Variables:")
-        for var_name in sorted(pyspec[preset][fork]['preset_vars'].keys()):
-            if args.search is None or args.search.lower() in var_name.lower():
-                print(f"  <spec preset_var=\"{var_name}\"{maybe_fork} />")
-
-        print("\nConfig Variables:")
-        for var_name in sorted(pyspec[preset][fork]['config_vars'].keys()):
-            if args.search is None or args.search.lower() in var_name.lower():
-                print(f"  <spec config_var=\"{var_name}\"{maybe_fork} />")
+        print(f"Available tags across all forks ({preset} preset):")
+
+        def _print_items_with_history(category_name, items_dict, spec_attr):
+            """Helper to print items with their fork history."""
+            if not items_dict:
+                return
+            print(f"\n{category_name}:")
+            for item_name in sorted(items_dict.keys()):
+                if args.search is None or args.search.lower() in item_name.lower():
+                    forks = items_dict[item_name]
+                    fork_list = ", ".join(forks)
+                    print(f"  <spec {spec_attr}=\"{item_name}\" /> ({fork_list})")
+
+        _print_items_with_history("Functions", history['functions'], "fn")
+        _print_items_with_history("Constants", history['constant_vars'], "constant_var")
+        _print_items_with_history("Custom Types", history['custom_types'], "custom_type")
+        _print_items_with_history("SSZ Objects", history['ssz_objects'], "ssz_object")
+        _print_items_with_history("Dataclasses", history['dataclasses'], "dataclass")
+        _print_items_with_history("Preset Variables", history['preset_vars'], "preset_var")
+        _print_items_with_history("Config Variables", history['config_vars'], "config_var")
 
     return 0
 
 
+
+
 def list_forks(args):
     """List all available forks."""
     pyspec = get_pyspec()
@@ -103,10 +78,10 @@ def list_forks(args):
         print(f"Available presets: {', '.join(pyspec.keys())}")
         return 1
 
+    # Filter out EIP forks
     forks = sorted(
-        pyspec[preset].keys(),
-        # Put phase0 at the top & EIP feature forks at the bottom
-        key=lambda x: (x != "phase0", x.startswith("eip"), x)
+        [fork for fork in pyspec[preset].keys() if not fork.startswith("eip")],
+        key=lambda x: (x != "phase0", x)
     )
 
     if args.format == "json":
@@ -148,20 +123,8 @@ def main():
     )
 
     # Parser for 'list-tags' command
-    list_tags_parser = subparsers.add_parser("list-tags", help="List available specification tags")
+    list_tags_parser = subparsers.add_parser("list-tags", help="List available specification tags with fork history")
     list_tags_parser.set_defaults(func=list_tags)
-    list_tags_parser.add_argument(
-        "--fork",
-        type=str,
-        help="Fork to list tags for",
-        default=get_latest_fork(),
-    )
-    list_tags_parser.add_argument(
-        "--preset",
-        type=str,
-        help="Preset to use (mainnet or minimal)",
-        default="mainnet",
-    )
     list_tags_parser.add_argument(
         "--format",
         type=str,

ethspecify/core.py

@@ -83,23 +83,23 @@ def diff(a_name, a_content, b_name, b_content):
 
 
 @functools.lru_cache()
-def get_links():
-    url = f"https://raw.githubusercontent.com/jtraglia/ethspecify/main/links.json"
+def get_links(version="nightly"):
+    url = f"https://raw.githubusercontent.com/jtraglia/ethspecify/main/pyspec/{version}/links.json"
     response = requests.get(url)
     response.raise_for_status()
     return response.json()
 
 
 @functools.lru_cache()
-def get_pyspec():
-    url = f"https://raw.githubusercontent.com/jtraglia/ethspecify/main/pyspec.json"
+def get_pyspec(version="nightly"):
+    url = f"https://raw.githubusercontent.com/jtraglia/ethspecify/main/pyspec/{version}/pyspec.json"
     response = requests.get(url)
     response.raise_for_status()
     return response.json()
 
 
-def get_previous_forks(fork):
-    pyspec = get_pyspec()
+def get_previous_forks(fork, version="nightly"):
+    pyspec = get_pyspec(version)
     config_vars = pyspec["mainnet"][fork]["config_vars"]
     previous_forks = ["phase0"]
     for key in config_vars.keys():
@@ -107,12 +107,14 @@ def get_previous_forks(fork):
             if key != f"{fork.upper()}_FORK_VERSION":
                 if key != "GENESIS_FORK_VERSION":
                     f = key.split("_")[0].lower()
-                    previous_forks.append(f)
+                    # Skip EIP forks
+                    if not f.startswith("eip"):
+                        previous_forks.append(f)
     return list(reversed(previous_forks))
 
 
-def get_spec(attributes, preset, fork):
-    pyspec = get_pyspec()
+def get_spec(attributes, preset, fork, version="nightly"):
+    pyspec = get_pyspec(version)
     spec = None
     if "function" in attributes or "fn" in attributes:
         if "function" in attributes and "fn" in attributes:
@@ -197,16 +199,154 @@ def get_spec(attributes, preset, fork):
         raise Exception("invalid spec tag")
     return spec
 
-def get_latest_fork():
+def get_latest_fork(version="nightly"):
     """A helper function to get the latest non-eip fork."""
-    pyspec = get_pyspec()
+    pyspec = get_pyspec(version)
     forks = sorted(
-        pyspec["mainnet"].keys(),
-        key=lambda x: (x != "phase0", x.startswith("eip"), x)
+        [fork for fork in pyspec["mainnet"].keys() if not fork.startswith("eip")],
+        key=lambda x: (x != "phase0", x)
+    )
+    return forks[-1] if forks else "phase0"
+
+
+def get_spec_item_changes(fork, preset="mainnet", version="nightly"):
+    """
+    Compare spec items in the given fork with previous forks to detect changes.
+    Returns dict with categories containing items marked as (new) or (modified).
+    """
+    pyspec = get_pyspec(version)
+    if fork not in pyspec[preset]:
+        raise ValueError(f"Fork '{fork}' not found in {preset} preset")
+
+    current_fork_data = pyspec[preset][fork]
+    previous_forks = get_previous_forks(fork, version)
+
+    changes = {
+        'functions': {},
+        'constant_vars': {},
+        'custom_types': {},
+        'ssz_objects': {},
+        'dataclasses': {},
+        'preset_vars': {},
+        'config_vars': {},
+    }
+
+    # Check each category of spec items
+    for category in changes.keys():
+        if category not in current_fork_data:
+            continue
+
+        for item_name, item_content in current_fork_data[category].items():
+            status = _get_item_status(item_name, item_content, category, previous_forks, pyspec, preset)
+            if status:
+                changes[category][item_name] = status
+
+    return changes
+
+
+def _get_item_status(item_name, current_content, category, previous_forks, pyspec, preset):
+    """
+    Determine if an item is new or modified compared to previous forks.
+    Returns 'new', 'modified', or None if unchanged.
+    """
+    # Check if item exists in any previous fork
+    found_in_previous = False
+    previous_content = None
+
+    for prev_fork in previous_forks:
+        if (prev_fork in pyspec[preset] and
+            category in pyspec[preset][prev_fork] and
+            item_name in pyspec[preset][prev_fork][category]):
+
+            found_in_previous = True
+            prev_content = pyspec[preset][prev_fork][category][item_name]
+
+            # Compare content with immediate previous version
+            if prev_content != current_content:
+                return "modified"
+            else:
+                # Found unchanged version, so this is not new or modified
+                return None
+
+    # If not found in any previous fork, it's new
+    if not found_in_previous:
+        return "new"
+
+    return None
+
+
+def get_spec_item_history(preset="mainnet", version="nightly"):
+    """
+    Get the complete history of all spec items across all forks.
+    Returns dict with categories containing items and their fork history.
+    """
+    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)
     )
-    for fork in reversed(forks):
-        if not fork.startswith("eip"):
-            return fork
+
+    # Track all unique items across all forks
+    all_items = {
+        'functions': set(),
+        'constant_vars': set(),
+        'custom_types': set(),
+        'ssz_objects': set(),
+        'dataclasses': set(),
+        'preset_vars': set(),
+        'config_vars': set(),
+    }
+
+    # Collect all item names
+    for fork in all_forks:
+        if fork not in pyspec[preset]:
+            continue
+        fork_data = pyspec[preset][fork]
+        for category in all_items.keys():
+            if category in fork_data:
+                all_items[category].update(fork_data[category].keys())
+
+    # Build history for each item
+    history = {}
+    for category in all_items.keys():
+        history[category] = {}
+        for item_name in all_items[category]:
+            item_history = _trace_item_history(item_name, category, all_forks, pyspec, preset)
+            if item_history:
+                history[category][item_name] = item_history
+
+    return history
+
+
+def _trace_item_history(item_name, category, all_forks, pyspec, preset):
+    """
+    Trace the history of a specific item across all forks.
+    Returns a list of forks where the item was introduced or modified.
+    """
+    history_forks = []
+    previous_content = None
+
+    for fork in all_forks:
+        if (fork in pyspec[preset] and
+            category in pyspec[preset][fork] and
+            item_name in pyspec[preset][fork][category]):
+
+            current_content = pyspec[preset][fork][category][item_name]
+
+            if previous_content is None:
+                # First appearance
+                history_forks.append(fork)
+            elif current_content != previous_content:
+                # Content changed
+                history_forks.append(fork)
+
+            previous_content = current_content
+
+    return history_forks
 
 def parse_common_attributes(attributes):
     try:
@@ -214,36 +354,41 @@ def parse_common_attributes(attributes):
     except KeyError:
         preset = "mainnet"
 
+    try:
+        version = attributes["version"]
+    except KeyError:
+        version = "nightly"
+
     try:
         fork = attributes["fork"]
     except KeyError:
-        fork = get_latest_fork()
+        fork = get_latest_fork(version)
 
     try:
         style = attributes["style"]
     except KeyError:
         style = "hash"
 
-    return preset, fork, style
+    return preset, fork, style, version
 
 def get_spec_item(attributes):
-    preset, fork, style = parse_common_attributes(attributes)
-    spec = get_spec(attributes, preset, fork)
+    preset, fork, style, version = parse_common_attributes(attributes)
+    spec = get_spec(attributes, preset, fork, version)
 
     if style == "full" or style == "hash":
         return spec
     elif style == "diff":
-        previous_forks = get_previous_forks(fork)
+        previous_forks = get_previous_forks(fork, version)
 
         previous_fork = None
         previous_spec = None
         for i, _ in enumerate(previous_forks):
             previous_fork = previous_forks[i]
-            previous_spec = get_spec(attributes, preset, previous_fork)
+            previous_spec = get_spec(attributes, preset, previous_fork, version)
             if previous_spec != "phase0":
                 try:
                     previous_previous_fork = previous_forks[i+1]
-                    previous_previous_spec = get_spec(attributes, preset, previous_previous_fork)
+                    previous_previous_spec = get_spec(attributes, preset, previous_previous_fork, version)
                     if previous_previous_spec == previous_spec:
                         continue
                 except KeyError:
@@ -263,7 +408,7 @@ def get_spec_item(attributes):
                 function_name = attributes["function"]
             else:
                 function_name = attributes["fn"]
-            for key, value in get_links().items():
+            for key, value in get_links(version).items():
                 if fork in key and key.endswith(function_name):
                     return value
             return "Could not find link"
@@ -322,8 +467,8 @@ def replace_spec_tags(file_path):
 
         attributes = extract_attributes(original_tag_text)
         print(f"spec tag: {attributes}")
-        preset, fork, style = parse_common_attributes(attributes)
-        spec = get_spec(attributes, preset, fork)
+        preset, fork, style, version = parse_common_attributes(attributes)
+        spec = get_spec(attributes, preset, fork, version)
         hash_value = hashlib.sha256(spec.encode('utf-8')).hexdigest()[:8]
 
         if style == "hash":

{ethspecify-0.2.0.dist-info → ethspecify-0.2.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ethspecify
-Version: 0.2.0
+Version: 0.2.2
 Summary: A utility for processing Ethereum specification tags.
 Home-page: https://github.com/jtraglia/ethspecify
 Author: Justin Traglia
@@ -66,6 +66,20 @@ 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

ethspecify-0.2.2.dist-info/RECORD

@@ -0,0 +1,9 @@
+ethspecify/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ethspecify/cli.py,sha256=wkJyDd55peeJjNe1vF8suje3Mc6ggEa3O6hvfGUZSD4,5162
+ethspecify/core.py,sha256=7H1mwkQ2YBxJbO-RCc-7RCy6cJoxFnWwfe-H9McUwaU,17881
+ethspecify-0.2.2.dist-info/licenses/LICENSE,sha256=Awxsr73mm9YMBVhBYnzeI7bNdRd-bH6RDtO5ItG0DaM,1071
+ethspecify-0.2.2.dist-info/METADATA,sha256=NT3bYROThPVfEI6LNWMOCjh12b-6GNrgY5s6uhjm1io,9185
+ethspecify-0.2.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+ethspecify-0.2.2.dist-info/entry_points.txt,sha256=09viGkCg9J3h0c9BFRN-BKaJUEaIc4JyULNgBP5EL_g,51
+ethspecify-0.2.2.dist-info/top_level.txt,sha256=0klaMvlVyOkXW09fwZTijJpdybITEp2c9zQKV5v30VM,11
+ethspecify-0.2.2.dist-info/RECORD,,

ethspecify-0.2.0.dist-info/RECORD

@@ -1,9 +0,0 @@
-ethspecify/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-ethspecify/cli.py,sha256=73NnY6-xvFcxMnpeZ1LqvU02EiNiPx5jOor1KPERenk,6903
-ethspecify/core.py,sha256=tkkuBXXJtjWZOSvrpohaFa89VsiocgdAm9QrB55dtGE,12963
-ethspecify-0.2.0.dist-info/licenses/LICENSE,sha256=Awxsr73mm9YMBVhBYnzeI7bNdRd-bH6RDtO5ItG0DaM,1071
-ethspecify-0.2.0.dist-info/METADATA,sha256=wE94OOQKuoZL8hGliq93NX7LQRLsU5eGbtD380J1kzc,8812
-ethspecify-0.2.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-ethspecify-0.2.0.dist-info/entry_points.txt,sha256=09viGkCg9J3h0c9BFRN-BKaJUEaIc4JyULNgBP5EL_g,51
-ethspecify-0.2.0.dist-info/top_level.txt,sha256=0klaMvlVyOkXW09fwZTijJpdybITEp2c9zQKV5v30VM,11
-ethspecify-0.2.0.dist-info/RECORD,,