Format share amounts using their decimal values

Author: dgunning

edgar/xbrl2/core.py

@@ -250,13 +250,12 @@ def format_value(value: Union[int, float, str], is_monetary: bool, scale: int,
 
     # Apply scaling
     scaled_value = value
-    if is_monetary:
-        if scale <= -9:  # Billions
-            scaled_value = value / 1_000_000_000
-        elif scale <= -6:  # Millions
-            scaled_value = value / 1_000_000
-        elif scale <= -3:  # Thousands
-            scaled_value = value / 1_000
+    if scale <= -9:  # Billions
+        scaled_value = value / 1_000_000_000
+    elif scale <= -6:  # Millions
+        scaled_value = value / 1_000_000
+    elif scale <= -3:  # Thousands
+        scaled_value = value / 1_000
 
     # Determine decimal places to show
     if isinstance(decimals, int):
@@ -265,23 +264,17 @@ def format_value(value: Union[int, float, str], is_monetary: bool, scale: int,
             decimal_places = min(2, decimals)
         else:
             # For negative decimals, adjust based on scaling
-            if is_monetary:
-                if scale <= -9:  # Billions
-                    decimal_places = min(2, max(0, decimals + 9))
-                elif scale <= -6:  # Millions
-                    decimal_places = min(2, max(0, decimals + 6))
-                elif scale <= -3:  # Thousands
-                    decimal_places = min(2, max(0, decimals + 3))
-                else:
-                    decimal_places = 0
+            if scale <= -9:  # Billions
+                decimal_places = min(2, max(0, decimals + 9))
+            elif scale <= -6:  # Millions
+                decimal_places = min(2, max(0, decimals + 6))
+            elif scale <= -3:  # Thousands
+                decimal_places = min(2, max(0, decimals + 3))
             else:
-                # For non-monetary values like share counts
-                # Check if the value is effectively a whole number
-                if abs(round(value) - value) < 0.001:
-                    decimal_places = 0  # Display as whole number
-                else:
-                    # Otherwise use decimals attribute to determine precision
-                    decimal_places = max(0, -decimals)
+                # For unscaled values, respect the decimals attribute
+                # If decimals is negative, show that many zeros to the left of decimal
+                # E.g., decimals=-2 means precision to hundreds place (two zeros after decimal)
+                decimal_places = max(0, -decimals)
     else:
         # Default decimal places
         if is_monetary:

edgar/xbrl2/rendering.py

@@ -20,6 +20,14 @@
 from edgar.files.html import Document
 from datetime import datetime
 
+share_concepts = [
+    'us-gaap_CommonStockSharesOutstanding',
+    'us-gaap_WeightedAverageNumberOfSharesOutstandingBasic',
+    'us-gaap_WeightedAverageNumberOfSharesOutstandingDiluted',
+    'us-gaap_WeightedAverageNumberOfDilutedSharesOutstanding',
+    'us-gaap_CommonStockSharesIssued'
+]
+
 
 def _is_html(text: str) -> bool:
     """
@@ -353,7 +361,26 @@ def render_statement(
     # Determine the dominant scale for monetary values in this statement
     dominant_scale = determine_dominant_scale(statement_data, periods_to_display)
 
-    # Add the fiscal period indicator and units note as a subtitle if available
+    # Determine the scale used for share amounts if present
+    shares_scale = None
+
+    # Look for share-related concepts to determine their scaling from the decimals attribute
+    for item in statement_data:
+        concept = item.get('concept', '')
+        if concept in share_concepts:
+            # Check decimals attribute to determine proper scaling
+            for period_key, _ in periods_to_display:
+                decimals = item.get('decimals', {}).get(period_key)
+                if isinstance(decimals, int) and decimals <= 0:
+                    # Use the decimals attribute to determine the scale
+                    # For shares, decimals is typically negative
+                    # -3 means thousands, -6 means millions, etc.
+                    shares_scale = decimals
+                    break
+            if shares_scale is not None:
+                break
+    
+    # Add the fiscal period indicator and note as a subtitle if available
     if formatted_periods:
         subtitles = []
 
@@ -363,12 +390,36 @@ def render_statement(
 
         # Add units note
         if is_monetary_statement:
+            monetary_scale_text = ""
             if dominant_scale == -3:
-                units_note = "[italic](In thousands, except per share data)[/italic]"
+                monetary_scale_text = "thousands"
             elif dominant_scale == -6:
-                units_note = "[italic](In millions, except per share data)[/italic]"
+                monetary_scale_text = "millions"
             elif dominant_scale == -9:
-                units_note = "[italic](In billions, except per share data)[/italic]"
+                monetary_scale_text = "billions"
+            
+            shares_scale_text = ""
+            if shares_scale is not None:
+                if shares_scale == -3:
+                    shares_scale_text = "thousands"
+                elif shares_scale == -6:
+                    shares_scale_text = "millions"
+                elif shares_scale == -9:
+                    shares_scale_text = "billions"
+                elif shares_scale == 0:
+                    shares_scale_text = "actual amounts"
+                else:
+                    # For other negative scales (like -4, -5, -7, etc.)
+                    # Use a more generic description based on the scale
+                    scale_factor = 10 ** (-shares_scale)
+                    if scale_factor >= 1000:
+                        shares_scale_text = f"scaled by {scale_factor:,}"
+            
+            # Construct appropriate units note
+            if monetary_scale_text and shares_scale_text and shares_scale != dominant_scale:
+                units_note = f"[italic](In {monetary_scale_text}, except shares in {shares_scale_text})[/italic]"
+            elif monetary_scale_text:
+                units_note = f"[italic](In {monetary_scale_text}, except per share data)[/italic]"
             else:
                 units_note = ""
 
@@ -595,8 +646,11 @@ def render_statement(
 
         # Format the label based on level and abstract status
         level = item['level']
+
         # Remove [Abstract] from label if present
         label = item['label'].replace(' [Abstract]', '')
+
+        concept = item['concept']
 
         # Get values for each period
         period_values = []
@@ -608,22 +662,39 @@ def render_statement(
             # Check label to identify non-monetary items like shares, ratios, etc.
             is_monetary = is_monetary_statement
 
-            # Check for shares-related values by examining label
+            # Check for shares-related values by examining concept names
             label_lower = label.lower()
-            if any(keyword in label_lower for keyword in [
-                'earnings per share', 'per common share', 'per share', 'in shares', 'shares outstanding'
-                'per basic', 'per diluted'
-            ]):
-                is_monetary = False
+            is_share_value = False
 
+            if concept in ['us-gaap_EarningsPerShareBasic', 'us-gaap_EarningsPerShareDiluted']:
+                is_monetary = False
+            elif concept in share_concepts:
+                is_monetary = False
+                is_share_value = True
+            
             # Ratio-related items should not be monetary
             if any(keyword == word for keyword in ['ratio', 'percentage', 'per cent']
                    for word in label_lower.split()):
                 is_monetary = False
 
             # Format numeric values
             if isinstance(value, (int, float)):
-                formatted_value = Text(format_value(value, is_monetary, dominant_scale, fact_decimals), justify="right")
+                # Handle share values differently
+                if is_share_value and isinstance(fact_decimals, int):
+                    # Use fact_decimals to determine the appropriate scaling for share values
+                    # This ensures correct display for companies of all sizes
+                    if fact_decimals <= -3:
+                        # Apply appropriate scaling based on the actual decimals value
+                        scale_factor = 10 ** (-fact_decimals)
+                        scaled_value = value / scale_factor
+                        # Always display share amounts with 0 decimal places for cleaner presentation
+                        formatted_value = Text(f"{scaled_value:,.0f}", justify="right")
+                    else:
+                        # For smaller numbers or positive decimals, use unscaled values
+                        formatted_value = Text(f"{value:,.0f}", justify="right")
+                else:
+                    # Format other values normally using the flexible format_value function
+                    formatted_value = Text(format_value(value, is_monetary, dominant_scale, fact_decimals), justify="right")
             else:
                 # Non-numeric values - check if it's HTML and convert if needed
                 if value and isinstance(value, str) and _is_html(value):

edgar/xbrl2/standardization.py

@@ -9,6 +9,7 @@
 import json
 import os
 from enum import Enum
+from json import JSONDecodeError
 from typing import Dict, List, Optional, Set, Tuple, Any
 from difflib import SequenceMatcher
 
@@ -107,8 +108,10 @@ def _load_mappings(self) -> Dict[str, Set[str]]:
                 else:
                     # Flat structure
                     return {k: set(v) for k, v in data.items()}
-                    
-        except (FileNotFoundError, json.JSONDecodeError):
+
+        except JSONDecodeError as e:
+            raise
+        except FileNotFoundError:
             # Return default mappings if file doesn't exist or is invalid
             return {
                 "Revenue": {"us-gaap_SalesRevenueNet", "us-gaap_Revenue", "us-gaap_Revenues"},

edgartools.md

@@ -0,0 +1,44 @@
+# Edgartools
+
+
+# Getting Started
+
+Import the module and most useful functions with:
+```python
+from edgar import *
+```
+
+To make requests to the SEC, you need to set your identity with:
+```python
+set_identity("user@domain.com")
+```
+
+## Get a Company 
+
+### Get a company by ticker symbol
+
+```python
+company = Company("AAPL")
+```
+
+### Get a company by CIK
+
+```python
+company = Company("0000320193")
+# OR
+company = Company(320193)
+```
+
+### Get company filings
+
+To get all filings for a company:
+```python
+filings = company.get_filings()
+```
+
+### Get company filings by form type
+
+To get all 10-K filings for a company:
+```python
+filings = company.get_filings(form="10-K")
+```