Refactor type assertions to use isinstance, add a note in the README about heuristic nature of hierarchy building

Author: alperkent-cmi

README.md

@@ -9,6 +9,9 @@
 
 A parser for extracting headings and hierarchical structure from Markdown files.
 
+> [!IMPORTANT]
+> This parser uses several heuristic rules to build hierarchies from diverse heading formats. Results may vary depending on document structure and formatting. Please review the [How Hierarchy is Built](#how-hierarchy-is-built) section before use to understand its capabilities and limitations for your specific use case.
+
 ## Features
 
 - Parse multiple heading formats (hash `#`, asterisk `**`, inline with colon, all-caps)

src/headhunter/hierarchy.py

@@ -246,7 +246,7 @@ def _update_heading_stack(
         """
         while heading_stack and heading_stack[-1][0] >= level:
             heading_stack.pop()
-        assert type(token.metadata) is models.HeadingMetadata  # for mypy
+        assert isinstance(token.metadata, models.HeadingMetadata)  # for mypy
         heading_stack.append((level, token.content, token.metadata))
 
     def _should_pop_inline_heading(

src/headhunter/matcher.py

@@ -399,7 +399,7 @@ def _split_content_token(
 
     # Create post-content tokens
     # Special handling for inline colon headings
-    assert type(heading_token.metadata) is models.HeadingMetadata  # for mypy
+    assert isinstance(heading_token.metadata, models.HeadingMetadata)  # for mypy
 
     if heading_token.metadata.is_inline:
         if after_text:
@@ -526,7 +526,7 @@ def _find_and_extract_heading(
                 heading_position_in_split = i
                 break
 
-        assert type(heading_position_in_split) is int  # for mypy
+        assert isinstance(heading_position_in_split, int)  # for mypy
         extracted_heading_idx = original_idx + heading_position_in_split
         heading_line_number = split_tokens[heading_position_in_split].line_number
 
@@ -605,7 +605,7 @@ def match_headings(
             match_token, match_idx = exact_match_result
             last_matched_token_index = match_idx
 
-            assert type(match_token.metadata) is models.HeadingMetadata  # for mypy
+            assert isinstance(match_token.metadata, models.HeadingMetadata)  # for mypy
 
             matched_headings.append(
                 {
@@ -657,7 +657,7 @@ def match_headings(
         last_matched_token_index = extracted_heading_idx
 
         extracted_token = current_tokens[extracted_heading_idx]
-        assert type(extracted_token.metadata) is models.HeadingMetadata  # for mypy
+        assert isinstance(extracted_token.metadata, models.HeadingMetadata)  # for mypy
         heading_signature = extracted_token.metadata.signature
 
         matched_headings.append(

src/headhunter/models.py

@@ -575,15 +575,15 @@ def match_headings(
             updated_documents.append(updated_doc)
 
             match_pct = updated_doc.metadata["match_percentage"]
-            assert type(match_pct) is float
+            assert isinstance(match_pct, float)
             match_percentages.append(float(match_pct))
 
             matched = updated_doc.metadata["matched_headings"]
-            assert type(matched) is list
+            assert isinstance(matched, list)
             all_matched_headings.extend(matched)
 
             missing = updated_doc.metadata["missing_headings"]
-            assert type(missing) is list
+            assert isinstance(missing, list)
             all_missing_headings.extend(missing)
 
             doc_id = str(updated_doc.metadata["id"])

src/headhunter/output.py

@@ -77,7 +77,7 @@ def to_dict(
             }
 
             parent = _pop_stack_to_parent_level(stack, ctx.level)
-            assert type(parent["sections"]) is list  # for mypy
+            assert isinstance(parent["sections"], list)  # for mypy
             parent["sections"].append(section)
             stack.append((ctx.level, section))
 
@@ -91,7 +91,7 @@ def to_dict(
                 "line_number": token.line_number,
             }
 
-            assert type(parent["sections"]) is list  # for mypy
+            assert isinstance(parent["sections"], list)  # for mypy
             parent["sections"].append(content_item)
 
     return root

tests/test_api.py

@@ -24,7 +24,7 @@ def test_process_text(
     )
     actual_output = parsed_text.to_dict()
 
-    assert type(parsed_text) is ParsedText
+    assert isinstance(parsed_text, ParsedText)
     assert actual_output == sample_mixed_json
 
 
@@ -57,7 +57,7 @@ def test_process_batch_df(
     json_files = parsed_batch.to_json(str(json_dir))
     tree_files = parsed_batch.to_tree(str(tree_dir))
 
-    assert type(parsed_batch) is ParsedBatch
+    assert isinstance(parsed_batch, ParsedBatch)
     assert actual_dataframe.equals(sample_dataframe_parsed)
     assert (
         "Unknown custom configuration parameter(s) will be ignored: 'random_param'. "
@@ -104,7 +104,7 @@ def test_process_text_with_matcher(
 
     actual_output = parsed_text.to_dict()
 
-    assert type(parsed_text) is ParsedText
+    assert isinstance(parsed_text, ParsedText)
     assert actual_output == sample_match_json
 
 
@@ -139,7 +139,7 @@ def test_process_batch_df_with_matcher(
     # Reorder expected columns to match actual output for comparison
     actual_output = actual_output[sample_dataframe_match_parsed.columns]
 
-    assert type(parsed_batch) is ParsedBatch
+    assert isinstance(parsed_batch, ParsedBatch)
     assert actual_output.equals(sample_dataframe_match_parsed)
 
 
@@ -219,7 +219,7 @@ def test_process_structured_df(
     )
     actual_dataframe = parsed_batch.to_dataframe()
 
-    assert type(parsed_batch) is ParsedBatch
+    assert isinstance(parsed_batch, ParsedBatch)
     assert len(parsed_batch.documents) == len(sample_structured_dataframe)
     assert actual_dataframe.equals(sample_structured_parsed)
 
@@ -240,7 +240,7 @@ def test_process_structured_df_auto_detect_columns(
     )
     actual_dataframe = parsed_batch.to_dataframe()
 
-    assert type(parsed_batch) is ParsedBatch
+    assert isinstance(parsed_batch, ParsedBatch)
     assert len(parsed_batch.documents) == len(sample_structured_dataframe)
     assert actual_dataframe.equals(sample_structured_parsed)