DOC: Clarify nbytes docstring

numpy · zvun · May 11, 2025 · May 12, 2025 · May 12, 2025 · May 12, 2025
commit 114a38feb3277a7fd89986e2d3a12b46ad91df88
diff --git a/numpy/_core/_add_newdocs.py b/numpy/_core/_add_newdocs.py
@@ -2676,10 +2676,14 @@

 add_newdoc('numpy._core.multiarray', 'ndarray', ('nbytes',
    """
-    Total bytes consumed by the elements of the array.
+    Total number of bytes the array's data would consume if stored
+    contiguously in memory.

    Notes
    -----
+    If the array is a view, this shows how much memory it *would* use
+    if it were copied into a separate array.
+
    Does not include memory consumed by non-element attributes of the
    array object.

@@ -2698,6 +2702,17 @@
    >>> np.prod(x.shape) * x.itemsize
    480

+    >>> import numpy as np
+    >>> arr = np.arange(100).reshape(10, 10, 1)
+    >>> arr_1 = np.broadcast_to(arr, (10, 10, 1000))
+    >>> arr_2 = np.lib.stride_tricks.sliding_window_view(arr, 5, 0)
+    >>> arr.nbytes
+    800
+    >>> arr_1.nbytes
+    800000
+    >>> arr_2.nbytes
+    2400
+
    """))
-Original file line number
+Diff line change
@@ -2676,10 +2676,14 @@
     add_newdoc('numpy._core.multiarray', 'ndarray', ('nbytes',
         """
-        Total bytes consumed by the elements of the array.
+        Total number of bytes the array's data would consume if stored
+        contiguously in memory.
         Notes
         -----
+        If the array is a view, this shows how much memory it *would* use
+        if it were copied into a separate array.
         Does not include memory consumed by non-element attributes of the
         array object.
             Copy link

  
      
    
  

  
      

  
  Member


      

  

  
    
      

      
            seberg
  

      

      

      


        May 12, 2025


      
    

  


        
      
  
  
  
    

    There was a problem hiding this comment.


  

 
  
    

    Choose a reason for hiding this comment

    
      The reason will be displayed to describe this comment to others. Learn more.
    

    
      
      


  


  
    
      Maybe we ca add that it also doesn't include memory indirectly held by the elements.

(I.e. if you store Python objects or the new StringDType)
    
  
  


    

        
      
  
  
    
  
  
  
    
    Sorry, something went wrong.
  

  
    
  
    
      

              Uh oh!

              
There was an error while loading. Please reload this page.


  
  


          
      
  
    
    
      
        
            
    All reactions
@@ -2698,6 +2702,17 @@
         >>> np.prod(x.shape) * x.itemsize
+        >>> import numpy as np
             Copy link

  
      
    
  

  
      

  
  Member


      

  

  
    
      

      
            seberg
  

      

      

      


        May 12, 2025


      
    

  


        
      
  
  
  
    

    There was a problem hiding this comment.


  

 
  
    

    Choose a reason for hiding this comment

    
      The reason will be displayed to describe this comment to others. Learn more.
    

    
      
      


  


  
    
      No need I think, but a sentence on why the next thing comes would help.
    
  
  


    

        
      
  
  
    
  
  
  
    
    Sorry, something went wrong.
  

  
    
  
    
      

              Uh oh!

              
There was an error while loading. Please reload this page.


  
  


          
      
  
    
    
      
        
            
    All reactions
+        >>> arr = np.arange(100).reshape(10, 10, 1)
+        >>> arr_1 = np.broadcast_to(arr, (10, 10, 1000))
+        >>> arr_2 = np.lib.stride_tricks.sliding_window_view(arr, 5, 0)
+        >>> arr.nbytes
+        >>> arr_1.nbytes
+        >>> arr_2.nbytes
             Copy link

  
      
    
  

  
      

  
  Member


      

  

  
    
      

      
            seberg
  

      

      

      


        May 12, 2025


      
    

  


        
      
  
  
  
    

    There was a problem hiding this comment.


  

 
  
    

    Choose a reason for hiding this comment

    
      The reason will be displayed to describe this comment to others. Learn more.
    

    
      
      


  


  
    
      This introduces way too much complexity for very little gain.  If anything at all, just do some slicing like arr[::2] or so.
    
  
  


    

        
      
  
  
    
  
  
  
    
    Sorry, something went wrong.
  

  
    
  
    
      

              Uh oh!

              
There was an error while loading. Please reload this page.


  
  


          
      
  
    
    
      
        
            
    All reactions
         """))
-          Expand Down