PyPI - ethspecify - Versions diffs - 0.3.7__tar.gz → 0.3.9__tar.gz - Mend

ethspecify 0.3.7tar.gz → 0.3.9tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (15) hide show

{ethspecify-0.3.7 → ethspecify-0.3.9}/PKG-INFO RENAMED Viewed

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ethspecify
-Version: 0.3.7
+Version: 0.3.9
 Summary: A utility for processing Ethereum specification tags.
 Home-page: https://github.com/jtraglia/ethspecify
 Author: Justin Traglia
@@ -26,39 +26,132 @@ Dynamic: summary
 # ethspecify
-A tool for referencing the Ethereum specifications in clients.
+A tool for referencing the Ethereum specifications in clients. This will:
-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.
+- Help developers keep track of specification changes.
+- Help auditors find important functions in client implementations.
-## Getting started
+## Table of contents
-### Installation
+- [Getting Started](#getting-started)
+  - [Install](#install)
+  - [Initialize](#initialize)
+- [Inline References](#inline-references)
+- [Centralized References](#centralized-references)
+  - [Configure](#configure)
+  - [Update](#update)
+  - [Map](#map)
+  - [Check](#check)
+  - [Exceptions](#exceptions)
+- [Style Options](#style-options)
+  - [`hash`](#hash)
+  - [`full`](#full)
+  - [`link`](#link)
+  - [`diff`](#diff)
+## Getting Started
+### Install
 ```
 pipx install ethspecify
 ```
-### Initialize specrefs
+### Initialize
-From the root of the client source directory, initialize a directory for specrefs:
+Create a `.ethspecify.yml` config file:
 ```
 $ ethspecify init v1.6.0-beta.0
+Successfully created .ethspecify.yml
+```
+To also generate a `specrefs/` directory with a YAML file for each
+specification category, use the `--specrefs` flag:
+```
+$ ethspecify init v1.6.0-beta.0 --specrefs
 Initializing specrefs directory: v1.6.0-beta.0
-Successfully created specrefs directory at: specrefs
+Successfully created .ethspecify.yml and specrefs/ directory
+```
+> [!TIP]
+> `nightly` is also a valid version, which tracks the latest
+> development specifications.
+## Inline References
+Add `<spec>` tags anywhere in the codebase to reference specification
+items. For example:
+```
+<spec fn="is_active_validator" fork="phase0" />
+```
+Then run `ethspecify` to populate the tag body with the corresponding
+specification content:
+```
+<spec fn="is_active_validator" fork="phase0" hash="5765e850">
+def is_active_validator(validator: Validator, epoch: Epoch) -> bool:
+    """
+    Check if ``validator`` is active.
+    """
+    return validator.activation_epoch <= epoch < validator.exit_epoch
+</spec>
 ```
-This creates a `specrefs` directory with `.ethspecify.yml` and YAML files for each spec category
-(constants, configs, presets, functions, containers, dataclasses, types).
+> [!NOTE]
+> The indentation of the `<spec>` tag is preserved when populating
+> the body. This means spec tags inside comments will have their
+> content indented to match:
+>
+> ```java
+> // <spec fn="is_active_validator" fork="phase0" hash="5765e850">
+> // def is_active_validator(validator: Validator, epoch: Epoch) -> bool:
+> //     """
+> //     Check if ``validator`` is active.
+> //     """
+> //     return validator.activation_epoch <= epoch < validator.exit_epoch
+> // </spec>
+> ```
+## Centralized References
+Specification references (specrefs) are YAML files that map
+specification items (constants, functions, containers, etc.) to
+their corresponding source file locations.
+### Configure
+The following options can be set in the `specrefs` section of
+`.ethspecify.yml`:
+| Option | Default | Description |
+|--------|---------|-------------|
+| `search_root` | `.` | Root directory for resolving source file paths |
+| `auto_standardize_names` | `false` | Rename entries to `item#fork` format |
+| `auto_add_missing_entries` | `false` | Add missing specification items with empty sources |
+| `require_exceptions_have_fork` | `false` | Require exceptions to use `item#fork` format |
+### Update
+To update to a newer specification version, change the `version`
+field in `.ethspecify.yml` and run:
-### Map sources
+```
+$ ethspecify
+```
+This updates the specification content in the YAML files to match
+the new version.
-Edit the YAML files to add sources for where each spec item is implemented.
+### Map
-If it's the entire file:
+Edit the YAML files to add sources for where each specification
+item is implemented.
+If it is the entire file:
 ```yaml
 - name: BlobParameters
@@ -72,7 +165,7 @@ If it's the entire file:
     </spec>
 ```
-If it's multiple entire files:
+If it is multiple entire files:
 ```yaml
 - name: BlobsBundleDeneb
@@ -90,7 +183,7 @@ If it's multiple entire files:
     </spec>
 ```
-If it's a specific part of a file:
+If it is a specific part of a file:
 ```yaml
 - name: EFFECTIVE_BALANCE_INCREMENT
@@ -103,7 +196,7 @@ If it's a specific part of a file:
     </spec>
 ```
-You can also use regex in the searches if that is necessary:
+Regex is also supported in searches:
 ```yaml
 - name: ATTESTATION_DUE_BPS
@@ -117,56 +210,57 @@ You can also use regex in the searches if that is necessary:
     </spec>
 ```
-### Check specrefs
+### Check
-Run the check command in CI to verify all spec items are properly mapped:
+Run the check command in CI to verify all specification items are
+properly mapped:
 ```
-$ ethspecify check --path=specrefs
+$ ethspecify check
 MISSING: constants.BLS_MODULUS#deneb
 ```
-### Add exceptions
+### Exceptions
-Some spec items may not be implemented in your client. Add them to the exceptions list in
-`specrefs/.ethspecify.yml`:
+Some specification items may not have a corresponding
+implementation. Add them to the exceptions list in
+`.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
+  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.
+This attribute can be used to change how the specification content
+is shown.
-### `hash` (default)
+### `hash`
-This style adds a hash of the specification content to the spec tag, without showing the content.
+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.
+> 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.
+This style displays the whole content of this specification item,
+including comments.
 ```
 <spec fn="is_fully_withdrawable_validator" fork="deneb" style="full">
@@ -184,7 +278,8 @@ def is_fully_withdrawable_validator(validator: Validator, balance: Gwei, epoch:
 ### `link`
-This style displays an ethspec.tools link to the specification item.
+This style displays an ethspec.tools link to the specification
+item.
 ```
 <spec fn="apply_pending_deposit" fork="electra" style="link" hash="83ee9126">
@@ -194,7 +289,8 @@ https://ethspec.tools/#specs/v1.7.0-alpha.1/functions-apply_pending_deposit-elec
 ### `diff`
-This style displays a diff with the previous fork's version of the specification.
+This style displays a diff with the previous fork's version of the
+specification.
 ```
 <spec ssz_object="BeaconState" fork="electra" style="diff">
@@ -217,10 +313,12 @@ This style displays a diff with the previous fork's version of the specification
 ```
 > [!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.
+> Comments are stripped from the specifications when the `diff`
+> style is used. This is because they complicate the diff; the
+> "[Modified in Fork]" comments are not valuable here.
-This can be used with any specification item, like functions too:
+This can be used with any specification item, like functions
+too:
 ```
 <spec fn="is_eligible_for_activation_queue" fork="electra" style="diff">

ethspecify-0.3.9/README.md ADDED Viewed

@@ -0,0 +1,309 @@
+# ethspecify
+A tool for referencing the Ethereum specifications in clients. This will:
+- Help developers keep track of specification changes.
+- Help auditors find important functions in client implementations.
+## Table of contents
+- [Getting Started](#getting-started)
+  - [Install](#install)
+  - [Initialize](#initialize)
+- [Inline References](#inline-references)
+- [Centralized References](#centralized-references)
+  - [Configure](#configure)
+  - [Update](#update)
+  - [Map](#map)
+  - [Check](#check)
+  - [Exceptions](#exceptions)
+- [Style Options](#style-options)
+  - [`hash`](#hash)
+  - [`full`](#full)
+  - [`link`](#link)
+  - [`diff`](#diff)
+## Getting Started
+### Install
+```
+pipx install ethspecify
+```
+### Initialize
+Create a `.ethspecify.yml` config file:
+```
+$ ethspecify init v1.6.0-beta.0
+Successfully created .ethspecify.yml
+```
+To also generate a `specrefs/` directory with a YAML file for each
+specification category, use the `--specrefs` flag:
+```
+$ ethspecify init v1.6.0-beta.0 --specrefs
+Initializing specrefs directory: v1.6.0-beta.0
+Successfully created .ethspecify.yml and specrefs/ directory
+```
+> [!TIP]
+> `nightly` is also a valid version, which tracks the latest
+> development specifications.
+## Inline References
+Add `<spec>` tags anywhere in the codebase to reference specification
+items. For example:
+```
+<spec fn="is_active_validator" fork="phase0" />
+```
+Then run `ethspecify` to populate the tag body with the corresponding
+specification content:
+```
+<spec fn="is_active_validator" fork="phase0" hash="5765e850">
+def is_active_validator(validator: Validator, epoch: Epoch) -> bool:
+    """
+    Check if ``validator`` is active.
+    """
+    return validator.activation_epoch <= epoch < validator.exit_epoch
+</spec>
+```
+> [!NOTE]
+> The indentation of the `<spec>` tag is preserved when populating
+> the body. This means spec tags inside comments will have their
+> content indented to match:
+>
+> ```java
+> // <spec fn="is_active_validator" fork="phase0" hash="5765e850">
+> // def is_active_validator(validator: Validator, epoch: Epoch) -> bool:
+> //     """
+> //     Check if ``validator`` is active.
+> //     """
+> //     return validator.activation_epoch <= epoch < validator.exit_epoch
+> // </spec>
+> ```
+## Centralized References
+Specification references (specrefs) are YAML files that map
+specification items (constants, functions, containers, etc.) to
+their corresponding source file locations.
+### Configure
+The following options can be set in the `specrefs` section of
+`.ethspecify.yml`:
+| Option | Default | Description |
+|--------|---------|-------------|
+| `search_root` | `.` | Root directory for resolving source file paths |
+| `auto_standardize_names` | `false` | Rename entries to `item#fork` format |
+| `auto_add_missing_entries` | `false` | Add missing specification items with empty sources |
+| `require_exceptions_have_fork` | `false` | Require exceptions to use `item#fork` format |
+### Update
+To update to a newer specification version, change the `version`
+field in `.ethspecify.yml` and run:
+```
+$ ethspecify
+```
+This updates the specification content in the YAML files to match
+the new version.
+### Map
+Edit the YAML files to add sources for where each specification
+item is implemented.
+If it is 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 is 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 is 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>
+```
+Regex is also supported in searches:
+```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
+Run the check command in CI to verify all specification items are
+properly mapped:
+```
+$ ethspecify check
+MISSING: constants.BLS_MODULUS#deneb
+```
+### Exceptions
+Some specification items may not have a corresponding
+implementation. Add them to the exceptions list in
+`.ethspecify.yml`:
+```yaml
+specrefs:
+  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`
+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 an ethspec.tools link to the specification
+item.
+```
+<spec fn="apply_pending_deposit" fork="electra" style="link" hash="83ee9126">
+https://ethspec.tools/#specs/v1.7.0-alpha.1/functions-apply_pending_deposit-electra
+</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. This is because they complicate the diff; the
+> "[Modified in Fork]" comments are not 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.7 → ethspecify-0.3.9}/ethspecify/cli.py RENAMED Viewed

@@ -3,7 +3,7 @@ import json
 import os
 import sys
-from .core import grep, replace_spec_tags, get_pyspec, get_spec_item_history, load_config, run_checks, sort_specref_yaml, generate_specref_files
+from .core import grep, replace_spec_tags, get_pyspec, get_spec_item_history, load_config, run_checks, sort_specref_yaml, generate_specref_files, generate_config_file
 def process(args):
@@ -200,25 +200,40 @@ def list_forks(args):
 def init(args):
-    """Initialize a specrefs directory with basic configuration and empty source mappings."""
-    output_dir = args.path or "specrefs"
+    """Initialize .ethspecify.yml and optionally a specrefs directory."""
     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.")
+    # Check if .ethspecify.yml already exists
+    if os.path.exists('.ethspecify.yml'):
+        print("Error: '.ethspecify.yml' already exists.")
+        print("Please remove the existing config file first.")
         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
+    if args.specrefs:
+        output_dir = args.path or "specrefs"
+        # 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:
+            print(f"Initializing specrefs directory: {version}")
+            generate_specref_files(output_dir, version, "mainnet")
+            print(f"Successfully created .ethspecify.yml and {output_dir}/ directory")
+            return 0
+        except Exception as e:
+            print(f"Error: {e}")
+            return 1
+    else:
+        try:
+            generate_config_file(version)
+            print(f"Successfully created .ethspecify.yml")
+            return 0
+        except Exception as e:
+            print(f"Error: {e}")
+            return 1
 def main():
@@ -296,13 +311,18 @@ def main():
     )
     # Parser for 'init' command
-    init_parser = subparsers.add_parser("init", help="Initialize a specrefs directory")
+    init_parser = subparsers.add_parser("init", help="Initialize .ethspecify.yml")
     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(
+        "--specrefs",
+        action="store_true",
+        help="Also create a specrefs directory with YAML files for each spec category",
+    )
     init_parser.add_argument(
         "--path",
         type=str,

{ethspecify-0.3.7 → ethspecify-0.3.9}/ethspecify/core.py RENAMED Viewed

@@ -1656,8 +1656,8 @@ def run_checks(project_dir, config):
                 source_root = os.path.join(project_dir, search_root_rel) if not os.path.isabs(search_root_rel) else search_root_rel
                 source_root = os.path.abspath(source_root)
             else:
-                # Default behavior: parent directory
-                source_root = os.path.dirname(project_dir)
+                # Default behavior: if we're in a specrefs directory, search in the parent directory
+                source_root = os.path.dirname(project_dir) if os.path.basename(project_dir) == 'specrefs' else project_dir
             valid_count, total_count, source_errors = check_source_files(yaml_path, source_root, [])
@@ -1717,8 +1717,8 @@ def run_checks(project_dir, config):
                 source_root = os.path.join(project_dir, search_root_rel) if not os.path.isabs(search_root_rel) else search_root_rel
                 source_root = os.path.abspath(source_root)
             else:
-                # Default behavior: parent directory
-                source_root = os.path.dirname(project_dir)
+                # Default behavior: if we're in a specrefs directory, search in the parent directory
+                source_root = os.path.dirname(project_dir) if os.path.basename(project_dir) == 'specrefs' else project_dir
             valid_count, total_count, source_errors = check_source_files(yaml_path, source_root, all_exceptions)
@@ -2022,6 +2022,30 @@ def add_missing_spec_items_to_yaml_files(project_dir, config, specrefs_files):
             add_missing_entries_to_yaml(yaml_path, new_entries)
+def generate_config_file(version="nightly"):
+    """Generate a .ethspecify.yml config file in the current directory."""
+    config_path = '.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('  search_root: .\n')
+        f.write('  auto_standardize_names: true\n')
+        f.write('  auto_add_missing_entries: true\n')
+        f.write('  require_exceptions_have_fork: true\n')
+        f.write('\n')
+        f.write('  exceptions:\n')
+        f.write('    # Add any exceptions here\n')
+    # Strip trailing whitespace
+    with open(config_path, 'r') as f:
+        lines = f.readlines()
+    with open(config_path, 'w') as f:
+        for line in lines:
+            f.write(line.rstrip() + '\n')
 def generate_specref_files(output_dir, version="nightly", preset="mainnet"):
     """
     Generate specref YAML files without sources for manual mapping.
@@ -2147,17 +2171,21 @@ def generate_specref_files(output_dir, version="nightly", preset="mainnet"):
                     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')
+    # Create .ethspecify.yml config file in current directory
+    config_path = '.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('  search_root: .\n')
+        f.write('  auto_standardize_names: true\n')
+        f.write('  auto_add_missing_entries: true\n')
+        f.write('  require_exceptions_have_fork: true\n')
         f.write('  files:\n')
         for category, (filename, _) in category_map.items():
             if items_by_category[category]:
-                f.write(f'    - {filename}\n')
+                f.write(f'    - {output_dir}/{filename}\n')
         f.write('\n')
         f.write('  exceptions:\n')
         f.write('    # Add any exceptions here\n')

{ethspecify-0.3.7 → ethspecify-0.3.9}/ethspecify.egg-info/PKG-INFO RENAMED Viewed

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ethspecify
-Version: 0.3.7
+Version: 0.3.9
 Summary: A utility for processing Ethereum specification tags.
 Home-page: https://github.com/jtraglia/ethspecify
 Author: Justin Traglia
@@ -26,39 +26,132 @@ Dynamic: summary
 # ethspecify
-A tool for referencing the Ethereum specifications in clients.
+A tool for referencing the Ethereum specifications in clients. This will:
-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.
+- Help developers keep track of specification changes.
+- Help auditors find important functions in client implementations.
-## Getting started
+## Table of contents
-### Installation
+- [Getting Started](#getting-started)
+  - [Install](#install)
+  - [Initialize](#initialize)
+- [Inline References](#inline-references)
+- [Centralized References](#centralized-references)
+  - [Configure](#configure)
+  - [Update](#update)
+  - [Map](#map)
+  - [Check](#check)
+  - [Exceptions](#exceptions)
+- [Style Options](#style-options)
+  - [`hash`](#hash)
+  - [`full`](#full)
+  - [`link`](#link)
+  - [`diff`](#diff)
+## Getting Started
+### Install
 ```
 pipx install ethspecify
 ```
-### Initialize specrefs
+### Initialize
-From the root of the client source directory, initialize a directory for specrefs:
+Create a `.ethspecify.yml` config file:
 ```
 $ ethspecify init v1.6.0-beta.0
+Successfully created .ethspecify.yml
+```
+To also generate a `specrefs/` directory with a YAML file for each
+specification category, use the `--specrefs` flag:
+```
+$ ethspecify init v1.6.0-beta.0 --specrefs
 Initializing specrefs directory: v1.6.0-beta.0
-Successfully created specrefs directory at: specrefs
+Successfully created .ethspecify.yml and specrefs/ directory
+```
+> [!TIP]
+> `nightly` is also a valid version, which tracks the latest
+> development specifications.
+## Inline References
+Add `<spec>` tags anywhere in the codebase to reference specification
+items. For example:
+```
+<spec fn="is_active_validator" fork="phase0" />
+```
+Then run `ethspecify` to populate the tag body with the corresponding
+specification content:
+```
+<spec fn="is_active_validator" fork="phase0" hash="5765e850">
+def is_active_validator(validator: Validator, epoch: Epoch) -> bool:
+    """
+    Check if ``validator`` is active.
+    """
+    return validator.activation_epoch <= epoch < validator.exit_epoch
+</spec>
 ```
-This creates a `specrefs` directory with `.ethspecify.yml` and YAML files for each spec category
-(constants, configs, presets, functions, containers, dataclasses, types).
+> [!NOTE]
+> The indentation of the `<spec>` tag is preserved when populating
+> the body. This means spec tags inside comments will have their
+> content indented to match:
+>
+> ```java
+> // <spec fn="is_active_validator" fork="phase0" hash="5765e850">
+> // def is_active_validator(validator: Validator, epoch: Epoch) -> bool:
+> //     """
+> //     Check if ``validator`` is active.
+> //     """
+> //     return validator.activation_epoch <= epoch < validator.exit_epoch
+> // </spec>
+> ```
+## Centralized References
+Specification references (specrefs) are YAML files that map
+specification items (constants, functions, containers, etc.) to
+their corresponding source file locations.
+### Configure
+The following options can be set in the `specrefs` section of
+`.ethspecify.yml`:
+| Option | Default | Description |
+|--------|---------|-------------|
+| `search_root` | `.` | Root directory for resolving source file paths |
+| `auto_standardize_names` | `false` | Rename entries to `item#fork` format |
+| `auto_add_missing_entries` | `false` | Add missing specification items with empty sources |
+| `require_exceptions_have_fork` | `false` | Require exceptions to use `item#fork` format |
+### Update
+To update to a newer specification version, change the `version`
+field in `.ethspecify.yml` and run:
-### Map sources
+```
+$ ethspecify
+```
+This updates the specification content in the YAML files to match
+the new version.
-Edit the YAML files to add sources for where each spec item is implemented.
+### Map
-If it's the entire file:
+Edit the YAML files to add sources for where each specification
+item is implemented.
+If it is the entire file:
 ```yaml
 - name: BlobParameters
@@ -72,7 +165,7 @@ If it's the entire file:
     </spec>
 ```
-If it's multiple entire files:
+If it is multiple entire files:
 ```yaml
 - name: BlobsBundleDeneb
@@ -90,7 +183,7 @@ If it's multiple entire files:
     </spec>
 ```
-If it's a specific part of a file:
+If it is a specific part of a file:
 ```yaml
 - name: EFFECTIVE_BALANCE_INCREMENT
@@ -103,7 +196,7 @@ If it's a specific part of a file:
     </spec>
 ```
-You can also use regex in the searches if that is necessary:
+Regex is also supported in searches:
 ```yaml
 - name: ATTESTATION_DUE_BPS
@@ -117,56 +210,57 @@ You can also use regex in the searches if that is necessary:
     </spec>
 ```
-### Check specrefs
+### Check
-Run the check command in CI to verify all spec items are properly mapped:
+Run the check command in CI to verify all specification items are
+properly mapped:
 ```
-$ ethspecify check --path=specrefs
+$ ethspecify check
 MISSING: constants.BLS_MODULUS#deneb
 ```
-### Add exceptions
+### Exceptions
-Some spec items may not be implemented in your client. Add them to the exceptions list in
-`specrefs/.ethspecify.yml`:
+Some specification items may not have a corresponding
+implementation. Add them to the exceptions list in
+`.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
+  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.
+This attribute can be used to change how the specification content
+is shown.
-### `hash` (default)
+### `hash`
-This style adds a hash of the specification content to the spec tag, without showing the content.
+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.
+> 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.
+This style displays the whole content of this specification item,
+including comments.
 ```
 <spec fn="is_fully_withdrawable_validator" fork="deneb" style="full">
@@ -184,7 +278,8 @@ def is_fully_withdrawable_validator(validator: Validator, balance: Gwei, epoch:
 ### `link`
-This style displays an ethspec.tools link to the specification item.
+This style displays an ethspec.tools link to the specification
+item.
 ```
 <spec fn="apply_pending_deposit" fork="electra" style="link" hash="83ee9126">
@@ -194,7 +289,8 @@ https://ethspec.tools/#specs/v1.7.0-alpha.1/functions-apply_pending_deposit-elec
 ### `diff`
-This style displays a diff with the previous fork's version of the specification.
+This style displays a diff with the previous fork's version of the
+specification.
 ```
 <spec ssz_object="BeaconState" fork="electra" style="diff">
@@ -217,10 +313,12 @@ This style displays a diff with the previous fork's version of the specification
 ```
 > [!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.
+> Comments are stripped from the specifications when the `diff`
+> style is used. This is because they complicate the diff; the
+> "[Modified in Fork]" comments are not valuable here.
-This can be used with any specification item, like functions too:
+This can be used with any specification item, like functions
+too:
 ```
 <spec fn="is_eligible_for_activation_queue" fork="electra" style="diff">

{ethspecify-0.3.7 → ethspecify-0.3.9}/setup.py RENAMED Viewed

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

ethspecify-0.3.7/README.md DELETED Viewed

@@ -1,211 +0,0 @@
-# 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 an ethspec.tools link to the specification item.
-```
-<spec fn="apply_pending_deposit" fork="electra" style="link" hash="83ee9126">
-https://ethspec.tools/#specs/v1.7.0-alpha.1/functions-apply_pending_deposit-electra
-</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>
-```